Add threadlocal to API.

3 files changed, 30 insertions, 15 deletions

diff --git a/docs/api/threadlocal.rst b/docs/api/threadlocal.rst
new file mode 100644
index 000000000..0c4a5a1ca
--- /dev/null
+++ b/docs/api/threadlocal.rst
@@ -0,0 +1,11 @@
+.. _configuration_module:
+
+:mod:`repoze.bfg.configuration`
+-------------------------------
+
+.. automodule:: repoze.bfg.threadlocal
+
+   .. autofunction:: get_current_request()
+
+   .. autofunction:: get_current_registry()
+
diff --git a/docs/index.rst b/docs/index.rst
index 97261b27a..da05ef4ba 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -77,6 +77,7 @@ Per-module :mod:`repoze.bfg` API documentation.
    api/security
    api/settings
    api/testing
+   api/threadlocal
    api/traversal
    api/url
    api/view
diff --git a/repoze/bfg/threadlocal.py b/repoze/bfg/threadlocal.py
index 5284b743f..cfd3e78ba 100644
--- a/repoze/bfg/threadlocal.py
+++ b/repoze/bfg/threadlocal.py
@@ -36,18 +36,13 @@ def defaults():
 
 manager = ThreadLocalManager(default=defaults)
 
-## **The below function ``get_current*`` functions are special.  They
-## are not part of the official BFG API, however, they're guaranteed
-## to live here "forever", so they may be relied on in emergencies.
-## However, they should be used extremely sparingly** (read: almost
-## never).
+## **The below function ``get_current*`` functions should be used
+## extremely sparingly.
 
 ## In particular, it's almost always usually a mistake to use
 ## ``get_current_request`` because its usage makes it possible to
-## write code that can be neither easily tested nor scripted.  The
-## author of this function reserves the right to point and laugh at
-## code which uses this function inappropriately.  Inappropriate usage
-## is defined as follows:
+## write code that can be neither easily tested nor scripted.
+## Inappropriate usage is defined as follows:
 
 ## - ``get_current_request`` should never be called within
 ##   :term:`view` code, or code called by view code.  View code
@@ -107,19 +102,27 @@ manager = ThreadLocalManager(default=defaults)
 ## to be executed.  Such scripts should expect this function to
 ## always return ``None``.
 
-## ``get_current_registry`` is mostly non-useful if you use the ZCA
-## API zope.component.getSiteManager will call it for you.
-
 def get_current_request():
     """Return the currently active request or ``None`` if no request
-    is currently active.  This is *not* an official API.
+    is currently active.
+
+    This function should be used *extremely sparingly*, usually only
+    in unit testing code.  it's almost always usually a mistake to use
+    ``get_current_request`` outside a testing context because its
+    usage makes it possible to write code that can be neither easily
+    tested nor scripted.
     """
     return manager.get()['request']
 
 def get_current_registry(context=None): # context required by getSiteManager API
     """Return the currently active component registry or the global
-    component registry if no request is currently active.  This is
-    *not* an official API.
+    component registry if no request is currently active.
+
+    This function should be used *extremely sparingly*, usually only
+    in unit testing code.  it's almost always usually a mistake to use
+    ``get_current_registry`` outside a testing context because its
+    usage makes it possible to write code that can be neither easily
+    tested nor scripted.
     """
     return manager.get()['registry']