Skip to content

Z
Zope
Commit 1387bfb5 authored by Amos Latteier's avatar Amos Latteier
Browse files
Options

Clean up transient object API docs. Still need permissions for transient objects.

parent 83fbdd94
Show whitespace changes
Inline Side-by-side
Showing with 163 additions and 147 deletions
lib/python/Products/Transience/help/TransienceInterfaces.py
View file @ 1387bfb5
......@@ -77,244 +77,260 @@
"""
Transient Objects
TransientObjectContainers implement:
"""
- ItemWithId
class TransientObjectContainer(Interface.Base):
"""
TransientObjectContainers hold transient objects, most often,
session data.
- StringKeyedHomogenousItemContainer
You will rarely have to script a transient object
container. You'll almost always deal with a TransientObject
itself which you'll usaually get as 'REQUEST.SESSION'.
"""
- TransientItemContainer
def getId(self):
"""
Returns a meaningful unique id for the object.
In particular, one uses the 'new__or__existing' method on
TransientObjectContainers to retrieve or create a TransientObject based
on a given string key.
Permission -- Always available
"""
If add or delete notifications are registered with the container, they
will be called back when items in the container are added or deleted,
with the item and the container as arguments. The callbacks may be
registered either as bound methods, functions, or named paths in Zope.
def get(self, k, default=None):
"""
Return value associated with key k. If value associated with k does
not exist, return default.
TransientObjects implement:
Permission -- 'Access Transient Objects'
"""
- ItemWithId
def has_key(self, k):
"""
Return true if container has value associated with key k, else
return false.
- Transient
Permission -- 'Access Transient Objects'
"""
- DictionaryLike
def delete(self, k):
"""
Delete value associated with key k, raise a KeyError if nonexistent.
- TTWDictionary
Permission -- 'Access Transient Objects'
"""
- ImmutablyValuedMappingOfPickleableObjects
def new(self, k):
"""
Creates a new subobject of the type supported by this container
with key "k" and returns it.
"""
If an object already exists in the container with key "k", a
KeyError is raised.
import Interface
"k" must be a string, else a TypeError is raised.
class Transient(Interface.Base):
def invalidate(self):
Permission -- 'Create Transient Objects'
"""
Invalidate (expire) the transient object.
Causes the transient object container's "before destruct" method
related to this object to be called as a side effect.
def new_or_existing(self, k):
"""
If an object already exists in the container with key "k", it
is returned.
def getLastAccessed(self):
"""
Return the time the transient object was last accessed in
integer seconds-since-the-epoch form.
"""
Otherwiser, create a new subobject of the type supported by this
container with key "k" and return it.
def setLastAccessed(self):
"""
Cause the last accessed time to be set to now.
"""
"k" must be a string, else a TypeError is raised.
def getCreated(self):
"""
Return the time the transient object was created in integer
seconds-since-the-epoch form.
Permission -- 'Create Transient Objects'
"""
class DictionaryLike(Interface.Base):
def keys(self):
"""
Return sequence of key elements.
def setTimeoutMinutes(self, timeout_mins):
"""
Set the number of minutes of inactivity allowable for subobjects
before they expire.
def values(self):
Permission -- 'Manage Transient Object Container'
"""
Return sequence of value elements.
def getTimeoutMinutes(self):
"""
Return the number of minutes allowed for subobject inactivity
before expiration.
def items(self):
Permission -- 'View management screens'
"""
Return sequence of (key, value) elements.
def getAddNotificationTarget(self):
"""
Returns the current 'after add' function, or None.
def get(self, k, default='marker'):
Permission -- 'View management screens'
"""
Return value associated with key k. If k does not exist and default
is not marker, return default, else raise KeyError.
def setAddNotificationTarget(self, f):
"""
Cause the 'after add' function to be 'f'.
def has_key(self, k):
If 'f' is not callable and is a string, treat it as a Zope path to
a callable function.
'after add' functions need accept a single argument: 'item', which
is the item being added to the container.
Permission -- 'Manage Transient Object Container'
"""
Return true if item referenced by key k exists.
def getDelNotificationTarget(self):
"""
Returns the current 'before destruction' function, or None.
def clear(self):
Permission -- 'View management screens'
"""
Remove all key/value pairs.
def setDelNotificationTarget(self, f):
"""
Cause the 'before destruction' function to be 'f'.
def update(self, d):
If 'f' is not callable and is a string, treat it as a Zope path to
a callable function.
'before destruction' functions need accept a single argument: 'item',
which is the item being destroyed.
Permission -- 'Manage Transient Object Container'
"""
Merge dictionary d into ourselves.
class TransientObject(Interface.Base):
"""
A transient object is a temporary object contained in a transient
object container.
Most of the time you'll simply treat a transient object as a
dictionary. You can use Python sub-item notation::
# DictionaryLike does NOT support copy()
SESSION['foo']=1
foo=SESSION['foo']
del SESSION['foo']
When using a transient object from Python-based Scripts or DTML
you can use the 'get', 'set', and 'delete' methods instead.
It's important to reassign mutuable sub-items when you change
them. For example::
l=SESSION['myList']
l.append('spam')
SESSION['myList']=l
This is necessary in order to save your changes.
"""
class ItemWithId(Interface.Base):
def getId(self):
"""
Returns a meaningful unique id for the object.
"""
class TTWDictionary(DictionaryLike, ItemWithId):
def set(self, k, v):
"""
Call _  _setitem_  _ with key k, value v.
Permission -- Always available
"""
def delete(self, k):
"""
Call _  _delitem_  _ with key k.
def invalidate(self):
"""
Invalidate (expire) the transient object.
def __guarded_setitem__(self, k, v):
"""
Call _  _setitem_  _ with key k, value v.
"""
Causes the transient object container's "before destruct" method
related to this object to be called as a side effect.
class ImmutablyValuedMappingOfPickleableObjects(Interface.Base):
def __setitem__(self, k, v):
"""
Sets key k to value v, if k is both hashable and pickleable and
v is pickleable, else raise TypeError.
Permission -- XXX
"""
def __getitem__(self, k):
def getLastAccessed(self):
"""
Returns the value associated with key k.
Return the time the transient object was last accessed in
integer seconds-since-the-epoch form.
Note that no guarantee is made to persist changes made to mutable
objects obtained via _  _getitem_  _, even if
they support the ZODB Persistence interface. In order to ensure
that changes to mutable values are persisted, you need to explicitly
put the value back in to the mapping via the
_  _setitem_  _.
Permission -- XXX
"""
def __delitem__(self, k):
"""
Remove the key/value pair related to key k.
def setLastAccessed(self):
"""
Cause the last accessed time to be set to now.
class HomogeneousItemContainer(Interface.Base):
"""
An object which:
1. Contains zero or more subobjects, all of the same type.
2. Is responsible for the creation of its subobjects.
3. Allows for the access of a subobject by key.
"""
def getSubobjectInterface(self):
"""
Returns the interface object which must be supported by items added
to or created by this container.
Permission -- XXX
"""
def get(self, k, default=None):
"""
Return value associated with key k. If value associated with k does
not exist, return default.
def getCreated(self):
"""
Return the time the transient object was created in integer
seconds-since-the-epoch form.
def has_key(self, k):
"""
Return true if container has value associated with key k, else
return false.
Permission -- XXX
"""
def delete(self, k):
"""
Delete value associated with key k, raise a KeyError if nonexistent.
def keys(self):
"""
Return sequence of key elements.
class StringKeyedHomogeneousItemContainer(HomogeneousItemContainer):
def new(self, k):
Permission -- XXX
"""
Creates a new subobject of the type supported by this container
with key "k" and returns it.
If an object already exists in the container with key "k", a
KeyError is raised.
"k" must be a string, else a TypeError is raised.
def values(self):
"""
Return sequence of value elements.
def new_or_existing(self, k):
Permission -- XXX
"""
If an object already exists in the container with key "k", it
is returned.
Otherwiser, create a new subobject of the type supported by this
container with key "k" and return it.
def items(self):
"""
Return sequence of (key, value) elements.
"k" must be a string, else a TypeError is raised.
Permission -- XXX
"""
class TransientItemContainer(Interface.Base):
def setTimeoutMinutes(self, timeout_mins):
def get(self, k, default='marker'):
"""
Set the number of minutes of inactivity allowable for subobjects
before they expire.
Return value associated with key k. If k does not exist and default
is not marker, return default, else raise KeyError.
Permission -- XXX
"""
def getTimeoutMinutes(self):
def has_key(self, k):
"""
Return the number of minutes allowed for subobject inactivity
before expiration.
Return true if item referenced by key k exists.
Permission -- XXX
"""
def getAddNotificationTarget(self):
def clear(self):
"""
Returns the current 'after add' function, or None.
Remove all key/value pairs.
Permission -- XXX
"""
def setAddNotificationTarget(self, f):
def update(self, d):
"""
Cause the 'after add' function to be 'f'.
Merge dictionary d into ourselves.
If 'f' is not callable and is a string, treat it as a Zope path to
a callable function.
Permission -- XXX
"""
'after add' functions need accept a single argument: 'item', which
is the item being added to the container.
def set(self, k, v):
"""
Call __setitem__ with key k, value v.
def getDelNotificationTarget(self):
Permission -- XXX
"""
Returns the current 'before destruction' function, or None.
def delete(self, k):
"""
Call __delitem__ with key k.
def setDelNotificationTarget(self, f):
Permission -- XXX
"""
Cause the 'before destruction' function to be 'f'.
If 'f' is not callable and is a string, treat it as a Zope path to
a callable function.
'before destruction' functions need accept a single argument: 'item',
which is the item being destroyed.
"""
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7