asyncutils.properties

Asynchronous descriptors, mimicking property and optionally applying a lock.

Classes

AsyncPropertyBase	A property with asynchronous getters, setters and deleters.
ConcurrentAsyncProperty	Allows set and delete operations to run concurrently once the operations are called, without any guarantee on the order of execution.
Deleters	Integer flags configuring a fallback deleter for async properties.
LazyAsyncProperty	A property that queues set and delete operations.
RWLockedAsyncProperty	Apply a reader-writer lock to the property. Naturally, setters and deleters are writers and getters are readers.

Module Contents

class asyncutils.properties.AsyncPropertyBase[T, R]

Bases: abc.ABC

A property with asynchronous getters, setters and deleters.

Create a new async property with getter fget, setter fset and deleter fdel.

fget must return an awaitable resolving to the value of the property and take only the instance as argument.

fset should take the instance and value as arguments.

fdel can be a callable taking the instance as an argument, or a member of Deleters to configure a basic deleter that disallows gets after deletion on the instance in question.

If the getter is not provided, return a partial decorator instead. In that overload, none of the accessors are to be passed.

doc, if passed, will be the docstring of the property in the form of the __doc__ attribute. Otherwise, an attempt is made to find it on the getter.

strict, which defaults to True, controls whether performing an operation that invokes an unset accessor is allowed.

If mutable is True (default False), the property can be reassigned and deleted on the class.

If assert_modifiers_return_none=False is not passed, the setter and deleter must both return None or an awaitable resolving to None, which will be awaited.

If hide is True (default False), accessing the attribute on the class it is defined in would raise AttributeError as if the property didn’t exist.

Subclasses must define wrap_aw(), and are allowed to override _init() and _repr_accessor(). Nothing else is customizable.

__delete__(instance: R, /) → None

Note that the deleter is to be called with the instance as the only argument.

__get__(instance: R, owner: type[R] | None = ..., /) → types.CoroutineType[Any, Any, T]

__get__(instance: None, owner: type[R], /) → types.CoroutineType[Any, Any, Self]

Call the getter and return a coroutine resolving to its result.

__getattr__(name: str, /) → Any

Find the attribute on the getter if it exists.

classmethod __init_subclass__(

/,

*,

lock_factory: collections.abc.Callable[[],

asyncutils._internal.prots.AsyncContextManager[Any]]=...,

**k: object,

) → None

lock_factory, a callable that returns a new per-instance async context manager, is required for immediate subclasses.

__reduce__() → str

Return the qualified name of this property for pickling. Hidden properties cannot be pickled.

__set__(instance: R, value: T, /) → None

Note that the setter is to be called with the instance and value as arguments.

__set_name__(owner: type[R], name: str, /) → None

Bind the property to the class.

_init(

fget: collections.abc.Callable[[R], collections.abc.Awaitable[T]],

/,

fset: collections.abc.Callable[[R, T], collections.abc.Awaitable[None] | None] | None = ...,

fdel: collections.abc.Callable[[R], collections.abc.Awaitable[None] | None] | Deleters = ...,

*,

doc: str | None = ...,

strict: bool = ...,

hide: bool = ...,

mutable: bool = ...,

assert_modifiers_return_none: bool = ...,

) → None

Set the necessary attributes on the property; called at construction.

static _repr_accessor(

accessor: collections.abc.Callable[Concatenate[R, Ellipsis], collections.abc.Awaitable[T | None] | None] | Deleters | None,

/,

) → str

Return a string representing an accessor. Called by the implementation of __repr__().

deleter(fdel: collections.abc.Callable[[R], collections.abc.Awaitable[None] | None] | Deleters, /) → Self

Return another async property with the given function as the deleter.

getter(fget: collections.abc.Callable[[R], collections.abc.Awaitable[T]], /) → Self

Return another async property with the given function as the getter.

setter(fset: collections.abc.Callable[[R, T], collections.abc.Awaitable[None] | None], /) → Self

Return another async property with the given function as the setter.

abstractmethod wrap_aw[S](aw: collections.abc.Awaitable[S], /) → collections.abc.Awaitable[S]

Return an awaitable resolving to the result of an awaitable, limited to those returned by the setter or deleter. This can be a coroutine, a future, a task or anything else, and affects the strategy used to handle assignments and deletions which must return synchronously but run in the background.

__doc__: str | None

The docstring for this property, or None if it doesn’t exist.

__module__: str | None

The module this property is defined in, determined by the function it decorates.

__name__: str

The name of this property, determined by the function it decorates.

property fdel: collections.abc.Callable[[R], collections.abc.Awaitable[None] | None] | Deleters

The deleter for this property.

property fget: collections.abc.Callable[[R], collections.abc.Awaitable[T]] | None

The getter function for this property, or None if it doesn’t exist.

property fset: collections.abc.Callable[[R, T], collections.abc.Awaitable[None] | None] | None

The setter function for this property, or None if it doesn’t exist.

class asyncutils.properties.ConcurrentAsyncProperty[T, R]

Bases: AsyncPropertyBase[T, R]

Allows set and delete operations to run concurrently once the operations are called, without any guarantee on the order of execution.

The setters and deleters can be implemented acquire a writer lock and the getter the corresponding reader lock from rwlocks with its lock policies that provide fluent decorator interfaces.

Note, however, that the accessor decorators must be outermost because they turn callables into properties.

wrap_aw[S](aw: collections.abc.Awaitable[S], /) → asyncio.Task[S]

Return a task for the awaitable returned by the setter or deleter.

__doc__: str | None

The docstring for this property, or None if it doesn’t exist.

__module__: str | None

The module this property is defined in, determined by the function it decorates.

__name__: str

The name of this property, determined by the function it decorates.

class asyncutils.properties.Deleters

Bases: enum.IntFlag

Integer flags configuring a fallback deleter for async properties.

Initialize self. See help(type(self)) for accurate signature.

CANNOT_SET_AFTER_DELETE = 1

This flag is only meaningful if NO_DELETER is not set. Setting this flag means the setter will not be allowed to run after the deleter has been executed on an instance.

CAN_DELETE_AGAIN = 2

If this flag is set, the deleter can be called multiple times on the same instance without raising AttributeError.

DEFAULT = 0

The default deleter.

NO_DELETER = 4

If this flag is set, the attribute still exists on the object after deletion, just like there was no deleter, if SILENT is set.

SILENT = 1

This flag is only meaningful if NO_DELETER is also set. Deletion will essentially become a no-op in that case, as opposed to the default behaviour which raises AttributeError.

class asyncutils.properties.LazyAsyncProperty[T, R]

Bases: AsyncPropertyBase[T, R]

A property that queues set and delete operations.

Operations are completed only when a get is called, strictly in order.

async wrap_aw[S](aw: collections.abc.Awaitable[S], /) → S

Wrap the awaitable in a coroutine, run lazily.

__doc__: str | None

The docstring for this property, or None if it doesn’t exist.

__module__: str | None

The module this property is defined in, determined by the function it decorates.

__name__: str

The name of this property, determined by the function it decorates.

class asyncutils.properties.RWLockedAsyncProperty[T, R]

Bases: ConcurrentAsyncProperty[T, R]

Apply a reader-writer lock to the property. Naturally, setters and deleters are writers and getters are readers.

policy is the class used to create the readers-writer lock for the property. It must subclass RWLock.

_init(

f: collections.abc.Callable[[R], collections.abc.Awaitable[T]],

/,

fset: collections.abc.Callable[[R, T], collections.abc.Awaitable[None] | None] | None = ...,

fdel: collections.abc.Callable[[R], collections.abc.Awaitable[None] | None] | Deleters = ...,

*,

policy: type[asyncutils.rwlocks.RWLock] = ...,

doc: str | None = ...,

strict: bool = ...,

hide: bool = ...,

mutable: bool = ...,

assert_modifiers_return_none: bool = ...,

) → None

Set the necessary attributes on the property; called at construction.

__doc__: str | None

The docstring for this property, or None if it doesn’t exist.

__module__: str | None

The module this property is defined in, determined by the function it decorates.

__name__: str

The name of this property, determined by the function it decorates.