[Zope-Checkins] CVS: Zope/lib/python/Products/Transience/help - TransienceInterfaces.py:1.4
Amos Latteier
amos@zope.com
Mon, 19 Nov 2001 20:08:52 -0500
Update of /cvs-repository/Zope/lib/python/Products/Transience/help
In directory cvs.zope.org:/tmp/cvs-serv18064
Modified Files:
TransienceInterfaces.py
Log Message:
Clean up transient object API docs. Still need permissions for transient objects.
=== Zope/lib/python/Products/Transience/help/TransienceInterfaces.py 1.3 => 1.4 ===
Transient Objects
- TransientObjectContainers implement:
-
- - ItemWithId
+"""
- - StringKeyedHomogenousItemContainer
+class TransientObjectContainer(Interface.Base):
+ """
+ TransientObjectContainers hold transient objects, most often,
+ session data.
- - TransientItemContainer
+ 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'.
+ """
+
+ 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):
+ Permission -- 'Create Transient Objects'
"""
- Return the time the transient object was created in integer
- seconds-since-the-epoch form.
+
+ def setTimeoutMinutes(self, timeout_mins):
"""
+ Set the number of minutes of inactivity allowable for subobjects
+ before they expire.
-class DictionaryLike(Interface.Base):
- def keys(self):
- """
- Return sequence of key elements.
+ Permission -- 'Manage Transient Object Container'
"""
- def values(self):
- """
- Return sequence of value elements.
+ def getTimeoutMinutes(self):
"""
+ Return the number of minutes allowed for subobject inactivity
+ before expiration.
- def items(self):
- """
- Return sequence of (key, value) elements.
+ Permission -- 'View management screens'
"""
- def get(self, k, default='marker'):
+ def getAddNotificationTarget(self):
"""
- Return value associated with key k. If k does not exist and default
- is not marker, return default, else raise KeyError.
+ Returns the current 'after add' function, or None.
+
+ Permission -- 'View management screens'
"""
- def has_key(self, k):
+ def setAddNotificationTarget(self, f):
"""
- Return true if item referenced by key k exists.
+ Cause the 'after add' function to be 'f'.
+
+ 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'
"""
- def clear(self):
+ def getDelNotificationTarget(self):
"""
- Remove all key/value pairs.
+ Returns the current 'before destruction' function, or None.
+
+ Permission -- 'View management screens'
"""
- def update(self, d):
+ def setDelNotificationTarget(self, f):
"""
- Merge dictionary d into ourselves.
+ 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.
+
+ Permission -- 'Manage Transient Object Container'
"""
- # DictionaryLike does NOT support copy()
-class ItemWithId(Interface.Base):
+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::
+
+ 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.
+ """
+
def getId(self):
"""
Returns a meaningful unique id for the object.
- """
-class TTWDictionary(DictionaryLike, ItemWithId):
- def set(self, k, v):
+ Permission -- Always available
"""
- Call _ _setitem_ _ with key k, value v.
+
+ def invalidate(self):
"""
+ Invalidate (expire) the transient object.
- def delete(self, k):
- """
- Call _ _delitem_ _ with key k.
- """
+ Causes the transient object container's "before destruct" method
+ related to this object to be called as a side effect.
- def __guarded_setitem__(self, k, v):
- """
- Call _ _setitem_ _ with key k, value v.
+ Permission -- XXX
"""
-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.
+ def getLastAccessed(self):
"""
+ Return the time the transient object was last accessed in
+ integer seconds-since-the-epoch form.
- def __getitem__(self, k):
+ Permission -- XXX
"""
- Returns the value associated with key k.
- 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_ _.
+ def setLastAccessed(self):
"""
+ Cause the last accessed time to be set to now.
- def __delitem__(self, k):
- """
- Remove the key/value pair related to key k.
+ Permission -- XXX
"""
-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.
+ def getCreated(self):
"""
+ Return the time the transient object was created in integer
+ seconds-since-the-epoch form.
- def get(self, k, default=None):
- """
- Return value associated with key k. If value associated with k does
- not exist, return default.
+ Permission -- XXX
"""
- def has_key(self, k):
- """
- Return true if container has value associated with key k, else
- return false.
+ def keys(self):
"""
+ Return sequence of key elements.
- def delete(self, k):
- """
- Delete value associated with key k, raise a KeyError if nonexistent.
+ Permission -- XXX
"""
-class StringKeyedHomogeneousItemContainer(HomogeneousItemContainer):
- def new(self, k):
+ def values(self):
"""
- 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.
+ Return sequence of value elements.
- "k" must be a string, else a TypeError is raised.
+ Permission -- XXX
"""
- def new_or_existing(self, k):
+ def items(self):
"""
- 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.
+ 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.
- """
+
+