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 Flash Player.

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

Contact: dev@pyamf.org

See Also: http://pyamf.org

Since: October 2007

Version: 0.4.1

Status: Production/Stable

Submodules | [hide private]

- pyamf.adapters: The adapter package provides additional functionality for other Python packages.
  - 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._google_appengine_ext_db: Google App Engine adapter module.
  - pyamf.adapters._sets: Adapter for the stdlib `sets` module.
  - pyamf.adapters._sqlalchemy: 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.logging: Logging utilities.
- 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]

| ClientTypes Typecodes used to identify AMF clients and servers.
| UndefinedType
| BaseError Base AMF Error.
| 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.
| ReferenceError Raised if an AMF data stream refers to a non-existent object or string reference.
| EncodeError Raised if the element could not be encoded to the stream.
| UnknownClassAlias Raised if the AMF stream specifies a class that does not have an alias.
| BaseContext I hold the AMF context for en/decoding streams.
| ASObject This class represents a Flash Actionscript Object (typed or untyped).
| MixedArray Used to be able to specify the `mixedarray` type.
| ClassMetaData I hold a list of tags relating to the class.
| ClassAlias Class alias.
| TypedObject This class is used when a strongly typed object is decoded but there is no registered class to apply it to.
| TypedObjectClassAlias
| BaseDecoder Base AMF decoder.
| CustomTypeFunc Custom type mappings.
| BaseEncoder Base AMF encoder.

Functions | [hide private]

register_class(klass, alias=None, attrs=None, attr_func=None, metadata=`[``]`) Registers a class to be used in the data streaming. | source code

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

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

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

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

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

ClassAlias

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

`bool`

has_alias(obj) Returns: Alias is available. | source code

decode(stream, encoding=0, context=None, strict=False) A generator function to decode a datastream. | source code

`StringIO`

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

get_decoder(encoding, data=None, context=None, strict=False) | source code

amf0.Decoder or amf3.Decoder

_get_decoder_class(encoding) Get compatible decoder. | source code

get_encoder(encoding, data=None, context=None, strict=False) Returns a subclassed instance of pyamf.BaseEncoder, based on `encoding` | source code

amf0.Encoder or amf3.Encoder

_get_encoder_class(encoding) Get compatible encoder. | source code

get_context(encoding) | source code

amf0.Context or amf3.Context

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

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

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

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

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

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

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

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

Variables | [hide private]

| __version__ = ``(`0`,` 4`,` 1`)`` PyAMF version number.
| CLASS_CACHE = ``{``'``RecordSet``'``:` <ClassAlias alias=RecordSet klass=`...`` Class mapping support.
| CLASS_LOADERS = `[]` Class loaders.
| TYPE_MAP = `{}` Custom type map.
| ERROR_CLASS_MAP = ``{``'``Server.Call.Failed``'``:` <class 'pyamf.remotin`...`` Maps error classes to string codes.
| 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.
| AMF3 = `3` Specifies that objects are serialized using AMF for ActionScript 3.0.
| ENCODING_TYPES = ``(`0`,` 3`)`` Supported AMF encoding types.
| CLIENT_TYPES = ``[`1`,` 0`,` 3`]`` List of AMF client typecodes.
| Undefined = `pyamf.Undefined` Represents the `undefined` value in a Flash client.

Imports: types, util, register_adapters, adapters

Function Details | [hide private]

### register_class(klass, alias=None, attrs=None, attr_func=None, metadata=`[``]`)

source code

Registers a class to be used in the data streaming.

Parameters:
  - `alias` (`str`) - The alias of klass, i.e. `org.example.Person`.
  - `attrs` (`list` or `None`) - A list of attributes that will be encoded for the class.
  - `attr_func` ()
  - `metadata` ()
Returns:
  The registered ClassAlias.
Raises:
  - `TypeError` - PyAMF doesn't support required init arguments.
  - `TypeError` - The `klass` is not callable.
  - `ValueError` - The `klass` or `alias` is already registered.

### 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.

### 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.

### 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.

### 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.

### 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.
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.

### get_class_alias(klass)

source code

Finds the alias registered to the class.

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

### has_alias(obj)

source code

Returns: `bool`
  Alias is available.

### decode(stream, encoding=0, context=None, strict=False)

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` (`mixed`) - Python data.
  - `encoding` (`int`) - AMF encoding type.
  - `context` (amf0.Context or amf3.Context) - Context.
Returns: `StringIO`
  File-like object.

### _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.

### _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.

### flex_loader(alias)

source code

Loader for Flex framework compatibility classes.

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

### 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.

### get_type(type_)

source code

Gets the declaration for the corresponding custom type.

Raises:
  - `KeyError` - Unknown type.

### remove_type(type_)

source code

Removes the custom type declaration.

Returns:
  Custom type declaration.

### 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.

### 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`.

### 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

Variables Details | [hide private]

### CLASS_CACHE

Class mapping support.

Value:

      {'RecordSet': <ClassAlias alias=RecordSet klass=<class 'pyamf.amf0.Rec
      ordSet'> @ 30486960>,
       'flex.data.messages.DataErrorMessage': <ClassAlias alias=flex.data.me
      ssages.DataErrorMessage klass=<class 'pyamf.flex.data.DataErrorMessage
      '> @ 36372848>,
       'flex.data.messages.DataMessage': <ClassAlias alias=flex.data.message
      s.DataMessage klass=<class 'pyamf.flex.data.DataMessage'> @ 36372528>,
       'flex.data.messages.PagedMessage': <ClassAlias alias=flex.data.messag
      ...

### ERROR_CLASS_MAP

Maps error classes to string codes.

Value:

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

### ALIAS_TYPES

Alias mapping support

Value:

      {<class 'pyamf.TypedObjectClassAlias'>: (<class 'pyamf.TypedObject'>),
       <class 'pyamf.adapters._sqlalchemy.SaMappedClassAlias'>: (<function i
      s_class_sa_mapped at 0x1bc64b0>)}