1. pyamf — pyamf

B{PyAMF} provides B{A}ction B{M}essage B{F}ormat (U{AMF<http://en.wikipedia.org/wiki/Action_Message_Format>}) support for Python that is compatible with the Adobe U{Flash Player<http://en.wikipedia.org/wiki/Flash_Player>}.

@copyright: Copyright (c) 2007-2009 The PyAMF Project. All Rights Reserved. @contact: U{users@pyamf.org<mailto:users@pyamf.org>} @see: U{http://pyamf.org}

@since: October 2007 @version: 0.6 @status: Production/Stable

pyamf.register_class(klass, alias=None)

Registers a class to be used in the data streaming.

@return: The registered L{ClassAlias}.

pyamf.register_class_loader(loader)

Registers a loader that is called to provide the C{Class} for a specific alias.

The L{loader} is provided with one argument, the C{Class} alias. If the loader succeeds in finding a suitable class then it should return that class, otherwise it should return C{None}.

@type loader: C{callable} @raise TypeError: The C{loader} is not callable. @raise ValueError: The C{loader} is already registered.

pyamf.encode(*args, **kwargs)

A helper function to encode an element.

@type args: C{mixed} @keyword element: Python data. @type encoding: C{int} @keyword encoding: AMF encoding type. @type context: L{amf0.Context<pyamf.amf0.Context>} or L{amf3.Context<pyamf.amf3.Context>} @keyword context: Context.

@rtype: C{StringIO} @return: File-like object.

pyamf.decode(*args, **kwargs)

A generator function to decode a datastream.

@kwarg stream: AMF data. @type stream: L{BufferedByteStream<pyamf.util.BufferedByteStream>} @type encoding: C{int} @kwarg encoding: AMF encoding type. @type context: L{AMF0 Context<pyamf.amf0.Context>} or L{AMF3 Context<pyamf.amf3.Context>} @kwarg context: Context. @return: Each element in the stream.

pyamf.get_class_alias(klass)

Finds the alias registered to the class.

@type klass: C{object} or class object. @return: The class alias linked to C{klass}. @rtype: L{ClassAlias} @raise UnknownClassAlias: Class not found.

pyamf.unregister_class(alias)

Deletes a class from the cache.

If C{alias} is a class, the matching alias is found.

@type alias: C{class} or C{str} @param alias: Alias for class to delete. @raise UnknownClassAlias: Unknown alias.

pyamf.register_alias_type(klass, *args)

This function allows you to map subclasses of L{ClassAlias} to classes listed in C{args}.

When an object is read/written from/to the AMF stream, a paired L{ClassAlias} instance is created (or reused), based on the Python class of that object. L{ClassAlias} provides important metadata for the class and can also control how the equivalent Python object is created, how the attributes are applied etc.

Use this function if you need to do something non-standard.

@see: L{pyamf.adapters._google_appengine_ext_db.DataStoreClassAlias} for a

good example.

@since: 0.4 @raise RuntimeError: Type is already registered. @raise TypeError: C{klass} must be a class. @raise ValueError: New aliases must subclass L{pyamf.ClassAlias}. @raise ValueError: At least one type must be supplied.

pyamf.unregister_alias_type(klass)

Removes the klass from the ALIAS_TYPE register.

@see: L{register_alias_type}

pyamf.unregister_class_loader(loader)

Unregisters a class loader.

@type loader: C{callable} @param loader: The object to be unregistered

@raise LookupError: The C{loader} was not registered.

pyamf.add_error_class(klass, code)

Maps an exception class to a string code. Used to map remoting C{onStatus} objects to an exception class so that an exception can be built to represent that error:

class AuthenticationError(Exception):
    pass

An example: C{add_error_class(AuthenticationError, ‘Auth.Failed’)}

@type code: C{str}

@raise TypeError: C{klass} must be a C{class} type. @raise TypeError: Error classes must subclass the C{__builtin__.Exception} class. @raise ValueError: Code is already registered.

An example:

>>> class AuthenticationError(Exception):
...     pass
...
>>> pyamf.add_error_class(AuthenticationError, 'Auth.Failed')
>>> print pyamf.ERROR_CLASS_MAP
{'TypeError': <type 'exceptions.TypeError'>, 'IndexError': <type 'exceptions.IndexError'>,
'Auth.Failed': <class '__main__.AuthenticationError'>, 'KeyError': <type 'exceptions.KeyError'>,
'NameError': <type 'exceptions.NameError'>, 'LookupError': <type 'exceptions.LookupError'>}

pyamf.remove_error_class(klass)

Removes a class from C{ERROR_CLASS_MAP}.

@raise ValueError: Code is not registered. @raise ValueError: Class is not registered. @raise TypeError: Invalid type, expected C{class} or C{string}.

An example:

>>> class AuthenticationError(Exception):
...     pass
...
>>> pyamf.add_error_class(AuthenticationError, 'Auth.Failed')
>>> pyamf.remove_error_class(AuthenticationError)

pyamf.add_type(type_, func=None)

Adds a custom type to L{TYPE_MAP}. A custom type allows fine grain control of what to encode to an AMF data stream.

@raise TypeError: Unable to add as a custom type (expected a class or callable). @raise KeyError: Type already exists.

pyamf.remove_type(type_)

Removes the custom type declaration.

@return: Custom type declaration.

pyamf.register_package(module=None, package=None, separator='.', ignore=[], strict=True)

This is a helper function that takes the concept of Actionscript packages and registers all the classes in the supplied Python module under that package. It auto-aliased all classes in C{module} based on C{package}.

e.g. C{mymodule.py}::

class User(object):

pass

class Permission(object):

pass

>>> import mymodule
>>> pyamf.register_package(mymodule, 'com.example.app')

Now all instances of C{mymodule.User} will appear in Actionscript under the alias ‘com.example.app.User’. Same goes for C{mymodule.Permission} - the Actionscript alias is ‘com.example.app.Permission’. The reverse is also true, any objects with the correct aliases will now be instances of the relevant Python class.

This function respects the C{__all__} attribute of the module but you can have further control of what not to auto alias by populating the C{ignore} argument.

This function provides the ability to register the module it is being called in, an example:

>>> class Foo:
...     pass
...
>>> class Bar:
...     pass
...
>>> import pyamf
>>> pyamf.register_package('foo')

You can also supply a list of classes to register. An example, taking the above classes:

>>> import pyamf
>>> pyamf.register_package([Foo, Bar], 'foo')

@param module: The Python module that will contain all the classes to

auto alias.

@type module: C{module} or C{dict} @param package: The base package name. e.g. ‘com.example.app’. If this

is C{None} then the value is inferred from module.__name__.

@type package: C{str} or C{unicode} or C{None} @param separator: The separator used to append to C{package} to form the

complete alias.

@type separator: C{str} @param ignore: To give fine grain control over what gets aliased and what

doesn’t, supply a list of classes that you B{do not} want to be aliased.

@type ignore: C{iterable} @param strict: If this value is C{True} then only classes that originate

from C{module} will be registered, all others will be left in peace.

@type strict: C{bool} @return: A collection of all the classes that were registered and their

respective L{ClassAlias} objects.

@since: 0.5

For example mymodule.py:

class User(object):
    pass

class Permission(object):
    pass

Register it like this:

>>> import mymodule
>>> pyamf.register_package(mymodule, 'com.example.app')

Now all instances of mymodule.User will appear in Actionscript under the alias ‘com.example.app.User’. Same goes for mymodule.Permission - the Actionscript alias is ‘com.example.app.Permission’. The reverse is also true, any objects with the correct aliases will now be instances of the relevant Python class.

This function respects the __all__ attribute of the module but you can have further control of what not to auto alias by populating the ignore argument.

This function provides the ability to register the module it is being called in, an example:

>>> class Foo:
...     pass
...
>>> class Bar:
...     pass
...
>>> pyamf.register_package('foo')

You can also supply a list of classes to register. An example, taking the above classes:

>>> pyamf.register_package([Foo, Bar], 'foo')

pyamf.AMF0

Specifies that objects are serialized using AMF for ActionScript 1.0 and 2.0 that were introduced in the Adobe Flash Player 6.

pyamf.AMF3

Specifies that objects are serialized using AMF for ActionScript 3.0 that was introduced in the Adobe Flash Player 9.

pyamf.DEFAULT_ENCODING

Default encoding

pyamf.version

PyAMF version number.

>>> pyamf.__version__ is pyamf.version
True
>>> pyamf.version
(0, 6, 1, 'rc1')
>>> str(pyamf.version)
'0.6.1rc1'

See:pyamf.versions

1.1. Type Maps

pyamf.CLASS_CACHE

Class mapping support.

>>> pyamf.CLASS_CACHE
{<class 'pyamf.ASObject'>: <ClassAlias alias= class=<class 'pyamf.ASObject'> @ 0x100568a50>}

See:register_class(), unregister_class() and register_package()

pyamf.ALIAS_TYPES

Alias mapping support

>>> pyamf.ALIAS_TYPES
{<class 'pyamf.TypedObjectClassAlias'>: (<class 'pyamf.TypedObject'>,),
 <class 'pyamf.ErrorAlias'>: (<type 'exceptions.Exception'>,)}

See:get_class_alias(), register_alias_type() and unregister_alias_type()

pyamf.ERROR_CLASS_MAP

Maps error classes to string codes.

>>> pyamf.ERROR_CLASS_MAP
{'LookupError': <type 'exceptions.LookupError'>, 'NameError': <type 'exceptions.NameError'>,
 'TypeError': <type 'exceptions.TypeError'>, 'IndexError': <type 'exceptions.IndexError'>,
 'KeyError': <type 'exceptions.KeyError'>}

See:add_error_class() and remove_error_class()

pyamf.TYPE_MAP

Custom type map.

>>> pyamf.TYPE_MAP
{<type 'array.array'>: <function to_list at 0x101345ed8>,
 <type 'collections.deque'>: <function to_list at 0x101345ed8>,
 <type 'collections.defaultdict'>: <function to_dict at 0x101349b18>}

See:get_type(), add_type() and remove_type()

pyamf.CLASS_LOADERS

Class loaders.

>>> pyamf.CLASS_LOADERS
[<function flex_loader at 0x100569e60>, <function blaze_loader at 0x100569de8>]

See:register_class_loader() and unregister_class_loader()

pyamf.ENCODING_TYPES

Supported AMF encoding types.

>>> pyamf.ENCODING_TYPES
(0, 3)

See:AMF0, AMF3, and DEFAULT_ENCODING

1.2. Exception Types

exception pyamf.BaseError

Base AMF Error.

All AMF related errors should be subclassed from this class.

exception pyamf.DecodeError

Raised if there is an error in decoding an AMF data stream.

exception pyamf.EOStream

Raised if the data stream has come to a natural end.

exception pyamf.ReferenceError

Raised if an AMF data stream refers to a non-existent object or string reference.

exception pyamf.EncodeError

Raised if the element could not be encoded to the stream.

@bug: See U{Docuverse blog (external) <http://www.docuverse.com/blog/donpark/2007/05/14/flash-9-amf3-bug>} for more info about the empty key string array bug.

exception pyamf.ClassAliasError

Generic error for anything class alias related.

exception pyamf.UnknownClassAlias

Raised if the AMF stream specifies an Actionscript class that does not have a Python class alias.

@see: L{register_class}

1.3. Other Types

pyamf.Undefined

class pyamf.ClassAlias(klass, alias=None, **kwargs)

Class alias. Provides class/instance meta data to the En/Decoder to allow fine grain control and some performance increases.

@ivar bases: A list of (class, alias) for all bases of this alias.