[Checkins] SVN: zope.security/trunk/ Convert doctests in 'zope.security.permission' into Sphinx doctest snppets.

Tres Seaver cvs-admin at zope.org
Sun Dec 23 20:54:02 UTC 2012


Log message for revision 128864:
  Convert doctests in 'zope.security.permission' into Sphinx doctest snppets.
  
  They are still tested under 'tox -e docs'.

Changed:
  _U  zope.security/trunk/
  A   zope.security/trunk/docs/api/permissions.rst
  U   zope.security/trunk/docs/index.rst
  U   zope.security/trunk/src/zope/security/permission.py
  U   zope.security/trunk/src/zope/security/tests/test_permission.py

-=-
Added: zope.security/trunk/docs/api/permissions.rst
===================================================================
--- zope.security/trunk/docs/api/permissions.rst	                        (rev 0)
+++ zope.security/trunk/docs/api/permissions.rst	2012-12-23 20:54:02 UTC (rev 128864)
@@ -0,0 +1,133 @@
+Defining and Using Permissions
+==============================
+
+.. testsetup::
+
+   from zope.component.testing import setUp
+   setUp()
+
+.. autoclass:: zope.security.permission.Permission
+   :members:
+   :member-order: bysource
+
+
+.. autofunction:: zope.security.permission.checkPermission
+
+.. doctest::
+
+   >>> from zope.security.permission import checkPermission
+   >>> from zope.component import provideUtility
+   >>> from zope.security.interfaces import IPermission
+   >>> from zope.security.permission import Permission
+   >>> x = Permission('x')
+   >>> provideUtility(x, IPermission, 'x')
+
+   >>> checkPermission(None, 'x')
+   >>> checkPermission(None, 'y')
+   Traceback (most recent call last):
+   ...
+   ValueError: ('Undefined permission id', 'y')
+   
+The :data:`zope.security.checker.CheckerPublic` permission always exists:
+
+.. doctest::
+   
+   >>> from zope.security.checker import CheckerPublic
+   >>> checkPermission(None, CheckerPublic)
+
+
+.. autofunction:: zope.security.permission.allPermissions
+
+.. doctest::
+
+   >>> from zope.security.permission import allPermissions
+   >>> from zope.component import provideUtility
+   >>> y = Permission('y')
+   >>> provideUtility(y, IPermission, 'y')
+
+   >>> ids = list(allPermissions(None))
+   >>> ids.sort()
+   >>> ids
+   [u'x', u'y']
+
+
+.. autofunction:: zope.security.permission.PermissionsVocabulary
+
+To illustrate, we need to register the permissions vocabulary:
+
+.. doctest::
+
+   >>> from zope.security.permission import PermissionsVocabulary
+   >>> from zope.schema.vocabulary import _clear
+   >>> _clear()
+
+   >>> from zope.schema.vocabulary import getVocabularyRegistry
+   >>> registry = getVocabularyRegistry()
+   >>> registry.register('Permissions', PermissionsVocabulary)
+
+We can now lookup the permissions we created earlier using the vocabulary:
+
+.. doctest::
+
+   >>> vocab = registry.get(None, 'Permissions')
+   >>> vocab.getTermByToken('x').value is x
+   True
+   >>> vocab.getTermByToken('y').value is y
+   True
+
+
+.. autofunction:: zope.security.permission.PermissionIdsVocabulary
+
+To illustrate, we need to register the permission IDs vocabulary:
+
+.. doctest::
+
+   >>> from zope.security.permission import PermissionIdsVocabulary
+   >>> registry.register('Permission Ids', PermissionIdsVocabulary)
+
+   We also need to register the special 'zope.Public' permission:
+
+   >>> provideUtility(Permission('zope.Public'), IPermission, 'zope.Public')
+
+We can now lookup these permissions using the vocabulary:
+
+.. doctest::
+
+   >>> vocab = registry.get(None, 'Permission Ids')
+
+The non-public permissions 'x' and 'y' are string values:
+
+.. doctest::
+
+   >>> vocab.getTermByToken('x').value
+   u'x'
+   >>> vocab.getTermByToken('y').value
+   u'y'
+
+However, the public permission value is CheckerPublic:
+
+.. doctest::
+
+   >>> vocab.getTermByToken('zope.Public').value is CheckerPublic
+   True
+
+and its title is shortened:
+
+.. doctest::
+
+   >>> vocab.getTermByToken('zope.Public').title
+   u'Public'
+
+The terms are sorted by title except for the public permission, which is
+listed first:
+
+.. doctest::
+
+   >>> [term.title for term in vocab]
+   [u'Public', u'x', u'y']
+
+
+.. testcleanup::
+
+   from zope.component.testing import tearDown
+   tearDown()

Modified: zope.security/trunk/docs/index.rst
===================================================================
--- zope.security/trunk/docs/index.rst	2012-12-23 20:54:01 UTC (rev 128863)
+++ zope.security/trunk/docs/index.rst	2012-12-23 20:54:02 UTC (rev 128864)
@@ -7,6 +7,7 @@
    :maxdepth: 2
 
    api/interfaces
+   api/permissions
 
 
 

Modified: zope.security/trunk/src/zope/security/permission.py
===================================================================
--- zope.security/trunk/src/zope/security/permission.py	2012-12-23 20:54:01 UTC (rev 128863)
+++ zope.security/trunk/src/zope/security/permission.py	2012-12-23 20:54:02 UTC (rev 128864)
@@ -32,23 +32,6 @@
 
 def checkPermission(context, permission_id):
     """Check whether a given permission exists in the provided context.
-
-    >>> from zope.component.testing import setUp, tearDown
-    >>> setUp()
-    >>> from zope.component import provideUtility
-    >>> provideUtility(Permission('x'), IPermission, 'x')
-
-    >>> checkPermission(None, 'x')
-    >>> checkPermission(None, 'y')
-    Traceback (most recent call last):
-    ...
-    ValueError: ('Undefined permission id', 'y')
-    
-    The CheckerPublic always exists:
-    
-    >>> checkPermission(None, CheckerPublic)
-    >>> tearDown()
-    
     """
     if permission_id is CheckerPublic:
         return
@@ -57,18 +40,6 @@
 
 def allPermissions(context=None):
     """Get the ids of all defined permissions
-
-    >>> from zope.component.testing import setUp, tearDown
-    >>> setUp()
-    >>> from zope.component import provideUtility
-    >>> provideUtility(Permission('x'), IPermission, 'x')
-    >>> provideUtility(Permission('y'), IPermission, 'y')
-
-    >>> ids = list(allPermissions(None))
-    >>> ids.sort()
-    >>> ids
-    [u'x', u'y']
-    >>> tearDown()
     """
     for id, permission in getUtilitiesFor(IPermission, context):
         if id != u'zope.Public':
@@ -78,37 +49,6 @@
     """A vocabulary of permission IDs.
 
     Term values are permissions, while term tokens are permission IDs.
-    
-    To illustrate, we need to register the permission IDs vocabulary:
-
-    >>> from zope.component.testing import setUp, tearDown
-    >>> setUp()
-    >>> from zope.schema.vocabulary import _clear
-    >>> _clear()
-
-    >>> from zope.schema.vocabulary import getVocabularyRegistry
-    >>> registry = getVocabularyRegistry()
-    >>> registry.register('Permissions', PermissionsVocabulary)
-
-    We also need to register some sample permission utilities:
-
-    >>> from zope.security.interfaces import IPermission
-    >>> from zope.security.permission import Permission
-    >>> from zope.component import provideUtility
-    >>> a = Permission('a')
-    >>> b = Permission('b')
-    >>> provideUtility(a, IPermission, 'a')
-    >>> provideUtility(b, IPermission, 'b')
-
-    We can now lookup these permissions using the vocabulary:
-
-    >>> vocab = registry.get(None, 'Permissions')
-    >>> vocab.getTermByToken('a').value is a
-    True
-    >>> vocab.getTermByToken('b').value is b
-    True
-    >>> tearDown()
-
     """
     terms = []
     for id, permission in getUtilitiesFor(IPermission, context):
@@ -128,57 +68,7 @@
 
     Terms are sorted by title except for 'Public', which always appears as
     the first term.
-
-    To illustrate, we need to register the permission IDs vocabulary:
-
-    >>> from zope.component.testing import setUp, tearDown
-    >>> setUp()
-    >>> from zope.schema.vocabulary import _clear
-    >>> _clear()
-
-    >>> from zope.schema.vocabulary import getVocabularyRegistry
-    >>> registry = getVocabularyRegistry()
-    >>> registry.register('Permission Ids', PermissionIdsVocabulary)
-
-    We also need to register some sample permission utilities, including
-    the special permission 'zope.Public':
-
-    >>> from zope.security.interfaces import IPermission
-    >>> from zope.security.permission import Permission
-    >>> from zope.component import provideUtility
-    >>> provideUtility(Permission('zope.Public'), IPermission, 'zope.Public')
-    >>> provideUtility(Permission('b'), IPermission, 'b')
-    >>> provideUtility(Permission('a'), IPermission, 'a')
-
-    We can now lookup these permissions using the vocabulary:
-
-    >>> vocab = registry.get(None, 'Permission Ids')
-
-    The non-public permissions 'a' and 'b' are string values:
-
-    >>> vocab.getTermByToken('a').value
-    u'a'
-    >>> vocab.getTermByToken('b').value
-    u'b'
-
-    However, the public permission value is CheckerPublic:
-
-    >>> vocab.getTermByToken('zope.Public').value is CheckerPublic
-    True
-
-    and its title is shortened:
-
-    >>> vocab.getTermByToken('zope.Public').title
-    u'Public'
-
-    The terms are sorted by title except for the public permission, which is
-    listed first:
-
-    >>> [term.title for term in vocab]
-    [u'Public', u'a', u'b']
-    >>> tearDown()
     """
-
     terms = []
     for name, permission in getUtilitiesFor(IPermission, context):
         if name == 'zope.Public':

Modified: zope.security/trunk/src/zope/security/tests/test_permission.py
===================================================================
--- zope.security/trunk/src/zope/security/tests/test_permission.py	2012-12-23 20:54:01 UTC (rev 128863)
+++ zope.security/trunk/src/zope/security/tests/test_permission.py	2012-12-23 20:54:02 UTC (rev 128864)
@@ -17,9 +17,5 @@
 
 
 def test_suite():
-    from zope.component.testing import setUp, tearDown
-    from doctest import DocTestSuite
     return unittest.TestSuite([
-        DocTestSuite('zope.security.permission',
-                     setUp=setUp, tearDown=tearDown),
         ])



More information about the checkins mailing list