Expandos - semi-persistent maps
=================================

An expando is actually a semi-persistent data structure that allows for some
interesting operations.  They can be used for testing, throw-away classes, or 
for those situations where you want an object that's just like another object
but with *one* tiny little difference.

Basic Expandos
~~~~~~~~~~~~~~~

First of all, expandos allow for arbitrary attributes
to be defined when they are instantiated::

    >>> from pysistence import Expando
    >>> a = Expando(foo='bar')
    >>> a.foo
    'bar'

Expandos also allow you to make copies of them with certain changes.  For
example, you can add on attributes::

    >>> from pysistence import Expando
    >>> a = Expando(foo='bar')
    >>> a
    {'foo': 'bar'}
    >>> b = a.using(asdf='jkl;')
    >>> b
    {'asdf': 'jkl;', 'foo': 'bar'}
    >>> a is b
    False

You can also remove attributes::

    >>> from pysistence import Expando
    >>> a = Expando(foo='bar')
    >>> a
    {'foo': 'bar'}
    >>> b = a.without('foo')
    >>> b
    {}

Expando classes
~~~~~~~~~~~~~~~~

You may also make a class that has all of the properties of an Expando, but
derives from another class::

    >>> from pysistence import make_expando_class
    >>> class Foo(object):
    ...     def bar(self):
    ...             print 'bar'
    ... 
    >>> ExpandoFoo = make_expando_class(Foo, 'ExpandoFoo')
    >>> f = ExpandoFoo(a = 'b')
    >>> f.a
    'b'
    >>> f.bar()
    bar

In fact, the class Expando itself is defined this way::

    Expando = make_expando_class(object, 'Expando')

You may also define class attributes in the mkExpndoClass function::

    >>> from pysistence import make_expando_class
    >>> SomeExpando = make_expando_class(object, 'SomeExpando', a='b')
    >>> SomeExpando.a
    'b'

.. module:: pysistence.expando
    :synopsis: semi-persistent maps

Reference
~~~~~~~~~~~~

.. function:: make_expando_class(base, name, **kwargs)

    Make an Expando class that inherits from *base*.  The class's __name__ attribute
    will be set by name.  Also, the class will have class attributes specified by
    *kwargs*.

    The returned class will have all of the functions of the Expando class (listed
    below).

.. class:: Expando(**kwargs)
   
    Make a new Expando class.  Expando classes will accept arbitrary keyword arguments
    to define instance attributes.

    .. method:: to_dict()

        Get a copy of the Expando object's __dict__ object.

    .. method:: to_public_dict()

        Get a copy of the Expando object's __dict__ object without any names that
        begin with an underscore.

    .. method:: without(*args)

        Get a copy of the Expando without the attributes named by *args* (which is a
        set of strings).

    .. method:: using(**kwargs)

        Get a copy of the Expando with instance attributes defined by kwargs.