typed_descriptors.prop

Descriptor class for cached properties.

Prop

class Prop(type, value, /, *, backed_by=None, use_dict=None, use_slots=None, typecheck=True)

Bases: DescriptorBase[T]

A descriptor class for cached properties, supporting:

• static type checking for the property value

• lazy caching (value only cached at first read)

See DescriptorBase for details on how the property value is cached in each instance.

final __get__(instance, _)

If the descriptor is accessed on an instance, returns the value of the property on the given instance.

If the descriptor is accessed on the owner class, i.e. if instance is None, returns the Prop object.

Parameters:

• instance (Any)

• _ (Type[Any])

Return type:

T | Self

__init__(type, value, /, *, backed_by=None, use_dict=None, use_slots=None, typecheck=True)

Creates a new property with the given type and value function.

Parameters:

• value (ValueFunction[T]) – function computing the property value

• type (Type[T] | Any) – the type of the property

• attr_name – the name of the backing attribute for the property cache, or None to use a default name

• typecheck (bool; default = True) – whether to perform dynamic typechecks (default: True)

• backed_by (Optional[str])

• use_dict (Optional[Literal[True]])

• use_slots (Optional[Literal[True]])

Raises:

• TypeError – if the type is not a valid type

• TypeError – if the value function is not callable

Return type:

None

final cache_on(instance)

Caches the property value on the given instance. Can be used to force property computation at a desired time, overriding the default lazy behaviour.

Raises:

AttributeError – if the property is already cached.

Parameters:

instance (Any)

Return type:

None

final is_cached_on(instance)

Whether the property is cached on the given instance.

Parameters:

instance (Any)

Return type:

bool

static value(value_fun=None, /, *, backed_by=None, use_dict=None, use_slots=None, typecheck=True)

An alias for cached_property.

It offers a way to declare Prop which is stylisticallly aligned to the Attr.validator decorator for attributes.

Parameters:

• value_fun (Optional[ValueFunction[T]])

• backed_by (Optional[str])

• use_dict (Optional[Literal[True]])

• use_slots (Optional[Literal[True]])

• typecheck (bool; default = True)

Return type:

PropFactory | Prop[T]

property value_fun

The function called to produce a value for this property on a given instance. It is called by the getter when the property doesn’t have a cached value, and the value returned is automatically cached.

Return type:

ValueFunction[T]

PropFactory

class PropFactory(*args, **kwargs)

Bases: Protocol

Structural type for functions which create Prop instances from value functions.

T_co

T_co = +T_co

Covariant type variable for generic values.

ValueFunction

class ValueFunction(*args, **kwargs)

Bases: Protocol[T_co]

Structural type for the value function of a Prop.

cached_property

cached_property(value_fun=None, /, *, backed_by=None, use_dict=None, use_slots=None, typecheck=True)

Decorator used to create a cached property from a value function, optionally specifying a backing attribute. See Prop and DescriptorBase for more information.

It can be used directly, for properties with default backing attribute name:

class C:

    @cached_property
    def x(self) -> Sequence[str]:
        ''' Value function for property 'C.x'. '''
        return 10

It can be used by supplying a custom backing attribute name to the backed_by argument:

class C:

    @cached_property(backed_by="_x")
    def x(self) -> Sequence[str]:
        ''' Value function for property 'C.x'. '''
        return 10

    __slots__ = ("_x", )

Note

The decorator is analogous to the built-in functools.cached_property, from which it takes its name, and it uses the same caching logic when __dict__ is available on owner class’s instances and no custom attribute name is used. Contrary to its built-in counterpart, however, this decorator can be used with a slotted attribute as backing attribute.

Parameters:

• value_fun (Optional[ValueFunction[T]])

• backed_by (Optional[str])

• use_dict (Optional[Literal[True]])

• use_slots (Optional[Literal[True]])

• typecheck (bool; default = True)

Return type:

PropFactory | Prop[T]

validate_value_fun

validate_value_fun(value_fun, /)

Runtime validation for value functions.

Raises:

• TypeError – if the argument is not a value function

• ValueError – if the function doesn’t have an explicit annotation for its return type.

Parameters:

value_fun (ValueFunction[T])

Return type:

None

value_fun_return_type

value_fun_return_type(value_fun, /)

Returns the return type annotation of a value function. Used by Prop to infer the property type from the value function return type annotation.

Raises:

• TypeError – if the argument is not a value function

• ValueError – if the function doesn’t have an explicit annotation for its return type.

Parameters:

value_fun (ValueFunction[T])

Return type:

Any