2.2. pyamf.amf3 — AMF3

AMF3 implementation.

C{AMF3} is the default serialization for U{ActionScript<http://en.wikipedia.org/wiki/ActionScript>} 3.0 and provides various advantages over L{AMF0<pyamf.amf0>}, which is used for ActionScript 1.0 and 2.0. It adds support for sending C{int} and C{uint} objects as integers and supports data types that are available only in ActionScript 3.0, such as L{ByteArray} and L{ArrayCollection}.

@see: U{Official AMF3 Specification in English (external) <http://opensource.adobe.com/wiki/download/attachments/1114283/amf3_spec_05_05_08.pdf>} @see: U{Official AMF3 Specification in Japanese (external) <http://opensource.adobe.com/wiki/download/attachments/1114283/JP_amf3_spec_121207.pdf>} @see: U{AMF3 documentation on OSFlash (external) <http://osflash.org/documentation/amf3>}

@since: 0.1

class pyamf.amf3.ByteArray(*args, **kwargs)

I am a C{StringIO} type object containing byte data from the AMF stream. ActionScript 3.0 introduced the C{flash.utils.ByteArray} class to support the manipulation of raw data in the form of an Array of bytes.

Supports C{zlib} compression.

Possible uses of the C{ByteArray} class:

• Creating a custom protocol to connect to a client.
• Writing your own AMF/Remoting packet.
• Optimizing the size of your data by using custom data types.

@see: U{ByteArray on Livedocs (external) <http://livedocs.adobe.com/flex/201/langref/flash/utils/ByteArray.html>}

compress()

Forces compression of the underlying stream.

class pyamf.amf3.ClassDefinition(alias)

This is an internal class used by Encoder/Decoder to hold details about transient class trait definitions.

class pyamf.amf3.Context

I hold the AMF3 context for en/decoding streams.

@ivar strings: A list of string references. @type strings: C{list} @ivar classes: A list of L{ClassDefinition}. @type classes: C{list} @ivar legacy_xml: A list of legacy encoded XML documents. @type legacy_xml: C{list}

addClass(alias, klass)

Creates a reference to C{class_def}.

@param alias: C{ClassDefinition} instance.

addLegacyXML(doc)

Creates a reference to C{doc}.

If C{doc} is already referenced that index will be returned. Otherwise a new index will be created.

@type doc: L{ET<util.ET>} @param doc: The XML document to reference. @rtype: C{int} @return: The reference to C{doc}.

addString(s)

Creates a reference to C{s}. If the reference already exists, that reference is returned.

@type s: C{str} @param s: The string to be referenced. @rtype: C{int} @return: The reference index.

@raise TypeError: The parameter C{s} is not of C{basestring} type.

clear()

Clears the context.

getClass(klass)

Return class reference.

@return: Class reference.

getClassByReference(ref)

Return class reference.

@return: Class reference.

getLegacyXML(ref)

Return the legacy XML reference. This is the C{flash.xml.XMLDocument} class in ActionScript 3.0 and the top-level C{XML} class in ActionScript 1.0 and 2.0.

@type ref: C{int} @param ref: The reference index. @return: Instance of L{ET<util.ET>} or C{None}

getLegacyXMLReference(doc)

Return legacy XML reference.

@type doc: L{ET<util.ET>} @param doc: The XML document to reference. @return: The reference to C{doc} or C{None}. @rtype: C{int}

getString(ref)

Gets a string based on a reference C{ref}.

@param ref: The reference index. @type ref: C{str}

@rtype: C{str} or C{None} @return: The referenced string.

getStringReference(s)

Return string reference.

@type s: C{str} @param s: The referenced string. @return: The reference index to the string. @rtype: C{int} or C{None}

class pyamf.amf3.DataInput(decoder=None)

I provide a set of methods for reading binary data with ActionScript 3.0.

This class is the I/O counterpart to the L{DataOutput} class, which writes binary data.

@see: U{IDataInput on Livedocs (external) <http://livedocs.adobe.com/flex/201/langref/flash/utils/IDataInput.html>}

readBoolean()

Read C{Boolean}.

@raise ValueError: Error reading Boolean. @rtype: C{bool} @return: A Boolean value, C{True} if the byte is nonzero, C{False} otherwise.

readByte()

Reads a signed byte.

@rtype: C{int} @return: The returned value is in the range -128 to 127.

readDouble()

Reads an IEEE 754 double-precision floating point number from the data stream.

@rtype: C{number} @return: An IEEE 754 double-precision floating point number.

readFloat()

Reads an IEEE 754 single-precision floating point number from the data stream.

@rtype: C{number} @return: An IEEE 754 single-precision floating point number.

readInt()

Reads a signed 32-bit integer from the data stream.

@rtype: C{int} @return: The returned value is in the range -2147483648 to 2147483647.

readMultiByte(length, charset)

Reads a multibyte string of specified length from the data stream using the specified character set.

@type length: C{int} @param length: The number of bytes from the data stream to read. @type charset: C{str} @param charset: The string denoting the character set to use.

@rtype: C{str} @return: UTF-8 encoded string.

readObject()

Reads an object from the data stream.

@return: The deserialized object.

readShort()

Reads a signed 16-bit integer from the data stream.

@rtype: C{uint} @return: The returned value is in the range -32768 to 32767.

readUTF()

Reads a UTF-8 string from the data stream.

The string is assumed to be prefixed with an unsigned short indicating the length in bytes.

@rtype: C{str} @return: A UTF-8 string produced by the byte representation of characters.

readUTFBytes(length)

Reads a sequence of C{length} UTF-8 bytes from the data stream and returns a string.

@type length: C{int} @param length: The number of bytes from the data stream to read. @rtype: C{str} @return: A UTF-8 string produced by the byte representation of characters of specified C{length}.

readUnsignedByte()

Reads an unsigned byte from the data stream.

@rtype: C{uint} @return: The returned value is in the range 0 to 255.

readUnsignedInt()

Reads an unsigned 32-bit integer from the data stream.

@rtype: C{uint} @return: The returned value is in the range 0 to 4294967295.

readUnsignedShort()

Reads an unsigned 16-bit integer from the data stream.

@rtype: C{uint} @return: The returned value is in the range 0 to 65535.

class pyamf.amf3.DataOutput(encoder=None)

I am a C{StringIO} type object containing byte data from the AMF stream. ActionScript 3.0 introduced the C{flash.utils.ByteArray} class to support the manipulation of raw data in the form of an Array of bytes. I provide a set of methods for writing binary data with ActionScript 3.0.

This class is the I/O counterpart to the L{DataInput} class, which reads binary data.

@see: U{IDataOutput on Livedocs (external) <http://livedocs.adobe.com/flex/201/langref/flash/utils/IDataOutput.html>}

writeBoolean(value)

Writes a Boolean value.

@type value: C{bool} @param value: A C{Boolean} value determining which byte is written. If the parameter is C{True}, C{1} is written; if C{False}, C{0} is written.

@raise ValueError: Non-boolean value found.

writeByte(value)

Writes a byte.

@type value: C{int}

writeDouble(value)

Writes an IEEE 754 double-precision (64-bit) floating point number.

@type value: C{number}

writeFloat(value)

Writes an IEEE 754 single-precision (32-bit) floating point number.

@type value: C{float}

writeInt(value)

Writes a 32-bit signed integer.

@type value: C{int}

writeMultiByte(value, charset)

Writes a multibyte string to the datastream using the specified character set.

@type value: C{str} @param value: The string value to be written. @type charset: C{str} @param charset: The string denoting the character set to use. Possible

character set strings include C{shift-jis}, C{cn-gb}, C{iso-8859-1} and others.

@see: U{Supported character sets on Livedocs (external)

<http://livedocs.adobe.com/flex/201/langref/charset-codes.html>}

writeObject(value, use_proxies=None)

Writes an object to data stream in AMF serialized format.

@param value: The object to be serialized.

writeShort(value)

Writes a 16-bit integer.

@type value: C{int} @param value: A byte value as an integer.

writeUTF(value)

Writes a UTF-8 string to the data stream.

The length of the UTF-8 string in bytes is written first, as a 16-bit integer, followed by the bytes representing the characters of the string.

@type value: C{str} @param value: The string value to be written.

writeUTFBytes(value)

Writes a UTF-8 string. Similar to L{writeUTF}, but does not prefix the string with a 16-bit length word.

@type value: C{str} @param value: The string value to be written.

writeUnsignedByte(value)

Writes an unsigned byte.

@type value: C{int} @since: 0.5

writeUnsignedInt(value)

Writes a 32-bit unsigned integer.

@type value: C{int} @param value: A byte value as an unsigned integer.

writeUnsignedShort(value)

Writes a 16-bit unsigned integer.

@type value: C{int} @param value: A byte value as an integer. @since: 0.5

class pyamf.amf3.Decoder(*args, **kwargs)

Decodes an AMF3 data stream.

context_class

alias of Context

readArray()

Reads an array from the stream.

@warning: There is a very specific problem with AMF3 where the first three bytes of an encoded empty C{dict} will mirror that of an encoded C{{‘’: 1, ‘2’: 2}}

@see: U{Docuverse blog (external) <http://www.docuverse.com/blog/donpark/2007/05/14/flash-9-amf3-bug>}

readBoolFalse()

Returns C{False}.

@return: C{False} @rtype: C{bool}

readBoolTrue()

Returns C{True}.

@return: C{True} @rtype: C{bool}

readByteArray()

Reads a string of data from the stream.

Detects if the L{ByteArray} was compressed using C{zlib}.

@see: L{ByteArray} @note: This is not supported in ActionScript 1.0 and 2.0.

readDate()

Read date from the stream.

The timezone is ignored as the date is always in UTC.

readInteger(signed=True)

Reads and returns an integer from the stream.

@type signed: C{bool} @see: U{Parsing integers on OSFlash <http://osflash.org/amf3/parsing_integers>} for the AMF3 integer data format.

readNull()

Read null.

@return: C{None} @rtype: C{None}

readNumber()

Read number.

readObject(use_proxies=None)

Reads an object from the stream.

Raises pyamf.EncodeError:  Decoding an object in amf3 tagged as amf0 only is not allowed. Raises pyamf.DecodeError:  Unknown object encoding. Raises pyamf.ReferenceError:  Bad object reference given.

readString()

Reads and returns a string from the stream.

readUndefined()

Read undefined.

readUnicode()

Reads and returns a decoded utf-u unicode from the stream.

readXML()

Read a legacy XML Document from the stream.

@return: The XML Document. @rtype: L{ET<util.ET>}

readXMLString()

Reads a string from the data stream and converts it into an XML Tree.

@return: The XML Document. @rtype: L{ET<util.ET>}

class pyamf.amf3.Encoder(*args, **kwargs)

Encodes an AMF3 data stream.

context_class

alias of Context

getTypeFunc(data)

Returns a function object that will encode data.

writeBoolean(n, **kwargs)

Writes a Boolean to the stream.

writeByteArray(n, **kwargs)

Writes a L{ByteArray} to the data stream.

@param n: The L{ByteArray} data to be encoded to the AMF3 data stream. @type n: L{ByteArray}

writeDate(n, **kwargs)

Writes a C{datetime} instance to the stream.

@type n: L{datetime} @param n: The C{Date} data to be encoded to the AMF3 data stream.

writeDict(n, use_proxies=None)

Writes a C{dict} to the stream.

@type n: C{__builtin__.dict} @param n: The C{dict} data to be encoded to the AMF3 data stream. @raise ValueError: Non C{int}/C{str} key value found in the C{dict} @raise EncodeError: C{dict} contains empty string keys.

writeInteger(n, **kwargs)

Writes an integer to the stream.

@type n: integer data @param n: The integer data to be encoded to the AMF3 data stream.

writeList(n, use_proxies=None)

Writes a C{tuple}, C{set} or C{list} to the stream.

@type n: One of C{__builtin__.tuple}, C{__builtin__.set}

or C{__builtin__.list}

@param n: The C{list} data to be encoded to the AMF3 data stream.

writeNull(*args, **kwargs)

Writes a C{null} value to the stream.

writeNumber(n, **kwargs)

Writes a float to the stream.

@type n: C{float}

writeObject(obj, use_proxies=None)

Writes an object to the stream.

Parameter:obj – The object data to be encoded to the AMF3 data stream.

writeString(s, writeType=True, **kwargs)

Writes a string to the stream. If C{n} is not a unicode string, an attempt will be made to convert it.

@type n: C{basestring} @param n: The string data to be encoded to the AMF3 data stream.

writeUndefined(*args, **kwargs)

Writes an C{pyamf.Undefined} value to the stream.

writeUnicode(u, writeType=True, **kwargs)

Writes a unicode object to the stream.

writeXML(n, use_proxies=None)

Writes a XML string to the data stream.

@type n: L{ET<util.ET>} @param n: The XML Document to be encoded to the AMF3 data stream.

pyamf.amf3.MAX_29B_INT

The maximum that can be represented by an signed 29 bit integer.

pyamf.amf3.MIN_29B_INT

The minimum that can be represented by an signed 29 bit integer.

class pyamf.amf3.ObjectEncoding

AMF object encodings.

DYNAMIC

Name-value encoding. The property names and values are encoded as string-data followed by AMF3-data until there is an empty string property name. If there is a class-def reference there are no property names and the number of values is equal to the number of properties in the class-def.

EXTERNAL

Externalizable object. What follows is the value of the “inner” object, including type code. This value appears for objects that implement IExternalizable, such as L{ArrayCollection} and L{ObjectProxy}.

PROXY

Proxy object.

STATIC

Property list encoding. The remaining integer-data represents the number of class members that exist. The property names are read as string-data. The values are then read as AMF3-data.

pyamf.amf3.REFERENCE_BIT

Reference bit.

pyamf.amf3.TYPE_ARRAY

ActionScript Arrays are described based on the nature of their indices, i.e. their type and how they are positioned in the Array.

pyamf.amf3.TYPE_BOOL_FALSE

The false type is represented by the false type marker and is used to encode a Boolean value of C{false}. No further information is encoded for this value.

pyamf.amf3.TYPE_BOOL_TRUE

The true type is represented by the true type marker and is used to encode a Boolean value of C{true}. No further information is encoded for this value.

pyamf.amf3.TYPE_BYTEARRAY

ActionScript 3.0 introduces the L{ByteArray} type to hold an Array of bytes. AMF 3 serializes this type using a variable length encoding 29-bit integer for the byte-length prefix followed by the raw bytes of the L{ByteArray}. @see: U{Parsing ByteArrays on OSFlash (external) <http://osflash.org/documentation/amf3/parsing_byte_arrays>}

pyamf.amf3.TYPE_DATE

In AMF 3 an ActionScript Date is serialized simply as the number of milliseconds elapsed since the epoch of midnight, 1st Jan 1970 in the UTC time zone. Local time zone information is not sent.

pyamf.amf3.TYPE_INTEGER

In AMF 3 integers are serialized using a variable length signed 29-bit integer. @see: U{Parsing Integers on OSFlash (external) <http://osflash.org/documentation/amf3/parsing_integers>}

pyamf.amf3.TYPE_NULL

The null type is represented by the null type marker. No further information is encoded for this value.

pyamf.amf3.TYPE_NUMBER

This type is used to encode an ActionScript Number or an ActionScript C{int} of value greater than or equal to 2^28 or an ActionScript uint of value greater than or equal to 2^29. The encoded value is is always an 8 byte IEEE-754 double precision floating point value in network byte order (sign bit in low memory). The AMF 3 number type is encoded in the same manner as the AMF 0 L{Number<pyamf.amf0.TYPE_NUMBER>} type.

pyamf.amf3.TYPE_OBJECT

A single AMF 3 type handles ActionScript Objects and custom user classes.

pyamf.amf3.TYPE_STRING

ActionScript String values are represented using a single string type in AMF 3 - the concept of string and long string types from AMF 0 is not used. Strings can be sent as a reference to a previously occurring String by using an index to the implicit string reference table. Strings are encoding using UTF-8 - however the header may either describe a string literal or a string reference.

pyamf.amf3.TYPE_UNDEFINED

The undefined type is represented by the undefined type marker. No further information is encoded for this value.

pyamf.amf3.TYPE_XML

ActionScript 3.0 introduced a new XML type however the legacy C{XMLDocument} type from ActionScript 1.0 and 2.0.is retained in the language as C{flash.xml.XMLDocument}. Similar to AMF 0, the structure of an C{XMLDocument} needs to be flattened into a string representation for serialization. As with other strings in AMF, the content is encoded in UTF-8. XMLDocuments can be sent as a reference to a previously occurring C{XMLDocument} instance by using an index to the implicit object reference table. @see: U{OSFlash documentation (external) <http://osflash.org/documentation/amf3#x07_-_xml_legacy_flash.xml.xmldocument_class>}

pyamf.amf3.TYPE_XMLSTRING

ActionScript 3.0 introduces a new top-level XML class that supports U{E4X<http://en.wikipedia.org/wiki/E4X>} syntax. For serialization purposes the XML type needs to be flattened into a string representation. As with other strings in AMF, the content is encoded using UTF-8.

pyamf.amf3.decode(stream, context=None, strict=False)

A helper function to decode an AMF3 datastream.

@type stream: L{BufferedByteStream<util.BufferedByteStream>} @param stream: AMF3 data. @type context: L{Context} @param context: Context.

pyamf.amf3.decode_int(stream, signed=False)

Decode C{int}.

pyamf.amf3.encode(*args, **kwargs)

A helper function to encode an element into AMF3 format.

@type args: List of args to encode. @keyword context: Any initial context to use. @type context: L{Context} @return: C{StringIO} type object containing the encoded AMF3 data. @rtype: L{BufferedByteStream<pyamf.util.BufferedByteStream>}

pyamf.amf3.encode_int(n)

Encodes an int as a variable length signed 29-bit integer as defined by the spec.

@param n: The integer to be encoded @return: The encoded string @rtype: C{str} @raise OverflowError: Out of range.

pyamf.amf3.use_proxies_default

If True encode/decode lists/tuples to L{ArrayCollections<ArrayCollection>} and dicts to L{ObjectProxy}

The pyamf.amf3 module supplies classes for [todo].

The pyamf.amf3 module exports the following constants:

See also

Module pyamf.amf0

AMF0 equivalent.