Validation#

Validation attaches input validation to Entry, Combobox, and Spinbox widgets — ready-made checks for text, numbers, ranges, patterns, and option lists, plus add for your own. A rejected value is refused as the user types or on focus-out. The Validation guide shows them in use.

class Validation#

Bases: object

Namespace of input-validation rules for Entry, Spinbox, and Combobox.

Each method attaches a rule to a widget; a value that fails the rule flags the widget with the ttk invalid state (a danger-colored border) until the contents become valid again. Call them like Validation.numeric(entry).

The when argument on every method controls when the rule runs:

  • "focusout" — when the widget loses focus (the default)

  • "focusin" — when the widget gains focus

  • "focus" — on both focus in and focus out

  • "key" — on every keystroke, as the user types

  • "all" — in all of the above situations

Use Validation.add for a custom rule (a function decorated with @validator).

static add(widget, func, when='focusout', **kwargs)#

Attach a custom rule to widget.

The rule func receives a ValidationEvent and returns a boolean; it is usually written with the @validator decorator. Extra keyword arguments are forwarded to the rule on each call (as add_range_validation forwards its bounds).

Parameters:

  • widget (Widget) – The Entry, Combobox, or Spinbox to validate.

  • func (Callable) – The validation function, called on each validation event.

  • when (str) – When the rule runs. See the class docstring for the options.

  • kwargs (Dict) – Optional arguments forwarded to func.

Return type:

None

static numeric(widget, when='focusout')#

Require the contents to be numeric (an empty field passes).

Parameters:
Return type:

None

static options(widget, options, when='focusout')#

Require the contents to be one of the values in options.

Parameters:
Return type:

None

static phonenumber(widget, when='focusout')#

Require the contents to match a common phone-number pattern.

Parameters:
Return type:

None

static range(widget, start, end, when='focusout')#

Require a number within start–end inclusive (an empty field passes).

Parameters:

  • widget (Widget) – The widget on which to add validation.

  • start (int or float) – The lower bound of the accepted range, inclusive.

  • end (int or float) – The upper bound of the accepted range, inclusive.

  • when (str) – When the rule runs. See the class docstring for the options.

Return type:

None

static regex(widget, pattern, when='focusout')#

Require the contents to match the regular expression pattern.

Parameters:
Return type:

None

static text(widget, when='focusout')#

Require the contents to be alphabetic (an empty field passes).

Parameters:
Return type:

None

validator(func)#

Decorates a standard function so that it receives the validation events returned by the validate command on the tkinter widgets.

Parameters:

func (Callable) – The validation function to be decorated.

Return type:

Callable[[…], bool]

class ValidationEvent(d, i, P, s, S, v, V, W)#

Bases: object

Contains the attributes of a validation event returned by the validatecommand on a tkinter widget.

Parameters:
actioncode#

0 for an attempted deletion, 1 for an attempted insertion, or -1 if the callback was for focusin, focusout, or a change to the textvariable.

Type:

str

insertdeleteindex#

When the user attempts to insert or delete text, this attribute will be the index of the beginning of the insertion or deletion. If the callback was due to focusin, focusout, or a change to the textvariable, the attribute will be -1.

Type:

str

postchangetext#

The value that the text will have if the change is allowed.

Type:

str

prechangetext#

The text in the entry before the change.

Type:

str

insertdeletetext#

The text inserted or deleted if the call was due to an insertion or deletion.

Type:

str

validationtype#

Specifies the widget’s validation option which specifies _when_ the validation will occur.

Type:

str

validationreason#

The reason for the validation callback (key, focusin, focusout, forced).

Type:

str

widget#

The widget object that is being validated.

Type:

Widget

See also#