[Checkins] SVN: zope.component/tseaver-test_cleanup/ Move examples to Sphinx API docs.

[Tres Seaver]

Log message for revision 127087:
  Move examples to Sphinx API docs.

Changed:
  _U  zope.component/tseaver-test_cleanup/
  A   zope.component/tseaver-test_cleanup/docs/api/security.rst
  U   zope.component/tseaver-test_cleanup/docs/api.rst
  U   zope.component/tseaver-test_cleanup/src/zope/component/security.py

-=-
Added: zope.component/tseaver-test_cleanup/docs/api/security.rst
===================================================================
--- zope.component/tseaver-test_cleanup/docs/api/security.rst	                        (rev 0)
+++ zope.component/tseaver-test_cleanup/docs/api/security.rst	2012-06-26 00:27:05 UTC (rev 127087)
@@ -0,0 +1,96 @@
+Security APIs
+=============
+
+.. automodule:: zope.component.security
+
+   .. autofunction:: securityAdapterFactory
+
+If a permission is provided when wrapping the adapter, it will be
+wrapped in a LocatingAdapterFactory.
+
+.. doctest::
+
+   >>> class Factory(object):
+   ...     pass
+
+If both locate and trusted are False and a non-public
+permission is provided, then the factory is wrapped into a
+LocatingUntrustedAdapterFactory:
+
+.. doctest::
+
+   >>> from zope.component.security import securityAdapterFactory
+   >>> from zope.security.adapter import LocatingUntrustedAdapterFactory
+   >>> factory = securityAdapterFactory(Factory, 'zope.AnotherPermission',
+   ...    locate=False, trusted=False)
+   >>> isinstance(factory, LocatingUntrustedAdapterFactory)
+   True
+
+If a PublicPermission is provided, then the factory is not touched.
+
+.. doctest::
+
+   >>> from zope.component.security import PublicPermission
+   >>> factory = securityAdapterFactory(Factory, PublicPermission,
+   ...    locate=False, trusted=False)
+   >>> factory is Factory
+   True
+
+Same for CheckerPublic:
+
+.. doctest::
+
+   >>> from zope.security.checker import CheckerPublic
+   >>> factory = securityAdapterFactory(Factory, CheckerPublic,
+   ...    locate=False, trusted=False)
+   >>> factory is Factory
+   True
+
+If the permission is None, the factory isn't touched:
+
+.. doctest::
+
+   >>> factory = securityAdapterFactory(Factory, None,
+   ...    locate=False, trusted=False)
+   >>> factory is Factory
+   True
+
+If the factory is trusted and a no permission is provided then the
+adapter is wrapped into a TrustedAdapterFactory:
+
+.. doctest::
+
+   >>> from zope.security.adapter import TrustedAdapterFactory
+   >>> factory = securityAdapterFactory(Factory, None,
+   ...    locate=False, trusted=True)
+   >>> isinstance(factory, TrustedAdapterFactory)
+   True
+
+Same for PublicPermission:
+
+.. doctest::
+
+   >>> factory = securityAdapterFactory(Factory, PublicPermission,
+   ...    locate=False, trusted=True)
+   >>> isinstance(factory, TrustedAdapterFactory)
+   True
+
+Same for CheckerPublic:
+
+.. doctest::
+
+   >>> factory = securityAdapterFactory(Factory, CheckerPublic,
+   ...    locate=False, trusted=True)
+   >>> isinstance(factory, TrustedAdapterFactory)
+   True
+
+If the factory is trusted and a locate is true, then the
+adapter is wrapped into a LocatingTrustedAdapterFactory:
+
+.. doctest::
+
+   >>> from zope.security.adapter import LocatingTrustedAdapterFactory
+   >>> factory = securityAdapterFactory(Factory, 'zope.AnotherPermission',
+   ...    locate=True, trusted=True)
+   >>> isinstance(factory, LocatingTrustedAdapterFactory)
+   True

Modified: zope.component/tseaver-test_cleanup/docs/api.rst
===================================================================
--- zope.component/tseaver-test_cleanup/docs/api.rst	2012-06-26 00:27:01 UTC (rev 127086)
+++ zope.component/tseaver-test_cleanup/docs/api.rst	2012-06-26 00:27:05 UTC (rev 127087)
@@ -11,3 +11,4 @@
    api/adapter
    api/factory
    api/interface
+   api/security

Modified: zope.component/tseaver-test_cleanup/src/zope/component/security.py
===================================================================
--- zope.component/tseaver-test_cleanup/src/zope/component/security.py	2012-06-26 00:27:01 UTC (rev 127086)
+++ zope.component/tseaver-test_cleanup/src/zope/component/security.py	2012-06-26 00:27:05 UTC (rev 127087)
@@ -13,13 +13,15 @@
 ##############################################################################
 """zope.security support for the configuration handlers
 """
-__docformat__ = "reStructuredText"
-
 from zope.interface import providedBy
-from zope.proxy import ProxyBase, getProxiedObject
-from zope.security.adapter import LocatingTrustedAdapterFactory, \
-    LocatingUntrustedAdapterFactory, TrustedAdapterFactory
-from zope.security.checker import Checker, CheckerPublic, InterfaceChecker
+from zope.proxy import ProxyBase
+from zope.proxy import getProxiedObject
+from zope.security.adapter import LocatingTrustedAdapterFactory
+from zope.security.adapter import LocatingUntrustedAdapterFactory
+from zope.security.adapter import TrustedAdapterFactory
+from zope.security.checker import Checker
+from zope.security.checker import CheckerPublic
+from zope.security.checker import InterfaceChecker
 from zope.security.proxy import Proxy
 
 
@@ -85,82 +87,6 @@
     return factory
 
 def securityAdapterFactory(factory, permission, locate, trusted):
-    """
-    If a permission is provided when wrapping the adapter, it will be
-    wrapped in a LocatingAdapterFactory.
-
-      >>> class Factory:
-      ...     pass
-
-    If both locate and trusted are False and a non-public
-    permission is provided, then the factory is wrapped into a
-    LocatingUntrustedAdapterFactory:
-
-      >>> factory = securityAdapterFactory(Factory, 'zope.AnotherPermission',
-      ...    locate=False, trusted=False)
-
-      >>> isinstance(factory, LocatingUntrustedAdapterFactory)
-      True
-
-    If a PublicPermission is provided, then the factory is not touched.
-
-      >>> factory = securityAdapterFactory(Factory, PublicPermission,
-      ...    locate=False, trusted=False)
-
-      >>> factory is Factory
-      True
-
-    Same for CheckerPublic:
-
-      >>> factory = securityAdapterFactory(Factory, CheckerPublic,
-      ...    locate=False, trusted=False)
-
-      >>> factory is Factory
-      True
-
-    If the permission is None, the factory isn't touched:
-
-      >>> factory = securityAdapterFactory(Factory, None,
-      ...    locate=False, trusted=False)
-
-      >>> factory is Factory
-      True
-
-    If the factory is trusted and a no permission is provided then the
-    adapter is wrapped into a TrustedAdapterFactory:
-
-      >>> factory = securityAdapterFactory(Factory, None,
-      ...    locate=False, trusted=True)
-
-      >>> isinstance(factory, TrustedAdapterFactory)
-      True
-
-    Same for PublicPermission:
-
-      >>> factory = securityAdapterFactory(Factory, PublicPermission,
-      ...    locate=False, trusted=True)
-
-      >>> isinstance(factory, TrustedAdapterFactory)
-      True
-
-    Same for CheckerPublic:
-
-      >>> factory = securityAdapterFactory(Factory, CheckerPublic,
-      ...    locate=False, trusted=True)
-
-      >>> isinstance(factory, TrustedAdapterFactory)
-      True
-
-    If the factory is trusted and a locate is true, then the
-    adapter is wrapped into a LocatingTrustedAdapterFactory:
-
-      >>> factory = securityAdapterFactory(Factory, 'zope.AnotherPermission',
-      ...    locate=True, trusted=True)
-
-      >>> isinstance(factory, LocatingTrustedAdapterFactory)
-      True
-
-    """
     if permission == PublicPermission:
         permission = CheckerPublic
     if locate or (permission is not None and permission is not CheckerPublic):