python-dehydrate

Small lib for representing python objects as a dicts.

Motivation

Why would you need library like this? One of obvious use cases is to convert
complex objects with methods, lots of atributes and so on into dicts for
serializing (into json/yaml/xml/pickle/whatever). You can control
dehydration process by describing how to fetch values from object and how to
present it in dehydrated structure using simple syntax.

Examples

Simple cases

In simplest of possible cases you just want get object, list wanted attributes
and get mapping with keys based on attribute names and values from them.
Use dehydrate shortcut for this case:

More complex cases

Sometimes you will want to add some value in dehydrated dict, which is not
attribute of dehydrated object. Or you may want not use attribute and add some
another handling for this element instead. In our example we creating
special class for this called PersonDehydrator (inherited from
dehydrate.Dehydrator) and set some methods on it:

In example you can see, that object has password attribute, but
PersonDehydrator’s get_password used for password spec. Also you can
mention, that result of calling get_superhero_status was set in key
is_superhero because of second item in spec was declared.
You can declare specs using attribute of dehydrator class
or by passing argument into its __init__ method.

Notes:

In docs I will refer to examples package, which you can find in repo.

Recursive dehydration

The most valuable feature of lib is that you can describe how to recursively
dehydrate complex fields on object:

You can see, that specs for nested elements are described with use of
dehydrate.S shortcut (And simple specs as well for the sake of sanity).
Acceptable arguments are for type='nested':

target — name, that describes how to get value from object (or use hook
on dehydrator)

dehydrator — class, which can be used for dehydrating of complex target
(dehydrate.Dehydrator by default).

specs — iterable of same structure as described above (it is optional
in case if you describe specs on dehydrator class, but make good sense,
if you ant use default Dehydrator class).

Installation

Simple:

pip install dehydrate

must be fine.

Requirements

six (did I mentioned python 3 support? We have one.)

Philosophy

Easy things should be done easily.

Complex things must be possible.

Testing

Test written with use of pytest library and neat pytest pep8 plugin.
You should run python setup.py test for running full test suite or
coverage run --source=dehydrate setup.py test for tests with coverage.
Tests automatically runs at Travis CI. Examples in documentation are also
picked by test command.

Contribution

Any contribution is welcome. Use fork/pull request mechanism on github.

If you add some code, you should add some tests, so coverage of master branch
should always be 100%. Refer to Testing section for more instructions.

Let me speak from my heart :). I will be very glad, if you correct my clumsy
english phrases in docs and docstings or even advise more appropriate names
for variables in code.