[Checkins] SVN: Zope/trunk/src/Products/Sessions/Session Use more canonical interface names.
Tres Seaver
tseaver at palladion.com
Mon May 11 13:27:38 EDT 2009
Log message for revision 99851:
Use more canonical interface names.
Changed:
U Zope/trunk/src/Products/Sessions/SessionDataManager.py
U Zope/trunk/src/Products/Sessions/SessionInterfaces.py
-=-
Modified: Zope/trunk/src/Products/Sessions/SessionDataManager.py
===================================================================
--- Zope/trunk/src/Products/Sessions/SessionDataManager.py 2009-05-11 16:53:37 UTC (rev 99850)
+++ Zope/trunk/src/Products/Sessions/SessionDataManager.py 2009-05-11 17:27:38 UTC (rev 99851)
@@ -32,7 +32,7 @@
from ZODB.POSException import ConflictError
from zope.interface import implements
-from Products.Sessions.SessionInterfaces import SessionDataManagerInterface
+from Products.Sessions.SessionInterfaces import ISessionDataManager
from Products.Sessions.SessionPermissions import ACCESS_CONTENTS_PERM
from Products.Sessions.SessionPermissions import ACCESS_SESSIONDATA_PERM
from Products.Sessions.SessionPermissions import ARBITRARY_SESSIONDATA_PERM
@@ -93,7 +93,7 @@
icon='misc_/CoreSessionTracking/datamgr.gif'
- implements(SessionDataManagerInterface)
+ implements(ISessionDataManager)
manage_sessiondatamgr = DTMLFile('dtml/manageDataManager',
globals())
Modified: Zope/trunk/src/Products/Sessions/SessionInterfaces.py
===================================================================
--- Zope/trunk/src/Products/Sessions/SessionInterfaces.py 2009-05-11 16:53:37 UTC (rev 99850)
+++ Zope/trunk/src/Products/Sessions/SessionInterfaces.py 2009-05-11 17:27:38 UTC (rev 99851)
@@ -10,48 +10,52 @@
# FOR A PARTICULAR PURPOSE
#
############################################################################
-"""
+""" Session APIs
-Session APIs
+o See Also
- See Also
-
- "Transient Object API":../../Transience/Help/TransienceInterfaces.py
"""
from zope.interface import Interface
-class BrowserIdManagerInterface(Interface):
- """
- Zope Browser Id Manager interface.
+class IBrowserIdManager(Interface):
+ """ Zope Browser Id Manager interface.
A Zope Browser Id Manager is responsible for assigning ids to site
visitors, and for servicing requests from Session Data Managers
related to the browser id.
"""
- def encodeUrl(url, style='querystring'):
- """
- Encodes a provided URL with the current request's browser id
- and returns the result. Two forms of URL-encoding are supported:
- 'querystring' and 'inline'. 'querystring' is the default.
+ def hasBrowserId():
+ """ Return true if there is a browser id for the current request.
- If the 'querystring' form is used, the browser id name/value pair
- are postfixed onto the URL as a query string. If the 'inline'
- form is used, the browser id name/value pair are prefixed onto
- the URL as the first two path segment elements.
+ o Permission required: Access contents information
- For example:
+ o Does *not* raise an error if the request contains a broken
+ browser id.
+ """
- The call encodeUrl('http://foo.com/amethod', style='querystring')
- might return 'http://foo.com/amethod?_ZopeId=as9dfu0adfu0ad'.
+ def getBrowserId(create=1):
+ """ Return a browser id for the current request.
- The call encodeUrl('http://foo.com/amethod, style='inline')
- might return 'http://foo.com/_ZopeId/as9dfu0adfu0ad/amethod'.
+ o If create is false, return None if there is no browser id associated
+ with the current request.
+
+ o If create is true, return a newly-created browser id if
+ there is no browser id associated with the current request.
+
+ o This method is useful in conjunction with 'getBrowserIdName' if you
+ wish to embed the browser-id-name/browser-id combination as a hidden
+ value in a POST-based form.
+
+ o The browser id is opaque, has no business meaning, and its length,
+ type, and composition are subject to change.
- Permission required: Access contents information
+ o Permission required: Access contents information
- Raises: BrowserIdManagerErr. If there is no current browser id.
+ o Raises BrowserIdManagerErr if an ill-formed browser id
+ is found in REQUEST.
"""
def getBrowserIdName():
@@ -63,30 +67,6 @@
Permission required: Access contents information
"""
- def getBrowserId(create=1):
- """
- If create=0, returns a the current browser id or None if there
- is no browser id associated with the current request. If create=1,
- returns the current browser id or a newly-created browser id if
- there is no browser id associated with the current request. This
- method is useful in conjunction with getBrowserIdName if you wish to
- embed the browser-id-name/browser-id combination as a hidden value in
- a POST-based form. The browser id is opaque, has no business meaning,
- and its length, type, and composition are subject to change.
-
- Permission required: Access contents information
-
- Raises: BrowserIdManagerErr. If ill-formed browser id
- is found in REQUEST.
- """
-
- def hasBrowserId():
- """
- Returns true if there is a browser id for this request.
-
- Permission required: Access contents information
- """
-
def isBrowserIdNew():
"""
Returns true if browser id is 'new'. A browser id is 'new'
@@ -98,121 +78,156 @@
Raises: BrowserIdManagerErr. If there is no current browser id.
"""
- def isBrowserIdFromForm():
- """
- Returns true if browser id comes from a form variable (query
- string or post).
+ def isBrowserIdFromCookie():
+ """ Return true if browser id comes from a cookie.
- Permission required: Access contents information
+ o Permission required: Access contents information
- Raises: BrowserIdManagerErr. If there is no current browser id.
+ o Raise BrowserIdManagerErr if there is no current browser id.
"""
- def isBrowserIdFromCookie():
+ def isBrowserIdFromForm():
+ """ Return true if browser id comes from a form variable.
+
+ o Variable may come from either the query string or a post.
+
+ o Permission required: Access contents information
+
+ o Raise BrowserIdManagerErr if there is no current browser id.
"""
- Returns true if browser id comes from a cookie.
- Permission required: Access contents information
+ def isBrowserIdFromUrl():
+ """ Return true if browser id comes from a cookie.
- Raises: BrowserIdManagerErr. If there is no current browser id.
+ o Permission required: Access contents information
+
+ o Raise BrowserIdManagerErr if there is no current browser id.
"""
def flushBrowserIdCookie():
- """
- Deletes the browser id cookie from the client browser, iff the
- 'cookies' browser id namespace is being used.
+ """ Deletes the browser id cookie from the client browser.
- Permission required: Access contents information
+ o Permission required: Access contents information
- Raises: BrowserIdManagerErr. If the 'cookies' namespace isn't
- a browser id namespace at the time of the call.
+ o Raise BrowserIdManagerErr if the 'cookies' namespace isn't
+ a browser id namespace.
"""
def setBrowserIdCookieByForce(bid):
- """
- Sets the browser id cookie to browser id 'bid' by force.
- Useful when you need to 'chain' browser id cookies across domains
- for the same user (perhaps temporarily using query strings).
+ """ Sets the browser id cookie to browser id 'bid' by force.
- Permission required: Access contents information
+ o Useful when you need to 'chain' browser id cookies across domains
+ for the same user (perhaps temporarily using query strings).
- Raises: BrowserIdManagerErr. If the 'cookies' namespace isn't
- a browser id namespace at the time of the call.
+ o Permission required: Access contents information
+
+ o Raise BrowserIdManagerErr if the 'cookies' namespace isn't
+ a browser id namespace.
"""
def getHiddenFormField():
+ """ Return a string usable as a hidden form field for the browser id.
+
+ o String is of the form::
+
+ <input type="hidden" name="_ZopeId" value="H7HJGYUFGFyHKH*" />
+
+ o name and the value represent the current browser id
+ name and current browser id.
"""
- Returns a string in the form:
- <input type="hidden" name="_ZopeId" value="H7HJGYUFGFyHKH*">
+ def encodeUrl(url, style='querystring'):
+ """ Encode a given URL with the current browser id.
+
+ o Two forms of URL-encoding are supported: 'querystring' and 'inline'.
+
+ o 'querystring' is the default.
- Where the name and the value represent the current browser id
- name and current browser id.
+ o If the 'querystring' form is used, the browser id name/value pair
+ are postfixed onto the URL as a query string.
+
+ o If the 'inline' form is used, the browser id name/value pair
+ are prefixed onto the URL as the first two path segment elements.
+
+ o For example:
+
+ - The call encodeUrl('http://foo.com/amethod', style='querystring')
+ might return 'http://foo.com/amethod?_ZopeId=as9dfu0adfu0ad'.
+
+ - The call encodeUrl('http://foo.com/amethod, style='inline')
+ might return 'http://foo.com/_ZopeId/as9dfu0adfu0ad/amethod'.
+
+ o Permission required: Access contents information
+
+ o Raise BrowserIdManagerErr if there is no current browser id.
"""
-class SessionDataManagerInterface(Interface):
- """
- Zope Session Data Manager interface.
+BrowserIdManagerInterface = IBrowserIdManager # BBB
+class ISessionDataManager(Interface):
+ """ Zope Session Data Manager interface.
+
A Zope Session Data Manager is responsible for maintaining Session
Data Objects, and for servicing requests from application code
related to Session Data Objects. It also communicates with a Browser
Id Manager to provide information about browser ids.
"""
def getBrowserIdManager():
- """
- Returns the nearest acquirable browser id manager.
+ """ Return the nearest acquirable browser id manager.
- Raises SessionDataManagerErr if no browser id manager can be found.
+ o Raise SessionDataManagerErr if no browser id manager can be found.
- Permission required: Access session data
+ o Permission required: Access session data
"""
def getSessionData(create=1):
- """
- Returns a Session Data Object associated with the current
- browser id. If there is no current browser id, and create is true,
- returns a new Session Data Object. If there is no current
- browser id and create is false, returns None.
+ """ Return a Session Data Object for the current browser id.
+
+ o If there is no current browser id, and create is true,
+ return a new Session Data Object.
+
+ o If there is no current browser id and create is false, returns None.
- Permission required: Access session data
+ o Permission required: Access session data
"""
def hasSessionData():
- """
- Returns true if a Session Data Object associated with the
- current browser id is found in the Session Data Container. Does
- not create a Session Data Object if one does not exist.
+ """ Does a Session Data Object exist for the current browser id?
- Permission required: Access session data
+ o Do not create a Session Data Object if one does not exist.
+
+ o Permission required: Access session data
"""
def getSessionDataByKey(key):
- """
- Returns a Session Data Object associated with 'key'. If there is
- no Session Data Object associated with 'key' return None.
+ """ Return a Session Data Object associated with 'key'.
+
+ o If there is no Session Data Object associated with 'key',
+ return None.
- Permission required: Access arbitrary user session data
+ o Permission required: Access arbitrary user session data
"""
-class SessionDataManagerErr(Interface):
- """
- Error raised during some session data manager operations, as
- explained in the API documentation of the Session Data Manager.
+SessionDataManagerInterface = ISessionDataManager # BBB
- This exception may be caught in PythonScripts. A successful
- import of the exception for PythonScript use would need to be::
+class SessionDataManagerErr(ValueError):
+ """ Error raised during some session data manager operations
+
+ o See ISesseionDataManager.
+ o This exception may be caught in PythonScripts. A successful
+ import of the exception for PythonScript use would need to be::
+
from Products.Sessions import SessionDataManagerErr
"""
-class BrowserIdManagerErr(Interface):
- """
- Error raised during some browser id manager operations, as
- explained in the API documentation of the Browser Id Manager.
+class BrowserIdManagerErr(ValueError):
+ """ Error raised during some browser id manager operations
+
+ o See IBrowserIdManager methods.
- This exception may be caught in PythonScripts. A successful
- import of the exception for PythonScript use would need to be::
+ o This exception may be caught in PythonScripts. A successful
+ import of the exception for PythonScript use would need to be::
from Products.Sessions import BrowserIdManagerErr
"""
More information about the Checkins
mailing list