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
Hide 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
"""
- 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.
"""
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