Checker Reference¶

Core	Date/Time	Numbers	File-related	Internet-related
`is_type`	`is_date`	`is_numeric`	`is_bytesIO`	`is_email`
`is_between`	`is_datetime`	`is_integer`	`is_stringIO`	`is_url`
`has_length`	`is_time`	`is_float`	`is_pathlike`	`is_domain`
`are_equivalent`	`is_timezone`	`is_fraction`	`is_on_filesystem`	`is_ip_address`
`are_dicts_equivalent`	`is_timedelta`	`is_decimal`	`is_file`	`is_ipv4`
`is_dict`			`is_directory`	`is_ipv6`
`is_json`			`is_readable`	`is_mac_address`
`is_string`			`is_writeable`	`is_mimetype`
`is_iterable`			`is_executable`
`is_not_empty`
`is_none`
`is_callable`
`is_uuid`
`is_variable_name`

Using Checkers¶

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.

Disabling Checking¶

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.

Caution

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

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

$ export CHECKERS_DISABLED = "is_variable_name, is_email, is_ipv4"

This disables the is_variable_name(), is_email(), and is_ipv4() validators respectively.

Now if we run:

from validator_collection import checkers, errors

result = checkers.is_variable_name('this is an invalid variable name')
# result will be True

The checker will return True.

However, if we run:

from validator_collection import checkers

result = validators.is_integer('this is an invalid variable name')
# result will be False

the checker will return False

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

from validator_collection import checkers, errors

result = checkers.is_variable_name('this is an invalid variable name',
                                   force_run = True)
# result will be False

will return False.

Core¶

is_type¶

is_type(obj, type_, **kwargs)[source]¶

Indicate if obj is a type in 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

are_equivalent¶

are_equivalent(*args, **kwargs)[source]¶

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:

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

are_dicts_equivalent¶

are_dicts_equivalent(*args, **kwargs)[source]¶

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

is_between¶

is_between(value, minimum=None, maximum=None, **kwargs)[source]¶

Indicate whether value is greater than or equal to a supplied minimum and/or less than or equal to maximum.

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 operators ValueError – if both `minimum` and `maximum` are `None`

has_length¶

has_length(value, minimum=None, maximum=None, **kwargs)[source]¶

Indicate whether value has a length greater than or equal to a supplied minimum and/or less than or equal to maximum.

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 TypeError – if `value` does not support length evaluation ValueError – if both `minimum` and `maximum` are `None`

is_dict¶

is_dict(value, **kwargs)[source]¶

Indicate whether value is a valid dict

Note

This will return True even if value is an empty dict.

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

is_json¶

is_json(value, schema=None, json_serializer=None, **kwargs)[source]¶

Indicate whether value is a valid JSON object.

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

is_string¶

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

Indicate whether value is a string.

Parameters:	value – The value to evaluate. coerce_value (`bool`) – If `True`, will check whether `value` can be coerced to a string if it is not already. 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:	`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

is_iterable¶

is_iterable(obj, forbid_literals=(<class 'str'>, <class 'bytes'>), minimum_length=None, maximum_length=None, **kwargs)[source]¶

Indicate whether obj is iterable.

Parameters:	forbid_literals (iterable) – A collection of literals that will be considered invalid even if they are (actually) iterable. Defaults to a `tuple` containing `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:	`True` if `obj` is a valid iterable, `False` if not.
Return type:	`bool`
Raises:	SyntaxError – if `kwargs` contains duplicate keyword parameters or duplicates keyword parameters passed to the underlying validator

is_not_empty¶

is_not_empty(value, **kwargs)[source]¶

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

is_none¶

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

Indicate whether value is None.

Parameters:	value – The value to evaluate. allow_empty (`bool`) – If `True`, accepts falsey values as equivalent to `None`. Defaults to `False`.
Returns:	`True` if `value` is `None`, `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

is_variable_name¶

is_variable_name(value, **kwargs)[source]¶

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.

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

is_callable¶

is_callable(value, **kwargs)[source]¶

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

is_uuid¶

is_uuid(value, **kwargs)[source]¶

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

Date / Time¶

is_date¶

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

Indicate whether value is a date.

Parameters:	value – The value to evaluate. 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 return `True` if `value` can be coerced to a `date`. If `False`, will only return `True` if `value` is a date value only. 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

is_datetime¶

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

Indicate whether value is a datetime.

Parameters:	value – The value to evaluate. 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 return `True` if `value` can be coerced to a `datetime`. If `False`, will only return `True` if `value` is a complete timestamp. 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

is_time¶

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

Indicate whether value is a time.

Parameters:	value – The value to evaluate. 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 return `True` if `value` can be coerced to a `time`. If `False`, will only return `True` if `value` is a valid time. 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

is_timezone¶

is_timezone(value, positive=True, **kwargs)[source]¶

Indicate whether value is a 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 – The value to evaluate. positive (`bool`) – Indicates whether the `value` is positive or negative (only has meaning 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

is_timedelta¶

is_timedelta(value, resolution=None, **kwargs)[source]¶

Indicate whether value is a timedelta.

Note

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 – 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

Numbers¶

is_numeric¶

is_numeric(value, minimum=None, maximum=None, **kwargs)[source]¶

Indicate whether value is a numeric value.

Parameters:	value – The value to evaluate. 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:	`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

is_integer¶

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

Indicate whether value contains a whole number.

Parameters:	value – The value to evaluate. coerce_value (`bool`) – If `True`, will return `True` if `value` can be coerced to whole number. If `False`, will only return `True` if `value` is already a whole number (regardless of type). 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 (`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

is_float¶

is_float(value, minimum=None, maximum=None, **kwargs)[source]¶

Indicate whether value is a float.

Parameters:	value – The value to evaluate. 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:	`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

is_fraction¶

is_fraction(value, minimum=None, maximum=None, **kwargs)[source]¶

Indicate whether value is a Fraction.

Parameters:	value – The value to evaluate. 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:	`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

is_decimal¶

is_decimal(value, minimum=None, maximum=None, **kwargs)[source]¶

Indicate whether value contains a Decimal.

Parameters:	value – The value to evaluate. 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:	`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

File-related¶

is_bytesIO¶

is_bytesIO(value, **kwargs)[source]¶

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.

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

is_stringIO¶

is_stringIO(value, **kwargs)[source]¶

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.

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

is_pathlike¶

is_pathlike(value, **kwargs)[source]¶

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

is_on_filesystem¶

is_on_filesystem(value, **kwargs)[source]¶

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

is_file¶

is_file(value, **kwargs)[source]¶

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

is_directory¶

is_directory(value, **kwargs)[source]¶

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

is_readable¶

is_readable(value, **kwargs)[source]¶

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.

Parameters:	value (Path-like object) – 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

is_writeable¶

is_writeable(value, **kwargs)[source]¶

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.

Note

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

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

Parameters:	value (Path-like object) – The value to evaluate.
Returns:	`True` if `value` is valid, `False` if it is not.
Return type:	`bool`
Raises:	NotImplementedError – if called on a Windows system SyntaxError – if `kwargs` contains duplicate keyword parameters or duplicates keyword parameters passed to the underlying validator

is_executable¶

is_executable(value, **kwargs)[source]¶

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 authentication methods).

Parameters:	value (Path-like object) – The value to evaluate.
Returns:	`True` if `value` is valid, `False` if it is not.
Return type:	`bool`
Raises:	NotImplementedError – if called on a Windows system SyntaxError – if `kwargs` contains duplicate keyword parameters or duplicates keyword parameters passed to the underlying validator

Internet-related¶

is_email¶

is_email(value, **kwargs)[source]¶

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 expressions that perform quickly.

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

is_url¶

is_url(value, **kwargs)[source]¶

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 expressions that perform quickly.

Parameters:	value – The value to evaluate. allow_special_ips (`bool`) – If `True`, will succeed when validating special IP addresses, such as loopback IPs like `127.0.0.1` or `0.0.0.0`. If `False`, will fail if `value` is a special 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

is_domain¶

is_domain(value, **kwargs)[source]¶

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:password@domain.dev) will fail validation.

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

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

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

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

is_ip_address¶

is_ip_address(value, **kwargs)[source]¶

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

is_ipv4¶

is_ipv4(value, **kwargs)[source]¶

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

is_ipv6¶

is_ipv6(value, **kwargs)[source]¶

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

is_mac_address¶

is_mac_address(value, **kwargs)[source]¶

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

is_mimetype¶

is_mimetype(value, **kwargs)[source]¶

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