Skip to main content

A package providing additional object cleanup functionality.

Project description

cleanup
=======

The **cleanup** module provides primitives aiding in releasing of no
longer used resources in an exception-safe manner. In particular, it defines
``defer``, a function that, when used as a context manager, acts as an object
for registering cleanup functions for acquired resources. An example:

```python
client = Client()
with defer() as d:
obj = Object()
d.defer(obj.destroy)
obj.register(client)
d.defer(obj.unregister, client)
# Alternative syntax:
# d.defer(lambda: obj.unregister(client))
raise Exception()
```

Here, the ``defer`` creates a context object ``d`` that is guaranteed to be
released during block exit (even in the face of exceptions). It is used to
"defer" an invocation of ``obj.destroy`` just after the object got created.
This way, the object is guaranteed to be destroyed properly. Furthermore, the
object is registered with a client. This registration should be undone before
the object vanishes and so another "defer" operation is used to register the
``unregister`` invocation.
This example also illustrates another important fact: execution of the various
cleanup routines happens in reverse order of their registration. This property
is important in most scenarios where resources of interest have dependencies.

Sometimes cleanup is only necessary in case an error occurs. That is, if
all operations (resource acquisitions etc.) succeed, we do not want to
roll back and undo a part of them. To that end, a defer context can be
"released" in which case no cleanup happens after block exit. Revisiting
the example above:

```python
client = Client()
with defer() as d:
obj = Object()
d.defer(obj.destroy)
obj.register(client)
d.defer(lambda: obj.unregister(client))

# Do some action that potentially raises an error.

# If we got here we want to keep the object created and registered
# with the client.
d.release()
```

This mechanism not only works on the level of a context but also for
individually deferred functions:
```python
client = Client()
with defer() as d:
obj = Object()
f = d.defer(obj.destroy)

# Do some action that potentially raises an error.

f.release()
```


Installation
------------

The **cleanup** package does not have any external dependencies. In
order to use it it only needs to be made known to Python, e.g., by
adding the path to the ``src/`` directory to the ``PYTHONPATH``
environment variable.

If you are using [Gentoo Linux](https://www.gentoo.org/), there is an
[ebuild](https://github.com/d-e-s-o/cleanup-ebuild) available that can
be used directly.


Support
-------

The module is tested with Python 3. There is no work going on to
ensure compatibility with Python 2.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for cleanupd, version 0.9.0.1
Filename, size File type Python version Upload date Hashes
Filename, size cleanupd-0.9.0.1.tar.gz (19.2 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page