Validators¶

A mechanism for validating that input meets a given set of criteria.

Usage¶

A validator is a callable that accepts a string as input, and returns None on success, or a string on failure. If a string is returned, that string will be used as an error message. For example, the following example will validate that the user's input starts with the text "Hello":

def must_say_hello(value):
    if value.lower().startswith("hello"):
        return None
    return "Why didn't you say hello?"

Toga provides built-in validators for a range of common validation types, as well as some base classes that can be used as a starting point for custom validators.

A list of validators can then be provided to any widget that performs validation, such as the TextInput widget. In the following example, a TextInput will validate that the user has entered text that starts with "hello", and has provided at least 10 characters of input:

import toga
from toga.validators import MinLength

widget = toga.TextInput(validators=[
    must_say_hello,
    MinLength(10)
])

Whenever the input changes, all validators will be evaluated in the order they have been specified. The first validator to fail will put the widget into an "error" state, and the error message returned by that validator will be displayed to the user.

Reference¶

toga.validators.BooleanValidator ¶

BooleanValidator(error_message, allow_empty=True)

An abstract base class for defining a simple validator.

Subclasses should implement the is_valid() method

PARAMETER	DESCRIPTION
`error_message`	The error to display to the user when the input isn't valid. TYPE: `str`
`allow_empty`	Optional; Is no input considered valid? Defaults to `True` TYPE: `bool` DEFAULT: `True`

is_valid `abstractmethod` ¶

is_valid(input_string)

Is the input string valid?

PARAMETER	DESCRIPTION
`input_string`	The string to validate. TYPE: `str`

RETURNS	DESCRIPTION
`bool`	`True` if the input is valid.

toga.validators.CountValidator ¶

CountValidator(
    count,
    expected_existence_message,
    expected_non_existence_message,
    expected_count_message,
    allow_empty=True,
)

An abstract base class for validators that are based on counting instances of some content in the overall content.

Subclasses should implement the count() method to identify the content of interest.

PARAMETER	DESCRIPTION
`count`	Optional; The expected count. TYPE: `int \| None`
`expected_existence_message`	The error message to show if matches are expected, but were not found. TYPE: `str`
`expected_non_existence_message`	The error message to show if matches were not expected, but were found. TYPE: `str`
`expected_count_message`	The error message to show if matches were expected, but a different number were found. TYPE: `str`
`allow_empty`	Optional; Is no input considered valid? Defaults to `True` TYPE: `bool` DEFAULT: `True`

count `abstractmethod` ¶

count(input_string)

Count the instances of content of interest in the input string.

PARAMETER	DESCRIPTION
`input_string`	The string to inspect for content of interest. TYPE: `str`

RETURNS	DESCRIPTION
`int`	The number of instances of content that the validator is looking for.

toga.validators.Contains ¶

Contains(substring, count=None, error_message=None, allow_empty=True)

Bases: CountValidator

A validator confirming that the string contains one or more copies of a substring.

PARAMETER	DESCRIPTION
`substring`	The substring that must exist in the input. TYPE: `str`
`count`	Optional; The exact number of matches that are expected. TYPE: `int \| None` DEFAULT: `None`
`error_message`	Optional; the error message to display when the input doesn't contain the substring (or the requested count of substrings). TYPE: `str \| None` DEFAULT: `None`
`allow_empty`	Optional; Is no input considered valid? Defaults to `True` TYPE: `bool` DEFAULT: `True`

toga.validators.ContainsDigit ¶

ContainsDigit(count=None, error_message=None, allow_empty=True)

Bases: CountValidator

A validator confirming that the string contains digits.

PARAMETER	DESCRIPTION
`count`	Optional; if provided, the exact count of digits that must exist. If not provided, the existence of any digit will make the string valid. TYPE: `int \| None` DEFAULT: `None`
`error_message`	Optional; the error message to display when the input doesn't contain digits (or the requested count of digits). TYPE: `str \| None` DEFAULT: `None`
`allow_empty`	Optional; Is no input considered valid? Defaults to `True` TYPE: `bool` DEFAULT: `True`

toga.validators.ContainsLowercase ¶

ContainsLowercase(count=None, error_message=None, allow_empty=True)

Bases: CountValidator

A validator confirming that the string contains lower case letters.

PARAMETER	DESCRIPTION
`count`	Optional; if provided, the exact count of lower case letters that must exist. If not provided, the existence of any lower case letter will make the string valid. TYPE: `int \| None` DEFAULT: `None`
`error_message`	Optional; the error message to display when the input doesn't contain lower case letters (or the requested count of lower case letters). TYPE: `str \| None` DEFAULT: `None`
`allow_empty`	Optional; Is no input considered valid? Defaults to `True` TYPE: `bool` DEFAULT: `True`

toga.validators.ContainsSpecial ¶

ContainsSpecial(count=None, error_message=None, allow_empty=True)

Bases: CountValidator

A validator confirming that the string contains "special" (i.e., non-alphanumeric) characters.

PARAMETER	DESCRIPTION
`count`	Optional; if provided, the exact count of special characters that must exist. If not provided, the existence of any special character will make the string valid. TYPE: `int \| None` DEFAULT: `None`
`error_message`	Optional; the error message to display when the input doesn't contain special characters (or the requested count of special characters). TYPE: `str \| None` DEFAULT: `None`
`allow_empty`	Optional; Is no input considered valid? Defaults to `True` TYPE: `bool` DEFAULT: `True`

toga.validators.ContainsUppercase ¶

ContainsUppercase(count=None, error_message=None, allow_empty=True)

Bases: CountValidator

A validator confirming that the string contains upper case letters.

PARAMETER	DESCRIPTION
`count`	Optional; if provided, the exact count of upper case letters that must exist. If not provided, the existence of any upper case letter will make the string valid. TYPE: `int \| None` DEFAULT: `None`
`error_message`	Optional; the error message to display when the input doesn't contain upper case letters (or the requested count of upper case letters). TYPE: `str \| None` DEFAULT: `None`
`allow_empty`	Optional; Is no input considered valid? Defaults to `True` TYPE: `bool` DEFAULT: `True`

toga.validators.Email ¶

Email(error_message=None, allow_empty=True)

Bases: MatchRegex

A validator confirming that the string is an email address.

Note

It's impossible to do true RFC-compliant email validation with a regex. This validator does a "best effort" validation. It will inevitably allow some email addresses that aren't technically valid. However, it shouldn't exclude any valid email addresses.

PARAMETER	DESCRIPTION
`error_message`	Optional; the error message to display when the input isn't a number. TYPE: `str \| None` DEFAULT: `None`
`allow_empty`	Optional; Is no input considered valid? Defaults to `True` TYPE: `bool` DEFAULT: `True`

toga.validators.EndsWith ¶

EndsWith(substring, error_message=None, allow_empty=True)

Bases: BooleanValidator

A validator confirming that the string ends with a given substring.

PARAMETER	DESCRIPTION
`substring`	The substring that the input must end with. TYPE: `str`
`error_message`	Optional; the error message to display when the string doesn't end with the given substring. TYPE: `str \| None` DEFAULT: `None`
`allow_empty`	Optional; Is no input considered valid? Defaults to `True` TYPE: `bool` DEFAULT: `True`

toga.validators.Integer ¶

Integer(error_message=None, allow_empty=True)

Bases: BooleanValidator

A validator confirming that the string is an integer.

PARAMETER	DESCRIPTION
`error_message`	Optional; the error message to display when the input isn't an integer. TYPE: `str \| None` DEFAULT: `None`
`allow_empty`	Optional; Is no input considered valid? Defaults to `True` TYPE: `bool` DEFAULT: `True`

toga.validators.LengthBetween ¶

LengthBetween(min_length, max_length, error_message=None, allow_empty=True)

Bases: BooleanValidator

A validator confirming that the length of input falls in a given range.

PARAMETER	DESCRIPTION
`min_length`	The minimum length of the string (inclusive). TYPE: `int \| None`
`max_length`	The maximum length of the string (inclusive). TYPE: `int \| None`
`error_message`	Optional; the error message to display when the length isn't in the given range. TYPE: `str \| None` DEFAULT: `None`
`allow_empty`	Optional; Is no input considered valid? Defaults to `True` TYPE: `bool` DEFAULT: `True`

toga.validators.MatchRegex ¶

MatchRegex(regex_string, error_message=None, allow_empty=True)

Bases: BooleanValidator

A validator confirming that the string matches a given regular expression.

PARAMETER	DESCRIPTION
`regex_string`	A regular expression that the input must match. TYPE: `str`
`error_message`	Optional; the error message to display when the input doesn't match the provided regular expression. TYPE: `str \| None` DEFAULT: `None`
`allow_empty`	Optional; Is no input considered valid? Defaults to `True` TYPE: `bool` DEFAULT: `True`

toga.validators.MaxLength ¶

MaxLength(length, error_message=None)

Bases: LengthBetween

A validator confirming that the length of input does not exceed a maximum size.

PARAMETER	DESCRIPTION
`length`	The maximum length of the string (inclusive). TYPE: `int`
`error_message`	Optional; the error message to display when the string is too long. TYPE: `str \| None` DEFAULT: `None`

toga.validators.MinLength ¶

MinLength(length, error_message=None, allow_empty=True)

Bases: LengthBetween

A validator confirming that the length of input exceeds a minimum size.

PARAMETER	DESCRIPTION
`length`	The minimum length of the string (inclusive). TYPE: `int`
`error_message`	Optional; the error message to display when the string isn't long enough. TYPE: `str \| None` DEFAULT: `None`
`allow_empty`	Optional; Is no input considered valid? Defaults to `True` TYPE: `bool` DEFAULT: `True`

toga.validators.NotContains ¶

NotContains(substring, error_message=None)

Bases: Contains

A validator confirming that the string does not contain a substring.

PARAMETER	DESCRIPTION
`substring`	A substring that must not exist in the input. TYPE: `str`
`error_message`	Optional; the error message to display when the input contains the provided substring. TYPE: `str \| None` DEFAULT: `None`

toga.validators.Number ¶

Number(error_message=None, allow_empty=True)

Bases: BooleanValidator

A validator confirming that the string is a number.

PARAMETER	DESCRIPTION
`error_message`	Optional; the error message to display when the input isn't a number. TYPE: `str \| None` DEFAULT: `None`
`allow_empty`	Optional; Is no input considered valid? Defaults to `True` TYPE: `bool` DEFAULT: `True`

toga.validators.StartsWith ¶

StartsWith(substring, error_message=None, allow_empty=True)

Bases: BooleanValidator

A validator confirming that the input starts with a given substring.

PARAMETER	DESCRIPTION
`substring`	The substring that the input must start with. TYPE: `str`
`error_message`	Optional; the error message to display when the string doesn't start with the given substring. TYPE: `str \| None` DEFAULT: `None`
`allow_empty`	Optional; Is no input considered valid? Defaults to `True` TYPE: `bool` DEFAULT: `True`

Validators¶

Usage¶

Reference¶

toga.validators.BooleanValidator ¶

is_valid abstractmethod ¶

toga.validators.CountValidator ¶

count abstractmethod ¶

toga.validators.Contains ¶

toga.validators.ContainsDigit ¶

toga.validators.ContainsLowercase ¶

toga.validators.ContainsSpecial ¶

toga.validators.ContainsUppercase ¶

toga.validators.Email ¶

toga.validators.EndsWith ¶

toga.validators.Integer ¶

toga.validators.LengthBetween ¶

toga.validators.MatchRegex ¶

toga.validators.MaxLength ¶

toga.validators.MinLength ¶

toga.validators.NotContains ¶

toga.validators.Number ¶

toga.validators.StartsWith ¶

is_valid `abstractmethod` ¶

count `abstractmethod` ¶