tkmilan.validation#

Validation objects for Spec variables.

All validation representations should be defined here, as standalone objects that can be tested directly, without Tk dependencies. tkmilan.var includes the Tk interfaces.

Module Attributes

LIMIT_ISTRING

Mapping between inclusion boolean, and boundary representation.

LIMIT_INFINITE

String representation of infinite boundary.

INFO_FORMAT_BASE

Metadata for LimitBounded.format_value, per supported base.

limT

Generic Type for var.Limit.

smvT

Generic Type-Checking variable type for SpecParsed.

Functions

StaticMapLabels(fn, lst, *[, defaultIndex])

Turn a list of labels into a mapping, by applying a function to get the value.

StaticMapValues(fn, lst, *[, defaultIndex])

Turn a list of values into a mapping, by applying a function to get the label.

Classes

LimitBounded(min_entry, max_entry, fn[, ...])

Represent a bounded range to limit a value, for integers (int).

LimitUnbounded(min_entry, max_entry, fn[, ...])

Represent a potentially unbounded range to limit a value, generic for any number type.

StaticList(values, *[, default, defaultIndex])

Represent a static list of labels, therefore a tuple of str.

StaticMap(mapping, *[, defaultLabel, ...])

Represent a static mapping between labels and its corresponding values.

VSpec()

Abstract parent class for all validation representations.
class tkmilan.validation.LimitBounded(min_entry: dataclasses.InitVar[Union[int, str]], max_entry: dataclasses.InitVar[Union[int, str]], fn: Callable[[str], int | None], step: int = 1, imin: bool = True, imax: bool = True, default: dataclasses.InitVar[Union[int, str, NoneType]] = None)#

Bases: Mapping[str, int], VSpec

Represent a bounded range to limit a value, for integers (int).

The range can be made to remove the limits themselves with imin and imax. The default is the limit being closed on both sides.

The range is bounded, there are no infinite limits. The step parameter controls if all intermediate values are valid.

The following arguments are not available on the final object:

Parameters:

  • min_entry – Minimum value, as string or number.

  • max_entry – Maximum value, as string or number.

  • default – Default value to be set, as string, number, or None to choose a valid value (the default). When None, a sane value is chosen. If both imin and imax as False, 0 is chosen, which might not be included on the range. Configures the default label.

The following parameters are available on the final object:

Parameters:

  • fn – A function that turns a string into number. Usually some kind of parser.

  • step – The step amount for the range of values. Defaults to 1.

  • imin – Include the limit on the minimum value itself. Defaults to True.

  • imax – Include the limit on the maximum value itself. Defaults to True.

The following parameters are available on the final object, calculated from the arguments:

Parameters:

  • min – Minimum value, as number.

  • min_value – Minimum value, as string. Good for showing to the user.

  • max – Maximum value, as number.

  • max_value – Maximum value, as string. Good for showing to the user.

  • rrange – The range object implementing this object.

  • ldefault – The default label to be shown to the user.

See also

Use LimitUnbounded if the limit is unbounded in any direction, or if the number is not an int subclass.

__len__() → int#

Count the amount of valid values.

Should be used as len(LimitBounded).

__getitem__(label: str) → int#

Get the value corresponding to the label.

If the value is invalid, KeyError is raised.

Should be used as LimitBounded[label].

__iter__() → Iterator[str]#

Iterate through all valid labels.

Should be used as:

for label in LimitBounded:
    print(label)
__contains__(label: object) → bool#

Check if the label is valid. Must be a str.

Should be used as label in LimitBounded.

count_padsize(base: int = 10) → int#

Count the strictly necessary amount of padding digits for the range of values.

Depending on the range of supported values, this will calculate the necessary amount of digits to store all possible values, when formatted with the given base. This allows for a label with fixed size.

Parameters:

base (int) – The base for the positional numeral system, amount of different symbols. For example, hexadecimal uses base=16.

See also

Use format_value to format a value directly.

format_value(value: int, *, base: Literal[2, 8, 10, 16], invalid: str = '') → str#

Format a given value with the strictly necessary amount of padding.

Uses standard format for integers with the given base. The amount of padding is given by the count_padsize function. If the range includes negative values, there will be an extra character on the left, for the signal.

Parameters:

  • value (int) – The value to format

  • base (Literal[2, 8, 10, 16]) – The base for the positional numeral system, amount of different symbols. For example, hexadecimal uses base=16.

  • invalid (str) – The invalid label. Make sure this is really invalid.

get_label(value: Any | None, *, invalid: str = '') → str#

Get a label that produces the given value.

The invalid label is produced for all non-int values.

Parameters:

  • value (Any | None) – The value object, or None to produce an invalid label.

  • invalid (str) – The invalid label. Make sure this is really invalid.

w(**kwargs) → LimitBounded#

Create a new LimitBounded with different parameters.

Reuse all parameters which are not given.

The only parameters that should be changed are:

  • imin: Include the limit on the minimum value itself.

  • imax: Include the limit on the maximum value itself.

  • step: The step amount for the range of values.

  • default: Default value to be set.

class tkmilan.validation.LimitUnbounded(min_entry: dataclasses.InitVar[Union[limT, str, NoneType]], max_entry: dataclasses.InitVar[Union[limT, str, NoneType]], fn: Callable[[str], limT | None], imin: bool = True, imax: bool = True, step: limT | None = None, default: dataclasses.InitVar[Union[limT, str, NoneType]] = None, infinite: dataclasses.InitVar[bool] = False)#

Bases: Mapping[str, limT], Generic[limT], VSpec

Represent a potentially unbounded range to limit a value, generic for any number type.

The range can be made to remove the limits themselves with imin and imax. The default is the limit being closed on both sides.

The range is unbounded, which mean some limits might be infinite. If both limits are infinite and this is intended, set infinite to avoid warnings.

The following arguments are not available on the final object:

Parameters:

  • min_entry – Minimum value, as string or number. None represents an infinite value.

  • max_entry – Maximum value, as string or number. None represents an infinite value.

  • default – Default value to be set, as string, number, or None to choose a valid value (the default). When None, a sane value is chosen. If both imin and imax as False, 0 is chosen, which might not be included on the range. Configures the default label.

  • infinite – Do not warn about completely unbounded min and max.

The following parameters are available on the final object:

Parameters:

  • fn – A function that turns a string into number. Usually some kind of parser.

  • step – The step amount for the range of values. Changing this value is unsupported for now, it included for compatibility with LimitBounded. Defaults to None.

  • imin – Include the limit on the minimum value itself. Defaults to True.

  • imax – Include the limit on the maximum value itself. Defaults to True.

The following parameters are available on the final object, calculated from the arguments:

Parameters:

  • min – Minimum value, as number. None if infinite.

  • min_value – Minimum value, as string. Good for showing to the user.

  • max – Maximum value, as number. None if infinite.

  • max_value – Maximum value, as string. Good for showing to the user.

  • ldefault – The default label to be shown to the user.

__getitem__(label: str) → limT#

Get the value corresponding to the label.

If the value is invalid, KeyError is raised.

Should be used as LimitUnbounded[label].

__contains__(label: object) → bool#

Check if the label is valid. Must be a str.

Should be used as label in LimitUnbounded.

get_label(value: limT | None, *, invalid: str = '') → str#

Get a label that produces the given value.

Parameters:

  • value (limT | None) – The value object, or None to produce an invalid label.

  • invalid (str) – The invalid label. Make sure this is really invalid.

w(**kwargs) → LimitUnbounded#

Create a new LimitUnbounded with different parameters.

Reuse all parameters which are not given.

The only parameters that should be changed are:

  • imin: Include the limit on the minimum value itself.

  • imax: Include the limit on the maximum value itself.

  • step: The step amount for the range of values.

  • default: Default value to be set.

class tkmilan.validation.StaticList(values: Iterable[str], *, default: str | None = None, defaultIndex: int | None = None)#

Bases: Tuple[str, …], VSpec

Represent a static list of labels, therefore a tuple of str.

The default label must be explicitely given, either directly as default, or indirectly as defaultIndex. Either way is validated to verify the default is a valid label.

Parameters:

  • values (Iterable[str]) – Values to construct the list.

  • default (str | None) – Default label. Optional.

  • defaultIndex (int | None) – Index for the default label, in the values sequence. Optional.

ldefault: str#

The default label

class tkmilan.validation.StaticMap(mapping: Mapping[str, smvT], *, defaultLabel: str | None = None, defaultValue: smvT | None = None)#

Bases: UserDict, Mapping[str, smvT], Generic[smvT], VSpec

Represent a static mapping between labels and its corresponding values.

The mapping parameter matches labels to values. This must be bi-injective, that is, there cannot be values corresponding to multiple labels.

The default label must be explicitely given, either directly as defaultLabel, or indirectly as defaultValue. Either way is validated to verify the default is a valid label.

Parameters:

  • mapping – Mapping between labels and values.

  • defaultLabel – Default label. Optional.

  • defaultValue – Default value, to derive the default label. Optional.

ldefault: str#

The default label

rlabels: Mapping[smvT, str]#

The reverse mapping, between values and its corresponding labels.

vdefault: smvT#

The default value

class tkmilan.validation.VSpec#

Bases: object

Abstract parent class for all validation representations.

class tkmilan.validation.limT#

Generic Type for var.Limit.

This is a typing.TypeVar, to be used only when typechecking. See typing.

alias of TypeVar(‘limT’, bound=Number)

class tkmilan.validation.smvT#

Generic Type-Checking variable type for SpecParsed.

This is a typing.TypeVar, to be used only when typechecking. See typing.

alias of TypeVar(‘smvT’)

tkmilan.validation.StaticMapLabels(fn: Callable[[str], smvT], lst: Sequence[str], *, defaultIndex: int | None = None, **kwargs) → StaticMap[smvT]#

Turn a list of labels into a mapping, by applying a function to get the value.

Wrapper for StaticMap.

tkmilan.validation.StaticMapValues(fn: Callable[[smvT], str], lst: Sequence[smvT], *, defaultIndex: int | None = None, **kwargs) → StaticMap[smvT]#

Turn a list of values into a mapping, by applying a function to get the label.

Wrapper for StaticMap.

tkmilan.validation.INFO_FORMAT_BASE: Mapping[int, Tuple[str, str, str]] = {2: ('0b', '0', 'b'), 8: ('0o', '0', 'o'), 10: ('', ' ', 'd'), 16: ('0x', '0', 'X')}#

Metadata for LimitBounded.format_value, per supported base.

tkmilan.validation.LIMIT_INFINITE: str = '∞'#

String representation of infinite boundary.

tkmilan.validation.LIMIT_ISTRING: Mapping[bool, str] = {False: ']', True: '['}#

Mapping between inclusion boolean, and boundary representation.