Metadata-Version: 1.1
Name: cleanupd
Version: 0.9.0.1
Summary: A package providing additional object cleanup functionality.
Home-page: https://github.com/d-e-s-o/cleanup
Author: Daniel Mueller
Author-email: deso@posteo.net
License: GPLv3
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.
        
Keywords: cleanup defer development
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries :: Python Modules
