Navigation

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

The Python standard library has a concept called “thread locals” (or thread-local
data). A thread local is a global object in which you can put stuff in and get back
later in a thread-safe and thread-specific way. That means that whenever you set
or get a value on a thread local object, the thread local object checks in which
thread 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 one
is greenlets. Also, whether every request gets its own thread is not
guaranteed in WSGI. It could be that a request is reusing a thread from
a 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 with
greenlets.

This binds the request to local.request. Every other piece of code executed
after this assignment in the same context can safely access local.request and
will get the same request object. The make_middleware method on the local
manager ensures that all references to the local objects are cleared up after
the request.

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

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

defget_request():returngetattr(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 local
manager. You can pass a local manager multiple locals or add additionals
later by appending them to manager.locals and every time the manager
cleans up it will clean up all the data left in the locals for this
context.

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

Local objects cannot manage themselves. For that you need a local
manager. You can pass a local manager multiple locals or add them later
by 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 ident
function for the wrapped locals.

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

Return the context identifier the local objects use internally for
this context. You cannot override this method to change the behavior
but use it to link other context local objects (such as SQLAlchemy’s
scoped sessions) to the Werkzeug locals.

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

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

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

Acts as a proxy for a werkzeug local. Forwards all operations to
a proxied object. The only operations not supported for forwarding
are right handed operands and any kind of assignment.

Example usage:

fromwerkzeug.localimportLocall=Local()# these are proxiesrequest=l('request')user=l('user')fromwerkzeug.localimportLocalStack_response_local=LocalStack()# this is a proxyresponse=_response_local()

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

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

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 find
out if you are dealing with a proxy you can do an isinstance() check: