optmanage.option

Descriptor to define options in an option manager.

Option

class Option(ty, default, validator=None)[source]

Bases: Generic[ValueT]

Descriptor for an option. For usage examples, see OptionManager.

See https://docs.python.org/3/reference/datamodel.html#descriptors for a discussion of descriptors in Python.

__get__(instance, _=None)[source]

Gets the current value for the given option. If no value has been set, the default value is returned.

Parameters:

instance (typing.Union[OptionManager, None]) –
_ (typing.Union[Type[OptionManager], None]) –

Return type:

typing.Union[ValueT, Self]

static __new__(cls, ty, default, validator=None)[source]

Creates a new option descriptor. For usage examples, see OptionManager.

Parameters:

ty (Any) – The type of the option.
default (ValueT) – The default value for the option.
validator (typing.Union[Validator[ValueT], None]) – An optional validator function, see Validator

Return type:

Self

__set__(instance, value)[source]

Sets the option to the given value. The value is validated before being set.

Raises:

TypeError – If the value has the wrong type.
ValueError – If the value is invalid for this option.
ValueError – If the option has a temporarily set value.

Parameters:

instance (OptionManager) –
value (ValueT) –

Return type:

None

__set_name__(owner, name)[source]

Hook to automatically bind the option to the option manager that owns it.

Parameters:

owner (Type[OptionManager]) –
name (str) –

Return type:

None

property default

The default value for this option.

Return type:: ValueT

property name

The name of this option.

Raises:: AttributeError – if accessed before the option has been bound to an option manager.
Return type:: str

property owner

The owner of this option.

Raises:: AttributeError – if accessed before the option has been bound to an option manager.
Return type:: Type[OptionManager]

reset(instance)[source]

Resets the option to its default value.

Parameters:: instance (OptionManager) –
Return type:: ValueT

property type

The type of this option.

Return type:: Type[ValueT]

validate(value)[source]

Validates a given value for this option:

Checks that the value has the correct type.
If a validator is specified, checks that the value is valid.

If the value is not valid, ValueError is raised.

Parameters:: value (ValueT) –
Return type:: None

property validator

The validator for this option, or None if no additional validation logic is specified (other than runtime type-checking).

Return type:: typing.Union[Validator[ValueT], None]

TYPE_CHECKING

TYPE_CHECKING = False

bool(x) -> bool

Returns True when the argument x 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.

Validator

class Validator(*args, **kwargs)[source]

Bases: Protocol[ValueT_contra]

Structural type for an option validator. There are two ways to signal that a value is invalid:

returning False
raising any Exception

There are two ways to signal that a value is valid:

returning True (as opposed to False)
returning None (as opposed to raising an exception)

In the context of option validation, a ValueError will be raised if validation fails: if the validator raised an exception, the ValueError is re-raised from it.

ValueT

ValueT = ~ValueT: Invariant type variable for option values (see Option).

ValueT_contra

ValueT_contra = -ValueT_contra: Contravariant type variable for option values (see Option).