Metadata-Version: 2.1
Name: threadref
Version: 1.1.2
Summary: ``weakref`` for threads.
Home-page: https://github.com/mentalisttraceur/python-threadref
Author: Alexander Kozhevnikov
Author-email: mentalisttraceur@gmail.com
License: 0BSD
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 2
Classifier: Operating System :: OS Independent

``weakref`` for Threads
=======================

Allows threads in Python to create "weak references"
to themselves that detect when the thread is no longer
running, similar to how a weak reference detects when
its referent object is no longer alive.

Provides a lightweight way for one or more independent
pieces of code to register per-thread cleanup callbacks
without coordination.


Versioning
----------

This library's version numbers follow the `SemVer 2.0.0
specification <https://semver.org/spec/v2.0.0.html>`_.


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

::

    pip install threadref


Usage
-----

Import
~~~~~~

.. code:: python

    import threadref


``ref``
~~~~~~~

Create a reference to the current thread, with a
callback that will fire when the thread exits:

.. code:: python

    reference = threadref.ref(lambda reference: ...)

Just like ``weakref.ref``, ``threadref.ref`` instances
must still be alive when their referent thread stops
running, or their callback will not be called.


``finalize``
~~~~~~~~~~~~

Create a finalizer for the current thread, which
will be called when the thread exits:

.. code:: python

    finalizer = threadref.finalize(function, *args, **kwargs)

Just like ``weakref.finalize``, ``threadref.finalize``
instances remain alive on their own as long as they
need to, so this is a simpler and nicer interface in
the typical case of registering cleanup functions.

Details
~~~~~~~

``threadref.ref`` and ``threadref.finalize`` wrap
``weakref.ref`` and ``weakref.finalize``, and the
interface is the same except that they act as if
they are referencing the thread itself instead of
taking a referent argument, and internally they
work by referencing an object saved on a private
``threading.local`` instance.


