Metadata-Version: 2.5
Name: boundinstance
Version: 0.1.1
Summary: Weakref-based instance descriptors.
Project-URL: Documentation, https://nstarman.github.io/boundinstance
Project-URL: Homepage, https://github.com/nstarman/boundinstance
Author: Nathaniel Starkman
License-Expression: BSD-3-Clause
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Requires-Python: >=3.12
Description-Content-Type: text/markdown

# boundinstance

[![CodSpeed](https://img.shields.io/endpoint?url=https://codspeed.io/badge.json)](https://app.codspeed.io/nstarman/boundinstance?utm_source=badge) [![codecov](https://codecov.io/gh/nstarman/boundinstance/branch/main/graph/badge.svg)](https://codecov.io/gh/nstarman/boundinstance)

`boundinstance` provides `InstanceDescriptor`, a descriptor that binds weakly to the instance it was accessed from, so a subclass can carry a reference back to its enclosing object without creating a reference cycle.

## Install

```bash
pip install boundinstance
```

## Usage

```python
from boundinstance import InstanceDescriptor


class Plot(InstanceDescriptor["Potential"]):
    def label(self) -> str:
        return f"plot of {self.enclosing.name}"


class Potential:
    plot = Plot()

    def __init__(self, name: str) -> None:
        self.name = name


hernquist = Potential("hernquist")
assert hernquist.plot.label() == "plot of hernquist"
```

The reference back to the enclosing object is weak, so it doesn't outlive a temporary: bind the enclosing object to a name before reading `enclosing` from it, or you'll hit a `ReferenceError` (`Potential("hernquist").plot.label()` fails; `hernquist.plot.label()` works because `hernquist` keeps the object alive).

## Compiled wheels

`boundinstance` ships mypyc-compiled wheels for supported platforms, plus a pure-Python sdist that needs no compiler. `boundinstance.COMPILED` reports whether the installed build is mypyc-compiled.
