Validator Reference¶

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

Core¶

dict¶

dict(value, allow_empty=False, json_serializer=None)[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 `ValueError` 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:	ValueError – if `value` is empty and `allow_empty` is `False` ValueError – if `value` is not a `dict`

string¶

string(value, allow_empty=False, coerce_value=False, minimum_length=None, maximum_length=None, whitespace_padding=False)[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 `ValueError` 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:	ValueError – if `value` is empty and `allow_empty` is `False` ValueError – if `value` is not a valid string and `coerce_value` is `False` ValueError – if `minimum_length` is supplied and the length of `value` is less than `minimum_length` and `whitespace_padding` is `False` ValueError – 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)[source]¶

Validate that value is a valid iterable.

Parameters:	value – The value to validate. allow_empty (`bool`) – If `True`, returns `None` if `value` is empty. If `False`, raises a `ValueError` 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:	ValueError – if `value` is empty and `allow_empty` is `False` ValueError – if `value` is not a valid iterable or `None` ValueError – if `minimum_length` is supplied and the length of `value` is less than `minimum_length` and `whitespace_padding` is `False` ValueError – if `maximum_length` is supplied and the length of `value` is more than the `maximum_length`

none¶

none(value, allow_empty=False)[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 `ValueError` if `value` is empty but not `None`. Defaults to `False`.
Returns:	`None`
Raises:	ValueError – if `allow_empty` is `False` and `value` is empty but not `None` and

not_empty¶

not_empty(value, allow_empty=False)[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 `ValueError` if `value` is empty. Defaults to `False`.
Returns:	`value` / `None`
Raises:	ValueError – if `value` is empty and `allow_empty` is `False`

uuid¶

uuid(value, allow_empty=False)[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 `ValueError` if `value` is empty. Defaults to `False`.
Returns:	`value` coerced to a `UUID` object / `None`
Return type:	`UUID` / `None`
Raises:	ValueError – if `value` is empty and `allow_empty` is `False` TypeError – if `value` cannot be coerced to a `UUID`

variable_name¶

variable_name(value, allow_empty=False)[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 `ValueError` if `value` is empty. Defaults to `False`.
Returns:	`value` / `None`
Return type:	`str` or `None`
Raises:	ValueError – if `allow_empty` is `False` and `value` is empty

Date / Time¶

date¶

date(value, allow_empty=False, minimum=None, maximum=None)[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 `ValueError` 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.
Returns:	`value` / `None`
Return type:	`date` / `None`
Raises:	ValueError – if `value` is empty and `allow_empty` is `False` ValueError – if `value` is not a valid value type or `None` ValueError – if `minimum` is supplied but `value` occurs before `minimum` ValueError – if `maximum` is supplied but `value` occurs after `minimum`

datetime¶

datetime(value, allow_empty=False, minimum=None, maximum=None)[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 `ValueError` 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.
Returns:	`value` / `None`
Return type:	`datetime` / `None`
Raises:	ValueError – if `value` is empty and `allow_empty` is `False` ValueError – if `minimum` is supplied but `value` occurs before `minimum` ValueError – if `maximum` is supplied but `value` occurs after `minimum`

time¶

time(value, allow_empty=False, minimum=None, maximum=None)[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 `ValueError` 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.
Returns:	`value` in UTC time / `None`
Return type:	`time` / `None`
Raises:	ValueError – if `value` is empty and `allow_empty` is `False` ValueError – if `value` is not a valid value type or `None` ValueError – if `minimum` is supplied but `value` occurs before `minimum` ValueError – if `maximum` is supplied but `value` occurs after `minimum`

timezone¶

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

Validate that value is a valid tzinfo.

Caution

This does not validate whether the value is a timezone that actually exists, nor can it resolve timzone 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 `ValueError` 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:	ValueError – if `value` is empty and `allow_empty` is `False` ValueError – if `value` is not a valid value type or `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)[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 a `ValueError` 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:	ValueError – if `value` is `None` and `allow_empty` is `False` ValueError – if `minimum` is supplied and `value` is less than the `minimum` ValueError – if `maximum` is supplied and `value` is more than the `maximum`

integer¶

integer(value, allow_empty=False, coerce_value=False, minimum=None, maximum=None, base=10)[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 `ValueError` 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:	ValueError – if `value` is `None` and `allow_empty` is `False` ValueError – if `minimum` is supplied and `value` is less than the `minimum` ValueError – if `maximum` is supplied and `value` is more than the `maximum`

float¶

float(value, allow_empty=False, minimum=None, maximum=None)[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 `ValueError` if `value` is `None`. Defaults to `False`.
Returns:	`value` / `None`
Return type:	`float` / `None`
Raises:	ValueError – if `value` is `None` and `allow_empty` is `False` ValueError – if `minimum` is supplied and `value` is less than the `minimum` ValueError – if `maximum` is supplied and `value` is more than the `maximum`

fraction¶

fraction(value, allow_empty=False, minimum=None, maximum=None)[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 `ValueError` if `value` is `None`. Defaults to `False`.
Returns:	`value` / `None`
Return type:	`Fraction` / `None`
Raises:	ValueError – if `value` is `None` and `allow_empty` is `False` ValueError – if `minimum` is supplied and `value` is less than the `minimum` ValueError – if `maximum` is supplied and `value` is more than the `maximum`

decimal¶

decimal(value, allow_empty=False, minimum=None, maximum=None)[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 `ValueError` 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:	ValueError – if `value` is `None` and `allow_empty` is `False` ValueError – if `minimum` is supplied and `value` is less than the `minimum` ValueError – if `maximum` is supplied and `value` is more than the `maximum`

File-related¶

bytesIO¶

bytesIO(value, allow_empty=False)[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 `ValueError` if `value` is empty. Defaults to `False`.
Returns:	`value` / `None`
Return type:	`StringIO` / `None`
Raises:	ValueError – if `value` is empty and `allow_empty` is `False`

stringIO¶

stringIO(value, allow_empty=False)[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 `ValueError` if `value` is empty. Defaults to `False`.
Returns:	`value` / `None`
Return type:	`StringIO` / `None`
Raises:	ValueError – if `value` is empty and `allow_empty` is `False`

path¶

path(value, allow_empty=False)[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 `ValueError` if `value` is empty. Defaults to `False`.
Returns:	The path represented by `value`.
Return type:	Path-like object / `None`
Raises:	ValueError – if `allow_empty` is `False` and `value` is empty ValueError – if `value` is not a valid path

path_exists¶

path_exists(value, allow_empty=False)[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 `ValueError` if `value` is empty. Defaults to `False`.
Returns:	The file name represented by `value`.
Return type:	Path-like object / `None`
Raises:	ValueError – if `allow_empty` is `False` and `value` is empty IOError – if `value` does not exist

file_exists¶

file_exists(value, allow_empty=False)[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 `ValueError` if `value` is empty. Defaults to `False`.
Returns:	The file name represented by `value`.
Return type:	Path-like object / `None`
Raises:	ValueError – if `allow_empty` is `False` and `value` is empty IOError – if `value` does not exist on the local filesystem ValueError – if `value` is not a valid file

directory_exists¶

directory_exists(value, allow_empty=False)[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 `ValueError` if `value` is empty. Defaults to `False`.
Returns:	The file name represented by `value`.
Return type:	Path-like object / `None`
Raises:	ValueError – if `allow_empty` is `False` and `value` is empty IOError – if `value` does not exist on the local filesystem ValueError – if `value` is not a valid directory

Internet-related¶

email¶

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

Validate that value is a valid email address.

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

url¶

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

Validate that value is a valid URL.

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

ip_address¶

ip_address(value, allow_empty=False)[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 `ValueError` if `value` is empty. Defaults to `False`.
Returns:	`value` / `None`
Raises:	ValueError – if `value` is empty and `allow_empty` is `False` ValueError – 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 `ValueError` if `value` is empty. Defaults to `False`.
Returns:	`value` / `None`
Raises:	ValueError – if `value` is empty and `allow_empty` is `False` ValueError – if `value` is not a valid IP version 4 address or empty with `allow_empty` set to `True`

ipv6¶

ipv6(value, allow_empty=False)[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 `ValueError` if `value` is empty. Defaults to `False`.
Returns:	`value` / `None`
Raises:	ValueError – if `value` is empty and `allow_empty` is `False` ValueError – 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)[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 `ValueError` if `value` is empty. Defaults to `False`.
Returns:	`value` / `None`
Return type:	`str` / `None`
Raises:	ValueError – if `value` is empty and `allow_empty` is `False` ValueError – if `value` is not a valid MAC address or empty with `allow_empty` set to `True`