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 @@ ...@@ -77,244 +77,260 @@
""" """
Transient Objects 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 Permission -- Always available
TransientObjectContainers to retrieve or create a TransientObject based """
on a given string key.
If add or delete notifications are registered with the container, they def get(self, k, default=None):
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 Return value associated with key k. If value associated with k does
registered either as bound methods, functions, or named paths in Zope. 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): Permission -- 'Create Transient Objects'
def invalidate(self):
""" """
Invalidate (expire) the transient object.
Causes the transient object container's "before destruct" method def new_or_existing(self, k):
related to this object to be called as a side effect.
""" """
If an object already exists in the container with key "k", it
is returned.
def getLastAccessed(self): Otherwiser, create a new subobject of the type supported by this
""" container with key "k" and return it.
Return the time the transient object was last accessed in
integer seconds-since-the-epoch form.
"""
def setLastAccessed(self): "k" must be a string, else a TypeError is raised.
"""
Cause the last accessed time to be set to now.
"""
def getCreated(self): Permission -- 'Create Transient Objects'
"""
Return the time the transient object was created in integer
seconds-since-the-epoch form.
""" """
class DictionaryLike(Interface.Base): def setTimeoutMinutes(self, timeout_mins):
def keys(self):
"""
Return sequence of key elements.
""" """
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): def getId(self):
""" """
Returns a meaningful unique id for the object. Returns a meaningful unique id for the object.
"""
class TTWDictionary(DictionaryLike, ItemWithId): Permission -- Always available
def set(self, k, v):
"""
Call _  _setitem_  _ with key k, value v.
""" """
def delete(self, k): def invalidate(self):
"""
Call _  _delitem_  _ with key k.
""" """
Invalidate (expire) the transient object.
def __guarded_setitem__(self, k, v): Causes the transient object container's "before destruct" method
""" related to this object to be called as a side effect.
Call _  _setitem_  _ with key k, value v.
"""
class ImmutablyValuedMappingOfPickleableObjects(Interface.Base): Permission -- XXX
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 __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 Permission -- XXX
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 __delitem__(self, k): def setLastAccessed(self):
"""
Remove the key/value pair related to key k.
""" """
Cause the last accessed time to be set to now.
class HomogeneousItemContainer(Interface.Base): Permission -- XXX
"""
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 get(self, k, default=None): def getCreated(self):
"""
Return value associated with key k. If value associated with k does
not exist, return default.
""" """
Return the time the transient object was created in integer
seconds-since-the-epoch form.
def has_key(self, k): Permission -- XXX
"""
Return true if container has value associated with key k, else
return false.
""" """
def delete(self, k): def keys(self):
"""
Delete value associated with key k, raise a KeyError if nonexistent.
""" """
Return sequence of key elements.
class StringKeyedHomogeneousItemContainer(HomogeneousItemContainer): Permission -- XXX
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 def values(self):
KeyError is raised.
"k" must be a string, else a TypeError is raised.
""" """
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 def items(self):
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 get(self, k, default='marker'):
def setTimeoutMinutes(self, timeout_mins):
""" """
Set the number of minutes of inactivity allowable for subobjects Return value associated with key k. If k does not exist and default
before they expire. 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 Return true if item referenced by key k exists.
before expiration.
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 Permission -- XXX
a callable function. """
'after add' functions need accept a single argument: 'item', which def set(self, k, v):
is the item being added to the container.
""" """
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