New Entity instance method
to_dict(only=None, exclude=None, with_collections=False, with_lazy=False, related_objects=False)
Returns a dictionary with attribute names and its values. This method can be used when you need to serialize an object to JSON or other format.
By default this method doesn’t include collections (relationships to-many) and lazy attributes. If an attribute’s values is an entity instance then only the primary key of this object will be added to the dictionary.
only – use this parameter if you want to get only the specified attributes. This argument can be used as a first positional argument. You can specify a list of attribute names obj.to_dict(['id', 'name']), a string separated by spaces: obj.to_dict('id name'), or a string separated by spaces with commas: obj.to_dict('id, name').
exclude – this parameter allows to exclude specified attributes. Attribute names can be specified the same way as for the only parameter.
related_objects – by default, all related objects represented as a primary key. If related_objects=True, then objects which have relationships with the current object will be added to the resulting dict as objects, not their primary keys. It can be useful if you want to walk the related objects and call the to_dict() method recursively.
with_collectionsTrue, then the relationships to-many will be represented as lists. If related_objects=False (which is by default), then those lists will consist of primary keys of related instances. If related_objects=True then to-many collections will be represented as lists of objects.
with_lazy – if True, then lazy attributes (such as BLOBs or attributes which are declared with lazy=True) will be included to the resulting dict.
For illustrating the usage of this method we will use the eStore example which comes with Pony distribution. Let’s get a customer object with the id=1 and convert it to a dictionary:
>>> from pony.orm.examples.estore import *
>>> c1 = Customer[1]
>>> c1.to_dict()
{'address': u'address 1',
'country': u'USA',
'email': u'john@example.com',
'id': 1,
'name': u'John Smith',
'password': u'***'}
If we don’t want to serialize the password attribute, we can exclude it this way:
>>> c1.to_dict(exclude='password')
{'address': u'address 1',
'country': u'USA',
'email': u'john@example.com',
'id': 1,
'name': u'John Smith'}
If you want to exclude more than one attribute, you can specify them as a list: exclude=['id', 'password'] or as a string: exclude='id, password' which is the same as exclude='id password'.
Also you can specify only the attributes, which you want to serialize using the parameter only:
>>> c1.to_dict(only=['id', 'name'])
{'id': 1, 'name': u'John Smith'}
>>> c1.to_dict('name email') # 'only' parameter as a positional argument
{'email': u'john@example.com', 'name': u'John Smith'}
By default the collections are not included to the resulting dict. If you want to include them, you can specify with_collections=True. Also you can specify the collection attribute in the only parameter:
>>> c1.to_dict(with_collections=True)
{'address': u'address 1',
'cart_items': [1, 2],
'country': u'USA',
'email': u'john@example.com',
'id': 1,
'name': u'John Smith',
'orders': [1, 2],
'password': u'***'}
By default all related objects (cart_items, orders) are represented as a list with their primary keys. If you want to see the related objects instances, you can specify related_objects=True:
>>> c1.to_dict(with_collections=True, related_objects=True)
{'address': u'address 1',
'cart_items': [CartItem[1], CartItem[2]],
'country': u'USA',
'email': u'john@example.com',
'id': 1,
'name': u'John Smith',
'orders': [Order[1], Order[2]],
'password': u'***'}