.. module:: dictalchemy Dictalchemy =========== Dictalchemy adds :func:`utils.asdict` and :func:`utils.fromdict` methods to `SQLAlchemy `_ declarative models. Currently this works with synonyms and simple relationships as one-to-many and many-to-many. Relationships can be followed in many levels. Using DictableModel ------------------- :class:`classes.DictableModel` can be used as base class for `declarative_base` or as a mixin for a declarative class. Example usage:: from dictalchemy import DictableModel from slqlachemy.ext.declarative import declarative_base Base = declarative_base(cls=DictableModel) Using make_class_dictable() --------------------------- This method can be run on existing classes to make them dictable. Example:: Base = declarative_base() make_class_dictable(Base) Default values -------------- Default values are defined in :mod:`dictalchemy.constants`. Using asdict() -------------- Any collection that inherits from `dict` or `list` is supported together with :class:`sqlalchemy.orm.dynamic.AppenderMixin`, :class:`sqlalchemy.orm.query.Query` :class:`sqlalchemy.orm.associationproxy._AssociationList` and :class:`sqlalchemy.orm.associationproxy._AssociationDict`. Simple example:: >>> session.query(User).asdict() {'id': 1, 'username': 'Gerald'} Using exclude_pk:: >>> session.query(User).asdict(exclude_pk=True) {'username': 'Gerald'} Using exclude:: >>> session.query(User).asdict(exclude=['id']) {'username': 'Gerald'} Using follow without arguments:: >>> session.query(User).asdict(follow={'groups':{}}) {'username': 'Gerald', groups=[{'id': 1, 'name': 'User'}]} Using follow with arguments:: >>> session.query(User).asdict(follow={'groups':{'exclude': ['id']}) {'username': 'Gerald', groups=[{'name': 'User'}]} Using follow with a `parent` argument:: >>> session.query(User).asdict(follow={'groups':{'parent': 'relationships', 'exclude': ['id']}) {'username': 'Gerald', 'relationships': {'groups':[{'name': 'User'}]}} Using include(for example for including synonyms/properties):: >>> session.query(User).asdict(include=['displayname'] {'id': 1, 'username': 'Gerald', 'displayname': 'Gerald'} The `asdict` argument `method` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. Note:: New in v 0.1.2.1 The argument `method` is used to determine which method asdict should call when following relations. If `method` is set in the follow arguments that method will be used instead. See the HAL example in :meth:`dictalchemy.utils.asdict`. Using fromdict() ---------------- Without arguments:: >>> user = session.query(User).first() >>> dict(user) {'id': 3, 'name': 'Gerald'} >>> user.fromdict({'name': 'Gerald the Great'}) >>> dict(user) {'name': 'Gerald the Great'} Excluding underscore:: >>> user = session.query(User).first() >>> dict(user, only=["_secret_id"]) {'_secret_id': 1} >>> user.fromdict({'_secret_id': 2}, exclude_underscore=False) >>> dict(user, only=["_secret_id"]) {'_secret_id': 2} Updating primary key:: >>> user = session.query(User).first() >>> dict(user, only=["id"]) {'id': 3} >>> user.fromdict({'id': 2}, allow_pk=True) >>> dict(user, only=["id"]) {'id': 2} Updating relationships:: >>> dict(user, follow=['address']) {'name': 'Gerald the Great', 'address': {'street': None}} >>> user.fromdict({'address': {'street': 'Main street'}) >>> dict(user, follow=['address']) {'name': 'Gerald the Great', 'address': {'street': 'Main street'}} Using include:: >>> user = session.query(User).first() >>> dict(user) {'id': 3, 'name': 'Gerald', 'a_synonym': 'Data'} >>> user.fromdict({'name': 'Gerald the Great', 'a_synonym': 'Other data'}, include=['a_synonym']) >>> dict(user) {'name': 'Gerald the Great', 'a_synonym': 'Other data'} Using only:: >>> user = session.query(User).first() >>> dict(user) {'id': 3, 'name': 'Gerald', 'a_synonym': 'Data'} >>> user.fromdict({'name': 'Gerald the Great', 'a_synonym': 'Other data'}, only=['name']) >>> dict(user) {'name': 'Gerald the Great', 'a_synonym': 'Data'} API --- .. automodule:: dictalchemy.classes :special-members: .. automodule:: dictalchemy.utils .. automodule:: dictalchemy.errors .. automodule:: dictalchemy.constants Python versions --------------- Dictalchemy supports python 2.7.3 and python 3.3 through `2to3`. Other versions are not tested. Source ------ The source is hosted on `http://github.com/danielholmstrom/dictalchemy `_. License ------- dictalchemy is released under the MIT license. .. toctree::