Validator Reference¶

Core	Date/Time	Numbers	File-related	Internet-related
`dict`	`date`	`numeric`	`bytesIO`	`email`
`json`	`datetime`	`integer`	`stringIO`	`url`
`string`	`time`	`float`	`path`	`domain`
`iterable`	`timezone`	`fraction`	`path_exists`	`ip_address`
`none`	`timedelta`	`decimal`	`file_exists`	`ipv4`
`not_empty`			`directory_exists`	`ipv6`
`uuid`			`readable`	`mac_address`
`variable_name`			`writeable`	`mimetype`
			`executable`

Using Validators¶

A validator does what it says on the tin: It validates that an input value is what you think it should be, and returns its valid form.

Each validator is expressed as the name of the thing being validated, for example email().

Each validator accepts a value as its first argument, and an optional allow_empty boolean as its second argument. For example:

email_address = validators.email(value, allow_empty = True)

If the value you’re validating validates successfully, it will be returned. If the value you’re validating needs to be coerced to a different type, the validator will try to do that. So for example:

validators.integer(1)
validators.integer('1')

will both return an int of 1.

If the value you’re validating is empty/falsey and allow_empty is False, then the validator will raise a EmptyValueError exception (which inherits from the built-in ValueError). If allow_empty is True, then an empty/falsey input value will be converted to a None value.

Caution

By default, allow_empty is always set to False.

Hint

Some validators (particularly numeric ones like integer) have additional options which are used to make sure the value meets criteria that you set for it. These options are always included as keyword arguments after the allow_empty argument, and are documented for each validator below.

When Validation Fails¶

Validators raise exceptions when validation fails. All exceptions raised inherit from built-in exceptions like ValueError, TypeError, and IOError.

If the value you’re validating fails its validation for some reason, the validator may raise different exceptions depending on the reason. In most cases, this will be a descendent of ValueError though it can sometimes be a TypeError, or an IOError, etc.

For specifics on each validator’s likely exceptions and what can cause them, please review the Validator Reference.

Hint

While validators will always raise built-in exceptions from the standard library, to give you greater programmatic control over how to respond when validation fails, we have defined a set of custom exceptions that inherit from those built-ins.

Our custom exceptions provide you with very specific, fine-grained information as to why validation for a given value failed. In general, most validators will raise ValueError or TypeError exceptions, and you can safely catch those and be fine. But if you want to handle specific types of situations with greater control, then you can instead catch EmptyValueError, CannotCoerceError, MaximumValueError, and the like.

For more detailed information, please see: Error Reference and Validator Reference.

Disabling Validation¶

Caution

If you are disabling validators using the VALIDATORS_DISABLED environment variable, their related checkers will also be disabled (meaning they will always return True).

Validation can at times be an expensive (in terms of performance) operation. As a result, there are times when you want to disable certain kinds of validation when running in production. Using the Validator-Collection this is simple:

Just add the name of the validator you want disabled to the VALIDATORS_DISABLED environment variable, and validation will automatically be skipped.

Caution

VALIDATORS_DISABLED expects a comma-separated list of values. If it isn’t comma-separated, it won’t work properly.

Here’s how it works in practice. Let’s say we define the following environment variable:

$ export VALIDATORS_DISABLED = "variable_name, email, ipv4"

This disables the variable_name(), email(), and ipv4() validators respectively.

Now if we run:

from validator_collection import validators, errors

try:
    result = validators.variable_name('this is an invalid variable name')
except ValueError:
    # handle the error

The validator will return the value supplied to it un-changed. So that means result will be equal to this is an invalid variable name.

However, if we run:

from validator_collection import validators, errors

try:
    result = validators.integer('this is an invalid variable name')
except errors.NotAnIntegerError:
    # handle the error

the validator will run and raise NotAnIntegerError.

We can force validators to run (even if disabled using the environment variable) by passing a force_run = True keyword argument. For example:

from validator_collection import validators, errors

try:
    result = validators.variable_name('this is an invalid variable name',
                                      force_run = True)
except ValueError:
    # handle the error

will produce a InvalidVariableNameError (which is a type of ValueError).

Core¶

dict¶

dict(value, allow_empty=False, json_serializer=None, **kwargs)[source]¶

Validate that value is a dict.

Hint

If value is a string, this validator will assume it is a JSON object and try to convert it into a dict

You can override the JSON serializer used by passing it to the json_serializer property. By default, will utilize the Python json encoder/decoder.

Parameters:	value – The value to validate. allow_empty (`bool`) – If `True`, returns `None` if `value` is empty. If `False`, raises a `EmptyValueError` if `value` is empty. Defaults to `False`. json_serializer (callable) – The JSON encoder/decoder to use to deserialize a string passed in `value`. If not supplied, will default to the Python `json` encoder/decoder.
Returns:	`value` / `None`
Return type:	`dict` / `None`
Raises:	EmptyValueError – if `value` is empty and `allow_empty` is `False` CannotCoerceError – if `value` cannot be coerced to a `dict` NotADictError – if `value` is not a `dict`

json¶

json(value, schema=None, allow_empty=False, json_serializer=None, **kwargs)[source]¶

Validate that value conforms to the supplied JSON Schema.

Note

schema supports JSON Schema Drafts 3 - 7. Unless the JSON Schema indicates the meta-schema using a $schema property, the schema will be assumed to conform to Draft 7.

Hint

If either value or schema is a string, this validator will assume it is a JSON object and try to convert it into a dict.

You can override the JSON serializer used by passing it to the json_serializer property. By default, will utilize the Python json encoder/decoder.

Parameters:	value – The value to validate. schema – An optional JSON Schema against which `value` will be validated. allow_empty (`bool`) – If `True`, returns `None` if `value` is empty. If `False`, raises a `EmptyValueError` if `value` is empty. Defaults to `False`. json_serializer (callable) – The JSON encoder/decoder to use to deserialize a string passed in `value`. If not supplied, will default to the Python `json` encoder/decoder.
Returns:	`value` / `None`
Return type:	`dict` / `list` of `dict` / `None`
Raises:	EmptyValueError – if `value` is empty and `allow_empty` is `False` CannotCoerceError – if `value` cannot be coerced to a `dict` NotJSONError – if `value` cannot be deserialized from JSON NotJSONSchemaError – if `schema` is not a valid JSON Schema object JSONValidationError – if `value` does not validate against the JSON Schema

string¶

string(value, allow_empty=False, coerce_value=False, minimum_length=None, maximum_length=None, whitespace_padding=False, **kwargs)[source]¶

Validate that value is a valid string.

Parameters:	value (`str` / `None`) – The value to validate. allow_empty (`bool`) – If `True`, returns `None` if `value` is empty. If `False`, raises a `EmptyValueError` if `value` is empty. Defaults to `False`. coerce_value (`bool`) – If `True`, will attempt to coerce `value` to a string if it is not already. If `False`, will raise a `ValueError` if `value` is not a string. Defaults to `False`. minimum_length (`int`) – If supplied, indicates the minimum number of characters needed to be valid. maximum_length (`int`) – If supplied, indicates the minimum number of characters needed to be valid. whitespace_padding (`bool`) – If `True` and the value is below the `minimum_length`, pad the value with spaces. Defaults to `False`.
Returns:	`value` / `None`
Return type:	`str` / `None`
Raises:	EmptyValueError – if `value` is empty and `allow_empty` is `False` CannotCoerceError – if `value` is not a valid string and `coerce_value` is `False` MinimumLengthError – if `minimum_length` is supplied and the length of `value` is less than `minimum_length` and `whitespace_padding` is `False` MaximumLengthError – if `maximum_length` is supplied and the length of `value` is more than the `maximum_length`

iterable¶

iterable(value, allow_empty=False, forbid_literals=(<class 'str'>, <class 'bytes'>), minimum_length=None, maximum_length=None, **kwargs)[source]¶

Validate that value is a valid iterable.

Hint

This validator checks to ensure that value supports iteration using any of Python’s three iteration protocols: the __getitem__ protocol, the __iter__ / next() protocol, or the inheritance from Python’s Iterable abstract base class.

If value supports any of these three iteration protocols, it will be validated. However, if iteration across value raises an unsupported exception, this function will raise an IterationFailedError

Parameters:	value – The value to validate. allow_empty (`bool`) – If `True`, returns `None` if `value` is empty. If `False`, raises a `EmptyValueError` if `value` is empty. Defaults to `False`. forbid_literals (iterable) – A collection of literals that will be considered invalid even if they are (actually) iterable. Defaults to `str` and `bytes`. minimum_length (`int`) – If supplied, indicates the minimum number of members needed to be valid. maximum_length (`int`) – If supplied, indicates the minimum number of members needed to be valid.
Returns:	`value` / `None`
Return type:	iterable / `None`
Raises:	EmptyValueError – if `value` is empty and `allow_empty` is `False` NotAnIterableError – if `value` is not a valid iterable or `None` IterationFailedError – if `value` is a valid iterable, but iteration fails for some unexpected exception MinimumLengthError – if `minimum_length` is supplied and the length of `value` is less than `minimum_length` and `whitespace_padding` is `False` MaximumLengthError – if `maximum_length` is supplied and the length of `value` is more than the `maximum_length`

none¶

none(value, allow_empty=False, **kwargs)[source]¶

Validate that value is None.

Parameters:	value – The value to validate. allow_empty (`bool`) – If `True`, returns `None` if `value` is empty but not `None`. If `False`, raises a `NotNoneError` if `value` is empty but not `None`. Defaults to `False`.
Returns:	`None`
Raises:	NotNoneError – if `allow_empty` is `False` and `value` is empty but not `None` and

not_empty¶

not_empty(value, allow_empty=False, **kwargs)[source]¶

Validate that value is not empty.

Parameters:	value – The value to validate. allow_empty (`bool`) – If `True`, returns `None` if `value` is empty. If `False`, raises a `EmptyValueError` if `value` is empty. Defaults to `False`.
Returns:	`value` / `None`
Raises:	EmptyValueError – if `value` is empty and `allow_empty` is `False`

uuid¶

uuid(value, allow_empty=False, **kwargs)[source]¶

Validate that value is a valid UUID.

Parameters:	value – The value to validate. allow_empty (`bool`) – If `True`, returns `None` if `value` is empty. If `False`, raises a `EmptyValueError` if `value` is empty. Defaults to `False`.
Returns:	`value` coerced to a `UUID` object / `None`
Return type:	`UUID` / `None`
Raises:	EmptyValueError – if `value` is empty and `allow_empty` is `False` CannotCoerceError – if `value` cannot be coerced to a `UUID`

variable_name¶

variable_name(value, allow_empty=False, **kwargs)[source]¶

Validate that the value is a valid Python variable name.

Caution

This function does NOT check whether the variable exists. It only checks that the value would work as a Python variable (or class, or function, etc.) name.

Parameters:	value – The value to validate. allow_empty (`bool`) – If `True`, returns `None` if `value` is empty. If `False`, raises a `EmptyValueError` if `value` is empty. Defaults to `False`.
Returns:	`value` / `None`
Return type:	`str` or `None`
Raises:	EmptyValueError – if `allow_empty` is `False` and `value` is empty

Date / Time¶

date¶

date(value, allow_empty=False, minimum=None, maximum=None, coerce_value=True, **kwargs)[source]¶

Validate that value is a valid date.

Parameters:	value (`str` / `datetime` / `date` / `None`) – The value to validate. allow_empty (`bool`) – If `True`, returns `None` if `value` is empty. If `False`, raises a `EmptyValueError` if `value` is empty. Defaults to `False`. minimum (`datetime` / `date` / compliant `str` / `None`) – If supplied, will make sure that `value` is on or after this value. maximum (`datetime` / `date` / compliant `str` / `None`) – If supplied, will make sure that `value` is on or before this value. coerce_value (`bool`) – If `True`, will attempt to coerce `value` to a `date` if it is a timestamp value. If `False`, will not.
Returns:	`value` / `None`
Return type:	`date` / `None`
Raises:	EmptyValueError – if `value` is empty and `allow_empty` is `False` CannotCoerceError – if `value` cannot be coerced to a `date` and is not `None` MinimumValueError – if `minimum` is supplied but `value` occurs before `minimum` MaximumValueError – if `maximum` is supplied but `value` occurs after `maximum`

datetime¶

datetime(value, allow_empty=False, minimum=None, maximum=None, coerce_value=True, **kwargs)[source]¶

Validate that value is a valid datetime.

Caution

If supplying a string, the string needs to be in an ISO 8601-format to pass validation. If it is not in an ISO 8601-format, validation will fail.

Parameters:	value (`str` / `datetime` / `date` / `None`) – The value to validate. allow_empty (`bool`) – If `True`, returns `None` if `value` is empty. If `False`, raises a `EmptyValueError` if `value` is empty. Defaults to `False`. minimum (`datetime` / `date` / compliant `str` / `None`) – If supplied, will make sure that `value` is on or after this value. maximum (`datetime` / `date` / compliant `str` / `None`) – If supplied, will make sure that `value` is on or before this value. coerce_value (`bool`) – If `True`, will coerce dates to `datetime` objects with times of 00:00:00. If `False`, will error if `value` is not an unambiguous timestamp. Defaults to `True`.
Returns:	`value` / `None`
Return type:	`datetime` / `None`
Raises:	EmptyValueError – if `value` is empty and `allow_empty` is `False` CannotCoerceError – if `value` cannot be coerced to a `datetime` value and is not `None` MinimumValueError – if `minimum` is supplied but `value` occurs before `minimum` MaximumValueError – if `maximum` is supplied but `value` occurs after `minimum`

time¶

time(value, allow_empty=False, minimum=None, maximum=None, coerce_value=True, **kwargs)[source]¶

Validate that value is a valid time.

Caution

This validator will always return the time as timezone naive (effectively UTC). If value has a timezone / UTC offset applied, the validator will coerce the value returned back to UTC.

Parameters:	value (`datetime` or `time`-compliant `str` / `datetime` / `time`) – The value to validate. allow_empty (`bool`) – If `True`, returns `None` if `value` is empty. If `False`, raises a `EmptyValueError` if `value` is empty. Defaults to `False`. minimum (`datetime` or `time`-compliant `str` / `datetime` / `time`) – If supplied, will make sure that `value` is on or after this value. maximum (`datetime` or `time`-compliant `str` / `datetime` / `time`) – If supplied, will make sure that `value` is on or before this value. coerce_value (`bool`) – If `True`, will attempt to coerce/extract a `time` from `value`. If `False`, will only respect direct representations of time. Defaults to `True`.
Returns:	`value` in UTC time / `None`
Return type:	`time` / `None`
Raises:	EmptyValueError – if `value` is empty and `allow_empty` is `False` CannotCoerceError – if `value` cannot be coerced to a `time` and is not `None` MinimumValueError – if `minimum` is supplied but `value` occurs before `minimum` MaximumValueError – if `maximum` is supplied but `value` occurs after `minimum`

timezone¶

timezone(value, allow_empty=False, positive=True, **kwargs)[source]¶

Validate that value is a valid tzinfo.

Caution

This does not verify whether the value is a timezone that actually exists, nor can it resolve timezone names (e.g. 'Eastern' or 'CET').

For that kind of functionality, we recommend you utilize: pytz

Parameters:	value (`str` / `tzinfo` / numeric / `None`) – The value to validate. allow_empty (`bool`) – If `True`, returns `None` if `value` is empty. If `False`, raises a `EmptyValueError` if `value` is empty. Defaults to `False`. positive (`bool`) – Indicates whether the `value` is positive or negative (only has meaning if `value` is a string). Defaults to `True`.
Returns:	`value` / `None`
Return type:	`tzinfo` / `None`
Raises:	EmptyValueError – if `value` is empty and `allow_empty` is `False` CannotCoerceError – if `value` cannot be coerced to `tzinfo` and is not `None` PositiveOffsetMismatchError – if `positive` is `True`, but the offset indicated by `value` is actually negative NegativeOffsetMismatchError – if `positive` is `False`, but the offset indicated by `value` is actually positive

timedelta¶

timedelta(value, allow_empty=False, resolution='seconds', **kwargs)[source]¶

Validate that value is a valid timedelta.

Note

Expects to receive a value that is either a timedelta, a numeric value that can be coerced to a timedelta, or a string that can be coerced to a timedelta. Coerceable string formats are:

HH:MM:SS

X day, HH:MM:SS

X days, HH:MM:SS

HH:MM:SS.us

X day, HH:MM:SS.us

X days, HH:MM:SS.us

where “us” refer to microseconds. Shout out to Alex Pitchford for sharing the string-parsing regex.

Parameters:	value (`str` / `timedelta` / numeric / `None`) – The value to validate. Accepts either a numeric value indicating a number of seconds or a string indicating an amount of time. allow_empty (`bool`) – If `True`, returns `None` if `value` is empty. If `False`, raises a `EmptyValueError` if `value` is empty. Defaults to `False`. resolution (`str`) – Indicates the time period resolution represented by `value`. Accepts `'years'`, `'weeks'`, `'days'`, `'hours'`, `'minutes'`, `'seconds'`, `'milliseconds'`, or `'microseconds'`. Defaults to `'seconds'`.
Returns:	`value` / `None`
Return type:	`timedelta` / `None`
Raises:	ValueError – if `resolution` is not a valid time period resolution EmptyValueError – if `value` is empty and `allow_empty` is `False` CannotCoerceError – if `value` cannot be coerced to `timedelta` and is not `None`

Numbers¶

Note

Because Python’s None is implemented as an integer value, numeric validators do not check “falsiness”. Doing so would find false positives if value were set to 0.

Instead, all numeric validators explicitly check for the Python global singleton None.

numeric¶

numeric(value, allow_empty=False, minimum=None, maximum=None, **kwargs)[source]¶

Validate that value is a numeric value.

Parameters:	value – The value to validate. allow_empty (`bool`) – If `True`, returns `None` if `value` is `None`. If `False`, raises an `EmptyValueError` if `value` is `None`. Defaults to `False`. minimum (numeric) – If supplied, will make sure that `value` is greater than or equal to this value. maximum (numeric) – If supplied, will make sure that `value` is less than or equal to this value.
Returns:	`value` / `None`
Raises:	EmptyValueError – if `value` is `None` and `allow_empty` is `False` MinimumValueError – if `minimum` is supplied and `value` is less than the `minimum` MaximumValueError – if `maximum` is supplied and `value` is more than the `maximum` CannotCoerceError – if `value` cannot be coerced to a numeric form

integer¶

integer(value, allow_empty=False, coerce_value=False, minimum=None, maximum=None, base=10, **kwargs)[source]¶

Validate that value is an int.

Parameters:	value – The value to validate. allow_empty (`bool`) – If `True`, returns `None` if `value` is `None`. If `False`, raises a `EmptyValueError` if `value` is `None`. Defaults to `False`. coerce_value (`bool`) – If `True`, will force any numeric `value` to an integer (always rounding up). If `False`, will raise an error if `value` is numeric but not a whole number. Defaults to `False`. minimum (numeric) – If supplied, will make sure that `value` is greater than or equal to this value. maximum (numeric) – If supplied, will make sure that `value` is less than or equal to this value. base – Indicates the base that is used to determine the integer value. The allowed values are 0 and 2–36. Base-2, -8, and -16 literals can be optionally prefixed with `0b/0B`, `0o/0O/0`, or `0x/0X`, as with integer literals in code. Base 0 means to interpret the string exactly as an integer literal, so that the actual base is 2, 8, 10, or 16. Defaults to `10`.
Returns:	`value` / `None`
Raises:	EmptyValueError – if `value` is `None` and `allow_empty` is `False` MinimumValueError – if `minimum` is supplied and `value` is less than the `minimum` MaximumValueError – if `maximum` is supplied and `value` is more than the `maximum` NotAnIntegerError – if `coerce_value` is `False`, and `value` is not an integer CannotCoerceError – if `value` cannot be coerced to an `int`

float¶

float(value, allow_empty=False, minimum=None, maximum=None, **kwargs)[source]¶

Validate that value is a float.

Parameters:	value – The value to validate. allow_empty (`bool`) – If `True`, returns `None` if `value` is `None`. If `False`, raises a `EmptyValueError` if `value` is `None`. Defaults to `False`.
Returns:	`value` / `None`
Return type:	`float` / `None`
Raises:	EmptyValueError – if `value` is `None` and `allow_empty` is `False` MinimumValueError – if `minimum` is supplied and `value` is less than the `minimum` MaximumValueError – if `maximum` is supplied and `value` is more than the `maximum` CannotCoerceError – if unable to coerce `value` to a `float`

fraction¶

fraction(value, allow_empty=False, minimum=None, maximum=None, **kwargs)[source]¶

Validate that value is a Fraction.

Parameters:	value – The value to validate. allow_empty (`bool`) – If `True`, returns `None` if `value` is `None`. If `False`, raises a `EmptyValueError` if `value` is `None`. Defaults to `False`.
Returns:	`value` / `None`
Return type:	`Fraction` / `None`
Raises:	EmptyValueError – if `value` is `None` and `allow_empty` is `False` MinimumValueError – if `minimum` is supplied and `value` is less than the `minimum` MaximumValueError – if `maximum` is supplied and `value` is more than the `maximum` CannotCoerceError – if unable to coerce `value` to a `Fraction`

decimal¶

decimal(value, allow_empty=False, minimum=None, maximum=None, **kwargs)[source]¶

Validate that value is a Decimal.

Parameters:	value – The value to validate. allow_empty (`bool`) – If `True`, returns `None` if `value` is `None`. If `False`, raises a `EmptyValueError` if `value` is `None`. Defaults to `False`. minimum (numeric) – If supplied, will make sure that `value` is greater than or equal to this value. maximum (numeric) – If supplied, will make sure that `value` is less than or equal to this value.
Returns:	`value` / `None`
Return type:	`Decimal` / `None`
Raises:	EmptyValueError – if `value` is `None` and `allow_empty` is `False` MinimumValueError – if `minimum` is supplied and `value` is less than the `minimum` MaximumValueError – if `maximum` is supplied and `value` is more than the `maximum` CannotCoerceError – if unable to coerce `value` to a `Decimal`

File-related¶

bytesIO¶

bytesIO(value, allow_empty=False, **kwargs)[source]¶

Validate that value is a BytesIO object.

Parameters:	value – The value to validate. allow_empty (`bool`) – If `True`, returns `None` if `value` is empty. If `False`, raises a `EmptyValueError` if `value` is empty. Defaults to `False`.
Returns:	`value` / `None`
Return type:	`BytesIO` / `None`
Raises:	EmptyValueError – if `value` is empty and `allow_empty` is `False` NotBytesIOError – if `value` is not a `BytesIO` object.

stringIO¶

stringIO(value, allow_empty=False, **kwargs)[source]¶

Validate that value is a StringIO object.

Parameters:	value – The value to validate. allow_empty (`bool`) – If `True`, returns `None` if `value` is empty. If `False`, raises a `EmptyValueError` if `value` is empty. Defaults to `False`.
Returns:	`value` / `None`
Return type:	`StringIO` / `None`
Raises:	EmptyValueError – if `value` is empty and `allow_empty` is `False` NotStringIOError – if `value` is not a `StringIO` object

path¶

path(value, allow_empty=False, **kwargs)[source]¶

Validate that value is a valid path-like object.

Parameters:	value – The value to validate. allow_empty (`bool`) – If `True`, returns `None` if `value` is empty. If `False`, raises a `EmptyValueError` if `value` is empty. Defaults to `False`.
Returns:	The path represented by `value`.
Return type:	Path-like object / `None`
Raises:	EmptyValueError – if `allow_empty` is `False` and `value` is empty NotPathlikeError – if `value` is not a valid path-like object

path_exists¶

path_exists(value, allow_empty=False, **kwargs)[source]¶

Validate that value is a path-like object that exists on the local filesystem.

Parameters:	value – The value to validate. allow_empty (`bool`) – If `True`, returns `None` if `value` is empty. If `False`, raises a `EmptyValueError` if `value` is empty. Defaults to `False`.
Returns:	The file name represented by `value`.
Return type:	Path-like object / `None`
Raises:	EmptyValueError – if `allow_empty` is `False` and `value` is empty NotPathlikeError – if `value` is not a path-like object PathExistsError – if `value` does not exist

file_exists¶

file_exists(value, allow_empty=False, **kwargs)[source]¶

Validate that value is a valid file that exists on the local filesystem.

Parameters:	value – The value to validate. allow_empty (`bool`) – If `True`, returns `None` if `value` is empty. If `False`, raises a `EmptyValueError` if `value` is empty. Defaults to `False`.
Returns:	The file name represented by `value`.
Return type:	Path-like object / `None`
Raises:	EmptyValueError – if `allow_empty` is `False` and `value` is empty NotPathlikeError – if `value` is not a path-like object PathExistsError – if `value` does not exist on the local filesystem NotAFileError – if `value` is not a valid file

directory_exists¶

directory_exists(value, allow_empty=False, **kwargs)[source]¶

Validate that value is a valid directory that exists on the local filesystem.

Parameters:	value – The value to validate. allow_empty (`bool`) – If `True`, returns `None` if `value` is empty. If `False`, raises a `EmptyValueError` if `value` is empty. Defaults to `False`.
Returns:	The file name represented by `value`.
Return type:	Path-like object / `None`
Raises:	EmptyValueError – if `allow_empty` is `False` and `value` is empty NotPathlikeError – if `value` is not a path-like object PathExistsError – if `value` does not exist on the local filesystem NotADirectoryError – if `value` is not a valid directory

readable¶

readable(value, allow_empty=False, **kwargs)[source]¶

Validate that value is a path to a readable file.

Caution

Use of this validator is an anti-pattern and should be used with caution.

Validating the readability of a file before attempting to read it exposes your code to a bug called TOCTOU.

This particular class of bug can expose your code to security vulnerabilities and so this validator should only be used if you are an advanced user.

A better pattern to use when reading from a file is to apply the principle of EAFP (“easier to ask forgiveness than permission”), and simply attempt to write to the file using a try ... except block:

try:
    with open('path/to/filename.txt', mode = 'r') as file_object:
        # read from file here
except (OSError, IOError) as error:
    # Handle an error if unable to write.

Parameters:	value (Path-like object) – The path to a file on the local filesystem whose readability is to be validated. allow_empty (`bool`) – If `True`, returns `None` if `value` is empty. If `False`, raises a `EmptyValueError` if `value` is empty. Defaults to `False`.
Returns:	Validated path-like object or `None`
Return type:	Path-like object or `None`
Raises:	EmptyValueError – if `allow_empty` is `False` and `value` is empty NotPathlikeError – if `value` is not a path-like object PathExistsError – if `value` does not exist on the local filesystem NotAFileError – if `value` is not a valid file NotReadableError – if `value` cannot be opened for reading

writeable¶

writeable(value, allow_empty=False, **kwargs)[source]¶

Validate that value is a path to a writeable file.

Caution

This validator does NOT work correctly on a Windows file system. This is due to the vagaries of how Windows manages its file system and the various ways in which it can manage file permission.

If called on a Windows file system, this validator will raise NotImplementedError().

Caution

Use of this validator is an anti-pattern and should be used with caution.

Validating the writability of a file before attempting to write to it exposes your code to a bug called TOCTOU.

This particular class of bug can expose your code to security vulnerabilities and so this validator should only be used if you are an advanced user.

A better pattern to use when writing to file is to apply the principle of EAFP (“easier to ask forgiveness than permission”), and simply attempt to write to the file using a try ... except block:

try:
    with open('path/to/filename.txt', mode = 'a') as file_object:
        # write to file here
except (OSError, IOError) as error:
    # Handle an error if unable to write.

Note

This validator relies on os.access() to check whether value is writeable. This function has certain limitations, most especially that:

It will ignore file-locking (yielding a false-positive) if the file is locked.
It focuses on local operating system permissions, which means if trying to access a path over a network you might get a false positive or false negative (because network paths may have more complicated authentication methods).

Parameters:	value (Path-like object) – The path to a file on the local filesystem whose writeability is to be validated. allow_empty (`bool`) – If `True`, returns `None` if `value` is empty. If `False`, raises a `EmptyValueError` if `value` is empty. Defaults to `False`.
Returns:	Validated absolute path or `None`
Return type:	Path-like object or `None`
Raises:	EmptyValueError – if `allow_empty` is `False` and `value` is empty NotImplementedError – if used on a Windows system NotPathlikeError – if `value` is not a path-like object NotWriteableError – if `value` cannot be opened for writing

executable¶

executable(value, allow_empty=False, **kwargs)[source]¶

Validate that value is a path to an executable file.

Caution

This validator does NOT work correctly on a Windows file system. This is due to the vagaries of how Windows manages its file system and the various ways in which it can manage file permission.

If called on a Windows file system, this validator will raise NotImplementedError().

Caution

Use of this validator is an anti-pattern and should be used with caution.

Validating the executability of a file before attempting to execute it exposes your code to a bug called TOCTOU.

This particular class of bug can expose your code to security vulnerabilities and so this validator should only be used if you are an advanced user.

A better pattern to use when writing to file is to apply the principle of EAFP (“easier to ask forgiveness than permission”), and simply attempt to execute the file using a try ... except block.

Note

This validator relies on os.access() to check whether value is executable. This function has certain limitations, most especially that:

It will ignore file-locking (yielding a false-positive) if the file is locked.
It focuses on local operating system permissions, which means if trying to access a path over a network you might get a false positive or false negative (because network paths may have more complicated authentication methods).

Parameters:	value (Path-like object) – The path to a file on the local filesystem whose writeability is to be validated. allow_empty (`bool`) – If `True`, returns `None` if `value` is empty. If `False`, raises a `EmptyValueError` if `value` is empty. Defaults to `False`.
Returns:	Validated absolute path or `None`
Return type:	Path-like object or `None`
Raises:	EmptyValueError – if `allow_empty` is `False` and `value` is empty NotImplementedError – if used on a Windows system NotPathlikeError – if `value` is not a path-like object NotAFileError – if `value` does not exist on the local file system NotExecutableError – if `value` cannot be executed

Internet-related¶

email¶

email(value, allow_empty=False, **kwargs)[source]¶

Validate that value is a valid email address.

Note

Email address validation is…complicated. The methodology that we have adopted here is generally compliant with RFC 5322 and uses a combination of string parsing and regular expressions.

String parsing in particular is used to validate certain highly unusual but still valid email patterns, including the use of escaped text and comments within an email address’ local address (the user name part).

This approach ensures more complete coverage for unusual edge cases, while still letting us use regular expressions that perform quickly.

Parameters:	value (`str` / `None`) – The value to validate. allow_empty (`bool`) – If `True`, returns `None` if `value` is empty. If `False`, raises a `EmptyValueError` if `value` is empty. Defaults to `False`.
Returns:	`value` / `None`
Return type:	`str` / `None`
Raises:	EmptyValueError – if `value` is empty and `allow_empty` is `False` CannotCoerceError – if `value` is not a `str` or `None` InvalidEmailError – if `value` is not a valid email address or empty with `allow_empty` set to `True`

url¶

url(value, allow_empty=False, allow_special_ips=False, **kwargs)[source]¶

Validate that value is a valid URL.

Note

URL validation is…complicated. The methodology that we have adopted here is generally compliant with RFC 1738, RFC 6761, RFC 2181 and uses a combination of string parsing and regular expressions,

This approach ensures more complete coverage for unusual edge cases, while still letting us use regular expressions that perform quickly.

Parameters:	value (`str` / `None`) – The value to validate. allow_empty (`bool`) – If `True`, returns `None` if `value` is empty. If `False`, raises a `EmptyValueError` if `value` is empty. Defaults to `False`. allow_special_ips (`bool`) – If `True`, will succeed when validating special IP addresses, such as loopback IPs like `127.0.0.1` or `0.0.0.0`. If `False`, will raise a `InvalidURLError` if `value` is a special IP address. Defaults to `False`.
Returns:	`value` / `None`
Return type:	`str` / `None`
Raises:	EmptyValueError – if `value` is empty and `allow_empty` is `False` CannotCoerceError – if `value` is not a `str` or `None` InvalidURLError – if `value` is not a valid URL or empty with `allow_empty` set to `True`

domain¶

domain(value, allow_empty=False, allow_ips=False, **kwargs)[source]¶

Validate that value is a valid domain name.

Caution

This validator does not verify that value exists as a domain. It merely verifies that its contents might exist as a domain.

Note

This validator checks to validate that value resembles a valid domain name. It is - generally - compliant with RFC 1035 and RFC 6761, however it diverges in a number of key ways:

Including authentication (e.g. username:password@domain.dev) will fail validation.

Including a path (e.g. domain.dev/path/to/file) will fail validation.

Including a port (e.g. domain.dev:8080) will fail validation.

If you are hoping to validate a more complete URL, we recommend that you see url.

Hint

Leading and trailing whitespace will be automatically stripped.

Parameters:	value (`str` / `None`) – The value to validate. allow_empty (`bool`) – If `True`, returns `None` if `value` is empty. If `False`, raises a `EmptyValueError` if `value` is empty. Defaults to `False`. allow_ips (`bool`) – If `True`, will succeed when validating IP addresses, If `False`, will raise a `InvalidDomainError` if `value` is an IP address. Defaults to `False`.
Returns:	`value` / `None`
Return type:	`str` / `None`
Raises:	EmptyValueError – if `value` is empty and `allow_empty` is `False` CannotCoerceError – if `value` is not a `str` or `None` InvalidDomainError – if `value` is not a valid domain name or empty with `allow_empty` set to `True` SlashInDomainError – if `value` contains a slash or backslash AtInDomainError – if `value` contains an `@` symbol ColonInDomainError – if `value` contains a `:` symbol WhitespaceInDomainError – if `value` contains whitespace

ip_address¶

ip_address(value, allow_empty=False, **kwargs)[source]¶

Validate that value is a valid IP address.

Note

First, the validator will check if the address is a valid IPv6 address. If that doesn’t work, the validator will check if the address is a valid IPv4 address.

If neither works, the validator will raise an error (as always).

Parameters:	value – The value to validate. allow_empty (`bool`) – If `True`, returns `None` if `value` is empty. If `False`, raises a `EmptyValueError` if `value` is empty. Defaults to `False`.
Returns:	`value` / `None`
Raises:	EmptyValueError – if `value` is empty and `allow_empty` is `False` InvalidIPAddressError – if `value` is not a valid IP address or empty with `allow_empty` set to `True`

ipv4¶

ipv4(value, allow_empty=False)[source]¶

Validate that value is a valid IP version 4 address.

Parameters:	value – The value to validate. allow_empty (`bool`) – If `True`, returns `None` if `value` is empty. If `False`, raises a `EmptyValueError` if `value` is empty. Defaults to `False`.
Returns:	`value` / `None`
Raises:	EmptyValueError – if `value` is empty and `allow_empty` is `False` InvalidIPAddressError – if `value` is not a valid IP version 4 address or empty with `allow_empty` set to `True`

ipv6¶

ipv6(value, allow_empty=False, **kwargs)[source]¶

Validate that value is a valid IP address version 6.

Parameters:	value – The value to validate. allow_empty (`bool`) – If `True`, returns `None` if `value` is empty. If `False`, raises a `EmptyValueError` if `value` is empty. Defaults to `False`.
Returns:	`value` / `None`
Raises:	EmptyValueError – if `value` is empty and `allow_empty` is `False` InvalidIPAddressError – if `value` is not a valid IP version 6 address or empty with `allow_empty` is not set to `True`

mac_address¶

mac_address(value, allow_empty=False, **kwargs)[source]¶

Validate that value is a valid MAC address.

Parameters:	value (`str` / `None`) – The value to validate. allow_empty (`bool`) – If `True`, returns `None` if `value` is empty. If `False`, raises a `EmptyValueError` if `value` is empty. Defaults to `False`.
Returns:	`value` / `None`
Return type:	`str` / `None`
Raises:	EmptyValueError – if `value` is empty and `allow_empty` is `False` CannotCoerceError – if `value` is not a valid `str` or string-like object InvalidMACAddressError – if `value` is not a valid MAC address or empty with `allow_empty` set to `True`

mimetype¶

mimetype(value, allow_empty=False, **kwargs)[source]¶

Validate that value is a valid MIME-type.

Parameters:	value (`str`) – The value to validate. allow_empty (`bool`) – If `True`, returns `None` if `value` is empty. If `False`, raises a `EmptyValueError` if `value` is empty. Defaults to `False`.
Returns:	`value` / `None`
Return type:	`str` / `None`
Raises:	EmptyValueError – if `value` is empty and `allow_empty` is `False` CannotCoerceError – if `value` is not a valid string InvalidMimeTypeError – if `value` is neither a valid MIME type nor empty with `allow_empty` set to `True`