Validator Collection Readthedocs Io en Latest
Validator Collection Readthedocs Io en Latest
Release 1.5.0
1 Validator Reference 3
1.1 Using Validators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.2 Core . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.3 Date / Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
1.4 Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
1.5 File-related . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
1.6 Internet-related . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
2 Checker Reference 25
2.1 Using Checkers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
2.2 Core . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
2.3 Date / Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
2.4 Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
2.5 File-related . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
2.6 Internet-related . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
3 Error Reference 45
3.1 Handling Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
3.2 Standard Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
3.3 Core . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
3.4 Date / Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
3.5 Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
3.6 File-related . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
3.7 Internet-related . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
i
5 Testing the Validator Collection 63
5.1 Testing Philosophy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
5.2 Test Organization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
5.3 Configuring & Running Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
5.4 Skipping Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
5.5 Incremental Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
6 Release History 67
6.1 Release 1.5.0 (released October 12, 2020) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
6.2 Release 1.4.2 (released June 20, 2020) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
6.3 Release 1.4.1 (released January 1, 2020) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
6.4 Release 1.4.0 (released December 21, 2019) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
6.5 Release 1.3.8 (released December 7, 2019) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
6.6 Release 1.3.7 (released September 7, 2019) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
6.7 Release 1.3.6 (released August 29, 2019) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
6.8 Release 1.3.5 (released May 17, 2019) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
6.9 Release 1.3.4 (released April 3, 2019) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
6.10 Release 1.3.3 (released March 23, 2019) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
6.11 Release 1.3.2 (released February 9, 2019) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
6.12 Release 1.3.1 (released November 30, 2018) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
6.13 Release 1.3.0 (released November 12, 2018) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
6.14 Release 1.2.0 (released August 4, 2018) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
6.15 Release 1.1.0 (released April 23, 2018) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
6.16 Release 1.0.0 (released April 16, 2018) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
7 Glossary 73
8 Installation 75
8.1 Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
11 Best Practices 85
11.1 Defensive Approach: Check, then Convert if Necessary . . . . . . . . . . . . . . . . . . . . . . . . 85
11.2 Confident Approach: try . . . except . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
13 Contributing 91
14 Testing 93
15 License 95
Index 101
ii
Validator Collection Documentation, Release 1.5.0
Version Compatability
The Validator Collection is designed to be compatible with Python 2.7 and Python 3.4 or higher.
Contents: 1
Validator Collection Documentation, Release 1.5.0
2 Contents:
CHAPTER 1
Validator Reference
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:
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')
3
Validator Collection Documentation, Release 1.5.0
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.
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.
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 program-
matic 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.
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.
Here’s how it works in practice. Let’s say we define the following environment variable:
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
try:
result = validators.variable_name('this is an invalid variable name',
force_run = True)
except ValueError:
# handle the error
1.2 Core
1.2.1 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
1.2. Core 5
Validator Collection Documentation, Release 1.5.0
1.2.2 json
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
1.2.3 string
1.2.4 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.
1.2. Core 7
Validator Collection Documentation, Release 1.5.0
1.2.5 none
1.2.6 not_empty
1.2.7 uuid
1.2.8 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
1.3.1 date
• 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
1.3.2 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
1.3.3 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
1.3.4 timezone
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 mean-
ing if value is a string). Defaults to True.
Returns value / None
1.3.5 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
1.4 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.
1.4.1 numeric
1.4.2 integer
1.4. Numbers 13
Validator Collection Documentation, Release 1.5.0
• 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
1.4.3 float
1.4.4 fraction
1.4.5 decimal
1.5 File-related
1.5.1 bytesIO
1.5. File-related 15
Validator Collection Documentation, Release 1.5.0
1.5.2 stringIO
1.5.3 path
1.5.4 path_exists
1.5.5 file_exists
1.5.6 directory_exists
1.5.7 readable
1.5. File-related 17
Validator Collection Documentation, Release 1.5.0
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 read-
ability 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
1.5.8 writeable
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 au-
thentication methods).
Parameters
• value (Path-like object) – The path to a file on the local filesystem whose write-
ability 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
1.5.9 executable
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 TOC-
TOU.
1.5. File-related 19
Validator Collection Documentation, Release 1.5.0
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 au-
thentication methods).
Parameters
• value (Path-like object) – The path to a file on the local filesystem whose write-
ability 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
1.6 Internet-related
1.6.1 email
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 expres-
sions 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
1.6.2 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 expres-
sions 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 ad-
dresses, 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
1.6. Internet-related 21
Validator Collection Documentation, Release 1.5.0
1.6.3 domain
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:[email protected]) 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.
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
1.6.4 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
1.6.5 ipv4
ipv4(value, allow_empty=False)
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
1.6.6 ipv6
1.6. Internet-related 23
Validator Collection Documentation, Release 1.5.0
1.6.7 mac_address
1.6.8 mimetype
Checker Reference
A checker is what it sounds like: It checks that an input value is what you expect it to be, and tells you True/False
whether it is or not.
Important: Checkers do not verify or convert object types. You can think of a checker as a tool that tells you whether
its corresponding validator would fail. See Best Practices for tips and tricks on using the two together.
Each checker is expressed as the name of the thing being validated, prefixed by is_. So the checker for an email
address is is_email() and the checker for an integer is is_integer().
Checkers take the input value you want to check as their first (and often only) positional argumet. If the input value
25
Validator Collection Documentation, Release 1.5.0
validates, they will return True. Unlike validators, checkers will not raise an exception if validation fails. They will
instead return False.
Hint: If you need to know why a given value failed to validate, use the validator instead.
Hint: Some checkers (particularly numeric ones like is_integer) have additional options which are used to
make sure the value meets criteria that you set for it. These options are always optional and are included as keyword
arguments after the input value argument. For details, please see the Checker Reference.
Caution: If you are disabling validators using the VALIDATORS_DISABLED environment variable, their related
checkers will also be disabled. This means they will always return True unless you call them using force_run
= True.
Checking 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 checking when running in production. Using the Validator-Collection this is simple:
Just add the name of the checker you want disabled to the CHECKERS_DISABLED environment variable,
and validation will automatically be skipped.
Here’s how it works in practice. Let’s say we define the following environment variable:
2.2 Core
2.2.1 is_type
Hint: This checker is particularly useful when you want to evaluate whether obj is of a particular type, but
importing that type directly to use in isinstance() would cause a circular import error.
To use this checker in that kind of situation, you can instead pass the name of the type you want to check as a
string in type_. The checker will evaluate it and see whether obj is of a type or inherits from a type whose
name matches the string you passed.
Parameters
• obj (object) – The object whose type should be checked.
• type (type / iterable of type / str with type name / iterable of str with type name) –
The type(s) to check against.
Returns True if obj is a type in type_. Otherwise, False.
Return type bool
Raises SyntaxError – if kwargs contains duplicate keyword parameters or duplicates keyword
parameters passed to the underlying validator
2.2.2 are_equivalent
are_equivalent(*args, **kwargs)
Indicate if arguments passed to this function are equivalent.
Hint: This checker operates recursively on the members contained within iterables and dict objects.
Caution: If you only pass one argument to this checker - even if it is an iterable - the checker will always
return True.
To evaluate members of an iterable for equivalence, you should instead unpack the iterable into the function
like so:
2.2. Core 27
Validator Collection Documentation, Release 1.5.0
obj = [1, 1, 1, 2]
result = are_equivalent(*obj)
# Will return ``False`` by unpacking and evaluating the iterable's members
result = are_equivalent(obj)
# Will always return True
Parameters
• args – One or more values, passed as positional arguments.
• strict_typing (bool) – If True, will only identify items as equivalent if they have
identical sub-typing. If False, related sub-types will be returned as equivalent. Defaults
to True.
Returns True if args are equivalent, and False if not.
Return type bool
Raises SyntaxError – if kwargs contains duplicate keyword parameters or duplicates keyword
parameters passed to the underlying validator
2.2.3 are_dicts_equivalent
are_dicts_equivalent(*args, **kwargs)
Indicate if dicts passed to this function have identical keys and values.
Parameters
• args – One or more values, passed as positional arguments.
• strict_typing (bool) – If True, will only identify items as equivalent if they have
identical sub-typing. If False, related sub-types will be returned as equivalent. Defaults
to True.
• missing_as_none (bool) – If True, will treat missing keys in one value and None
keys in the other as equivalent. If False, missing and None keys will fail. Defaults to
False.
Returns True if args have identical keys/values, and False if not.
Return type bool
Raises SyntaxError – if kwargs contains duplicate keyword parameters or duplicates keyword
parameters passed to the underlying validator
2.2.4 is_between
Note: This function works on any value that support comparison operators, whether they are numbers or not.
Technically, this means that value, minimum, or maximum need to implement the Python magic methods
__lte__ and __gte__.
If value, minimum, or maximum do not support comparison operators, they will raise NotImplemented.
Parameters
• value (anything that supports comparison operators) – The value to
check.
• minimum (anything that supports comparison operators / None) – If supplied, will return
True if value is greater than or equal to this value.
• maximum (anything that supports comparison operators / None) – If supplied, will return
True if value is less than or equal to this value.
Returns True if value is greater than or equal to a supplied minimum and less than or equal to a
supplied maximum. Otherwise, returns False.
Return type bool
Raises
• SyntaxError – if kwargs contains duplicate keyword parameters or duplicates keyword
parameters passed to the underlying validator
• NotImplemented – if value, minimum, or maximum do not support comparison op-
erators
• ValueError – if both minimum and maximum are None
2.2.5 has_length
Note: This function works on any value that supports the len() operation. This means that value must
implement the __len__ magic method.
If value does not support length evaluation, the checker will raise NotImplemented.
Parameters
• value (anything that supports length evaluation) – The value to
check.
• minimum (numeric) – If supplied, will return True if value is greater than or equal to
this value.
• maximum (numeric) – If supplied, will return True if value is less than or equal to this
value.
Returns True if value has length greater than or equal to a supplied minimum and less than or
equal to a supplied maximum. Otherwise, returns False.
Return type bool
Raises
• SyntaxError – if kwargs contains duplicate keyword parameters or duplicates keyword
parameters passed to the underlying validator
2.2. Core 29
Validator Collection Documentation, Release 1.5.0
2.2.6 is_dict
is_dict(value, **kwargs)
Indicate whether value is a valid dict
2.2.7 is_json
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.
Parameters
• value – The value to evaluate.
• schema (dict / str / None) – An optional JSON schema against which value will be
validated.
Returns True if value is valid, False if it is not.
Return type bool
Raises SyntaxError – if kwargs contains duplicate keyword parameters or duplicates keyword
parameters passed to the underlying validator
2.2.8 is_string
2.2.9 is_iterable
2.2.10 is_not_empty
is_not_empty(value, **kwargs)
Indicate whether value is empty.
Parameters value – The value to evaluate.
Returns True if value is empty, False if it is not.
Return type bool
Raises SyntaxError – if kwargs contains duplicate keyword parameters or duplicates keyword
parameters passed to the underlying validator
2.2.11 is_none
2.2. Core 31
Validator Collection Documentation, Release 1.5.0
2.2.12 is_variable_name
is_variable_name(value, **kwargs)
Indicate whether 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.
2.2.13 is_callable
is_callable(value, **kwargs)
Indicate whether value is callable (like a function, method, or class).
Parameters value – The value to evaluate.
Returns True if value is valid, False if it is not.
Return type bool
Raises SyntaxError – if kwargs contains duplicate keyword parameters or duplicates keyword
parameters passed to the underlying validator
2.2.14 is_uuid
is_uuid(value, **kwargs)
Indicate whether value contains a UUID
Parameters value – The value to evaluate.
Returns True if value is valid, False if it is not.
Return type bool
Raises SyntaxError – if kwargs contains duplicate keyword parameters or duplicates keyword
parameters passed to the underlying validator
2.3.1 is_date
2.3.2 is_datetime
2.3.3 is_time
2.3.4 is_timezone
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 – The value to evaluate.
• positive (bool) – Indicates whether the value is positive or negative (only has mean-
ing if value is a string). Defaults to True.
Returns True if value is valid, False if it is not.
Return type bool
Raises SyntaxError – if kwargs contains duplicate keyword parameters or duplicates keyword
parameters passed to the underlying validator
2.3.5 is_timedelta
• X days, HH:MM:SS.us
where “us” refer to microseconds. Shout out to Alex Pitchford for sharing the string-parsing regex.
Parameters
• value – The value to evaluate.
• resolution (str) – Indicates the time period resolution represented by value.
Accepts 'years', 'weeks', 'days', 'hours', 'minutes', 'seconds',
'milliseconds', or 'microseconds'. Defaults to 'seconds'.
Returns True if value is valid, False if it is not.
Return type bool
Raises SyntaxError – if kwargs contains duplicate keyword parameters or duplicates keyword
parameters passed to the underlying validator
2.4 Numbers
2.4.1 is_numeric
2.4.2 is_integer
2.4. Numbers 35
Validator Collection Documentation, Release 1.5.0
• 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 (int) – 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 True if value is valid, False if it is not.
Return type bool
Raises SyntaxError – if kwargs contains duplicate keyword parameters or duplicates keyword
parameters passed to the underlying validator
2.4.3 is_float
2.4.4 is_fraction
2.4.5 is_decimal
2.5 File-related
2.5.1 is_bytesIO
is_bytesIO(value, **kwargs)
Indicate whether value is a BytesIO object.
Note: This checker will return True even if value is empty, so long as its type is a BytesIO.
2.5.2 is_stringIO
is_stringIO(value, **kwargs)
Indicate whether value is a StringIO object.
Note: This checker will return True even if value is empty, so long as its type is a String.
2.5. File-related 37
Validator Collection Documentation, Release 1.5.0
2.5.3 is_pathlike
is_pathlike(value, **kwargs)
Indicate whether value is a path-like object.
Parameters value – The value to evaluate.
Returns True if value is valid, False if it is not.
Return type bool
Raises SyntaxError – if kwargs contains duplicate keyword parameters or duplicates keyword
parameters passed to the underlying validator
2.5.4 is_on_filesystem
is_on_filesystem(value, **kwargs)
Indicate whether value is a file or directory that exists on the local filesystem.
Parameters value – The value to evaluate.
Returns True if value is valid, False if it is not.
Return type bool
Raises SyntaxError – if kwargs contains duplicate keyword parameters or duplicates keyword
parameters passed to the underlying validator
2.5.5 is_file
is_file(value, **kwargs)
Indicate whether value is a file that exists on the local filesystem.
Parameters value – The value to evaluate.
Returns True if value is valid, False if it is not.
Return type bool
Raises SyntaxError – if kwargs contains duplicate keyword parameters or duplicates keyword
parameters passed to the underlying validator
2.5.6 is_directory
is_directory(value, **kwargs)
Indicate whether value is a directory that exists on the local filesystem.
Parameters value – The value to evaluate.
Returns True if value is valid, False if it is not.
Return type bool
Raises SyntaxError – if kwargs contains duplicate keyword parameters or duplicates keyword
parameters passed to the underlying validator
2.5.7 is_readable
is_readable(value, **kwargs)
Indicate whether value is 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.
2.5.8 is_writeable
is_writeable(value, **kwargs)
Indicate whether value is 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.
2.5. File-related 39
Validator Collection Documentation, Release 1.5.0
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 au-
thentication methods).
2.5.9 is_executable
is_executable(value, **kwargs)
Indicate whether value is 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 writability 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 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 au-
thentication methods).
2.6 Internet-related
2.6.1 is_email
is_email(value, **kwargs)
Indicate whether value is an 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 expres-
sions that perform quickly.
2.6.2 is_url
is_url(value, **kwargs)
Indicate whether value is a 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 expres-
sions that perform quickly.
Parameters
• value – The value to evaluate.
2.6. Internet-related 41
Validator Collection Documentation, Release 1.5.0
2.6.3 is_domain
is_domain(value, **kwargs)
Indicate whether value is a valid domain.
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:[email protected]) 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.
Parameters
• value – The value to evaluate.
• allow_ips (bool) – If True, will succeed when validating IP addresses, If False, will
fail if value is an IP address. Defaults to False.
Returns True if value is valid, False if it is not.
Return type bool
Raises SyntaxError – if kwargs contains duplicate keyword parameters or duplicates keyword
parameters passed to the underlying validator
2.6.4 is_ip_address
is_ip_address(value, **kwargs)
Indicate whether value is a valid IP address (version 4 or version 6).
Parameters value – The value to evaluate.
Returns True if value is valid, False if it is not.
Return type bool
Raises SyntaxError – if kwargs contains duplicate keyword parameters or duplicates keyword
parameters passed to the underlying validator
2.6.5 is_ipv4
is_ipv4(value, **kwargs)
Indicate whether value is a valid IP version 4 address.
Parameters value – The value to evaluate.
Returns True if value is valid, False if it is not.
Return type bool
Raises SyntaxError – if kwargs contains duplicate keyword parameters or duplicates keyword
parameters passed to the underlying validator
2.6.6 is_ipv6
is_ipv6(value, **kwargs)
Indicate whether value is a valid IP version 6 address.
Parameters value – The value to evaluate.
Returns True if value is valid, False if it is not.
Return type bool
Raises SyntaxError – if kwargs contains duplicate keyword parameters or duplicates keyword
parameters passed to the underlying validator
2.6.7 is_mac_address
is_mac_address(value, **kwargs)
Indicate whether value is a valid MAC address.
Parameters value – The value to evaluate.
Returns True if value is valid, False if it is not.
Return type bool
Raises SyntaxError – if kwargs contains duplicate keyword parameters or duplicates keyword
parameters passed to the underlying validator
2.6.8 is_mimetype
is_mimetype(value, **kwargs)
Indicate whether value is a valid MIME type.
Parameters value – The value to evaluate.
Returns True if value is valid, False if it is not.
Return type bool
Raises SyntaxError – if kwargs contains duplicate keyword parameters or duplicates keyword
parameters passed to the underlying validator
2.6. Internet-related 43
Validator Collection Documentation, Release 1.5.0
Error Reference
• Handling Errors
– Validator Names/Types
– Validator Messages
– Stack Traces
• Standard Errors
– EmptyValueError (from ValueError)
– CannotCoerceError (from TypeError)
– MinimumValueError (from ValueError)
– MaximumValueError (from ValueError)
– ValidatorUsageError (from ValueError)
– CoercionFunctionEmptyError (from ValidatorUsageError)
– CoercionFunctionError (from ValueError)
• Core
– MinimumLengthError (from ValueError)
– MaximumLengthError (from ValueError)
– NotNoneError (from ValueError)
– NotADictError (from ValueError)
– NotJSONError (from ValueError)
– NotJSONSchemaError (from ValueError)
– JSONValidationError (from ValueError)
45
Validator Collection Documentation, Release 1.5.0
Tip: By design, checkers never raise exceptions. If a given value fails, a checker will just return False.
Validators always raise exceptions when validation fails.
When validators fail, they raise exceptions. There are three ways for exceptions to provide you with information that
is useful in different circumstances:
1. Exception Type. The type of the exception itself (and the name of that type) tells you a lot about the nature
of the error. On its own, this should be enough for you to understand “what went wrong” and “why validation
failed”. Most importantly, this is easy to catch in your code using try ... except blocks, giving you
fine-grained control over how to handle exceptional situations.
2. Message. Each exception is raised when a human-readable message, a brief string that says “this is why this
exception was raised”. This is primarily useful in debugging your code, because at run-time we don’t want to
parse strings to make control flow decisions.
3. Stack Trace. Each exception is raised with a stacktrace of the exceptions and calls that preceded it. This helps
to provide the context for the error, and is (typically) most useful for debugging and logging purposes. In rare
circumstances, we might want to programmatically parse this information. . . but that’s a pretty rare requirement.
We have designed the exceptions raised by the Validator-Collection to leverage all three of these types of information.
By design, all exceptions raised by the Validator-Collection inherit from the built-in exceptions defined in the standard
library. This makes it simple to plug the Validator-Collection into existing validation code you have which already
catches ValueError, TypeError, and the like.
However, because we have sub-classed the built-in exceptions, you can easily apply more fine-grained control over
your code.
For example, let us imagine a validation which will fail:
value = validators.decimal('123.45',
allow_empty = False,
minimum = 0,
maximum = 100)
By design, we know that this value will fail validation. We have specified a maximum of 100, and the value being
passed in is (a string) with a value of 123.45. This will fail.
We can catch this using a standard/built-in ValueError like so:
try:
value = validators.decimal('123.45',
allow_empty = False,
minimum = 0,
maximum = 100)
except ValueError as error:
# Handle the error
Looking at the documentation for validators.decimal(), we can see that this will catch all of the following
situations:
try:
value = validators.decimal('123.45',
allow_empty = False,
minimum = 0,
maximum = 100)
except errors.EmptyValueError as error:
# Handle the situation where an empty value was received.
except errors.MinimumValueError as error:
# Handle the situation when a value is less than the allowed minimum.
except errors.MaximumValueError as error:
# Handle the situation when a value is more than the allowed minimum.
Both approaches will work, but one gives you a little more precise control over how your code handles a failed
validation.
Tip: We strongly recommend that you review the exceptions raised by each of the Validator Reference you use. Each
validator precisely documents which exceptions it raises, and each exception’s documentation shows what built-in
exceptions it inherits from.
Because the Validator-Collection produces exceptions which inherit from the standard library, we leverage the same
API. This means they print to standard output with a human-readable message that provides an explanation for “what
went wrong.”
Because the Validator-Collection produces exceptions which inherit from the standard library, it leverages the same
API for handling stack trace information. This means that it will be handled just like a normal exception in unit test
frameworks, logging solutions, and other tools that might need that information.
class EmptyValueError
Exception raised when an empty value is detected, but the validator does not allow for empty values.
Note: While in general, an “empty” value means a value that is falsey, for certain specific validators “empty”
means explicitly None.
Please see: Validator Reference.
class CannotCoerceError
Exception raised when a value cannot be coerced to an expected type.
INHERITS FROM: TypeError
class MinimumValueError
Exception raised when a value has a lower or earlier value than the minimum allowed.
INHERITS FROM: ValueError
class MaximumValueError
Exception raised when a value exceeds a maximum allowed value.
INHERITS FROM: ValueError
class ValidatorUsageError
Exception raised when the validator was used incorrectly.
INHERITS FROM: ValueError
class CoercionFunctionEmptyError
Exception raised when a coercion function was empty.
INHERITS FROM: ValueError -> ValidatorUsageError
class CoercionFunctionError
Exception raised when a Coercion Function produces an Exception.
INHERITS FROM: ValueError
3.3 Core
class MinimumLengthError
Exception raised when a value has a lower length than the minimum allowed.
INHERITS FROM: ValueError
class MaximumLengthError
Exception raised when a value exceeds a maximum allowed length.
INHERITS FROM: ValueError
class NotNoneError
Exception raised when a value of None is expected, but a different empty value was detected.
INHERITS FROM: ValueError
class NotADictError
Exception raised when a value is not a dict.
INHERITS FROM: ValueError
class NotJSONError
Exception raised when a value cannot be serialized/de-serialized to a JSON object.
INHERITS FROM: ValueError
class NotJSONSchemaError
Exception raised when a schema supplied is not a valid JSON Schema.
INHERITS FROM: ValueError
class JSONValidationError
Exception raised when a value fails validation against a JSON Schema.
INHERITS FROM: ValueError
class NotAnIterableError
Exception raised when a value is not an iterable.
INHERITS FROM: TypeError -> CannotCoerceError
class IterationFailedError
Exception raised when a value conforms to one of Python’s supported iterable protocols, but iterating across the
object produced an unexpected Exception.
INHERITS FROM: TypeError -> CannotCoerceError -> NotAnIterableError
class NotCallableError
Exception raised when a given value is not callable.
INHERITS FROM: ValueError
class InvalidVariableNameError
Exception raised when a value is not a valid Python variable name.
INHERITS FROM: ValueError
class UTCOffsetError
Exception raised when the UTC offset exceeds +/- 24 hours.
INHERITS FROM: ValueError
class NegativeOffsetMismatchError
Exception raised when a negative offset is expected, but the value indicates a positive offset.
INHERITS FROM: ValueError
class PositiveOffsetMismatchError
Exception raised when a positive offset is expected, but the value indicates a negative offset.
INHERITS FROM: ValueError
3.5 Numbers
class NotAnIntegerError
Exception raised when a value is not being coerced and is not an integer type.
INHERITS FROM: ValueError
3.6 File-related
class NotPathlikeError
Exception raised when a given value is not a path-like object.
INHERITS FROM: ValueError
class PathExistsError
Exception raised when a path does not exist.
INHERITS FROM: IOError
class NotAFileError
Exception raised when a path is not a file.
INHERITS FROM: IOError
class NotADirectoryError
Exception raised when a path is not a directory.
INHERITS FROM: IOError
class NotReadableError
Exception raised when a path is not readable.
INHERITS FROM: IOError
class NotWriteableError
Exception raised when a path is not writeable.
INHERITS FROM: IOError
class NotExecutableError
Exception raised when a path is not executable.
INHERITS FROM: IOError
class NotBytesIOError
Exception raised when a given value is not a BytesIO object.
INHERITS FROM: ValueError
class NotStringIOError
Exception raised when a given value is not a StringIO object.
INHERITS FROM: ValueError
3.7 Internet-related
class InvalidEmailError
Exception raised when an email fails validation.
INHERITS FROM: ValueError
class InvalidURLError
Exception raised when a URL fails validation.
INHERITS FROM: ValueError
3.7. Internet-related 53
Validator Collection Documentation, Release 1.5.0
class InvalidDomainError
Exception raised when a domain fails validation.
INHERITS FROM: ValueError
class SlashInDomainError
Exception raised when a domain value contains a slash or backslash.
INHERITS FROM: ValueError -> InvalidDomainError
class AtInDomainError
Exception raised when a domain value contains an @ symbol.
INHERITS FROM: ValueError -> InvalidDomainError
class ColonInDomainError
Exception raised when a domain value contains a colon (:).
INHERITS FROM: ValueError -> InvalidDomainError
class WhitespaceInDomainError
Exception raised when a domain value contains whitespace.
INHERITS FROM: ValueError -> InvalidDomainError
class InvalidIPAddressError
Exception raised when a value is not a valid IP address.
INHERITS FROM: ValueError
class InvalidMACAddressError
Exception raised when a value is not a valid MAC address.
INHERITS FROM: ValueError
class InvalidMimeTypeError
Exception raised when a value is not a valid MIME type.
INHERITS FROM: ValueError
3.7. Internet-related 55
Validator Collection Documentation, Release 1.5.0
Note: As a general rule of thumb, the Validator Collection applies PEP 8 styling, with some important differences.
One of my favorite ways of thinking about idiomatic design comes from a talk given by Luciano Ramalho at Pycon
20165 where he listed traits of a Pythonic API as being:
• don’t force [the user] to write boilerplate code
• provide ready to use functions and objects
• don’t force [the user] to subclass unless there’s a very good reason
• include the batteries: make easy tasks easy
• are simple to use but not simplistic: make hard tasks possible
• leverage the Python data model to:
– provide objects that behave as you expect
– avoid boilerplate through introspection (reflection) and metaprogramming.
57
Validator Collection Documentation, Release 1.5.0
Contents:
• Design Philosophy
• Style Guide
– Basic Conventions
– Naming Conventions
– Design Conventions
– Documentation Conventions
* Sphinx
* Docstrings
• Dependencies
• Preparing Your Development Environment
• Ideas and Feature Requests
• Testing
• Submitting Pull Requests
• Building Documentation
• Contributors
• References
The Validator Collection is meant to be a “beautiful” and “usable” library. That means that it should offer an idiomatic
API that:
• works out of the box as intended,
• minimizes “bootstrapping” to produce meaningful output, and
• does not force users to understand how it does what it does.
In other words:
Users should simply be able to drive the car without looking at the engine.
# GOOD
if x:
do_something()
# BAD
if x: do_something()
• When testing if an object has a value, be sure to use if x is None: or if x is not None. Do not
confuse this with if x: and if not x:.
• Use the if x: construction for testing truthiness, and if not x: for testing falsiness. This is different
from testing:
– if x is True:
– if x is False:
– if x is None:
• As of right now, because we feel that it negatively impacts readability and is less-widely used in the community,
we are not using type annotations.
• variable_name and not variableName or VariableName. Should be a noun that describes what
information is contained in the variable. If a bool, preface with is_ or has_ or similar question-word that
can be answered with a yes-or-no.
• function_name and not function_name or functionName. Should be an imperative that describes
what the function does (e.g. get_next_page).
• CONSTANT_NAME and not constant_name or ConstantName.
• ClassName and not class_name or Class_Name.
• Functions at the module level can only be aware of objects either at a higher scope or singletons (which effec-
tively have a higher scope).
• Functions and methods can use one positional argument (other than self or cls) without a default value. Any
other arguments must be keyword arguments with default value given.
def do_some_function(argument):
# rest of function...
def do_some_function(first_arg,
second_arg = None,
third_arg = True):
# rest of function ...
• Functions and methods that accept values should start by validating their input, throwing exceptions as appro-
priate.
• When defining a class, define all attributes in __init__.
• When defining a class, start by defining its attributes and methods as private using a single-underscore prefix.
Then, only once they’re implemented, decide if they should be public.
• Don’t be afraid of the private attribute/public property/public setter pattern:
class SomeClass(object):
def __init__(*args, **kwargs):
self._private_attribute = None
@property
def private_attribute(self):
# custom logic which may override the default return
return self._private_attribute
@setter.private_attribute
def private_attribute(self, value):
# custom logic that creates modified_value
self._private_attribute = modified_value
• Separate a function or method’s final (or default) return from the rest of the code with a blank line (except
for single-line functions/methods).
We are very big believers in documentation (maybe you can tell). To document the Validator Collection we rely on
several tools:
Sphinx1
Sphinx1 is used to organize the library’s documentation into this lovely readable format (which will also be published
to ReadTheDocs2 ). This documentation is written in reStructuredText3 files which are stored in <project>/docs.
Tip: As a general rule of thumb, we try to apply the ReadTheDocs2 own Documentation Style Guide4 to our RST
documentation.
1 http://sphinx-doc.org
2 https://readthedocs.org
3 http://www.sphinx-doc.org/en/stable/rest.html
4 http://documentation-style-guide-sphinx.readthedocs.io/en/latest/style-guide.html
Docstrings
• Docstrings are used to document the actual source code itself. When writing docstrings we adhere to the con-
ventions outlined in PEP 257.
4.3 Dependencies
Python 3.x
• jsonschema for JSON Schema validation
Python 2.x
• jsonschema for JSON Schema validation
• The regex drop-in replacement for Python’s (buggy) standard re module.
Note: This conditional dependency will be automatically installed if you are installing to Python 2.x.
Check for open issues or create a new issue to start a discussion around a bug or feature idea.
4.6 Testing
4.3. Dependencies 61
Validator Collection Documentation, Release 1.5.0
After you have made changes that you think are ready to be included in the main library, submit a pull request on
Github and one of our developers will review your changes. If they’re ready (meaning they’re well documented, pass
unit tests, etc.) then they’ll be merged back into the main repository and slated for inclusion in the next release.
In order to build documentation locally, you can do so from the command line using:
validator-collection/ $ cd docs
validator-collection/docs $ make html
When the build process has finished, the HTML documentation will be locally available at:
validator-collection/docs/_build/html/index.html
Note: Built documentation (the HTML) is not included in the project’s Git repository. If you need local documenta-
tion, you’ll need to build it.
4.9 Contributors
4.10 References
Contents
Note: Unit tests for the Validator Collection are written using pytest1 and a comprehensive set of test automation
are provided by tox2 .
There are many schools of thought when it comes to test design. When building the Validator Collection, we decided
to focus on practicality. That means:
1 https://docs.pytest.org/en/latest/
2 https://tox.readthedocs.io
63
Validator Collection Documentation, Release 1.5.0
• DRY is good, KISS is better. To avoid repetition, our test suite makes extensive use of fixtures, parametrization,
and decorator-driven behavior. This minimizes the number of test functions that are nearly-identical. However,
there are certain elements of code that are repeated in almost all test functions, as doing so will make future
readability and maintenance of the test suite easier.
• Coverage matters. . . kind of. We have documented the primary intended behavior of every function in the
Validator Collection library, and the most-likely failure modes that can be expected. At the time of writing, we
have about 85% code coverage. Yes, yes: We know that is less than 100%. But there are edge cases which are
almost impossible to bring about, based on confluences of factors in the wide world. Our goal is to test the key
functionality, and as bugs are uncovered to add to the test functions as necessary.
Each individual test module (e.g. test_validators.py) corresponds to a conceptual grouping of functionality.
For example:
• test_validators.py tests validator functions found in validator_collection/_validators.
py
Certain test modules are tightly coupled, as the behavior in one test module may have implications on the execution
of tests in another. These test modules use a numbering convention to ensure that they are executed in their required
order, so that test_1_NAME.py is always executed before test_2_NAME.py.
The Validator Collection does not use any custom command-line options in its test suite.
Tip: For a full list of the CLI options, including the defaults available, try:
validator-collection $ cd tests/
validator-collection/tests/ $ pytest --help
Because the Validator Collection has a very simple test suite, we have not prepared a pytest.ini configuration
file.
tests/ $ pytest
Test Module
Test Function
Note: Because of the simplicity of the Validator Collection, the test suite does not currently support any test skipping.
Note: The Validator Collection test suite does support incremental testing using, however at the moment none of
the tests designed rely on this functionality.
A variety of test functions are designed to test related functionality. As a result, they are designed to execute incre-
mentally. In order to execute tests incrementally, they need to be defined as methods within a class that you decorate
with the @pytest.mark.incremental decorator as shown below:
@pytest.mark.incremental
class TestIncremental(object):
def test_function1(self):
pass
def test_modification(self):
assert 0
def test_modification2(self):
pass
This class will execute the TestIncremental.test_function1() test, execute and fail on the
TestIncremental.test_modification() test, and automatically fail TestIncremental.
test_modification2() because of the .test_modification() failure.
To pass state between incremental tests, add a state argument to their method definitions. For example:
@pytest.mark.incremental
class TestIncremental(object):
def test_function(self, state):
state.is_logged_in = True
assert state.is_logged_in = True
def test_modification1(self, state):
assert state.is_logged_in is True
state.is_logged_in = False
assert state.is_logged_in is False
def test_modification2(self, state):
assert state.is_logged_in is True
Given the example above, the third test (test_modification2) will fail because test_modification up-
dated the value of state.is_logged_in.
Note: state is instantiated at the level of the entire test session (one run of the test suite). As a result, it can be
affected by tests in other test modules.
Release History
Contributors
Contents
• Release History
– Release 1.5.0 (released October 12, 2020)
– Release 1.4.2 (released June 20, 2020)
– Release 1.4.1 (released January 1, 2020)
– Release 1.4.0 (released December 21, 2019)
– Release 1.3.8 (released December 7, 2019)
– Release 1.3.7 (released September 7, 2019)
– Release 1.3.6 (released August 29, 2019)
– Release 1.3.5 (released May 17, 2019)
– Release 1.3.4 (released April 3, 2019)
– Release 1.3.3 (released March 23, 2019)
– Release 1.3.2 (released February 9, 2019)
67
Validator Collection Documentation, Release 1.5.0
* Features Added
* Bugs Fixed
– Release 1.1.0 (released April 23, 2018)
* Features Added
* Bugs Fixed
* Testing
* Documentation
– Release 1.0.0 (released April 16, 2018)
• #64: Fixed URL validator and checker to ensure that protocol is case insensitive.
• #63: Added a MIME type validator and checker.
• ENHANCEMENT: Added missing_as_none option to checkers.are_dicts_equivalent().
• ENHANCEMENT: Added strict_typing option to checkers.are_equivalent().
• #59: Fixed URL and domain validation to fail properly on unsafe characters.
• #37: Added regex matching to variable name validation. Still checks compilation but first must pass regex
validation.
• #28 and #29: Fixed an error where special URLs (localhost) and special IPs (e.g. 10.1.1.1) failed when used
with an explicit port or path.
• #25: Fixed an error where an underscore in a host name was not being properly recognized (h/t @mastak) when
parsing URLs and domain names.
• #23: Fixed an error where URL / domain validators and checkers were (incorrectly) failing on valid special
names (e.g. localhost, etc.) and special IPs (e.g. 10.1.1.1).
• #24: Fixed bug where checkers returned false-negatives when the underlying validator raised a SyntaxError.
6.15.3 Testing
• #6: Added unit tests for disabling validators and checkers based on the VALIDATORS_DISABLED and
CHECKERS_DISABLED environment variables, with support for the force_run = True override.
• #7: Added more extensive email address cases to test compliance with RFC 5322.
• Added unit tests for validators.domain() and checkers.is_domain().
• #5: Added unit tests for validators.readable() and checkers.is_readable() that work on the
Linux platform. Missing unit tests on Windows.
• #4: Added unit tests for validators.writeable() and checkers.is_writeable().
• #9: Added unit tests for validators.executable() and checkers.is_executable().
6.15.4 Documentation
• Added CHANGES.rst.
• #7: Added additional detail to validators.email() documentation.
• #8: Added detailed exception / error handling documentation.
• #8: Updated validator error documentation.
• #6: Added documentation on disabling validators and checkers.
Glossary
Checker A function which takes an input value and indicates (True/False) whether it contains what you expect.
Will always return a Boolean value, and will not raise an exception on failure.
Validator A function which takes an input value and ensures that it is what (the type or contents) you expect it to
be. Will return the value or None depending on the arguments you pass to it, and will raise an exception if
validation fails.
The Validator Collection is a Python library that provides more than 60 functions that can be used to validate the type
and contents of an input value.
Each function has a consistent syntax for easy use, and has been tested on Python 2.7, 3.4, 3.5, 3.6, 3.7, and 3.8.
For a list of validators available, please see the lists below.
Contents
• Validator Collection
– Installation
* Dependencies
– Available Validators and Checkers
– Hello, World and Standard Usage
* Using Validators
* Using Checkers
– Best Practices
73
Validator Collection Documentation, Release 1.5.0
– Contributing
– Testing
– License
– Indices and tables
74 Chapter 7. Glossary
CHAPTER 8
Installation
8.1 Dependencies
Python 3.x
• jsonschema for JSON Schema validation
Python 2.x
• jsonschema for JSON Schema validation
• The regex drop-in replacement for Python’s (buggy) standard re module.
Note: This conditional dependency will be automatically installed if you are installing to Python 2.x.
75
Validator Collection Documentation, Release 1.5.0
76 Chapter 8. Installation
CHAPTER 9
Validators
Checkers
77
Validator Collection Documentation, Release 1.5.0
All validator functions have a consistent syntax so that using them is pretty much identical. Here’s how it works:
email_address = validators.email('[email protected]')
# The value of email_address will now be "[email protected]"
email_address = validators.email('this-is-an-invalid-email')
# Will raise a ValueError
try:
email_address = validators.email(None)
# Will raise an EmptyValueError
except errors.EmptyValueError:
# Handling logic goes here
except errors.InvalidEmailError:
# More handlign logic goes here
is_email_address = checkers.is_email('[email protected]')
# The value of is_email_address will now be True
is_email_address = checkers.is_email('this-is-an-invalid-email')
# The value of is_email_address will now be False
is_email_address = checkers.is_email(None)
# The value of is_email_address will now be False
Pretty simple, right? Let’s break it down just in case: Each validator comes in two flavors: a validator and a checker.
79
Validator Collection Documentation, Release 1.5.0
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:
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')
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.
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 program-
matic 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.
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.
Here’s how it works in practice. Let’s say we define the following environment variable:
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:
try:
result = validators.integer('this is an invalid variable name')
except errors.NotAnIntegerError:
# handle the error
try:
result = validators.variable_name('this is an invalid variable name',
force_run = True)
except ValueError:
# handle the error
A checker is what it sounds like: It checks that an input value is what you expect it to be, and tells you True/False
whether it is or not.
Important: Checkers do not verify or convert object types. You can think of a checker as a tool that tells you whether
its corresponding validator would fail. See Best Practices for tips and tricks on using the two together.
Each checker is expressed as the name of the thing being validated, prefixed by is_. So the checker for an email
address is is_email() and the checker for an integer is is_integer().
Checkers take the input value you want to check as their first (and often only) positional argumet. If the input value
validates, they will return True. Unlike validators, checkers will not raise an exception if validation fails. They will
instead return False.
Hint: If you need to know why a given value failed to validate, use the validator instead.
Hint: Some checkers (particularly numeric ones like is_integer) have additional options which are used to
make sure the value meets criteria that you set for it. These options are always optional and are included as keyword
arguments after the input value argument. For details, please see the Checker Reference.
Caution: If you are disabling validators using the VALIDATORS_DISABLED environment variable, their related
checkers will also be disabled. This means they will always return True unless you call them using force_run
= True.
Checking 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 checking when running in production. Using the Validator-Collection this is simple:
Just add the name of the checker you want disabled to the CHECKERS_DISABLED environment variable,
and validation will automatically be skipped.
Here’s how it works in practice. Let’s say we define the following environment variable:
Best Practices
Checkers and Validators are designed to be used together. You can think of them as a way to quickly and easily verify
that a value contains the information you expect, and then make sure that value is in the form your code needs it in.
There are two fundamental patterns that we find work well in practice.
We find this pattern is best used when we don’t have any certainty over a given value might contain. It’s fundamentally
defensive in nature, and applies the following logic:
1. Check whether value contains the information we need it to or can be converted to the form we need it in.
2. If value does not contain what we need but can be converted to what we need, do the conversion.
3. If value does not contain what we need but cannot be converted to what we need, raise an error (or handle it
however it needs to be handled).
We tend to use this where we’re first receiving data from outside of our control, so when we get data from a user, from
the internet, from a third-party API, etc.
Here’s a quick example of how that might look in code:
def some_function(value):
# Check whether value contains a whole number.
is_valid = checkers.is_integer(value,
coerce_value = False)
85
Validator Collection Documentation, Release 1.5.0
return value
value = some_function(3.14)
# value will now be 4
new_value = some_function('not-a-number')
# will raise ValueError
Let’s break down what this code does. First, we define some_function() which takes a value. This function uses
the is_integer() checker to see if value contains a whole number, regardless of its type.
If it doesn’t contain a whole number, maybe it contains a numeric value that can be rounded up to a whole number? It
again uses the is_integer() to check if that’s possible. If it is, then it calls the integer() validator to coerce
value to a whole number.
If it can’t coerce value to a whole number? It raises a ValueError.
Sometimes, we’ll have more confidence in the values that we can expect to work with. This means that we might
expect value to generally have the kind of data we need to work with. This means that situations where value
doesn’t contain what we need will truly be exceptional situations, and can be handled accordingly.
In this situation, a good approach is to apply the following logic:
1. Skip a checker entirely, and just wrap the validator in a try...except block.
We tend to use this in situations where we’re working with data that our own code has produced (meaning we know -
generally - what we can expect, unless something went seriously wrong).
Here’s an example:
def some_function(value):
try:
email_address = validators.email(value, allow_empty = False)
except errors.InvalidEmailError as error:
# handle the error here
except ValueError as error:
# handle other ValueErrors here
return email_address
email = some_function('[email protected]')
# This will return the email address.
email = some_function('not-a-valid-email')
# This will raise a ValueError that some_function() will handle.
(continues on next page)
email = some_function(None)
# This will raise a ValueError that some_function() will handle.
So what’s this code do? It’s pretty straightforward. some_function() expects to receive a value that contains
an email address. We expect that value will typically be an email address, and not something weird (like a number
or something). So we just try the validator - and if validation fails, we handle the error appropriately.
You can ask questions and report issues on the project’s Github Issues Page
89
Validator Collection Documentation, Release 1.5.0
Contributing
We welcome contributions and pull requests! For more information, please see the Contributor Guide. And thanks to
all those who’ve already contributed:
• Chris Modzelewski (@insightindustry)
• Jordan Reiter (@JordanReiter)
• Ihor Liubymov (@mastak)
• Alon Bar Tzlil (@aivrit)
91
Validator Collection Documentation, Release 1.5.0
Testing
We use TravisCI for our build automation and ReadTheDocs for our documentation.
Detailed information about our test suite and how to run tests locally can be found in our Testing Reference.
93
Validator Collection Documentation, Release 1.5.0
License
95
Validator Collection Documentation, Release 1.5.0
• genindex
• modindex
• search
97
Validator Collection Documentation, Release 1.5.0
t
tests, 63
v
validator_collection.checkers, 27
validator_collection.errors, 45
validator_collection.validators, 5
99
Validator Collection Documentation, Release 1.5.0
101
Validator Collection Documentation, Release 1.5.0
102 Index
Validator Collection Documentation, Release 1.5.0
R
readable() (in module valida-
tor_collection.validators), 17
S
SlashInDomainError (class in valida-
tor_collection.errors), 54
string() (in module validator_collection.validators),
7
stringIO() (in module valida-
tor_collection.validators), 16
Index 103