API docs update.

Author: thijstriemstra

pyamf/__init__.py

@@ -37,13 +37,16 @@
 #: L{ClassAlias} object.
 #: @see: L{register_class}, L{unregister_class}, and L{register_package}
 CLASS_CACHE = {}
+
 #: Class loaders. An iterable of callables that are handed a string alias and
 #: return a class object or C{None} it not handled.
 #: @see: L{register_class_loader} and L{unregister_class_loader}
 CLASS_LOADERS = set()
+
 #: Custom type map.
 #: @see: L{get_type}, L{add_type}, and L{remove_type}
 TYPE_MAP = {}
+
 #: Maps error classes to string codes.
 #: @see: L{add_error_class} and L{remove_error_class}
 ERROR_CLASS_MAP = {
@@ -61,9 +64,11 @@
 #: Specifies that objects are serialized using AMF for ActionScript 1.0
 #: and 2.0 that were introduced in the Adobe Flash Player 6.
 AMF0 = 0
+
 #: Specifies that objects are serialized using AMF for ActionScript 3.0
 #: that was introduced in the Adobe Flash Player 9.
 AMF3 = 3
+
 #: Supported AMF encoding types.
 #: @see: L{AMF0}, L{AMF3}, and L{DEFAULT_ENCODING}
 ENCODING_TYPES = (AMF0, AMF3)
@@ -159,11 +164,14 @@ class TypedObject(dict):
     registered class to apply it to.
 
     This object can only be used for standard streams - i.e. not externalized
-    data. If encountered, a L{DecodeError} will be raised.
+    data. If encountered, and C{strict} mode is C{False}, a L{DecodeError}
+    or L{EncodeError} will be raised.
 
     @ivar alias: The alias of the typed object.
     @type alias: C{string}
     @since: 0.4
+    @raise DecodeError: Unable to decode an externalised stream.
+    @raise EncodeError: Unable to encode an externalised stream.
     """
 
     def __init__(self, alias):
@@ -229,10 +237,13 @@ def getEncodableAttributes(self, obj, **kwargs):
 def register_class(klass, alias=None):
     """
     Registers a class to be used in the data streaming. This is the equivalent
-    to the C{[RemoteClass(alias="foobar")]} AS3 metatag.
+    of the C{[RemoteClass(alias="foobar")]} metatag in Adobe Flex, and the
+    C{flash.net.registerClassAlias} method in Actionscript 3.0.
 
     @return: The registered L{ClassAlias} instance.
     @see: L{unregister_class}
+    @see: U{flash.net.registerClassAlias on Adobe Help (external)
+            <http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/flash/net/package.html#registerClassAlias%28%29>}
     """
     meta = util.get_class_meta(klass)
 
@@ -409,8 +420,9 @@ def decode(stream, *args, **kwargs):
     A generator function to decode a datastream.
 
     @param stream: AMF data to be decoded.
-    @type stream: byte data.
+    @type stream: byte data
     @kwarg encoding: AMF encoding type. One of L{ENCODING_TYPES}.
+    @type encoding: C{int}
     @return: A generator that will decode each element in the stream.
     """
     encoding = kwargs.pop('encoding', DEFAULT_ENCODING)
@@ -423,8 +435,9 @@ def encode(*args, **kwargs):
     """
     A helper function to encode an element.
 
-    @param args: The python data to be encoded.
+    @param args: The Python data to be encoded.
     @kwarg encoding: AMF encoding type. One of L{ENCODING_TYPES}.
+    @type encoding: C{int}
     @return: A L{util.BufferedByteStream} object that contains the data.
     """
     encoding = kwargs.pop('encoding', DEFAULT_ENCODING)
@@ -442,6 +455,8 @@ def get_decoder(encoding, *args, **kwargs):
     """
     Returns a L{codec.Decoder} capable of decoding AMF[C{encoding}] streams.
 
+    @param encoding: AMF encoding type. One of L{ENCODING_TYPES}.
+    @type encoding: C{int}
     @raise ValueError: Unknown C{encoding}.
     """
     def _get_decoder_class():
@@ -469,7 +484,9 @@ def get_encoder(encoding, *args, **kwargs):
     """
     Returns a L{codec.Encoder} capable of encoding AMF[C{encoding}] streams.
 
-    @raise ValueError: Unknown C{encoding}.
+    @kwarg encoding: AMF encoding type. One of L{ENCODING_TYPES}.
+    @type encoding: C{int}
+    @raise ValueError: Unknown C{encoding} type.
     """
     def _get_encoder_class():
         if encoding == AMF0:
@@ -497,7 +514,10 @@ def blaze_loader(alias):
     Loader for BlazeDS framework compatibility classes, specifically
     implementing C{ISmallMessage}.
 
+    @type alias: C{string}
     @see: U{BlazeDS<http://opensource.adobe.com/wiki/display/blazeds/BlazeDS>}
+    @see: U{ISmallMessage on Adobe Help (external)
+            <http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/messaging/messages/ISmallMessage.html>}
     @since: 0.5
     """
     if alias not in ['DSC', 'DSK']:
@@ -512,6 +532,7 @@ def flex_loader(alias):
     """
     Loader for L{Flex<pyamf.flex>} framework compatibility classes.
 
+    @type alias: C{string}
     @raise UnknownClassAlias: Trying to load an unknown Flex compatibility class.
     """
     if not alias.startswith('flex.'):
@@ -535,7 +556,8 @@ def 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 TypeError: Unable to add C{_type} as a custom type (expected a class
+                      or callable).
     @raise KeyError: Type already exists.
     @see: L{get_type} and L{remove_type}
     """
@@ -612,6 +634,9 @@ def add_error_class(klass, code):
     @param code: Exception code
     @type code: C{str}
     @see: L{remove_error_class}
+    @raise TypeError: C{klass} must be of class type.
+    @raise TypeError: Error classes must subclass the C{__builtin__.Exception} class.
+    @raise ValueError: C{code} is already registered to an error class.
     """
     if not isinstance(code, python.str_types):
         code = code.decode('utf-8')
@@ -643,7 +668,10 @@ def remove_error_class(klass):
        >>> pyamf.add_error_class(AuthenticationError, 'Auth.Failed')
        >>> pyamf.remove_error_class(AuthenticationError)
 
+    @type klass: C{str} or class
     @see: L{add_error_class}
+    @raise ValueError: Cannot find registered class.
+    @raise TypeError: C{klass} is invalid type.
     """
     if isinstance(klass, python.str_types):
         if klass not in ERROR_CLASS_MAP:
@@ -751,16 +779,18 @@ def register_package(module=None, package=None, separator='.', ignore=[],
     @type package: C{string} or C{None}
     @param separator: The separator used to append to C{package} to form the
         complete alias.
+    @type separator: C{string}
     @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: Whether only classes that originate from C{module} will be
         registered.
+    @type strict: C{boolean}
 
     @return: A dict of all the classes that were registered and their respective
         L{ClassAlias} counterparts.
     @since: 0.5
-    @raise TypeError: Cannot get a list of classes from C{module}
+    @raise TypeError: Cannot get a list of classes from C{module}.
     """
     if isinstance(module, python.str_types):
         if module == '':
@@ -843,7 +873,7 @@ def set_default_etree(etree):
     return xml.set_default_interface(etree)
 
 
-#: setup some some standard class registrations and class loaders.
+# setup some some standard class registrations and class loaders.
 register_class(ASObject)
 register_class_loader(flex_loader)
 register_class_loader(blaze_loader)

pyamf/amf3.py

@@ -86,7 +86,7 @@
 #: @see: U{OSFlash documentation (external)
 #: <http://osflash.org/documentation/amf3#x07_-_xml_legacy_flashxmlxmldocument_class>}
 TYPE_XML = '\x07'
-#: In AMF 3 an ActionScript Date is serialized simply as the number of
+#: In AMF 3 an ActionScript Date is serialized 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.
 TYPE_DATE = '\x08'
@@ -112,7 +112,9 @@
 #: Reference bit.
 REFERENCE_BIT = 0x01
 
-#: The maximum that can be represented by a signed 29 bit integer.
+#: The maximum value for an int that will avoid promotion to an
+#: ActionScript Number when sent via AMF 3 is represented by a
+#: signed 29 bit integer: 2^28 - 1.
 MAX_29B_INT = 0x0FFFFFFF
 
 #: The minimum that can be represented by a signed 29 bit integer.
@@ -151,8 +153,6 @@ class ObjectEncoding:
 class DataOutput(object):
     """
     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
@@ -327,8 +327,8 @@ class DataInput(object):
     """
     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.
+    This class is the I/O counterpart to the L{DataOutput} class, which writes
+    binary data.
 
     @see: U{IDataInput on Livedocs (external)
     <http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/flash/utils/IDataInput.html>}
@@ -670,7 +670,7 @@ def getClassByReference(self, ref):
 
     def getClass(self, klass):
         """
-        Return class reference.
+        Returns a class reference.
 
         @return: Class reference.
         """
@@ -681,6 +681,7 @@ def addClass(self, alias, klass):
         Creates a reference to C{class_def}.
 
         @param alias: C{ClassDefinition} instance.
+        @type alias: C{ClassDefinition}
         """
         ref = self.class_idx
 
@@ -999,6 +1000,9 @@ def _readDynamic(self, class_def, obj):
     def readObject(self):
         """
         Reads an object from the stream.
+
+        @raise ReferenceError: Unknown reference found.
+        @raise DecodeError: Unknown object encoding detected.
         """
         ref = self.readInteger(False)
 
@@ -1242,8 +1246,13 @@ def writeDate(self, n):
         """
         Writes a C{datetime} instance to the stream.
 
+        Does not support C{datetime.time} instances because AMF3 has
+        no way to encode time objects, so please use C{datetime.datetime}
+        instead.
+
         @type n: L{datetime}
         @param n: The C{Date} data to be encoded to the AMF3 data stream.
+        @raise EncodeError: A datetime.time instance was found
         """
         if isinstance(n, datetime.time):
             raise pyamf.EncodeError('A datetime.time instance was found but '
@@ -1521,7 +1530,7 @@ def encode_int(n):
     @param n: The integer to be encoded
     @return: The encoded string
     @rtype: C{str}
-    @raise OverflowError: Out of range.
+    @raise OverflowError: C{c} is out of range.
     """
     global ENCODED_INT_CACHE
 

pyamf/flex/__init__.py

@@ -21,7 +21,7 @@ class ArrayCollection(list):
 
     The C{ArrayCollection} class is a wrapper class that exposes an Array
     as a collection that can be accessed and manipulated using the
-    methods and properties of the `ICollectionView` or `IList`
+    methods and properties of the C{ICollectionView} or C{IList}
     interfaces in the Flex framework.
 
     @see: U{ArrayCollection on Livedocs <http://

pyamf/flex/messaging.py

@@ -51,7 +51,7 @@ class AbstractMessage(object):
     @type clientId: C{str}
     @ivar destination: Message destination.
     @type destination: C{str}
-    @ivar headers: Message headers. Core header names start with DS.
+    @ivar headers: Message headers. Core header names start with C{DS}.
     @type headers: C{dict}
     @ivar messageId: Unique Message ID.
     @type messageId: C{str}
@@ -202,10 +202,12 @@ def __writeamf__(self, output):
 
     def getSmallMessage(self):
         """
-        Return a ISmallMessage representation of this object. If one is not
-        available, L{NotImplementedError} will be raised.
+        Return a C{ISmallMessage} representation of this object. If one is not
+        available, C{NotImplementedError} will be raised.
 
         @since: 0.5
+        @see: U{ISmallMessage on Adobe Help (external)<http://
+            help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/messaging/messages/ISmallMessage.html>}
         """
         raise NotImplementedError
 
@@ -214,7 +216,7 @@ class AsyncMessage(AbstractMessage):
     """
     I am the base class for all asynchronous Flex messages.
 
-    @see: U{AsyncMessage on Livedocs<http://
+    @see: U{AsyncMessage on Adobe Help<http://
         help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/messaging/messages/AsyncMessage.html>}
 
     @ivar correlationId: Correlation id of the message.
@@ -263,7 +265,7 @@ def __writeamf__(self, output):
 
     def getSmallMessage(self):
         """
-        Return a ISmallMessage representation of this async message.
+        Return a C{ISmallMessage} representation of this async message.
 
         @since: 0.5
         """
@@ -277,7 +279,7 @@ class AcknowledgeMessage(AsyncMessage):
     Every message sent within the messaging system must receive an
     acknowledgement.
 
-    @see: U{AcknowledgeMessage on Livedocs<http://
+    @see: U{AcknowledgeMessage on Adobe Help (external)<http://
         help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/messaging/messages/AcknowledgeMessage.html>}
     """
 
@@ -302,7 +304,7 @@ def __writeamf__(self, output):
 
     def getSmallMessage(self):
         """
-        Return a ISmallMessage representation of this acknowledge message.
+        Return a C{ISmallMessage} representation of this acknowledge message.
 
         @since: 0.5
         """
@@ -314,7 +316,7 @@ class CommandMessage(AsyncMessage):
     Provides a mechanism for sending commands related to publish/subscribe
     messaging, ping, and cluster operations.
 
-    @see: U{CommandMessage on Livedocs<http://
+    @see: U{CommandMessage on Adobe Help (external)<http://
         help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/messaging/messages/CommandMessage.html>}
 
     @ivar operation: The command
@@ -396,7 +398,7 @@ def __writeamf__(self, output):
 
     def getSmallMessage(self):
         """
-        Return a ISmallMessage representation of this command message.
+        Return a C{ISmallMessage} representation of this command message.
 
         @since: 0.5
         """
@@ -409,7 +411,7 @@ class ErrorMessage(AcknowledgeMessage):
 
     This class is used to report errors within the messaging system.
 
-    @see: U{ErrorMessage on Livedocs<http://
+    @see: U{ErrorMessage on Adobe Help (external)<http://
         help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/messaging/messages/ErrorMessage.html>}
     """
 
@@ -443,7 +445,7 @@ def __init__(self, *args, **kwargs):
 
     def getSmallMessage(self):
         """
-        Return a ISmallMessage representation of this error message.
+        Return a C{ISmallMessage} representation of this error message.
 
         @since: 0.5
         """
@@ -454,7 +456,7 @@ class RemotingMessage(AbstractMessage):
     """
     I am used to send RPC requests to a remote endpoint.
 
-    @see: U{RemotingMessage on Livedocs<http://
+    @see: U{RemotingMessage on Adobe Help (external)<http://
         help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/messaging/messages/RemotingMessage.html>}
     """