agglovar.meta.descriptors

Descriptors for common variable control.

Descriptors control behavior of instance and class variables, such as setting default values or checking values as they are assigned to attributes or class variables.

Classes:

• AutoInitBase: Base class for descriptors that should auto-initialize their private values. Implements

  boilerplate code for descriptors in this submodule.

• OneWayBool: One-way boolean descriptor. Initialized to either True or False, and when changed, it cannot be

  changed back.

• BoundedInt: An integer type with optional minimum and maximum value enforcement.

Classes

AutoInitBase	Base class for descriptors that should auto-initialize their private values.
BoundedFloat	Integer descriptor with optional minimum and maximum value enforcement.
BoundedInt	Integer descriptor with optional minimum and maximum value enforcement.
CheckedBool	Descriptor that coerces values to bool (or None) on assignment.
CheckedObject	Descriptor that holds an arbitrary object value.
CheckedString	Enforces string constraints and supports a set of transformations before assignment.
OneWayBool	One-way boolean. Once it changes from its default, it cannot change back.

Module Contents

class agglovar.meta.descriptors.AutoInitBase(default: T | None = None, optional: bool | None = None, name_priv: str | None = None)

Bases: abc.ABC, Generic[T]

Base class for descriptors that should auto-initialize their private values.

When objects of a specific class have the same attributes (i.e. keys in __dict__ are the same), instances can share keys instead of each instance having its own keys. If a descriptor is used as a public interface for a private attribute, the private attribute is not created in each instance. This base class modifies the __init__ method of instances so that all private attributes are initialized to some default value before __init__ completes. This ensures that when private variables are first accessed, they do not create a new key in the object __dict__ and force the keys to be copied instead of shared across instances.

abstractmethod __delete__(obj) → None

Delete (disabled).

Raises:

NotImplementedError – Always.

__get__(obj, objtype=None) → T

Get value.

classmethod __init_subclass__(**kwargs) → None

Mark subclasses as non-base so they can be instantiated.

__set__(obj, value: T) → None

Set value.

__set_name__(owner, name) → None

Set name of the public and private variable names.

Parameters:

• owner – Class that owns the descriptor.

• name – Public name.

abstractmethod non_optional_default() → T

Get a default value when the parameter is not optional and the default is None.

default: T | None

name_priv: str = ''

name_pub: str = ''

optional: bool | None = True

class agglovar.meta.descriptors.BoundedFloat(min_val: float | tuple[float, bool] | None = None, max_val: float | tuple[float, bool] | None = None, default: float | None = None, optional: bool | None = None, name_priv: str | None = None)

Bases: AutoInitBase[float]

Integer descriptor with optional minimum and maximum value enforcement.

__set__(obj, value) → None

Set value.

non_optional_default() → float

Return a default value when the parameter is not optional and the default is None.

validate(value) → bool

Check value against bounds.

max_inclusive: bool

max_val: float | None

min_inclusive: bool

min_val: float | None

property range_str: str

Get range string.

class agglovar.meta.descriptors.BoundedInt(min_val: int | tuple[int, bool] | None = None, max_val: int | tuple[int, bool] | None = None, allow_truncation: bool = False, default: int | None = None, optional: bool | None = None, name_priv: str | None = None)

Bases: AutoInitBase[int]

Integer descriptor with optional minimum and maximum value enforcement.

__set__(obj, value) → None

Set value.

non_optional_default() → int

Return a default value when the parameter is not optional and the default is None.

validate(value) → bool

Check value against bounds.

allow_truncation = False

max_inclusive

max_val: int | None

min_inclusive

min_val: int | None

property range_str: str

Get range string.

class agglovar.meta.descriptors.CheckedBool(default: bool | None = None, optional: bool | None = None, name_priv: str | None = None)

Bases: AutoInitBase[bool]

Descriptor that coerces values to bool (or None) on assignment.

__set__(obj, value) → None

Set value.

non_optional_default() → bool

Return a default value when the parameter is not optional and the default is None.

class agglovar.meta.descriptors.CheckedObject(default: object | None = None, optional: bool | None = None, name_priv: str | None = None)

Bases: AutoInitBase[object]

Descriptor that holds an arbitrary object value.

non_optional_default() → object

Return a default value when the parameter is not optional and the default is None.

class agglovar.meta.descriptors.CheckedString(min_len: int | None = None, max_len: int | None = None, strip: bool | str = False, match: re.Pattern | str | collections.abc.Callable[[str], Any] | set[str] | None = None, sub: tuple[str, str] | tuple[re.Pattern, str] | collections.abc.Callable[[str], Any | None] | collections.abc.Mapping[str, str] | tuple[collections.abc.Mapping[str, str], str] | None = None, default: str | None = None, optional: bool | None = None, name_priv: str | None = None)

Bases: AutoInitBase[str]

Enforces string constraints and supports a set of transformations before assignment.

__set__(obj, value) → None

Set value.

non_optional_default() → T

Non-optional default value.

validate(value) → str | None

Transform and validate string.

Parameters:

value – Value string or None.

Returns:

Transformed and validated value or None if value is None.

Raises:

ValueError – If value fails validation.

match: collections.abc.Callable[[str], bool]

max_len: int | None

min_len: int | None

strip: collections.abc.Callable[[str], str]

sub

class agglovar.meta.descriptors.OneWayBool(default: bool = False, name_priv: str | None = None)

Bases: CheckedBool

One-way boolean. Once it changes from its default, it cannot change back.

__set__(obj, value) → None

Check if value is frozen and set if not.

Parameters:

• obj – Object.

• value – Value.