Ñò
ô†³Kc @ sÆ d Z d d k Z d d k i i Z d d d d g Z d e f d „ ƒ YZ d e f d „ ƒ YZ d
e f d „ ƒ YZ d e f d „ ƒ YZ
d e f d
„ ƒ YZ e ƒ Z d „ Z
e
i e
_ d S( s©
Registry for handling request-local module globals sanely
Dealing with module globals in a thread-safe way is good if your
application is the sole responder in a thread, however that approach fails
to properly account for various scenarios that occur with WSGI applications
and middleware.
What is actually needed in the case where a module global is desired that
is always set properly depending on the current request, is a stacked
thread-local object. Such an object is popped or pushed during the request
cycle so that it properly represents the object that should be active for
the current request.
To make it easy to deal with such variables, this module provides a special
StackedObjectProxy class which you can instantiate and attach to your
module where you'd like others to access it. The object you'd like this to
actually "be" during the request is then registered with the
RegistryManager middleware, which ensures that for the scope of the current
WSGI application everything will work properly.
Example:
.. code-block:: python
#yourpackage/__init__.py
from paste.registry import RegistryManager, StackedObjectProxy
myglobal = StackedObjectProxy()
#wsgi app stack
app = RegistryManager(yourapp)
#inside your wsgi app
class yourapp(object):
def __call__(self, environ, start_response):
obj = someobject # The request-local object you want to access
# via yourpackage.myglobal
if environ.has_key('paste.registry'):
environ['paste.registry'].register(myglobal, obj)
You will then be able to import yourpackage anywhere in your WSGI app or in
the calling stack below it and be assured that it is using the object you
registered with Registry.
RegistryManager can be in the WSGI stack multiple times, each time it
appears it registers a new request context.
Performance
===========
The overhead of the proxy object is very minimal, however if you are using
proxy objects extensively (Thousands of accesses per request or more), there
are some ways to avoid them. A proxy object runs approximately 3-20x slower
than direct access to the object, this is rarely your performance bottleneck
when developing web applications.
Should you be developing a system which may be accessing the proxy object
thousands of times per request, the performance of the proxy will start to
become more noticeable. In that circumstance, the problem can be avoided by
getting at the actual object via the proxy with the ``_current_obj`` function:
.. code-block:: python
#sessions.py
Session = StackedObjectProxy()
# ... initialization code, etc.
# somemodule.py
import sessions
def somefunc():
session = sessions.Session._current_obj()
# ... tons of session access
This way the proxy is used only once to retrieve the object for the current
context and the overhead is minimized while still making it easy to access
the underlying object. The ``_current_obj`` function is preceded by an
underscore to more likely avoid clashing with the contained object's
attributes.
**NOTE:** This is *highly* unlikely to be an issue in the vast majority of
cases, and requires incredibly large amounts of proxy object access before
one should consider the proxy object to be causing slow-downs. This section
is provided solely in the extremely rare case that it is an issue so that a
quick way to work around it is documented.
iÿÿÿÿNt StackedObjectProxyt RegistryManagert StackedObjectRestorert restorert NoDefaultc B s e Z RS( ( t __name__t
__module__( ( ( s2 /usr/lib/python2.6/site-packages/paste/registry.pyR b s c B s e Z d Z e d d „ Z d „ Z d „ Z d „ Z d „ Z d „ Z d „ Z
d „ Z d
„ Z d „ Z
d „ Z d
„ Z d „ Z d „ Z d „ Z d „ Z d d „ Z d „ Z d „ Z d e i e _ d „ Z d e i e _ d d „ Z d e i e _ RS( sÈ Track an object instance internally using a stack
The StackedObjectProxy proxies access to an object internally using a
stacked thread-local. This makes it safe for complex WSGI environments
where access to the object may be desired in multiple places without
having to pass the actual object around.
New objects are added to the top of the stack with _push_object while
objects can be removed with _pop_object.
t Defaultc C sB | | i d ( t reprR R t AttributeErrorR R R t id( R ( ( s2 /usr/lib/python2.6/site-packages/paste/registry.pyt __repr__ s c C s t | i ƒ ƒ S( N( t iterR ( R ( ( s2 /usr/lib/python2.6/site-packages/paste/registry.pyt __iter__¥ s c C s t | i ƒ ƒ S( N( t lenR ( R ( ( s2 /usr/lib/python2.6/site-packages/paste/registry.pyt __len__¨ s c C s | | i ƒ j S( N( R ( R R# ( ( s2 /usr/lib/python2.6/site-packages/paste/registry.pyt __contains__« s c C s t | i ƒ ƒ S( N( t boolR ( R ( ( s2 /usr/lib/python2.6/site-packages/paste/registry.pyt __nonzero__® s c C sz y | i i } Wn t j
o
d } n X| o | d S| i i d t ƒ } | t j o | St d | i ƒ ‚ d S( sÙ Returns the current active object being proxied to
In the event that no object was pushed, the default object if
provided will be used. Otherwise, a TypeError will be raised.
iÿÿÿÿR
s8 No object (name: %s) has been registered for this threadN( R t objectsR+ t NoneR t getR R R ( R R5 t obj( ( s2 /usr/lib/python2.6/site-packages/paste/registry.pyR ± s
c C sP y | i i i | ƒ Wn2 t j
o& g | i _ | i i i | ƒ n Xd S( sˆ Make ``obj`` the active object for this thread-local.
This should be used like:
.. code-block:: python
obj = yourobject()
module.glob = StackedObjectProxy()
module.glob._push_object(obj)
try:
... do stuff ...
finally:
module.glob._pop_object(conf)
N( R R5 t appendR+ ( R R8 ( ( s2 /usr/lib/python2.6/site-packages/paste/registry.pyt _push_objectÇ s
c C sj yD | i i i ƒ } | o' | | j o t d | | f ƒ ‚ n Wn t j
o t d ƒ ‚ n Xd S( s² Remove a thread-local object.
If ``obj`` is given, it is checked against the popped object and an
error is emitted if they don't match.
sB The object popped (%s) is not the same as the object expected (%s)s- No object has been registered for this threadN( R R5 t popt AssertionErrorR+ ( R R8 t popped( ( s2 /usr/lib/python2.6/site-packages/paste/registry.pyt _pop_objectÝ s c C s* y | i i SWn t j
o g SXd S( sj Returns all of the objects stacked in this container
(Might return [] if there are none)
N( R R5 R< ( R ( ( s2 /usr/lib/python2.6/site-packages/paste/registry.pyt
_object_stackí s c C s. t i ƒ } | o t i | | ƒ S| i ƒ S( N( R t in_restorationt get_saved_proxied_objt _current_obj_orig( R t
request_id( ( s2 /usr/lib/python2.6/site-packages/paste/registry.pyt _current_obj_restorationû s s. %s
(StackedObjectRestorer restoration enabled)c C s" t i ƒ p | i | ƒ n d S( N( R R@ t _push_object_orig( R R8 ( ( s2 /usr/lib/python2.6/site-packages/paste/registry.pyt _push_object_restoration s
c C s" t i ƒ p | i | ƒ n d S( N( R R@ t _pop_object_orig( R R8 ( ( s2 /usr/lib/python2.6/site-packages/paste/registry.pyt _pop_object_restoration s
N( R R t __doc__R R R R R R" R$ R% R& R) R- R/ R1 R2 R4 R R: R6 R> R? RD RF RH ( ( ( s2 /usr/lib/python2.6/site-packages/paste/registry.pyR d s8
t Registryc B sA e Z d Z d „ Z d „ Z d „ Z d „ Z e Z d „ Z RS( sƒ Track objects and stacked object proxies for removal
The Registry object is instantiated a single time for the request no
matter how many times the RegistryManager is used in a WSGI stack. Each
RegistryManager must call ``prepare`` before continuing the call to
start a new context for object registering.
Each context is tracked with a dict inside a list. The last list
element is the currently executing context. Each context dict is keyed
by the id of the StackedObjectProxy instance being proxied, the value
is a tuple of the StackedObjectProxy instance and the object being
tracked.
c C s
g | _ d S( s¥ Create a new Registry object
``prepare`` must still be called before this Registry object can be
used to register objects.
N( t reglist( R ( ( s2 /usr/lib/python2.6/site-packages/paste/registry.pyR ! s c C s | i i h ƒ d S( sõ Used to create a new registry context
Anytime a new RegistryManager is called, ``prepare`` needs to be
called on the existing Registry object. This sets up a new context
for registering objects.
N( RK R9 ( R ( ( s2 /usr/lib/python2.6/site-packages/paste/registry.pyt prepare* s c C sg | i d } t | ƒ } | | j o | i | | d ƒ | | =n | i | ƒ | | f | | R: ( R t stackedR8 t myreglistt
stacked_id( ( s2 /usr/lib/python2.6/site-packages/paste/registry.pyt register4 s
c C s~ | i d } xj | D]b \ } } t | ƒ } | | j o | i | | d ƒ | | =n | i | ƒ | | f | | R: ( R t stacklistRN RM R8 RO ( ( s2 /usr/lib/python2.6/site-packages/paste/registry.pyt
multiregister> s
c C sB x. | i d i ƒ D] \ } } | i | ƒ q W| i i ƒ d S( sk Remove all objects from all StackedObjectProxy instances that
were tracked at this Registry contextiÿÿÿÿN( RK t
itervaluesR> R; ( R RM R8 ( ( s2 /usr/lib/python2.6/site-packages/paste/registry.pyt cleanupU s ( R R RI R RL RP RR t replaceRT ( ( ( s2 /usr/lib/python2.6/site-packages/paste/registry.pyRJ s
c B s, e Z d Z e d „ Z d „ Z d „ Z RS( sK Creates and maintains a Registry context
RegistryManager creates a new registry context for the registration of
StackedObjectProxy instances. Multiple RegistryManager's can be in a
WSGI stack and will manage the context so that the StackedObjectProxies
always proxy to the proper object.
The object being registered can be any object sub-class, list, or dict.
Registering objects is done inside a WSGI application under the
RegistryManager instance, using the ``environ['paste.registry']``
object which is a Registry instance.
c C s | | _ | | _ d S( N( t applicationt streaming( R RV RW ( ( s2 /usr/lib/python2.6/site-packages/paste/registry.pyR k s c C s) d } | i d t ƒ ƒ } | i ƒ | i o | i | | | ƒ Sy | i | | ƒ } Wn¿ t j
o } | i d ƒ oY t } x4 | i d g ƒ D] } t
| | ƒ o
t } q• q• W| p t i
| ƒ qÕ n | i ƒ ‚ n@ | i d ƒ o t i
| ƒ n | i ƒ ‚ n X| i ƒ | S( Ns paste.registrys paste.evalexceptions paste.expected_exceptions( R6 t
setdefaultRJ RL RW t streaming_iterRV t ExceptionR7 t Falset
isinstancet TrueR t save_registry_stateRT ( R t environt start_responset app_itert regt et expectedt expect( ( s2 /usr/lib/python2.6/site-packages/paste/registry.pyR) o s2
c c sö y& x | i | | ƒ D] } | Vq WWn¿ t j
o } | i d ƒ oY t } x4 | i d g ƒ D] } t | | ƒ o
t } qb qb W| p t i | ƒ q¢ n | i ƒ ‚ n@ | i d ƒ o t i | ƒ n | i ƒ ‚ n X| i ƒ d S( Ns paste.evalexceptions paste.expected_exceptions( RV RZ R7 R[ R\ R] R R^ RT ( R Rb R_ R` t itemRc Rd Re ( ( s2 /usr/lib/python2.6/site-packages/paste/registry.pyRY “ s*
( R R RI R[ R R) RY ( ( ( s2 /usr/lib/python2.6/site-packages/paste/registry.pyR \ s $c B sV e Z d Z d „ Z d „ Z d „ Z d „ Z d „ Z d „ Z d „ Z d „ Z
RS( s Track StackedObjectProxies and their proxied objects for automatic
restoration within EvalException's interactive debugger.
An instance of this class tracks all StackedObjectProxy state in existence
when unexpected exceptions are raised by WSGI applications housed by
EvalException and RegistryManager. Like EvalException, this information is
stored for the life of the process.
When an unexpected exception occurs and EvalException is present in the
WSGI stack, save_registry_state is intended to be called to store the
Registry state and enable automatic restoration on all currently registered
StackedObjectProxies.
With restoration enabled, those StackedObjectProxies' _current_obj
(overwritten by _current_obj_restoration) method's strategy is modified:
it will return its appropriate proxied object from the restorer when
a restoration context is active in the current thread.
The StackedObjectProxies' _push/pop_object methods strategies are also
changed: they no-op when a restoration context is active in the current
thread (because the pushing/popping work is all handled by the
Registry/restorer).
The request's Registry objects' reglists are restored from the restorer
when a restoration context begins, enabling the Registry methods to work
while their changes are tracked by the restorer.
The overhead of enabling restoration is negligible (another threadlocal
access for the changed StackedObjectProxy methods) for normal use outside
of a restoration context, but worth mentioning when combined with
StackedObjectProxies normal overhead. Once enabled it does not turn off,
however:
o Enabling restoration only occurs after an unexpected exception is
detected. The server is likely to be restarted shortly after the exception
is raised to fix the cause
o StackedObjectRestorer is only enabled when EvalException is enabled (not
on a production server) and RegistryManager exists in the middleware
stackc C s h | _ t i ƒ | _ d S( N( t saved_registry_statesR R
t restoration_context_id( R ( ( s2 /usr/lib/python2.6/site-packages/paste/registry.pyR Ú s c C s¨ | i d ƒ } | p* t | i ƒ p | i | ƒ | i j o d S| | i f | i | i | ƒ t _restorationt _orig( s _current_objs _push_objects _pop_object( R R ( R RM t func_namet orig_funct restoration_func( ( s2 /usr/lib/python2.6/site-packages/paste/registry.pyRj s
c C s d d k l } | | ƒ S( s2 Return a unique identifier for the current requestiÿÿÿÿ( t get_debug_count( t paste.evalexception.middlewareRs ( R R_ Rs ( ( s2 /usr/lib/python2.6/site-packages/paste/registry.pyRi s c C s@ | | i j o | i | \ } } | | _ n | | i _ d S( sW Enable a restoration context in the current thread for the specified
request_idN( Rg RK Rh RC ( R RC Rk RK ( ( s2 /usr/lib/python2.6/site-packages/paste/registry.pyt restoration_begin$ s
c C s' y
| i ` Wn t j
o n Xd S( s9 Register a restoration context as finished, if one existsN( Rh RC R+ ( R ( ( s2 /usr/lib/python2.6/site-packages/paste/registry.pyt restoration_end. s
c C s t | i d t ƒ S( sŠ Determine if a restoration context is active for the current thread.
Returns the request_id it's active for if so, otherwise FalseRC ( R Rh R[ ( R ( ( s2 /usr/lib/python2.6/site-packages/paste/registry.pyR@ 5 s ( R R RI R R^ RA Rj Ri Ru Rv R@ ( ( ( s2 /usr/lib/python2.6/site-packages/paste/registry.pyR ± s (
c C s
t | ƒ S( N( R ( t appt global_conf( ( s2 /usr/lib/python2.6/site-packages/paste/registry.pyt make_registry_manager> s ( RI t syst paste.util.threadinglocalt utilR t __all__t objectR R RJ R R R Ry ( ( ( s2 /usr/lib/python2.6/site-packages/paste/registry.pyt [ s ®JU‰