summaryrefslogtreecommitdiff
path: root/docs/narr/threadlocals.rst
diff options
context:
space:
mode:
authorChris McDonough <chrism@plope.com>2011-01-27 23:06:55 -0500
committerChris McDonough <chrism@plope.com>2011-01-27 23:06:55 -0500
commit70acd25f40f32fc6cbb3b5d38a695b8982b52a31 (patch)
treeecaee199a36054a3664c39a7955cb441aaf6503d /docs/narr/threadlocals.rst
parent45c45f3ba6b688c988957056cb2c49883329dfe5 (diff)
downloadpyramid-70acd25f40f32fc6cbb3b5d38a695b8982b52a31.tar.gz
pyramid-70acd25f40f32fc6cbb3b5d38a695b8982b52a31.tar.bz2
pyramid-70acd25f40f32fc6cbb3b5d38a695b8982b52a31.zip
module name contractions
Diffstat (limited to 'docs/narr/threadlocals.rst')
-rw-r--r--docs/narr/threadlocals.rst18
1 files changed, 9 insertions, 9 deletions
diff --git a/docs/narr/threadlocals.rst b/docs/narr/threadlocals.rst
index 13bfe41cb..909f643a0 100644
--- a/docs/narr/threadlocals.rst
+++ b/docs/narr/threadlocals.rst
@@ -32,7 +32,7 @@ bad idea, at least if code readability counts as an important concern.
For historical reasons, however, thread local variables are indeed
consulted by various :app:`Pyramid` API functions. For example,
the implementation of the :mod:`pyramid.security` function named
-:func:`pyramid.security.authenticated_userid` retrieves the thread
+:func:`~pyramid.security.authenticated_userid` retrieves the thread
local :term:`application registry` as a matter of course to find an
:term:`authentication policy`. It uses the
:func:`pyramid.threadlocal.get_current_registry` function to
@@ -43,8 +43,8 @@ allows arbitrary authentication policies to be "plugged in".
When they need to do so, :app:`Pyramid` internals use two API
functions to retrieve the :term:`request` and :term:`application
-registry`: :func:`pyramid.threadlocal.get_current_request` and
-:func:`pyramid.threadlocal.get_current_registry`. The former
+registry`: :func:`~pyramid.threadlocal.get_current_request` and
+:func:`~pyramid.threadlocal.get_current_registry`. The former
returns the "current" request; the latter returns the "current"
registry. Both ``get_current_*`` functions retrieve an object from a
thread-local data structure. These API functions are documented in
@@ -88,17 +88,17 @@ the :mod:`pyramid.scripting` API will never cause any Router code
to be executed. However, the :mod:`pyramid.scripting` APIs also
push some values on to the thread locals stack as a matter of course.
Such scripts should expect the
-:func:`pyramid.threadlocal.get_current_request` function to always
+:func:`~pyramid.threadlocal.get_current_request` function to always
return ``None``, and should expect the
-:func:`pyramid.threadlocal.get_current_registry` function to return
+:func:`~pyramid.threadlocal.get_current_registry` function to return
exactly the same :term:`application registry` for every request.
Why You Shouldn't Abuse Thread Locals
-------------------------------------
You probably should almost never use the
-:func:`pyramid.threadlocal.get_current_request` or
-:func:`pyramid.threadlocal.get_current_registry` functions, except
+:func:`~pyramid.threadlocal.get_current_request` or
+:func:`~pyramid.threadlocal.get_current_registry` functions, except
perhaps in tests. In particular, it's almost always a mistake to use
``get_current_request`` or ``get_current_registry`` in application
code because its usage makes it possible to write code that can be
@@ -134,7 +134,7 @@ follows:
application depend upon it) means you're forming a dependency in the
wrong direction.
-Use of the :func:`pyramid.threadlocal.get_current_request` function
+Use of the :func:`~pyramid.threadlocal.get_current_request` function
in application code *is* still useful in very limited circumstances.
As a rule of thumb, usage of ``get_current_request`` is useful
**within code which is meant to eventually be removed**. For
@@ -151,7 +151,7 @@ time, the older implementation code is disused and the hack that uses
``get_current_request`` is removed. This would be an appropriate
place to use the ``get_current_request``.
-Use of the :func:`pyramid.threadlocal.get_current_registry`
+Use of the :func:`~pyramid.threadlocal.get_current_registry`
function should be limited to testing scenarios. The registry made
current by use of the
:meth:`pyramid.config.Configurator.begin` method during a