[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