..

Copyright 2009-2017 Ram Rachum. This work is licensed under a Creative

Commons Attribution-ShareAlike 3.0 Unported License, with attribution to

"Ram Rachum at ram.rachum.com" including link. The license may be obtained

at http://creativecommons.org/licenses/by-sa/3.0/

.. _topics-context-management:

:mod:`context_management`

=========================

Context managers are awesome

----------------------------

I love context managers, and I love the :keyword:`with` keyword. If you've

never dealt with context managers or :keyword:`with`, `here's a practical guide

which explains how to use them.`_ You may also read the more official :pep:`343` which introduced these features to the language.

Using :keyword:`with` and context managers in your code contributes a lot to making your code more beautiful and maintainable. Every time you replace a :keyword:`try`\-:keyword:`finally` clause with a :keyword:`with` clause, an angel gets a pair of wings.

Now, you don't *need* any official :class:`ContextManager` class in order to

use context managers or define them; you just need to define

:meth:`__enter__` and :meth:`__exit__` methods in your class, and then you

can use your class as a context manager. *But*, if you use the

:class:`ContextManager` class as a base class to your context manager class,

you could enjoy a few more features that might make your code a bit more

concise and elegant.

What does :class:`ContextManager` add?

--------------------------------------

The :class:`ContextManager` class allows using context managers as decorators

(in addition to their normal use) and supports writing context managers in a

new form called :meth:`manage_context`. (As well as the original forms).

First let's import:

>>> from python_toolbox import context_management

Now let's go over the features one by one.

The :class:`ContextManager` class allows you to **define** context managers in

new ways and to **use** context managers in new ways. I'll explain both of

these; let's start with **defining** context managers.

Defining context managers

-------------------------

There are 3 different ways in which context managers can be defined, and each

has their own advantages and disadvantages over the others.

- The classic way to define a context manager is to define a class with

:meth:`__enter__` and :meth:`__exit__` methods. This is allowed, and if you

do this you should still inherit from :class:`ContextManager`. Example:

>>> class MyContextManager(context_management.ContextManager):

... def __enter__(self):

... pass # preparation

... def __exit__(self, type_=None, value=None, traceback=None):

... pass # cleanup

- As a decorated generator, like so:

>>> @context_management.ContextManagerType

... def MyContextManager():

... # preparation

... try:

... yield

... finally:

... pass # cleanup

The advantage of this approach is its brevity, and it may be a good fit for

relatively simple context managers that don't require defining an actual class.

This usage is nothing new; it's also available when using the standard

library's :func:`contextlib.contextmanager` decorator. One thing that is

allowed here that :mod:`contextlib` doesn't allow is to yield the context

manager itself by doing ``yield context_management.SelfHook``.

- The third and novel way is by defining a class with a :meth:`manage_context`

method which returns a decorator. Example:

>>> class MyContextManager(ContextManager):

... def manage_context(self):

... do_some_preparation()

... with other_context_manager:

... yield self

This approach is sometimes cleaner than defining :meth:`__enter__` and

:meth:`__exit__`; especially when using another context manager inside

:meth:`manage_context`. In our example we did ``with other_context_manager``

in our :meth:`manage_context`, which is shorter, more idiomatic and less

double-underscore-y than the equivalent classic definition:

>>> class MyContextManager(object):

... def __enter__(self):

... do_some_preparation()

... other_context_manager.__enter__()

... return self

... def __exit__(self, *exc):

... return other_context_manager.__exit__(*exc)

Another advantage of the :meth:`manage_context` approach over

:meth:`__enter__` and :meth:`__exit__` is that it's better at handling

exceptions, since any exceptions would be raised inside

:meth:`manage_context` where we could :keyword:`except` them, which is much

more idiomatic than the way :meth:`__exit__` handles exceptions, which is by

receiving their type and returning whether to swallow them or not.

These were the different ways of defining a context manager. Now let's see the

different ways of **using** a context manager:

Using context managers

----------------------

There are 2 different ways in which context managers can be used:

- The plain old honest-to-Guido :keyword:`with` keyword:

>>> with MyContextManager() as my_context_manager:

... do_stuff()

- As a decorator to a function:

>>> @MyContextManager()

... def do_stuff():

... pass # doing stuff

When the ``do_stuff`` function will be called, the context manager will be

used. This functionality is also available in the standard library of Python

3.2+ by using :class:`contextlib.ContextDecorator`, but here it is

combined with all the other goodies given by :class:`ContextManager`.

Another advantage that :class:`ContextManager` has over

:class:`contextlib.ContextDecorator` is that

it uses `Michele Simionato's excellent decorator module`_ to preserve the

decorated function's signature.

That's it. Inherit all your context managers from :class:`ContextManager` (or

decorate your generator functions with :class:`ContextManagerType`) to enjoy

all of these benefits.

.. _here's a practical guide which explains how to use them.: http://effbot.org/zone/python-with-statement.htm

.. _Michele Simionato's excellent decorator module: http://pypi.python.org/pypi/decorator