Skip to content

API¤

boundinstance's public surface is exactly three names: InstanceDescriptor, COMPILED, and __version__.

boundinstance.InstanceDescriptor ¤

A descriptor that binds weakly to the instance it is accessed from.

Assign an instance to a class attribute and every access from an instance returns a fresh copy holding a weak reference to that instance, reachable as enclosing (or __self__, mirroring bound methods).

Examples¤

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") hernquist.plot.label() 'plot of hernquist'

Accessing it on the class is an error, since there is no instance to bind:

Potential.plot Traceback (most recent call last): ... AttributeError: 'plot' can only be accessed from a 'Potential' object

__self__ property ¤

The object this descriptor is bound to.

Raises¤

ReferenceError If this descriptor was never bound, or its referent has been collected.

enclosing property ¤

The object this descriptor is bound to.

Each access dereferences a weak reference, so assign it to a local when using it repeatedly.

Raises¤

ReferenceError If this descriptor was never bound, or its referent has been collected.

__get__(enclosing: BndTo | None, enclosing_cls: type[BndTo] | None) -> typing.Self ¤

Return a copy of this descriptor bound to enclosing.

__set__(obj: typing.Any, value: object) -> typing.NoReturn ¤

Reject assignment to the attribute.

__set_name__(owner: type, name: str) -> None ¤

Record the attribute name on the enclosing class.

boundinstance.COMPILED = False module-attribute ¤

Returns True when the argument is true, False otherwise. The builtins True and False are the only two instances of the class bool. The class bool is a subclass of the class int, and cannot be subclassed.

boundinstance.__version__ = '0.1.1.dev2+g59800336b' module-attribute ¤

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.

The enclosing object must support weak references¤

InstanceDescriptor binds with a weakref.ref, so the object it is accessed from has to be weakly referenceable. Ordinary Python classes are. Two kinds are not, and both raise TypeError from __get__, naming the offending class:

  • a class defining __slots__ without listing __weakref__ — add it to the slots;
  • a mypyc-compiled native class, which has no weak-reference support at all — decorate it @mypyc_attr(native_class=False) to opt it out of mypyc's native representation.

The restriction only holds when every class in the hierarchy declares __slots__ and omits __weakref__; a subclass that declares no __slots__ regains support from the __dict__ Python adds for it.

Class access is a runtime error, not a static one¤

Cls.attr — accessing a descriptor from the class rather than an instance — raises AttributeError at runtime, naming both the attribute and the class. It is not rejected statically: __get__'s class-access overload (not shown above, since overloads aren't rendered) is typed to return Never, spelled NoReturn in the source, which shapes IDE completions and unreachability analysis for that expression, but mypy does not flag Cls.attr itself as an error at the call site. A # type: ignore on that line is reported as unused by mypy --warn-unused-ignores. Whether your type checker treats Cls.attr as unreachable code is orthogonal to whether it flags the access as an error — check both if that distinction matters to you.