Metadata-Version: 1.0
Name: flatty
Version: 0.1.1
Summary: flatty - marshaller/unmarshaller for light-schema python objects
Home-page: http://packages.python.org/flatty
Author: Christian Haintz
Author-email: christian.haintz@orangelabs.at
License: BSD
Description: ================================================================
        Flatty - marshaller/unmarshaller for light-schema python objects
        ================================================================
        
        Introduction
        ------------
        
        ``Flatty`` is a microframework for easily creating flexible python class schemas.
        Normaly you will use flatty on top of marshallers which uses python dict as
        input/output format. Think of couchdb, json, xml, yaml, etc. With flatty you can
        easily store an object-oriented class schema in these systems by just storing
        the data (no meta-data is stored).
        
        **Key Features:**
        
        - easy to use
        - only plain data is marshaled, no class meta-data
        - extensible, add custom converters for your own needs and types
        - can be easily extended to support unique features of a marshal framework
        - light-weight (flatty has currently less than 200 lines of code)
        - OpenSource BSD-licensed
        
        
        Getting started with Flatty
        ---------------------------
        
        Let's go:
        
        >>> import flatty
        
        This imports the flatty module. Now we can define a schema using python
        classes:
        
        >>> class Bar(flatty.Schema):
        ...	 a_num = int
        ...	 a_str = str
        ...	 a_thing = None
        
        The class `Bar`has 3 attributes. `a_num` is typed as int, `a_str` as string
        and `a_thing` can be of any type. Types are checked during flattening and
        unflattening and couse a `TypeError` Exception if type does not fit.
        
        >>> class Foo(flatty.Schema):
        ...	 my_typed_list = flatty.TypedList.set_type(Bar)
        
        The class `Foo` defines just one attribute `my_typed_list`. As the name
        might already explain, the type of this attribute is a list. It acts like a
        normal python list (actually it is inherited from `list`) with one difference
        it only accepts items instances of type `Bar`.
        
        .. note::
        
        The benefit of this "strict" typing with `TypedList` is that `Flatty`
        knows which types you expect and can create instances of class `Bar` during
        unflattening. Because flatty doesn't marshal type information it needs
        this information during unmarshaling to restore the correct types
        
        You can also use just a normal python list but when you unflat your data
        you will just get "classless" items instead of `Bar` instances.
        
        There is also a `TypedDict` to produce "strict" typed dicts
        
        Next we create some instances. You see we can use named arguments in the
        constructor to fill the attributes.
        
        >>> my_bar = Bar(a_num=42, a_str='hello world', a_thing='whatever type here')
        >>> foo = Foo(my_typed_list=[my_bar,])
        
        No we have `my_bar`added to the list of `foo`.
        
        .. note::
        
        Above you can see that we use a python list (not `TypedList`)
        ``my_typed_list=[my_bar,]``	to create the `foo` instance with the
        `my_typed_list` attribute.
        
        Flatty, flat it!
        
        >>> flatted = foo.flatit()
        >>> print flatted
        {'my_typed_list': [{'a_num': 42, 'a_str': 'hello world', 'a_thing': 'whatever type here'}]}
        
        Voila, this is the flattened dictionary you get.
        
        Per default just instances
        of type `Schema`, `datetime`, `date`, `time` will be flattened. But if  -
        for example - your marshaller don't understand integers just strings
        you can easily add a `Converter` for type `int` (see reference).
        
        The `flatted` can now be stored using your favorite low-level marshaller
        (couchdb, json, yaml, xml, etc).
        
        Next we see how we can restore objects only using the flatted data and the
        schema.
        
        >>> restored_obj = Foo.unflatit(flatted)
        >>> isinstance(restored_obj, Foo)
        True
        >>> isinstance(restored_obj.my_typed_list[0], Bar)
        True
        >>> restored_obj.my_typed_list[0].a_num
        42
        
        The restored_obj is a new object filled with the data of flatted
        
        
        Bug Tracker:
        ------------
        
        If you find any issues please report them on https://github.com/ceelian/Flatty/issues
        
        
        Getting Flatty
        --------------
        
        You can get the python package on the `Python Package Index`_
        
        .. _`Python Package Index`: http://pypi.python.org/pypi/flatty
        
        The git repository is available at `github.com Flatty`_
        
        .. _`github.com Flatty`: https://github.com/ceelian/Flatty
        
        
        Installation
        ------------
        
        
        ``Flatty`` can be installed via the Python Package Index of from source.
        
        Using ``easy_install`` to install ``Flatty``::
        
        $ easy_install Flatty
        
        
        If you have downloaded a source tarball you can install it
        by doing the following::
        
        $ python setup.py build
        $ python setup.py install
        
        
        Supported by
        ------------
        Wingware - The Python IDE (http://wingware.com)
        
        Contributing
        ------------
        
        We are welcome everyone who wants to contribute to Flatty.
        Development of Flatty happens at  https://github.com/ceelian/Flatty
        
        License
        -------
        
        Flatty is released under the BSD License.
        The full license text is in the root folder of the Flatty Package.
        
        
        
Keywords: rpc amqp
Platform: any
Classifier: Development Status :: 3 - Alpha
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: License :: OSI Approved :: BSD License
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Pre-processors
Classifier: Topic :: Software Development :: Libraries :: Python Modules
