[Zope3-checkins] SVN: Zope3/trunk/src/zope/app/session/ Docstring formatting

Stuart Bishop stuart at stuartbishop.net
Mon Jul 12 12:05:03 EDT 2004


Log message for revision 26427:
Docstring formatting


-=-
Modified: Zope3/trunk/src/zope/app/session/__init__.py
===================================================================
--- Zope3/trunk/src/zope/app/session/__init__.py	2004-07-12 14:58:12 UTC (rev 26426)
+++ Zope3/trunk/src/zope/app/session/__init__.py	2004-07-12 16:05:02 UTC (rev 26427)
@@ -11,8 +11,7 @@
 # FOR A PARTICULAR PURPOSE.
 #
 ##############################################################################
-"""
-Session implementation using cookies
+"""Core session interfaces and implementation
 
 $Id$
 """

Modified: Zope3/trunk/src/zope/app/session/http.py
===================================================================
--- Zope3/trunk/src/zope/app/session/http.py	2004-07-12 14:58:12 UTC (rev 26426)
+++ Zope3/trunk/src/zope/app/session/http.py	2004-07-12 16:05:02 UTC (rev 26427)
@@ -11,8 +11,7 @@
 # FOR A PARTICULAR PURPOSE.
 #
 ##############################################################################
-"""
-Session implementation using cookies
+"""Session implementation using cookies
 
 $Id$
 """
@@ -129,7 +128,7 @@
             >>> id1 != id2
             True
 
-           """
+        """
         data = "%.20f%.20f%.20f" % (random.random(), time.time(), time.clock())
         digest = sha.sha(data).digest()
         s = digestEncode(digest)
@@ -141,44 +140,44 @@
     def getRequestId(self, request):
         """Return the browser id encoded in request as a string
         
-           Return None if an id is not set.
+        Return None if an id is not set.
 
-           For example:
+        For example:
 
-             >>> from zope.publisher.http import HTTPRequest
-             >>> request = HTTPRequest(None, None, {}, None)
-             >>> bim = CookieClientIdManager()
+            >>> from zope.publisher.http import HTTPRequest
+            >>> request = HTTPRequest(None, None, {}, None)
+            >>> bim = CookieClientIdManager()
 
-           Because no cookie has been set, we get no id:
+        Because no cookie has been set, we get no id:
 
-             >>> bim.getRequestId(request) is None
-             True
-             >>> id1 = bim.generateUniqueId()
+            >>> bim.getRequestId(request) is None
+            True
+            >>> id1 = bim.generateUniqueId()
 
-           We can set an id:
+        We can set an id:
 
-             >>> bim.setRequestId(request, id1)
+            >>> bim.setRequestId(request, id1)
 
-           And get it back:
+        And get it back:
 
-             >>> bim.getRequestId(request) == id1
-             True
+            >>> bim.getRequestId(request) == id1
+            True
 
-           When we set the request id, we also set a response cookie.  We
-           can simulate getting this cookie back in a subsequent request:
+        When we set the request id, we also set a response cookie.  We
+        can simulate getting this cookie back in a subsequent request:
 
-             >>> request2 = HTTPRequest(None, None, {}, None)
-             >>> request2._cookies = dict(
-             ...   [(name, cookie['value'])
-             ...    for (name, cookie) in request.response._cookies.items()
-             ...   ])
+            >>> request2 = HTTPRequest(None, None, {}, None)
+            >>> request2._cookies = dict(
+            ...   [(name, cookie['value'])
+            ...    for (name, cookie) in request.response._cookies.items()
+            ...   ])
 
-           And we get the same id back from the new request:
+        And we get the same id back from the new request:
 
-             >>> bim.getRequestId(request) == bim.getRequestId(request2)
-             True
+            >>> bim.getRequestId(request) == bim.getRequestId(request2)
+            True
 
-           """
+        """
 
         # If there is an id set on the response, use that but don't trust it.
         # We need to check the response in case there has already been a new
@@ -200,54 +199,55 @@
     def setRequestId(self, request, id):
         """Set cookie with id on request.
 
-           This sets the response cookie:
+        This sets the response cookie:
 
-           See the examples in getRequestId.
+        See the examples in getRequestId.
 
-           Note that the id is checkec for validity. Setting an
-           invalid value is silently ignored:
+        Note that the id is checkec for validity. Setting an
+        invalid value is silently ignored:
 
-             >>> from zope.publisher.http import HTTPRequest
-             >>> request = HTTPRequest(None, None, {}, None)
-             >>> bim = CookieClientIdManager()
-             >>> bim.getRequestId(request)
-             >>> bim.setRequestId(request, 'invalid id')
-             >>> bim.getRequestId(request)
+            >>> from zope.publisher.http import HTTPRequest
+            >>> request = HTTPRequest(None, None, {}, None)
+            >>> bim = CookieClientIdManager()
+            >>> bim.getRequestId(request)
+            >>> bim.setRequestId(request, 'invalid id')
+            >>> bim.getRequestId(request)
 
-           For now, the cookie path is the application URL:
+        For now, the cookie path is the application URL:
 
-             >>> cookie = request.response.getCookie(bim.namespace)
-             >>> cookie['path'] == request.getApplicationURL(path_only=True)
-             True
+            >>> cookie = request.response.getCookie(bim.namespace)
+            >>> cookie['path'] == request.getApplicationURL(path_only=True)
+            True
 
-           In the future, it should be the site containing the
-           CookieClientIdManager
+        In the future, it should be the site containing the
+        CookieClientIdManager
 
-           By default, session cookies don't expire:
+        By default, session cookies don't expire:
 
-             >>> cookie.has_key('expires')
-             False
+            >>> cookie.has_key('expires')
+            False
 
-           Expiry time of 0 means never (well - close enough)
+        Expiry time of 0 means never (well - close enough)
 
-             >>> bim.cookieLifetime = 0
-             >>> request = HTTPRequest(None, None, {}, None)
-             >>> bid = bim.getClientId(request)
-             >>> cookie = request.response.getCookie(bim.namespace)
-             >>> cookie['expires']
-             'Tue, 19 Jan 2038 00:00:00 GMT'
+            >>> bim.cookieLifetime = 0
+            >>> request = HTTPRequest(None, None, {}, None)
+            >>> bid = bim.getClientId(request)
+            >>> cookie = request.response.getCookie(bim.namespace)
+            >>> cookie['expires']
+            'Tue, 19 Jan 2038 00:00:00 GMT'
 
-           A non-zero value means to expire after than number of seconds:
+        A non-zero value means to expire after than number of seconds:
 
-             >>> bim.cookieLifetime = 3600
-             >>> request = HTTPRequest(None, None, {}, None)
-             >>> bid = bim.getClientId(request)
-             >>> cookie = request.response.getCookie(bim.namespace)
-             >>> import rfc822
-             >>> expires = time.mktime(rfc822.parsedate(cookie['expires']))
-             >>> expires > time.mktime(time.gmtime()) + 55*60
-             True
-           """
+            >>> bim.cookieLifetime = 3600
+            >>> request = HTTPRequest(None, None, {}, None)
+            >>> bid = bim.getClientId(request)
+            >>> cookie = request.response.getCookie(bim.namespace)
+            >>> import rfc822
+            >>> expires = time.mktime(rfc822.parsedate(cookie['expires']))
+            >>> expires > time.mktime(time.gmtime()) + 55*60
+            True
+
+        """
         # TODO: Currently, the path is the ApplicationURL. This is reasonable,
         #     and will be adequate for most purposes.
         #     A better path to use would be that of the folder that contains

Modified: Zope3/trunk/src/zope/app/session/interfaces.py
===================================================================
--- Zope3/trunk/src/zope/app/session/interfaces.py	2004-07-12 14:58:12 UTC (rev 26426)
+++ Zope3/trunk/src/zope/app/session/interfaces.py	2004-07-12 16:05:02 UTC (rev 26427)
@@ -35,6 +35,7 @@
         session id will be preserved. Depending on the specific method,
         further action might be necessary on the part of the user.  See the
         documentation for the specific implementation and its interfaces.
+
         """
 
 
@@ -58,6 +59,7 @@
     Note that this interface does not support the full mapping interface -
     the keys need to remain secret so we can't give access to keys(), 
     values() etc.
+
     """
     timeout = schema.Int(
             title=_(u"Timeout"),
@@ -93,22 +95,30 @@
     """This object allows retrieval of the correct ISessionData
     for a particular product id
     
-    >>> session = ISession(request)[product_id]
-    >>> session['color'] = 'red'
-    True
+        >>> session = ISession(request)[product_id]
+        >>> session['color'] = 'red'
+        True
 
-    >>> ISessionData.providedBy(session)
-    True
+        >>> ISessionData.providedBy(session)
+        True
+
     """
 
     def __getitem__(product_id):
-        """Locate the correct ISessionDataContainer for the given product id
-        and return that product id's ISessionData"""
+        """Return the relevant ISessionData
+        
+        This involves locating the correct ISessionDataContainer for the 
+        given product id and return that product id's ISessionData
+        
+        """
 
 
 class ISessionData(IReadMapping, IMapping):
-    """Storage for a particular product id's session data, containing
-    0 or more ISessionPkgData instances"""
+    """Storage for a particular product id's session data
+    
+    Contains 0 or more ISessionPkgData instances
+    
+    """
 
     lastAccessTime = schema.Int(
             title=_("Last Access Time"),
@@ -135,6 +145,7 @@
 
     Data is stored persistently and transactionally. Data stored must
     be persistent or pickable.
+
     """
 
 # BBB, generation 0, 2004-07-12

Modified: Zope3/trunk/src/zope/app/session/session.py
===================================================================
--- Zope3/trunk/src/zope/app/session/session.py	2004-07-12 14:58:12 UTC (rev 26426)
+++ Zope3/trunk/src/zope/app/session/session.py	2004-07-12 16:05:02 UTC (rev 26427)
@@ -11,8 +11,7 @@
 # FOR A PARTICULAR PURPOSE.
 #
 ##############################################################################
-"""
-Session implementation
+"""Session implementation
 
 $Id$
 """
@@ -58,6 +57,7 @@
         True
 
         >>> tests.tearDown()
+
     """
     implements(IClientId)
 
@@ -89,33 +89,33 @@
             >>> sdc.resolution = 3
             >>> sdc['clientid'] = sd = SessionData()
 
-            To ensure stale data is removed, we can wind
-            back the clock using undocumented means...
+        To ensure stale data is removed, we can wind
+        back the clock using undocumented means...
             
             >>> sd.lastAccessTime = sd.lastAccessTime - 64
             >>> sdc._v_last_sweep = sdc._v_last_sweep - 4
 
-            Now the data should be garbage collected
+        Now the data should be garbage collected
 
             >>> sdc['clientid']
             Traceback (most recent call last):
                 [...]
             KeyError: 'clientid'
 
-            Ensure lastAccessTime on the ISessionData is being updated 
-            occasionally. The ISessionDataContainer maintains this whenever
-            the ISessionData is set or retrieved.
+        Ensure lastAccessTime on the ISessionData is being updated 
+        occasionally. The ISessionDataContainer maintains this whenever
+        the ISessionData is set or retrieved.
 
-            lastAccessTime on the ISessionData is set when it is added
-            to the ISessionDataContainer
+        lastAccessTime on the ISessionData is set when it is added
+        to the ISessionDataContainer
 
             >>> sdc['client_id'] = sd = SessionData()
             >>> sd.lastAccessTime > 0
             True
 
-            lastAccessTime is also updated whenever the ISessionData
-            is retrieved through the ISessionDataContainer, at most
-            once every 'resolution' seconds.
+        lastAccessTime is also updated whenever the ISessionData
+        is retrieved through the ISessionDataContainer, at most
+        once every 'resolution' seconds.
 
             >>> then = sd.lastAccessTime = sd.lastAccessTime - 4
             >>> now = sdc['client_id'].lastAccessTime
@@ -125,15 +125,16 @@
             >>> now == sdc['client_id'].lastAccessTime
             True
 
-            Ensure lastAccessTime is not modified and no garbage collection
-            occurs when timeout == 0. We test this by faking a stale
-            ISessionData object.
+        Ensure lastAccessTime is not modified and no garbage collection
+        occurs when timeout == 0. We test this by faking a stale
+        ISessionData object.
 
             >>> sdc.timeout = 0
             >>> sd.lastAccessTime = sd.lastAccessTime - 5000
             >>> lastAccessTime = sd.lastAccessTime
             >>> sdc['client_id'].lastAccessTime == lastAccessTime
             True
+
         """
         if self.timeout == 0:
             return IterableUserDict.__getitem__(self, pkg_id)
@@ -160,7 +161,7 @@
             >>> sdc = PersistentSessionDataContainer()
             >>> sad = SessionData()
 
-            __setitem__ sets the ISessionData's lastAccessTime
+        __setitem__ sets the ISessionData's lastAccessTime
 
             >>> sad.lastAccessTime
             0
@@ -168,11 +169,12 @@
             >>> 0 < sad.lastAccessTime <= time.time()
             True
 
-            We can retrieve the same object we put in
+        We can retrieve the same object we put in
 
             >>> sdc['1'] is sad
             True
-            """
+
+        """
         session_data.lastAccessTime = int(time.time())
         return IterableUserDict.__setitem__(self, pkg_id, session_data)
 
@@ -183,12 +185,12 @@
             >>> sdc['1'] = SessionData()
             >>> sdc['2'] = SessionData()
 
-            Wind back the clock on one of the ISessionData's
-            so it gets garbage collected
+        Wind back the clock on one of the ISessionData's
+        so it gets garbage collected
 
             >>> sdc['2'].lastAccessTime -= sdc.timeout * 2
 
-            Sweep should leave '1' and remove '2'
+        Sweep should leave '1' and remove '2'
 
             >>> sdc.sweep()
             >>> sd1 = sdc['1']
@@ -196,7 +198,8 @@
             Traceback (most recent call last):
                 [...]
             KeyError: '2'
-            """
+
+        """
         # We only update the lastAccessTime every 'resolution' seconds.
         # To compensate for this, we factor in the resolution when
         # calculating the expiry time to ensure that we never remove
@@ -213,9 +216,10 @@
 
 
 class RAMSessionDataContainer(PersistentSessionDataContainer):
-    """A SessionDataContainer that stores data in RAM. Currently session
-        data is not shared between Zope clients, so server affinity will
-        need to be maintained to use this in a ZEO cluster.
+    """A SessionDataContainer that stores data in RAM.
+    
+    Currently session data is not shared between Zope clients, so 
+    server affinity will need to be maintained to use this in a ZEO cluster.
 
         >>> sdc = RAMSessionDataContainer()
         >>> sdc['1'] = SessionData()
@@ -223,7 +227,8 @@
         True
         >>> ISessionData.providedBy(sdc['1'])
         True
-        """
+
+    """
     def __init__(self):
         self.resolution = 5*60
         self.timeout = 1 * 60 * 60
@@ -270,24 +275,24 @@
             >>> ISession.providedBy(Session(request))
             True
 
-            Setup some sessions, each with a distinct namespace
+        Setup some sessions, each with a distinct namespace
 
             >>> session1 = Session(request)['products.foo']
             >>> session2 = Session(request)['products.bar']
             >>> session3 = Session(request2)['products.bar']
 
-            If we use the same parameters, we should retrieve the
-            same object
+        If we use the same parameters, we should retrieve the
+        same object
 
             >>> session1 is Session(request)['products.foo']
             True
 
-            Make sure it returned sane values
+        Make sure it returned sane values
 
             >>> ISessionPkgData.providedBy(session1)
             True
 
-            Make sure that pkg_ids don't share a namespace.
+        Make sure that pkg_ids don't share a namespace.
 
             >>> session1['color'] = 'red'
             >>> session2['color'] = 'blue'
@@ -300,6 +305,7 @@
             'vomit'
 
             >>> tests.tearDown()
+
         """
 
         # First locate the ISessionDataContainer by looking up
@@ -332,6 +338,7 @@
         True
         >>> session.lastAccessTime
         0
+
     """
     implements(ISessionData)
     lastAccessTime = 0

Modified: Zope3/trunk/src/zope/app/session/tests.py
===================================================================
--- Zope3/trunk/src/zope/app/session/tests.py	2004-07-12 14:58:12 UTC (rev 26426)
+++ Zope3/trunk/src/zope/app/session/tests.py	2004-07-12 16:05:02 UTC (rev 26427)
@@ -12,9 +12,9 @@
 # FOR A PARTICULAR PURPOSE.
 #
 ##############################################################################
-'''
+"""
 $Id$
-'''
+"""
 import unittest, doctest, os, os.path, sys
 from zope.app import zapi
 from zope.app.tests import ztapi, placelesssetup



More information about the Zope3-Checkins mailing list