Package pyamf

[hide private]
[frames] | no frames]

# Package pyamf

source code

PyAMF provides Action Message Format (AMF) support for Python that is compatible with the Adobe Flash Player.

Copyright: Copyright (c) 2007-2009 The PyAMF Project. All Rights Reserved.

Contact: users@pyamf.org

See Also: http://pyamf.org

Since: October 2007

Version: 0.5.1

Status: Production/Stable

Submodules | [hide private]

- pyamf.adapters: The adapter package provides additional functionality for other Python packages.
  - pyamf.adapters._array: `array` adapter module.
  - pyamf.adapters._collections: collections adapter module.
  - pyamf.adapters._decimal: Adapter for the `decimal` module.
  - pyamf.adapters._django_db_models_base: `django.db.models` adapter module.
  - pyamf.adapters._django_db_models_fields: `django.db.models.fields` adapter module.
  - pyamf.adapters._django_db_models_query: Django query adapter module.
  - pyamf.adapters._django_utils_translation: `django.utils.translation` adapter module.
  - pyamf.adapters._google_appengine_ext_db: Google App Engine adapter module.
  - pyamf.adapters._sets: Adapter for the stdlib `sets` module.
  - pyamf.adapters._sqlalchemy_orm: SQLAlchemy adapter module.
  - pyamf.adapters._sqlalchemy_orm_collections: SQLAlchemy adapter module.
  - pyamf.adapters.util: Useful helpers for adapters.
- pyamf.amf0: AMF0 implementation.
- pyamf.amf3: AMF3 implementation.
- pyamf.flex: Compatibility classes/functions for Flex.
  - pyamf.flex.data: Flex Data Management Service implementation.
  - pyamf.flex.messaging: Flex Messaging implementation.
- pyamf.remoting: AMF Remoting support.
  - pyamf.remoting.amf0: AMF0 Remoting support.
  - pyamf.remoting.amf3: AMF3 RemoteObject support.
  - pyamf.remoting.client: Remoting client implementation.
  - pyamf.remoting.gateway: Remoting server implementations.
    - pyamf.remoting.gateway.django: Gateway for the Django framework.
    - pyamf.remoting.gateway.google: Gateway for Google App Engine.
    - pyamf.remoting.gateway.twisted: Twisted server implementation.
    - pyamf.remoting.gateway.wsgi: WSGI server implementation.
- pyamf.sol: Local Shared Object implementation.
- pyamf.util: AMF Utilities.
  - pyamf.util.imports: Tools for doing dynamic imports.

Classes | [hide private]

| ASObject This class represents a Flash Actionscript Object (typed or untyped).
| BaseContext I hold the AMF context for en/decoding streams.
| BaseDecoder Base AMF decoder.
| BaseEncoder Base AMF encoder.
| BaseError Base AMF Error.
| ClassAlias Class alias.
| ClassAliasError Generic error for anything class alias related.
| ClientTypes Typecodes used to identify AMF clients and servers.
| CustomTypeFunc Custom type mappings.
| DecodeError Raised if there is an error in decoding an AMF data stream.
| EOStream Raised if the data stream has come to a natural end.
| EncodeError Raised if the element could not be encoded to the stream.
| ErrorAlias Adapts Python exception objects to Adobe Flash Player error objects.
| MixedArray Used to be able to specify the `mixedarray` type.
| ReferenceError Raised if an AMF data stream refers to a non-existent object or string reference.
| TypedObject This class is used when a strongly typed object is decoded but there is no registered class to apply it to.
| TypedObjectClassAlias
| UndefinedType
| UnknownClassAlias Raised if the AMF stream specifies an Actionscript class that does not have a Python class alias.

Functions | [hide private]

amf0.Context or amf3.Context

_get_context_class(encoding) Gets a compatible context class. | source code

amf0.Decoder or amf3.Decoder

_get_decoder_class(encoding) Get compatible decoder. | source code

amf0.Encoder or amf3.Encoder

_get_encoder_class(encoding) Get compatible encoder. | source code

add_error_class(klass, code) Maps an exception class to a string code. | source code

add_type(type_, func=None) Adds a custom type to TYPE_MAP. | source code

blaze_loader(alias) Loader for BlazeDS framework compatibility classes, specifically implementing `ISmallMessage`. | source code

decode(*args, **kwargs) A generator function to decode a datastream. | source code

`StringIO`

encode(*args, **kwargs) A helper function to encode an element. | source code

flex_loader(alias) Loader for Flex framework compatibility classes. | source code

ClassAlias

get_class_alias(klass) Finds the alias registered to the class. | source code

get_context(encoding, **kwargs) | source code

get_decoder(encoding, *args, **kwargs) Returns a subclassed instance of pyamf.BaseDecoder, based on `encoding` | source code

get_encoder(encoding, *args, **kwargs) Returns a subclassed instance of pyamf.BaseEncoder, based on `encoding` | source code

get_module(mod_name) Load a module based on `mod_name`. | source code

get_type(type_) Gets the declaration for the corresponding custom type. | source code

load_class(alias) Finds the class registered to the alias. | source code

register_alias_type(klass, *args) This function allows you to map subclasses of ClassAlias to classes listed in `args`. | source code

register_class(klass, alias=None) Registers a class to be used in the data streaming. | source code

register_class_loader(loader) Registers a loader that is called to provide the `Class` for a specific alias. | source code

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. | source code

remove_error_class(klass) Removes a class from `ERROR_CLASS_MAP`. | source code

remove_type(type_) Removes the custom type declaration. | source code

unregister_class(alias) Deletes a class from the cache. | source code

unregister_class_loader(loader) Unregisters a class loader. | source code

Variables | [hide private]

| ALIAS_TYPES = ``{`<class 'pyamf.TypedObjectClassAlias'>`:` `(`<class `...`` Alias mapping support
| AMF0 = `0` Specifies that objects are serialized using AMF for ActionScript 1.0 and 2.0 that were introduced in the Adobe Flash Player 6.
| AMF3 = `3` Specifies that objects are serialized using AMF for ActionScript 3.0 that was introduced in the Adobe Flash Player 9.
| CLASS_CACHE = ``{``'``DSA``'``:` <ClassAlias alias=DSA class=<class 'pyam`...`` Class mapping support.
| CLASS_LOADERS = `[]` Class loaders.
| CLIENT_TYPES = ``[`1`,` 0`,` 3`]`` List of AMF client typecodes.
| DEFAULT_ENCODING = `0` Default encoding
| ENCODING_TYPES = ``(`0`,` 3`)`` Supported AMF encoding types.
| ERROR_CLASS_MAP = ``{``'``Server.Call.Failed``'``:` <class 'pyamf.remotin`...`` Maps error classes to string codes.
| TYPE_MAP = `{}` Custom type map.
| Undefined = `pyamf.Undefined` Represents the `undefined` value in a Adobe Flash Player client.
| __version__ = ``(`0`,` 5`,` 1`)`` PyAMF version number.

Imports: util, adapters, inspect, register_adapters, set, types

Function Details | [hide private]

### _get_context_class(encoding)

source code

Gets a compatible context class.

Parameters:
  - `encoding` (`int`) - AMF encoding version.
Returns: amf0.Context or amf3.Context
  AMF0 or AMF3 context class.
Raises:
  - `ValueError` - AMF encoding version is unknown.

### _get_decoder_class(encoding)

source code

Get compatible decoder.

Parameters:
  - `encoding` (`int`) - AMF encoding version.
Returns: amf0.Decoder or amf3.Decoder
  AMF0 or AMF3 decoder.
Raises:
  - `ValueError` - AMF encoding version is unknown.

### _get_encoder_class(encoding)

source code

Get compatible encoder.

Parameters:
  - `encoding` (`int`) - AMF encoding version.
Returns: amf0.Encoder or amf3.Encoder
  AMF0 or AMF3 encoder.
Raises:
  - `ValueError` - AMF encoding version is unknown.

### add_error_class(klass, code)

source code

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

       class AuthenticationError(Exception):
           pass

An example: `add_error_class(AuthenticationError, 'Auth.Failed')`

Parameters:
  - `code` (`str`)
Raises:
  - `TypeError` - `klass` must be a `class` type.
  - `TypeError` - Error classes must subclass the `__builtin__.Exception` class.
  - `ValueError` - Code is already registered.

### add_type(type_, func=None)

source code

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

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

### blaze_loader(alias)

source code

Loader for BlazeDS framework compatibility classes, specifically implementing `ISmallMessage`.

See Also: BlazeDS (external)

Since: 0.5

### decode(*args, **kwargs)

source code

A generator function to decode a datastream.

Parameters:
  - `stream` (BufferedByteStream) - AMF data.
  - `encoding` (`int`) - AMF encoding type.
  - `context` (AMF0 Context or AMF3 Context) - Context.
Returns:
  Each element in the stream.

### encode(*args, **kwargs)

source code

A helper function to encode an element.

Parameters:
  - `element` - Python data.
  - `encoding` (`int`) - AMF encoding type.
  - `context` (amf0.Context or amf3.Context) - Context.
  - `args` (`mixed`)
Returns: `StringIO`
  File-like object.

### flex_loader(alias)

source code

Loader for Flex framework compatibility classes.

Raises:
  - `UnknownClassAlias` - Trying to load unknown Flex compatibility class.

### get_class_alias(klass)

source code

Finds the alias registered to the class.

Parameters:
  - `klass` (`object` or class object.)
Returns: ClassAlias
  The class alias linked to `klass`.
Raises:
  - `UnknownClassAlias` - Class not found.

### get_module(mod_name)

source code

Load a module based on `mod_name`.

Parameters:
  - `mod_name` (`str`) - The module name.
Returns:
  Module.
Raises:
  - `ImportError` - Unable to import an empty module.

### get_type(type_)

source code

Gets the declaration for the corresponding custom type.

Raises:
  - `KeyError` - Unknown type.

### load_class(alias)

source code

Finds the class registered to the alias.

The search is done in order:

1. Checks if the class name has been registered via register_class or register_package.
2. Checks all functions registered via register_class_loader.
3. Attempts to load the class via standard module loading techniques.

Parameters:
  - `alias` (`str`) - The class name.
Returns:
  Class registered to the alias.
Raises:
  - `UnknownClassAlias` - The `alias` was not found.
  - `TypeError` - Expecting class type or ClassAlias from loader.

### register_alias_type(klass, *args)

source code

This function allows you to map subclasses of ClassAlias to classes listed in `args`.

When an object is read/written from/to the AMF stream, a paired ClassAlias instance is created (or reused), based on the Python class of that object. 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.

Raises:
  - `RuntimeError` - Type is already registered.
  - `TypeError` - `klass` must be a class.
  - `ValueError` - New aliases must subclass pyamf.ClassAlias.
  - `ValueError` - At least one type must be supplied.

See Also: pyamf.adapters._google_appengine_ext_db.DataStoreClassAlias for a good example.

Since: 0.4

### register_class(klass, alias=None)

source code

Registers a class to be used in the data streaming.

Returns:
  The registered ClassAlias.

### register_class_loader(loader)

source code

Registers a loader that is called to provide the `Class` for a specific alias.

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

Parameters:
  - `loader` (`callable`)
Raises:
  - `TypeError` - The `loader` is not callable.
  - `ValueError` - The `loader` is already registered.

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

source code

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 `module` based on `package`.

e.g. `mymodule.py`:

       class User(object):
           pass

       class Permission(object):
           pass

    >>> 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
    ...
    >>> 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')

Parameters:
  - `module` (`module` or `dict`) - The Python module that will contain all the classes to auto alias.
  - `package` (`str` or `unicode` or `None`) - The base package name. e.g. 'com.example.app'. If this is `None` then the value is inferred from module.__name__.
  - `separator` (`str`) - The separator used to append to `package` to form the complete alias.
  - `ignore` (`iterable`) - To give fine grain control over what gets aliased and what doesn't, supply a list of classes that you do not want to be aliased.
  - `strict` (`bool`) - If this value is `True` then only classes that originate from `module` will be registered, all others will be left in peace.
Returns:
  A collection of all the classes that were registered and their respective ClassAlias objects.

Since: 0.5

### remove_error_class(klass)

source code

Removes a class from `ERROR_CLASS_MAP`.

Raises:
  - `ValueError` - Code is not registered.
  - `ValueError` - Class is not registered.
  - `TypeError` - Invalid type, expected `class` or `string`.

### remove_type(type_)

source code

Removes the custom type declaration.

Returns:
  Custom type declaration.

### unregister_class(alias)

source code

Deletes a class from the cache.

If `alias` is a class, the matching alias is found.

Parameters:
  - `alias` (`class` or `str`) - Alias for class to delete.
Raises:
  - `UnknownClassAlias` - Unknown alias.

### unregister_class_loader(loader)

source code

Unregisters a class loader.

Parameters:
  - `loader` (`callable`) - The object to be unregistered
Raises:
  - `LookupError` - The `loader` was not registered.

Variables Details | [hide private]

### ALIAS_TYPES

Alias mapping support

Value:

      {<class 'pyamf.TypedObjectClassAlias'>: (<class 'pyamf.TypedObject'>),
       <class 'pyamf.ErrorAlias'>: (<type 'exceptions.Exception'>),
       <class 'pyamf.adapters._sqlalchemy_orm.SaMappedClassAlias'>: (<functi
      on is_class_sa_mapped at 0x1d51070>)}

### CLASS_CACHE

Class mapping support.

Value:

      {'DSA': <ClassAlias alias=DSA class=<class 'pyamf.flex.messaging.Async
      MessageExt'> @ 0x1dab870>,
       'DSC': <ClassAlias alias=DSC class=<class 'pyamf.flex.messaging.Comma
      ndMessageExt'> @ 0x1dab890>,
       'DSK': <ClassAlias alias=DSK class=<class 'pyamf.flex.messaging.Ackno
      wledgeMessageExt'> @ 0x1dab8b0>,
       'RecordSet': <ClassAlias alias=RecordSet class=<class 'pyamf.amf0.Rec
      ordSet'> @ 0x191e130>,
      ...

### ERROR_CLASS_MAP

Maps error classes to string codes.

Value:

      {'Server.Call.Failed': <class 'pyamf.remoting.RemotingCallFailed'>}