agglovar.meta.descriptors ========================= .. py:module:: agglovar.meta.descriptors .. autoapi-nested-parse:: 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 ------- .. autoapisummary:: agglovar.meta.descriptors.AutoInitBase agglovar.meta.descriptors.BoundedFloat agglovar.meta.descriptors.BoundedInt agglovar.meta.descriptors.CheckedBool agglovar.meta.descriptors.CheckedObject agglovar.meta.descriptors.CheckedString agglovar.meta.descriptors.OneWayBool Module Contents --------------- .. py:class:: AutoInitBase(default: Optional[T] = None, optional: Optional[bool] = None, name_priv: Optional[str] = None) Bases: :py:obj:`abc.ABC`, :py:obj:`Generic`\ [\ :py:obj:`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. .. py:method:: __delete__(obj) -> None :abstractmethod: Delete (disabled). :raises NotImplementedError: Always. .. py:method:: __get__(obj, objtype=None) -> T Get value. .. py:method:: __init_subclass__(**kwargs) -> None :classmethod: Mark subclasses as non-base so they can be instantiated. .. py:method:: __set__(obj, value: T) -> None Set value. .. py:method:: __set_name__(owner, name) -> None Set name of the public and private variable names. :param owner: Class that owns the descriptor. :param name: Public name. .. py:method:: non_optional_default() -> T :abstractmethod: Get a default value when the parameter is not optional and the default is None. .. py:attribute:: default :type: Optional[T] .. py:attribute:: name_priv :type: str :value: '' .. py:attribute:: name_pub :type: str :value: '' .. py:attribute:: optional :type: Optional[bool] :value: True .. py:class:: BoundedFloat(min_val: Optional[float | tuple[float, bool]] = None, max_val: Optional[float | tuple[float, bool]] = None, default: Optional[float] = None, optional: Optional[bool] = None, name_priv: Optional[str] = None) Bases: :py:obj:`AutoInitBase`\ [\ :py:obj:`float`\ ] Integer descriptor with optional minimum and maximum value enforcement. .. py:method:: __set__(obj, value) -> None Set value. .. py:method:: non_optional_default() -> float Return a default value when the parameter is not optional and the default is None. .. py:method:: validate(value) -> bool Check value against bounds. .. py:attribute:: max_inclusive :type: bool .. py:attribute:: max_val :type: Optional[float] .. py:attribute:: min_inclusive :type: bool .. py:attribute:: min_val :type: Optional[float] .. py:property:: range_str :type: str Get range string. .. py:class:: BoundedInt(min_val: Optional[int | tuple[int, bool]] = None, max_val: Optional[int | tuple[int, bool]] = None, allow_truncation: bool = False, default: Optional[int] = None, optional: Optional[bool] = None, name_priv: Optional[str] = None) Bases: :py:obj:`AutoInitBase`\ [\ :py:obj:`int`\ ] Integer descriptor with optional minimum and maximum value enforcement. .. py:method:: __set__(obj, value) -> None Set value. .. py:method:: non_optional_default() -> int Return a default value when the parameter is not optional and the default is None. .. py:method:: validate(value) -> bool Check value against bounds. .. py:attribute:: allow_truncation :value: False .. py:attribute:: max_inclusive .. py:attribute:: max_val :type: Optional[int] .. py:attribute:: min_inclusive .. py:attribute:: min_val :type: Optional[int] .. py:property:: range_str :type: str Get range string. .. py:class:: CheckedBool(default: Optional[bool] = None, optional: Optional[bool] = None, name_priv: Optional[str] = None) Bases: :py:obj:`AutoInitBase`\ [\ :py:obj:`bool`\ ] Descriptor that coerces values to bool (or None) on assignment. .. py:method:: __set__(obj, value) -> None Set value. .. py:method:: non_optional_default() -> bool Return a default value when the parameter is not optional and the default is None. .. py:class:: CheckedObject(default: Optional[object] = None, optional: Optional[bool] = None, name_priv: Optional[str] = None) Bases: :py:obj:`AutoInitBase`\ [\ :py:obj:`object`\ ] Descriptor that holds an arbitrary object value. .. py:method:: non_optional_default() -> object Return a default value when the parameter is not optional and the default is None. .. py:class:: CheckedString(min_len: Optional[int] = None, max_len: Optional[int] = None, strip: bool | str = False, match: Optional[re.Pattern | str | collections.abc.Callable[[str], Any] | set[str]] = None, sub: Optional[tuple[str, str] | tuple[re.Pattern, str] | collections.abc.Callable[[str], Optional[Any]] | collections.abc.Mapping[str, str] | tuple[collections.abc.Mapping[str, str], str]] = None, default: Optional[str] = None, optional: Optional[bool] = None, name_priv: Optional[str] = None) Bases: :py:obj:`AutoInitBase`\ [\ :py:obj:`str`\ ] Enforces string constraints and supports a set of transformations before assignment. .. py:method:: __set__(obj, value) -> None Set value. .. py:method:: non_optional_default() -> T Non-optional default value. .. py:method:: validate(value) -> Optional[str] Transform and validate string. :param value: Value string or None. :return: Transformed and validated value or `None` if `value` is `None`. :raises ValueError: If value fails validation. .. py:attribute:: match :type: collections.abc.Callable[[str], bool] .. py:attribute:: max_len :type: Optional[int] .. py:attribute:: min_len :type: Optional[int] .. py:attribute:: strip :type: collections.abc.Callable[[str], str] .. py:attribute:: sub .. py:class:: OneWayBool(default: bool = False, name_priv: Optional[str] = None) Bases: :py:obj:`CheckedBool` One-way boolean. Once it changes from its default, it cannot change back. .. py:method:: __set__(obj, value) -> None Check if value is frozen and set if not. :param obj: Object. :param value: Value.