From 8525cfd9c5509d8c4c61cc1d2463486be7f01dad Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Thu, 14 May 2009 02:53:03 +0000 Subject: - Added API docs for the ``repoze.bfg.testing`` methods ``registerAdapter``, ``registerUtiity``, ``registerSubscriber``, and ``cleanUp``. - Added glossary entry for "root factory". --- CHANGES.txt | 16 ++++++++++++++-- docs/api/testing.rst | 8 ++++++++ docs/glossary.rst | 10 ++++++++++ repoze/bfg/testing.py | 42 +++++++++++++++++++++++++++++++++++++++++- 4 files changed, 73 insertions(+), 3 deletions(-) diff --git a/CHANGES.txt b/CHANGES.txt index b62768d42..461cbc560 100644 --- a/CHANGES.txt +++ b/CHANGES.txt @@ -1,5 +1,17 @@ +0.8dev +====== + +Documentation +------------- + +- Added API docs for the ``repoze.bfg.testing`` methods + ``registerAdapter``, ``registerUtiity``, ``registerSubscriber``, and + ``cleanUp``. + +- Added glossary entry for "root factory". + 0.8a6 (2009-05-11) -------------------- +================== Features -------- @@ -41,7 +53,7 @@ Bug Fixes part of the final Routes 1.11 release. 0.8a5 (2009-05-08) ------------------- +================== Features -------- diff --git a/docs/api/testing.rst b/docs/api/testing.rst index 9aebc7d30..7870ed1d3 100644 --- a/docs/api/testing.rst +++ b/docs/api/testing.rst @@ -17,6 +17,14 @@ .. autofunction:: registerViewPermission + .. autofunction:: registerUtility + + .. autofunction:: registerAdapter + + .. autofunction:: registerSubscriber + + .. autofunction:: cleanUp + .. autoclass:: DummyModel :members: diff --git a/docs/glossary.rst b/docs/glossary.rst index b55f8395c..6d4d83f51 100644 --- a/docs/glossary.rst +++ b/docs/glossary.rst @@ -338,3 +338,13 @@ Glossary itself, its parent, its parent's parent, and so on. The order of the sequence is context-first, then the parent of the context, then its parent's parent, and so on. + Root Factory + The "root factory" of an :mod:`repoze.bfg` application is called + on every request sent to the application. The root factory + returns the traversal root of an application. It is + conventionally named ``get_root``. An application must supply a + root factory to :mod:`repoze.bfg` within a call to + ``repoze.bfg.router.make_app``; however, an application's root + factory may be passed to ``make_app`` as ``None``, in which case + the application performs no graph traversal and uses :term:`URL + dispatch` for all URL-to-view code mappings. diff --git a/repoze/bfg/testing.py b/repoze/bfg/testing.py index 42d5e88fd..0ff1dbade 100644 --- a/repoze/bfg/testing.py +++ b/repoze/bfg/testing.py @@ -106,12 +106,35 @@ def registerViewPermission(name, result=True, viewpermission=None, return registerAdapter(viewpermission, for_, IViewPermission, name) def registerUtility(impl, iface=Interface, name=''): + """ Register a Zope component architecture utility component. + This is exposed as a convenience in this package to avoid needing + to import the ``registerUtility`` function from ``zope.component`` + within unit tests that make use of the ZCA. ``impl`` is the + implementation of the utility. ``iface`` is the interface type + ``zope.interface.Interface`` by default. ``name`` is the empty + string by default. See `The ZCA book + `_ for more information + about ZCA utilities.""" import zope.component gsm = zope.component.getGlobalSiteManager() gsm.registerUtility(impl, iface, name=name) return impl def registerAdapter(impl, for_=Interface, provides=Interface, name=''): + """ Register a Zope component architecture adapter component. + This is exposed as a convenience in this package to avoid needing + to import the ``registerAdapter`` function from ``zope.component`` + within unit tests that make use of the ZCA. ``impl`` is the + implementation of the component (often a class). ``for_`` is the + ``for`` interface type ``zope.interface.Interface`` by default. If + ``for`` is not a tuple or list, it will be converted to a + one-tuple before being passed to underlying ZCA registerAdapter + API. ``name`` is the empty string by default. ``provides`` is + the ZCA provides interface, also ``zope.interface.Interface`` by + default. ``name`` is the name of the adapter, the empty string by + default. See `The ZCA book + `_ for more information + about ZCA adapters.""" import zope.component gsm = zope.component.getGlobalSiteManager() if not isinstance(for_, (tuple, list)): @@ -120,6 +143,17 @@ def registerAdapter(impl, for_=Interface, provides=Interface, name=''): return impl def registerSubscriber(subscriber, iface=Interface): + """ Register a Zope component architecture subscriber component. + This is exposed as a convenience in this package to avoid needing + to import the ``registerHandler`` function from ``zope.component`` + within unit tests that make use of the ZCA. ``subscriber`` is the + implementation of the component (often a function). ``iface`` is + the interface type the subscriber will be registered for + (``zope.interface.Interface`` by default). If ``iface`` is not a + tuple or list, it will be converted to a one-tuple before being + passed to underlying zca registerHandler query. See `The ZCA book + `_ for more information + about ZCA subscribers.""" import zope.component gsm = zope.component.getGlobalSiteManager() if not isinstance(iface, (tuple, list)): @@ -382,7 +416,13 @@ def addCleanUp(func, args=(), kw={}): _cleanups.append((func, args, kw)) def cleanUp(): - """Clean up global data.""" + """Clean up BFG testing registrations. Use in the ``tearDown`` of + unit tests that use the ``register*`` methods in the testing + module (e.g. if your unit test uses + ``repoze.bfg.testing.registerDummyRenderer`` or + ``repoze.bfg.testing.registerDummySecurityPolicy``). If you use + the ``register*`` functions without calling cleanUp, unit tests + will not be isolated with respect to registrations they perform.""" for func, args, kw in _cleanups: func(*args, **kw) -- cgit v1.2.3