Python库 | pjpersist-1.1.2.dev0.tar.gz

================================= PostGreSQL/JSONB Data Persistence ================================= This document outlines the general capabilities of the ``pjpersist`` package. ``pjpersist`` is a PostGreSQL/JSONB storage implementation for persistent Python objects. It is *not* a storage for the ZODB. The goal of ``pjpersist`` is to provide a data manager that serializes objects to JSONB blobs at transaction boundaries. The PJ data manager is a persistent data manager, which handles events at transaction boundaries (see ``transaction.interfaces.IDataManager``) as well as events from the persistency framework (see ``persistent.interfaces.IPersistentDataManager``). An instance of a data manager is supposed to have the same life time as the transaction, meaning that it is assumed that you create a new data manager when creating a new transaction: >>> import transaction Note: The ``conn`` object is a ``psycopg.Connection`` instance. In this case our tests use the ``pjpersist_test`` database. Let's now define a simple persistent object: >>> import datetime >>> import persistent >>> class Person(persistent.Persistent): ... ... def __init__(self, name, phone=None, address=None, friends=None, ... visited=(), birthday=None): ... self.name = name ... self.address = address ... self.friends = friends or {} ... self.visited = visited ... self.phone = phone ... self.birthday = birthday ... self.today = datetime.datetime(2014, 5, 14, 12, 30) ... ... def __str__(self): ... return self.name ... ... def __repr__(self): ... return '<%s %s>' %(self.__class__.__name__, self) We will fill out the other objects later. But for now, let's create a new person and store it in PJ: >>> stephan = Person(u'Stephan') >>> stephan <Person Stephan> The datamanager provides a ``root`` attribute in which the object tree roots can be stored. It is special in the sense that it immediately writes the data to the DB: >>> dm.root['stephan'] = stephan >>> dm.root['stephan'] <Person Stephan> Custom Persistence Tables ------------------------- By default, persistent objects are stored in a table having the escaped Python path of the class: >>> from pjpersist import serialize >>> person_cn = serialize.get_dotted_name(Person, True) >>> person_cn 'u__main___dot_Person' >>> transaction.commit() >>> dumpTable(person_cn) [{'data': {u'_py_persistent_type': u'__main__.Person', u'address': None, u'birthday': None, u'friends': {}, u'name': u'Stephan', u'phone': None, u'today': {u'_py_type': u'datetime.datetime', u'value': u'2014-05-14T12:30:00'}, u'visited': []}, 'id': u'0001020304050607080a0b0c0'}] As you can see, the stored document for the person looks very much like a natural JSON document. But oh no, I forgot to specify the full name for Stephan. Let's do that: >>> dm.root['stephan'].name = u'Stephan Richter' >>> dm.root['stephan']._p_changed True This time, the data is not automatically saved: >>> fetchone(person_cn)['data']['name'] u'Stephan' So we have to commit the transaction first: >>> dm.root['stephan']._p_changed True >>> transaction.commit() >>> dm.root['stephan']._p_changed >>> fetchone(person_cn)['data']['name'] u'Stephan Richter' Let's now add an address for Stephan. Addresses are also persistent objects: >>> class Address(persistent.Persistent): ... _p_pj_table = 'address' ... ... def __init__(self, city, zip): ... self.city = city ... self.zip = zip ... ... def __str__(self): ... return '%s (%s)' %(self.city, self.zip) ... ... def __repr__(self): ... return '<%s %s>' %(self.__class__.__name__, self) pjpersist supports a special attribute called ``_p_pj_table``, which allows you to specify a custom table to use. >>> stephan = dm.root['stephan'] >>> stephan.address = Address('Maynard', '01754') >>> stephan.address <Address Maynard (01754)> Note that the address is not immediately saved in the database: >>> dumpTable('address', isolate=True) relation "address" does not exist ... But once we commit the transaction, everything is available: >>> transaction.commit() >>> dumpTable('address') [{'data': {u'_py_persistent_type': u'__main__.Address', u'city': u'Maynard', u'zip': u'01754'}, 'id': u'0001020304050607080a0b0c0'}] >>> dumpTable(person_cn) [{'data': {u'_py_persistent_type': u'__main__.Person', u'address': {u'_py_type': u'DBREF', u'database': u'pjpersist_test', u'id': u'0001020304050607080a0b0c0', u'table': u'address'}, u'birthday': None, u'friends': {}, u'name': u'Stephan Richter', u'phone': None, u'today': {u'_py_type': u'datetime.datetime', u'value': u'2014-05-14T12:30:00'}, u'visited': []}, 'id': u'0001020304050607080a0b0c0'}] >>> dm.root['stephan'].address <Address Maynard (01754)> Non-Persistent Objects ---------------------- As you can see, even the reference looks nice and all components are easily visible. But what about arbitrary non-persistent, but picklable, objects? Well, let's create a phone number object for that: >>> class Phone(object): ... ... def __init__(self, country, area, number): ... self.country = country ... self.area = area ... self.number = number ... ... def __str__(self): ... return '%s-%s-%s' %(self.country, self.area, self.number) ... ... def __repr__(self): ... return '<%s %s>' %(self.__class__.__name__, self) >>> dm.root['stephan'].phone = Phone('+1', '978', '394-5124') >>> dm.root['stephan'].phone <Phone +1-978-394-5124> Let's now commit the transaction and look at the JSONB document again: >>> transaction.commit() >>> dm.root['stephan'].phone <Phone +1-978-394-5124> >>> dumpTable(person_cn) [{'data': {u'_py_persistent_type': u'__main__.Person', u'address': {u'_py_type': u'DBREF', u'database': u'pjpersist_test', u'id': u'0001020304050607080a0b0c0', u'table': u'address'}, u'birthday': None, u'friends': {}, u'name': u'Stephan Richter', u'phone': {u'_py_type': u'__main__.Phone', u'area': u'978', u'country': u'+1', u'number': u'394-5124'}, u'today': {u'_py_type': u'datetime.datetime', u'value': u'2014-05-14T12:30:00'}, u'visited': []}, 'id': u'0001020304050607080a0b0c0'}] As you can see, for arbitrary non-persistent objects we need a small hint in the sub-document, but it is very minimal. If the ``__reduce__`` method returns a more complex construct, more meta-data is written. We will see that next when storing a date and other arbitrary data: >>> dm.root['stephan'].friends = {'roy': Person(u'Roy Mathew')} >>> dm.root['stephan'].visited = (u'Germany', u'USA') >>> dm.root['stephan'].birthday = datetime.date(1980, 1, 25) >>> transaction.commit() >>> dm.root['stephan'].friends {u'roy': <Person Roy Mathew>} >>> dm.root['stephan'].visited [u'Germany', u'USA'] >>> dm.root['stephan'].birthday datetime.date(1980, 1, 25) As you can see, a dictionary key is always converted to unicode and tuples are always maintained as lists, since JSON does not have two sequence types. >>> import pprint >>> pprint.pprint(dict( ... fetchone(person_cn, """data @> '{"name": "Stephan Richter"}'"""))) {'data': {u'_py_persistent