tkmilan.var#

Variable classes. Extends the existing variable types defined in tkinter.

Module Attributes

`objT`	Generic Type-Checking variable type for `ObjectList`.
`spvT`	Generic Type-Checking variable type for `SpecParsed`.
`MAP_VALIDATIONS`	Mapping between `validation.VSpec` representations, and the corresponding variable class.
`ValidationLimit`	Configure widget validation to enhance the tooltip information with `Spec` violation information.

Functions

trace(var, function, *[, trace_mode, ...])

Trace the variable var.

Classes

`Boolean`([master, value, name])	Value holder for `bool`.
`Double`([master, value, name])	Value holder for `float`.
`Int`([master, value, name])	Value holder for `int`.
`Limit`(limit, args, *kwargs)	Represent a range to limit a value, for simple integers.
`LimitBounded`(limit, args, *kwargs)	A bounded variant of the `Limit` range.
`LimitUnbounded`(limit, args, *kwargs)	An unbounded variant of the `Limit` range.
`ObjectList`([master, value, name])	Generic value holder for a sequence of object of `objT` type.
`Spec`([spec])	Abstract parent class for validated `String` variables.
`SpecCountable`([spec])	Abstract parent class for validated `String` variables, with countable amount of valid alternatives.
`SpecParsed`([spec])	Abstract parent class for validated `String` variables, with a parsed value (instead of a boolean validation).
`StaticList`([spec])	Specifies a static list of labels.
`StaticMap`([spec])	Specifies a static mapping between labels and its corresponding values.
`String`([master, value, name])	Value holder for `str`.
`StringList`([master, value, name])	Value holder for a list of `str`.
`Variable`([master, value, name])	Parent class for all value holders
`aggregator`([master, value, name])	Synthetic value holder for an aggregation of other variables.
`nothing`([master, value, name])	Value holder for `None`.

class tkmilan.var.Boolean(master=None, value=None, name=None)#

Bases: BooleanVar, Variable

Value holder for bool.

class tkmilan.var.Double(master=None, value=None, name=None)#

Bases: DoubleVar, Variable

Value holder for float.

class tkmilan.var.Int(master=None, value=None, name=None)#

Bases: IntVar, Variable

Value holder for int.

class tkmilan.var.Limit(limit: LimitBounded | LimitUnbounded, *args, **kwargs)#

Bases: SpecParsed[int]

Represent a range to limit a value, for simple integers.

The range is represented as the container parameter, one of the LimitBounded or LimitUnbounded <validation.LimitUnbounded>.

When instancing directly, the limit parameter will instance the right subclass. This means this class can not be instanced directly without arguments, and when instance with a validation representation, it will create an object of the right subclass.

Parameters:: limit (LimitBounded | LimitUnbounded) – The validation representation for this type. Mandatory.

All other arguments are passed to the right subclass.

See also

The supported subclasses:

LimitBounded
LimitUnbounded

getLabel(value: spvT | None) → str#

Return the label corresponding to the given value.

This is very efficient.

See also

The upstream function this aliases is SpecParsed.getLabel.

get_spinargs(*, dincrement: float = 1.0) → Tuple[float, float, float]#

Get all SpinboxN value arguments.

Parameters:: dincrement (float) – Default increment value, when the limit does not support it. Defaults to 1.0.

Return Value:

Returns a tuple with three floating point values:

from
to
increment

container: LimitBounded | LimitUnbounded#

The container object representing the specification, a mapping between label and value.

Follows the mapping class interface.

class tkmilan.var.LimitBounded(limit: LimitBounded | LimitUnbounded, *args, **kwargs)#

Bases: Limit, SpecCountable

A bounded variant of the Limit range.

Since this is bounded, it’s a countable specification.

Parameters:

limit (LimitBounded | LimitUnbounded) – The LimitBounded range object..
name – Name of the variable (passed to String). Optional, defaults to an autogenerated name.

Note

The name is defined in a global namespace, common to the entire application.

container: LimitBounded | LimitUnbounded#

The container object representing the specification, a mapping between label and value.

Follows the mapping class interface.

ldefault: str#: The default label to be shown to the user.

class tkmilan.var.LimitUnbounded(limit: LimitBounded | LimitUnbounded, *args, **kwargs)#

Bases: Limit

An unbounded variant of the Limit range.

Since this is unbounded, it’s not a countable specification.

Parameters:

limit (LimitBounded | LimitUnbounded) – The LimitUnbounded range object.
name – Name of the variable (passed to String). Optional, defaults to an autogenerated name.

Note

The name is defined in a global namespace, common to the entire application.

container: LimitBounded | LimitUnbounded#

The container object representing the specification, a mapping between label and value.

Follows the mapping class interface.

ldefault: str#: The default label to be shown to the user.

class tkmilan.var.ObjectList(master=None, value=None, name=None)#

Bases: Variable, Generic[objT]

Generic value holder for a sequence of object of objT type.

Just keep an instance variable with the “actual” value. Pretend the value is just an empty str.

See also

StringList: Simpler version of this, supports only str.

get() → Sequence[objT]#

Return value of variable.

set(value: Sequence[objT]) → None#

Set the variable to VALUE.

class tkmilan.var.Spec(spec: VSpec | None = None, *args, **kwargs)#

Bases: String

Abstract parent class for validated String variables.

This variable tracks the label value, but also its valid states, which makes it so that the state type is a model.VState, not a simple str.

Note that this might specify a complex validation, not just a list of discrete values, nor a continous range, for example.

Note

This should not be instanced directly, it’s a parent class to be subclassed on other variable types.

See also

For a countable variant of this, see SpecCountable. For a valued variant of this, see SpecParsed.

__contains__(label: str) → bool#

Check if the label label satisfies the specification.

Wraps the container interface.

Should be used as label in Spec.

get() → VState[bool]#

Returns the value of the variable, as VState.

The value alternates between True for valid labels, and None for invalid labels.

set(state: str | VState[bool])#

Set the variable to state.

Only the label is set, either for direct str or VState.

Note

In debug mode, when setting the variable using a VState, the value itself is re-validated.

container: Container[str]#

The container object representing the specification.

Follows the container class interface.

ldefault: str#: The default label to be shown to the user.

class tkmilan.var.SpecCountable(spec: VSpec | None = None, *args, **kwargs)#

Bases: Spec

Abstract parent class for validated String variables, with countable amount of valid alternatives.

This is an alternative to Spec, when the amount of possible valid values is countable.

Note

This should not be instanced directly, it’s a parent class to be subclassed on other variable types.

See also

For a simpler version of this, see Spec. For a valued variant of the base class, see SpecParsed.

__contains__(label: str) → bool#

Check if the label label satisfies the specification.

Wraps the container interface.

Should be used as label in Spec.

__len__() → int#

Count how many labels this specification contains.

Should be used as len(SpecCountable).

lall() → Sequence[str]#

Get all valid labels supported by this variable.

container: Container[str]#

The container object representing the specification.

Follows the container class interface.

ldefault: str#: The default label to be shown to the user.

class tkmilan.var.SpecParsed(spec: VSpec | None = None, *args, **kwargs)#

Bases: Spec, Generic[spvT]

Abstract parent class for validated String variables, with a parsed value (instead of a boolean validation).

Note

This should not be instanced directly, it’s a parent class to be subclassed on other variable types.

See also

For a simpler version of this, see Spec. For a countable variant of the base class, see SpecCountable.

get() → VState[spvT | None]#

Returns the value of the variable, as VState.

The value alternates between the parsed label, and None for invalid labels.

See also

The base class version is Spec.get. It is compatible, but with different semantics.

getLabel(value: spvT | None) → str#

Return the first label corresponding to the given value.

This is not very efficient, and the mapping might not be bi-injective. It’s mostly implemented for completeness’ sake.

Returns:: lempty if the value is not valid.
Return type:: str

set(state: str | VState[spvT | None])#

Set the variable to state.

Only the label is set, either for direct str or VState.

Note

In debug mode, when setting the variable using a VState, the value itself is re-validated.

In debug mode, mark the variable with _complexValidation = True to skip the validation about broken VState.

See also

The base class version is Spec.set. It is compatible, but with different semantics.

container: Mapping[str, spvT]#

The container object representing the specification, a mapping between label and value.

Follows the mapping class interface.

lempty: str = ''#

The default label for invalid values.

This is only necessary on rare circumstances. Should map to an invalid value.

class tkmilan.var.StaticList(spec: VSpec | None = None, *args, **kwargs)#

Bases: SpecCountable

Specifies a static list of labels.

Parameters:

spec (VSpec | None) – The list validation object.
name – Name of the variable (passed to String). Optional, defaults to an autogenerated name.

Note

The name is defined in a global namespace, common to the entire application.

container: Container[str]#

The container object representing the specification.

Follows the container class interface.

ldefault: str#: The default label to be shown to the user.

class tkmilan.var.StaticMap(spec: VSpec | None = None, *args, **kwargs)#

Bases: SpecCountable, SpecParsed[spvT]

Specifies a static mapping between labels and its corresponding values.

Parameters:

spec (VSpec | None) – The mapping validation object.
name – Name of the variable (passed to String). Optional, defaults to an autogenerated name.

Note

The name is defined in a global namespace, common to the entire application.

getLabel(value: spvT | None) → str#

Return the label corresponding to the given value.

This is very efficient, and the mapping is enforced to be bi-injective.

See also

The upstream function this aliases is SpecParsed.getLabel.

container: Container[str]#

The container object representing the specification, a mapping between label and value.

Follows the mapping class interface.

ldefault: str#: The default label to be shown to the user.

class tkmilan.var.String(master=None, value=None, name=None)#

Bases: StringVar, Variable

Value holder for str.

class tkmilan.var.StringList(master=None, value=None, name=None)#

Bases: Variable

Value holder for a list of str.

In Tk, everything is a string and the syntax for lists is similar to Python, so this is technically supported, but sounds like a coincidence.

Works well, though.

See also

ObjectList for an arbitrary list of Python objects.

get() → Iterable[str]#

Return value of variable.

set(value: Iterable[str]) → None#

Set the variable to VALUE.

class tkmilan.var.Variable(master=None, value=None, name=None)#

Bases: Variable

Parent class for all value holders

ignoreContainerTrace: bool = False#: When this variable is attached to a container, do not consider it for tracing purposes.

ready: bool = True#

Check if the variable is ready for usage.

Defaults to True, this exists for compatibility with aggregator.

class tkmilan.var.aggregator(master=None, value=None, name=None, *, cwidget: tkmilan_mixin.MixinWidget)#

Bases: Variable

Synthetic value holder for an aggregation of other variables.

Useful for container widgets.

get() → None#

Return value of variable.

set(value: None = None)#

Set the variable to VALUE.

property ready: bool#: Check if the variable is ready for usage.

tout: TimeoutIdle | None#

Hold the TimeoutIdle object that indicates this variable is setup.

Since this variable is a synthetic variable, useful only when triggered from other function, it needs configuration before it can be used. For optimisation reasons, this is not done right on __init__ like most other variables.

Defaults to None, indicating it is not ready. See ready.

class tkmilan.var.nothing(master=None, value=None, name=None)#

Bases: Variable

Value holder for None.

Useful for widgets that don’t store anything, like buttons.

get()#: Return value of variable.

set(value: None)#

Set the variable to VALUE.

class tkmilan.var.objT#

Generic Type-Checking variable type for ObjectList.

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

alias of TypeVar(‘objT’)

class tkmilan.var.spvT#

Generic Type-Checking variable type for SpecParsed.

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

alias of TypeVar(‘spvT’)

tkmilan.var.trace(var: Variable, function: Callable, *, trace_mode: Literal['read', 'write', 'unset'] = 'write', trace_initial: bool = False, **kwargs: Any) → str#

Trace the variable var.

There is no Python documentation, see Tk trace variable documentation.

The function arguments will be:

var: The traced variable
etype: The trace mode (see trace_mode)
The other given kwargs

It is possible to run the function as soon as the trace is defined. This is useful if the trace is used to keep state in sync.

Parameters:

var (Variable) – The traced variable.
function (Callable) – The callback function.
trace_mode (Literal['read', 'write', 'unset']) – The trace mode, when should the callback be invoked. None when running on the initial function call (see trace_initial).
trace_initial (bool) – Run the callback function on start. Runs async (similar to model.TimeoutIdle).
kwargs (Any) – Passed to the callback function.

Returns:

Return the function identifier, as stored by Tk.

Return type:

str

tkmilan.var.MAP_VALIDATIONS = {<class 'tkmilan.validation.StaticList'>: <class 'tkmilan.var.StaticList'>, <class 'tkmilan.validation.StaticMap'>: <class 'tkmilan.var.StaticMap'>, <class 'tkmilan.validation.LimitBounded'>: <class 'tkmilan.var.LimitBounded'>, <class 'tkmilan.validation.LimitUnbounded'>: <class 'tkmilan.var.LimitUnbounded'>}#: Mapping between validation.VSpec representations, and the corresponding variable class.

tkmilan.var.ValidationLimit = VSettings(postVar=True, postInitial=True, fn=<function __vfn_limit>, fnSimple=False, tt=None, ttSimple=False, tkWhen='none')#

Configure widget validation to enhance the tooltip information with Spec violation information.

This distinguishes between an invalid value, and a value outside the Spec. This is more apparent on Limit.

This is only experimental code, but should work as intended on this narrow case.

To be used as:

Widget(self, ...
            validation=var.ValidationLimit,
            ...
            ).putTooltip()