Context Locals

Sooner or later you have some things you want to have in every single viewor helper function or whatever. In PHP the way to go are globalvariables. However, that isn’t possible in WSGI applications without amajor drawback: As soon as you operate on the global namespace yourapplication isn’t thread-safe any longer.

The Python standard library has a concept called “thread locals” (or thread-localdata). A thread local is a global object in which you can put stuff in and get backlater in a thread-safe and thread-specific way. That means that whenever you setor get a value on a thread local object, the thread local object checks in whichthread you are and retrieves the value corresponding to your thread (if one exists).So, you won’t accidentally get another thread’s data.

This approach, however, has a few disadvantages. For example, besides threads,there are other types of concurrency in Python. A very popular oneis greenlets. Also, whether every request gets its own thread is notguaranteed in WSGI. It could be that a request is reusing a thread froma previous request, and hence data is left over in the thread local object.

Werkzeug provides its own implementation of local data storage called werkzeug.local.This approach provides a similar functionality to thread locals but also works withgreenlets.

Here’s a simple example of how one could use werkzeug.local:

  1. from werkzeug.local import Local, LocalManager
  2.  
  3. local = Local()
  4. local_manager = LocalManager([local])
  5.  
  6. def application(environ, start_response):
  7.     local.request = request = Request(environ)
  8.     ...
  9.  
  10. application = local_manager.make_middleware(application)

This binds the request to local.request. Every other piece of code executedafter this assignment in the same context can safely access local.request andwill get the same request object. The make_middleware method on the localmanager ensures that all references to the local objects are cleared up afterthe request.

The same context means the same greenlet (if you’re using greenlets) inthe same thread and same process.

If a request object is not yet set on the local object and you try toaccess it, you will get an AttributeError. You can use getattr to avoidthat:

  1. def get_request():
  2.     return getattr(local, 'request', None)

This will try to get the request or return None if the request is not(yet?) available.

Note that local objects cannot manage themselves, for that you need a localmanager. You can pass a local manager multiple locals or add additionalslater by appending them to manager.locals and every time the managercleans up it will clean up all the data left in the locals for thiscontext.

  • werkzeug.local.releaselocal(_local)
  • Releases the contents of the local for the current context.This makes it possible to use locals without a manager.

Example:

  1. >>> loc = Local()
  2. >>> loc.foo = 42
  3. >>> release_local(loc)
  4. >>> hasattr(loc, 'foo')
  5. False

With this function one can release Local objects as wellas LocalStack objects. However it is not possible torelease data held by proxies that way, one always has to retaina reference to the underlying local object in order to be ableto release it.

New in version 0.6.1.

  • class werkzeug.local.LocalManager(locals=None, ident_func=None)
  • Local objects cannot manage themselves. For that you need a localmanager. You can pass a local manager multiple locals or add them laterby appending them to manager.locals. Every time the manager cleans up,it will clean up all the data left in the locals for this context.

The ident_func parameter can be added to override the default identfunction for the wrapped locals.

Changed in version 0.6.1: Instead of a manager the release_local() function can be usedas well.

Changed in version 0.7: ident_func was added.

  • cleanup()

  • Manually clean up the data in the locals for this context. Callthis at the end of the request or use make_middleware().

  • get_ident()

  • Return the context identifier the local objects use internally forthis context. You cannot override this method to change the behaviorbut use it to link other context local objects (such as SQLAlchemy’sscoped sessions) to the Werkzeug locals.

Changed in version 0.7: You can pass a different ident function to the local manager thatwill then be propagated to all the locals passed to theconstructor.

  • makemiddleware(_app)

  • Wrap a WSGI application so that cleaning up happens afterrequest end.

  • middleware(func)

  • Like make_middleware but for decorating functions.

Example usage:

  1. @manager.middlewaredef application(environ, start_response):    …

The difference to make_middleware is that the function passedwill have all the arguments copied from the inner application(name, docstring, module).

  • class werkzeug.local.LocalStack
  • This class works similar to a Local but keeps a stackof objects instead. This is best explained with an example:
  1. >>> ls = LocalStack()
  2. >>> ls.push(42)
  3. >>> ls.top
  4. 42
  5. >>> ls.push(23)
  6. >>> ls.top
  7. 23
  8. >>> ls.pop()
  9. 23
  10. >>> ls.top
  11. 42

They can be force released by using a LocalManager or withthe release_local() function but the correct way is to pop theitem from the stack after using. When the stack is empty it willno longer be bound to the current context (and as such released).

By calling the stack without arguments it returns a proxy that resolves tothe topmost item on the stack.

New in version 0.6.1.

  • pop()

  • Removes the topmost item from the stack, will return theold value or None if the stack was already empty.

  • push(obj)

  • Pushes a new item to the stack

  • top

  • The topmost item on the stack. If the stack is empty,None is returned.
  • class werkzeug.local.LocalProxy(local, name=None)
  • Acts as a proxy for a werkzeug local. Forwards all operations toa proxied object. The only operations not supported for forwardingare right handed operands and any kind of assignment.

Example usage:

  1. from werkzeug.local import Local
  2. l = Local()
  3.  
  4. # these are proxies
  5. request = l('request')
  6. user = l('user')
  7.  
  8.  
  9. from werkzeug.local import LocalStack
  10. _response_local = LocalStack()
  11.  
  12. # this is a proxy
  13. response = _response_local()

Whenever something is bound to l.user / l.request the proxy objectswill forward all operations. If no object is bound a RuntimeErrorwill be raised.

To create proxies to Local or LocalStack objects,call the object as shown above. If you want to have a proxy to anobject looked up by a function, you can (as of Werkzeug 0.6.1) passa function to the LocalProxy constructor:

  1. session = LocalProxy(lambda: get_current_request().session)

Changed in version 0.6.1: The class can be instantiated with a callable as well now.

Keep in mind that repr() is also forwarded, so if you want to findout if you are dealing with a proxy you can do an isinstance() check:

  1. >>> from werkzeug.local import LocalProxy
  2. >>> isinstance(request, LocalProxy)
  3. True

You can also create proxy objects by hand:

  1. from werkzeug.local import Local, LocalProxy
  2. local = Local()
  3. request = LocalProxy(local, 'request')
  • _get_current_object()
  • Return the current object. This is useful if you want the realobject behind the proxy at a time for performance reasons or becauseyou want to pass the object into a different context.