[go: up one dir, main page]
Skip to content

textual.validation

This module provides a number of classes for validating input.

See Validating Input for details.

Failure dataclass 

Failure(validator, value=None, description=None)

Information about a validation failure.

description class-attribute instance-attribute 

description = None

An optional override for describing this failure. Takes precedence over any messages set in the Validator.

validator instance-attribute 

validator

The Validator which produced the failure.

value class-attribute instance-attribute 

value = None

The value which resulted in validation failing.

Function 

Function(function, failure_description=None)

Bases: Validator

A flexible validator which allows you to provide custom validation logic.

function instance-attribute 

function = function

Function which takes the value to validate and returns True if valid, and False otherwise.

ReturnedFalse dataclass 

ReturnedFalse(validator, value=None, description=None)

Bases: Failure

Indicates validation failed because the supplied function returned False.

describe_failure 

describe_failure(failure)

Describes why the validator failed.

Parameters:

Name Type Description Default

failure

Failure

Information about why the validation failed.

 required

Returns:

Type Description
str | None

A string description of the failure.

validate 

validate(value)

Validate that the supplied function returns True.

Parameters:

Name Type Description Default

value

str

The value to pass into the supplied function.

 required

Returns:

Type Description
ValidationResult

A ValidationResult indicating success if the function returned True, and failure if the function return False.

Integer 

Integer(
    minimum=None, maximum=None, failure_description=None
)

Bases: Number

Validator which ensures the value is an integer which falls within a range.

NotAnInteger dataclass 

NotAnInteger(validator, value=None, description=None)

Bases: Failure

Indicates a failure due to the value not being a valid integer.

describe_failure 

describe_failure(failure)

Describes why the validator failed.

Parameters:

Name Type Description Default

failure

Failure

Information about why the validation failed.

 required

Returns:

Type Description
str | None

A string description of the failure.

validate 

validate(value)

Ensure that value is an integer, optionally within a range.

Parameters:

Name Type Description Default

value

str

The value to validate.

 required

Returns:

Type Description
ValidationResult

The result of the validation.

Length 

Length(
    minimum=None, maximum=None, failure_description=None
)

Bases: Validator

Validate that a string is within a range (inclusive).

maximum instance-attribute 

maximum = maximum

The inclusive maximum length of the value, or None if unbounded.

minimum instance-attribute 

minimum = minimum

The inclusive minimum length of the value, or None if unbounded.

Incorrect dataclass 

Incorrect(validator, value=None, description=None)

Bases: Failure

Indicates a failure due to the length of the value being outside the range.

describe_failure 

describe_failure(failure)

Describes why the validator failed.

Parameters:

Name Type Description Default

failure

Failure

Information about why the validation failed.

 required

Returns:

Type Description
str | None

A string description of the failure.

validate 

validate(value)

Ensure that value falls within the maximum and minimum length constraints.

Parameters:

Name Type Description Default

value

str

The value to validate.

 required

Returns:

Type Description
ValidationResult

The result of the validation.

Number 

Number(
    minimum=None, maximum=None, failure_description=None
)

Bases: Validator

Validator that ensures the value is a number, with an optional range check.

maximum instance-attribute 

maximum = maximum

The maximum value of the number, inclusive. If None, the maximum is unbounded.

minimum instance-attribute 

minimum = minimum

The minimum value of the number, inclusive. If None, the minimum is unbounded.

NotANumber dataclass 

NotANumber(validator, value=None, description=None)

Bases: Failure

Indicates a failure due to the value not being a valid number (decimal/integer, inc. scientific notation)

NotInRange dataclass 

NotInRange(validator, value=None, description=None)

Bases: Failure

Indicates a failure due to the number not being within the range [minimum, maximum].

describe_failure 

describe_failure(failure)

Describes why the validator failed.

Parameters:

Name Type Description Default

failure

Failure

Information about why the validation failed.

 required

Returns:

Type Description
str | None

A string description of the failure.

validate 

validate(value)

Ensure that value is a valid number, optionally within a range.

Parameters:

Name Type Description Default

value

str

The value to validate.

 required

Returns:

Type Description
ValidationResult

The result of the validation.

Regex 

Regex(regex, flags=0, failure_description=None)

Bases: Validator

A validator that checks the value matches a regex (via re.fullmatch).

flags instance-attribute 

flags = flags

The flags to pass to re.fullmatch.

regex instance-attribute 

regex = regex

The regex which we'll validate is matched by the value.

NoResults dataclass 

NoResults(validator, value=None, description=None)

Bases: Failure

Indicates validation failed because the regex could not be found within the value string.

describe_failure 

describe_failure(failure)

Describes why the validator failed.

Parameters:

Name Type Description Default

failure

Failure

Information about why the validation failed.

 required

Returns:

Type Description
str | None

A string description of the failure.

validate 

validate(value)

Ensure that the value matches the regex.

Parameters:

Name Type Description Default

value

str

The value that should match the regex.

 required

Returns:

Type Description
ValidationResult

The result of the validation.

URL 

URL(failure_description=None)

Bases: Validator

Validator that checks if a URL is valid (ensuring a scheme is present).

InvalidURL dataclass 

InvalidURL(validator, value=None, description=None)

Bases: Failure

Indicates that the URL is not valid.

describe_failure 

describe_failure(failure)

Describes why the validator failed.

Parameters:

Name Type Description Default

failure

Failure

Information about why the validation failed.

 required

Returns:

Type Description
str | None

A string description of the failure.

validate 

validate(value)

Validates that value is a valid URL (contains a scheme).

Parameters:

Name Type Description Default

value

str

The value to validate.

 required

Returns:

Type Description
ValidationResult

The result of the validation.

ValidationResult dataclass 

ValidationResult(failures=list())

The result of calling a Validator.validate method.

failure_descriptions property 

failure_descriptions

Utility for extracting failure descriptions as strings.

Useful if you don't care about the additional metadata included in the Failure objects.

Returns:

Type Description
list[str]

A list of the string descriptions explaining the failing validations.

failures class-attribute instance-attribute 

failures = field(default_factory=list)

A list of reasons why the value was invalid. Empty if valid=True

is_valid property 

is_valid

True if the validation was successful.

failure staticmethod 

failure(failures)

Construct a failure ValidationResult.

Parameters:

Name Type Description Default

failures

Sequence[Failure]

The failures.

 required

Returns:

Type Description
ValidationResult

A failure ValidationResult.

merge staticmethod 

merge(results)

Merge multiple ValidationResult objects into one.

Parameters:

Name Type Description Default

results

Sequence['ValidationResult']

List of ValidationResult objects to merge.

 required

Returns:

Type Description
'ValidationResult'

Merged ValidationResult object.

success staticmethod 

success()

Construct a successful ValidationResult.

Returns:

Type Description
ValidationResult

A successful ValidationResult.

Validator 

Validator(failure_description=None)

Bases: ABC

Base class for the validation of string values.

Commonly used in conjunction with the Input widget, which accepts a list of validators via its constructor. This validation framework can also be used to validate any 'stringly-typed' values (for example raw command line input from sys.args).

To implement your own Validator, subclass this class.

Example 
class Palindrome(Validator):
    def validate(self, value: str) -> ValidationResult:
        def is_palindrome(value: str) -> bool:
            return value == value[::-1]
        return self.success() if is_palindrome(value) else self.failure("Not palindrome!")

failure_description instance-attribute 

failure_description = failure_description

A description of why the validation failed.

The description (intended to be user-facing) to attached to the Failure if the validation fails. This failure description is ultimately accessible at the time of validation failure via the Input.Changed or Input.Submitted event, and you can access it on your message handler (a method called, for example, on_input_changed or a method decorated with @on(Input.Changed).

describe_failure 

describe_failure(failure)

Return a string description of the Failure.

Used to provide a more fine-grained description of the failure. A Validator could fail for multiple reasons, so this method could be used to provide a different reason for different types of failure.

Warning

This method is only called if no other description has been supplied. If you supply a description inside a call to self.failure(description="..."), or pass a description into the constructor of the validator, those will take priority, and this method won't be called.

Parameters:

Name Type Description Default

failure

Failure

Information about why the validation failed.

 required

Returns:

Type Description
str | None

A string description of the failure.

failure 

failure(description=None, value=None, failures=None)

Shorthand for signaling validation failure.

You can return failure(...) from a Validator.validate implementation to signal validation succeeded.

Parameters:

Name Type Description Default

description

str | None

The failure description that will be used. When used in conjunction with the Input widget, this is the description that will ultimately be available inside the handler for Input.Changed. If not supplied, the failure_description from the Validator will be used. If that is not supplied either, then the describe_failure method on Validator will be called.

 None

value

str | None

The value that was considered invalid. This is optional, and only needs to be supplied if required in your Input.Changed handler.

 None

failures

Failure | Sequence[Failure] | None

The reasons the validator failed. If not supplied, a generic Failure will be included in the ValidationResult returned from this function.

 None

Returns:

Type Description
ValidationResult

A ValidationResult representing failed validation, and containing the metadata supplied to this function.

success 

success()

Shorthand for ValidationResult(True).

You can return success() from a Validator.validate method implementation to signal that validation has succeeded.

Returns:

Type Description
ValidationResult

A ValidationResult indicating validation succeeded.

validate abstractmethod 

validate(value)

Validate the value and return a ValidationResult describing the outcome of the validation.

Parameters:

Name Type Description Default

value

str

The value to validate.

 required

Returns:

Type Description
ValidationResult

The result of the validation.