Python persistent interface
A persistent object can be in one of several states:
The object has been created but not saved in a data manager.
In this state, the _p_changed attribute is non-None and false and the _p_jar attribute is None.
The object has been saved and has not been changed since it was saved.
In this state, the _p_changed attribute is non-None and false and the _p_jar attribute is set to a data manager.
This state is identical to the saved state except that the object cannot transition to the ghost state. This is a special state used by C methods of persistent objects to make sure that state is not unloaded in the middle of computation.
In this state, the _p_changed attribute is non-None and false and the _p_jar attribute is set to a data manager.
There is no Python API for detecting whether an object is in the sticky state.
The object has been changed.
In this state, the _p_changed attribute is true and the _p_jar attribute is set to a data manager.
the object is in memory but its state has not been loaded from the database (or its state has been unloaded). In this state, the object doesn't contain any application data.
In this state, the _p_changed attribute is None, and the _p_jar attribute is set to the data manager from which the object was obtained.
In all the above, _p_oid (the persistent object id) is set when _p_jar first gets set.
The following state transitions are possible:
This transition occurs when an object is saved in the database. This usually happens when an unsaved object is added to (e.g. as an attribute or item of) a saved (or changed) object and the transaction is committed.
This transition occurs when someone sets an attribute or sets _p_changed to a true value on a saved, sticky or ghost object. When the transition occurs, the persistent object is required to call the register() method on its data manager, passing itself as the only argument.
Prior to ZODB 3.6, setting _p_changed to a true value on a ghost object was ignored (the object remained a ghost, and getting its _p_changed attribute continued to return None).
This transition occurs when C code marks the object as sticky to prevent its deactivation.
This transition occurs when a saved object is deactivated or invalidated. See discussion below.
This transition occurs when C code unmarks the object as sticky to allow its deactivation.
This transition occurs when a transaction is committed. After saving the state of a changed object during transaction commit, the data manager sets the object's _p_changed to a non-None false value.
This transition occurs when a transaction is aborted. All changed objects are invalidated by the data manager by an abort.
This transition occurs when an attribute or operation of a ghost is accessed and the object's state is loaded from the database.
Note that there is a separate C API that is not included here. The C API requires a specific data layout and defines the sticky state.
About Invalidation, Deactivation and the Sticky & Ghost States
The sticky state is intended to be a short-lived state, to prevent an object's state from being discarded while we're in C routines. It is an error to invalidate an object in the sticky state.
Deactivation is a request that an object discard its state (become a ghost). Deactivation is an optimization, and a request to deactivate may be ignored. There are two equivalent ways to request deactivation:
There are two ways to invalidate an object: call the _p_invalidate() method (preferred) or delete its _p_changed attribute. This cannot be ignored, and is used when semantics require invalidation. Normally, an invalidated object transitions to the ghost state. However, some objects cannot be ghosts. When these objects are invalidated, they immediately reload their state from their data manager, and are then in the saved state.
_p_jar
(Attribute)
The data manager for the object.
The data manager implements the IPersistentDataManager interface. If there is no data manager, then this is None.
_p_oid
(Attribute)
The object id.
It is up to the data manager to assign this. The special value None is reserved to indicate that an object id has not been assigned. Non-None object ids must be non-empty strings. The 8-byte string ' '*8 (8 NUL bytes) is reserved to identify the database root object.
_p_serial
(Attribute)
The object serial number.
This member is used by the data manager to distiguish distinct revisions of a given persistent object.
This is an 8-byte string (not Unicode).
_p_changed
(Attribute)
The persistent state of the object.
This is one of:
The object state may be changed by assigning or deleting this attribute; however, assigning None is ignored if the object is not in the saved state, and may be ignored even if the object is in the saved state.
At and after ZODB 3.6, setting _p_changed to a true value for a ghost object activates the object; prior to 3.6, setting _p_changed to a true value on a ghost object was ignored.
Note that an object can transition to the changed state only if
it has a data manager. When such a state change occurs, the
register
method of the data manager must be called, passing the
persistent object.
Deleting this attribute forces invalidation independent of existing state, although it is an error if the sticky state is current.
* = required
_p_activate()
Activate the object.
Change the object to the saved state if it is a ghost.
_p_deactivate()
Deactivate the object.
Possibly change an object in the saved state to the ghost state. It may not be possible to make some persistent objects ghosts, and, for optimization reasons, the implementation may choose to keep an object in the saved state.
__getstate__()
Get the object data.
The state should not include persistent attributes ("_p_name"). The result must be picklable.
_p_invalidate()
Invalidate the object.
Invalidate the object. This causes any data to be thrown away, even if the object is in the changed state. The object is moved to the ghost state; further accesses will cause object data to be reloaded.
__setstate__(state)
Set the object data.
There are no extended adapters registered for this interface.
There are no views available.
zope.app.sqlscript.sqlscript.Arguments
persistent.list.PersistentList
zope.index.field.index.FieldIndex
zope.app.catalog.catalog.Catalog
BTrees.OOBTree.OOBucket
zope.app.component.back35.UtilityRegistration
zope.error.error.ErrorReportingUtility
zope.minmax._minmax.Maximum
BTrees.LLBTree.LLBucket
zope.dublincore.annotatableadapter.ZDCAnnotationData
zope.app.pluggableauth.BTreePrincipalSource
zope.securitypolicy.role.LocalRole
zope.app.component.back35.RegistrationManager
BTrees.fsBTree.fsBTree
ZODB.broken.PersistentBroken
zope.app.intid.IntIds
zope.session.session.SessionData
BTrees.IIBTree.IIBucket
zope.app.cache.ram.RAMCache
BTrees.OIBTree.OIBTree
zope.minmax._minmax.Minimum
zope.app.component.back35.AdapterRegistration
BTrees.LFBTree.LFBTree
zope.app.file.image.Image
zope.app.component.back35.AdapterRegistration2
z3checkins.message.CheckinMessage
BTrees.IOBTree.IOSet
zope.app.workflow.stateful.definition.StatesContainer
zope.app.onlinehelp.onlinehelptopic.OnlineHelpResource
BTrees.IIBTree.IISet
BTrees.LOBTree.LOBTree
zope.session.session.PersistentSessionDataContainer
buddydemo.buddy.Buddy
zope.app.workflow.stateful.instance.StatefulProcessInstance
zope.rdb.ZopeDatabaseAdapter
BTrees.OLBTree.OLTreeSet
BTrees.OOBTree.OOTreeSet
BTrees.fsBTree.fsTreeSet
zope.securitypolicy.securitymap.PersistentSecurityMap
BTrees.fsBTree.fsBucket
zope.app.zptpage.zptpage.ZPTPage
zope.app.principalannotation.PrincipalAnnotationUtility
zope.session.session.RAMSessionDataContainer
zope.app.catalog.field.FieldIndex
BTrees.OIBTree.OITreeSet
zope.app.authentication.authentication.PluggableAuthentication
BTrees.IOBTree.IOTreeSet
BTrees.IOBTree.IOBucket
zope.app.authentication.session.SessionCredentialsPlugin
zope.app.workflow.definition.ProcessDefinitionElementContainer
zope.app.i18nfile.i18nfile.I18nFile
zope.app.container.ordered.OrderedContainer
BTrees.IFBTree.IFBucket
BTrees.OLBTree.OLSet
BTrees.IFBTree.IFBTree
zope.app.component.site.SiteManagementFolder
BTrees.IFBTree.IFSet
BTrees.LOBTree.LOBucket
zope.component.persistentregistry.PersistentAdapterRegistry
zope.app.workflow.stateful.definition.TransitionsContainer
zope.app.authentication.groupfolder.GroupInformation
zope.app.authentication.principalfolder.InternalPrincipal
BTrees.LOBTree.LOTreeSet
zope.app.workflow.stateful.definition.State
zope.app.interface.PersistentInterfaceClass
zope.app.security.permission.LocalPermission
buddydemo.buddy.BuddyFolder
zope.minmax._minmax.AbstractValue
zope.app.container.btree.BTreeContainer
BTrees.IIBTree.IITreeSet
BTrees.LFBTree.LFSet
BTrees.OOBTree.OOSet
zope.app.interface.wref.FlexibleWeakKeyDictionary
zope.app.sqlscript.sqlscript.SQLScript
BTrees.LLBTree.LLTreeSet
zope.app.preference.default.DefaultPreferenceProvider
zope.app.pluggableauth.PluggableAuthentication
zope.app.workflow.definition.ProcessDefinition
zope.rdb.gadflyda.GadflyAdapter
zope.app.principalannotation.Annotations
BTrees.LLBTree.LLBTree
z3checkins.message.Message
zope.app.component.site._LocalAdapterRegistry
BTrees.fsBTree.fsSet
zope.app.i18nfile.i18nimage.I18nImage
BTrees.Length.Length
zope.app.workflow.stateful.definition.Transition
zope.app.component.back35.SimpleRegistration
zope.app.dtmlpage.dtmlpage.DTMLPage
zope.index.text.baseindex.BaseIndex
persistent.wref.PersistentWeakKeyDictionary
persistent.mapping.PersistentMapping
zope.app.homefolder.homefolder.HomeFolderManager
zope.app.authentication.groupfolder.GroupFolder
zope.app.workflow.stateful.contentworkflow.ContentWorkflowsManager
persistent.Persistent
zope.app.pythonpage.PythonPage
zope.app.authentication.httpplugins.HTTPBasicAuthCredentialsPlugin
BTrees.OLBTree.OLBTree
zope.app.container.contained.ContainedProxy
zope.app.folder.folder.Folder
zope.app.pluggableauth.SimplePrincipal
zope.app.file.file.File
BTrees.OIBTree.OIBucket
zope.app.workflow.stateful.instance.RelevantData
persistent.dict.PersistentDict
BTrees.IOBTree.IOBTree
zope.app.workflow.stateful.definition.StatefulProcessDefinition
zope.index.text.lexicon.Lexicon
BTrees.LFBTree.LFTreeSet
zope.app.catalog.text.TextIndex
zope.error.error.RootErrorReportingUtility
zope.index.text.okapiindex.OkapiIndex
BTrees.IFBTree.IFTreeSet
BTrees.OIBTree.OISet
zope.app.i18n.translationdomain.TranslationDomain
zope.app.i18n.messagecatalog.MessageCatalog
zope.app.component.site.LocalSiteManager
BTrees.LFBTree.LFBucket
zope.session.session.SessionPkgData
z3checkins.folder.CheckinFolder
zope.app.authentication.principalfolder.PrincipalFolder
zodbcode.function.PersistentFunction
BTrees.LOBTree.LOSet
BTrees.OLBTree.OLBucket
zope.index.text.textindex.TextIndex
BTrees.IIBTree.IIBTree
zope.app.file.file.FileChunk
zope.app.container.contained.ContainedProxyBase
BTrees.LLBTree.LLSet
zope.session.http.CookieClientIdManager
zope.app.component.back35.ComponentRegistration
BTrees.OOBTree.OOBTree