**************************
  What's New in PyAMF 0.5
**************************

:Release: 0.5
:Date: |today|

PyAMF 0.5 is a cleanup of the internals of 0.4 and it provides some performance
optimizations. In accomplishing this, a number of features were added:

.. contents::


Highlighted Features
====================

* A new way to handle attribute en/decoding. New features include excluding
  attributes, read-only attributes, and proxied attributes. If you use
  external classes, this one is also for you.  Check the
  :doc:`Attribute Control <../architecture/attributecontrol>` document for
  more details.
* The lazy loading module (``pyamf.util.imports``) that powers the adapter
  modules has been completely revamped. There were too many edge cases that
  would cause problems in the import mechanism. We now supply a module
  finder/loader in ``sys.meta_path`` so we can intercept the import calls.
  This has completely cleared up the problems we were seeing and it has the
  added benefit of halving the time it took to run the 650+ unit tests in
  the suite!
* The cPyAMF extension has been completely revamped and no longer uses
  ``cStringIO`` to handle the byte packing. The extension has also been
  extended to cover more of the library. This has given a nice speed-up but
  we are by no means finished.
* Support for non-UTC timezones has been added. If you supply ``timezone_offset``
  to the ``pyamf.remoting.gateway.*.*Gateway`` classes then any datetimes will
  be offset against that figure (in seconds). This is only useful for legacy
  systems so you don't need to change anything if you are already using UTC
  (in fact using UTC is the recommended practice).
* Support has been provided for decoding and encoding ISmallMessage objects.
  This means better integration with ``BlazeDS`` and sets the foundations for
  better Flex Messaging support.
* A new way to bulk register classes has been introduced - ``register_package``
  You can register a module:

  .. code-block:: python
  
     import pyamf

     from myproj.myapp import models

     pyamf.register_package(models, 'foo.bar')


Backward Incompatible API Changes
=================================

* The ``pyamf.logging`` module has been removed because it didn't do very much.
* A number of utility functions that weren't being used, or were implemented
  in the Python standard library, have been removed. These include:

  * ``pyamf.util.getmro``
  * ``pyamf.util.make_classic_instance``
  * ``pyamf.util.IndexedCollection.remove``

* The dependancy on `fpconst <http://pypi.python.org/pypi/fpconst>`_ has been
  removed. This means that PyAMF will make no attempt to correct what the Python
  interpreter spits out for exceptional floats (see our `blog post
  <http://blog.pyamf.org/archives/when-is-nan-not-a-number-with-python-24>`_
  about the issue).
* Most of the arguments for ``pyamf.register_class`` were removed, due to the
  new attribute control (see above).


Gateway Updates
===============

* The ``logger`` attribute is now set to ``None`` by default. Supply a logger
  instance to reactivate the old functionality.
* If ``debug`` is ``False`` then any stacktraces will not be sent to the client.


Integration
===========

Python 2.6
----------

Besides greater stability for the Windows platform, more types from
the Python 2.6 standard library are now supported, including:

+--------------------------------+-------------------+--------------+
| Module                         | Encode      	     | Decode       |
+================================+===================+==============+
| ``collections.deque``          | ``list``    	     | ``list``     |
+--------------------------------+-------------------+--------------+
| ``collections.defaultdict``    | untyped object    | ``dict``     |
+--------------------------------+-------------------+--------------+
| ``collections.namedtuple``     | ``list``          | ``list``     |
+--------------------------------+-------------------+--------------+
| ``array.array``                | ``list``          | ``list``     |
+--------------------------------+-------------------+--------------+


Flash Player
------------

Python exceptions are now mapped to Actionscript exceptions (where possible),
including the ``name`` and ``message`` attributes. You can now map error
classes:

.. code-block:: python

   import pyamf

   pyamf.register_class(ValueError, 'com.acme.app.errors.ValueError')


Django
------

* Django models can now have dynamic properties assigned to them and they will
  be encoded correctly.

* Support for model inheritance:

.. code-block:: python
   :linenos:

   from django.db import models

   class CommonInfo(models.Model):
       name = models.CharField(max_length=100) 
       age = models.PositiveIntegerField()

       class Meta:
           abstract = True

   class Student(CommonInfo):
       home_group = models.CharField(max_length=5)

* Support for ``FileField``/``ImageField`` (thanks
  `@jhooks <http://twitter.com/jhooks>`_!).

* ``parent`` -> ``child`` relationships will be referenced correctly, such that
  ``parent.child.parent is parent``. In this situation, PyAMF 0.4 would encode
  3 separate objects, but PyAMF 0.5 will correctly encode 2 (``parent`` being
  encoded as a reference).


Google App Engine
-----------------

* Greater support for the standard property types has been included
  (specifically ``db.FloatProperty``).
* Support for ``db.polymodel.PolyModel`` has been included.

.. code-block:: python
   :linenos:

   from google.appengine.ext.db import polymodel

   class Poly(polymodel.PolyModel):
       s = db.StringProperty()

   class DeepPoly(Poly):
       d = db.IntegerProperty()

