From 925580d4cefde38afd98466b4834a586c9b4c7ef Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Fri, 27 Nov 2009 08:45:56 +0000 Subject: Add threadlocal to API. --- repoze/bfg/threadlocal.py | 33 ++++++++++++++++++--------------- 1 file changed, 18 insertions(+), 15 deletions(-) (limited to 'repoze') 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'] -- cgit v1.2.3