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_ip_address`
`are_equivalent`	`is_timezone`	`is_fraction`	`is_on_filesystem`	`is_ipv4`
`are_dicts_equivalent`		`is_decimal`	`is_file`	`is_ipv6`
`is_dict`			`is_directory`	`is_mac_address`
`is_string`
`is_iterable`
`is_not_empty`
`is_none`
`is_callable`
`is_uuid`
`is_variable_name`

Core¶

is_type¶

is_type(obj, type_)[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`

are_equivalent¶

are_equivalent(*args)[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.
Returns:	`True` if `args` are equivalent, and `False` if not.
Return type:	`bool`

are_dicts_equivalent¶

are_dicts_equivalent(*args)[source]¶

Indicate if dicts passed to this function have identical keys and values.

Parameters:	args – One or more values, passed as positional arguments.
Returns:	`True` if `args` have identical keys/values, and `False` if not.
Return type:	`bool`

is_between¶

is_between(value, minimum=None, maximum=None)[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:	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)[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:	TypeError – if `value` does not support length evaluation ValueError – if both `minimum` and `maximum` are `None`

is_dict¶

is_dict(value)[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`

is_string¶

is_string(value, coerce_value=False, minimum_length=None, maximum_length=None, whitespace_padding=False)[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`

is_iterable¶

is_iterable(obj, forbid_literals=(<class 'str'>, <class 'bytes'>), minimum_length=None, maximum_length=None)[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`

is_not_empty¶

is_not_empty(value)[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`

is_none¶

is_none(value, allow_empty=False)[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`

is_variable_name¶

is_variable_name(value)[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`

is_callable¶

is_callable(value)[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`

is_uuid¶

is_uuid(value)[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`

Date / Time¶

is_date¶

is_date(value, minimum=None, maximum=None)[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.
Returns:	`True` if `value` is valid, `False` if it is not.
Return type:	`bool`

is_datetime¶

is_datetime(value, minimum=None, maximum=None)[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.
Returns:	`True` if `value` is valid, `False` if it is not.
Return type:	`bool`

is_time¶

is_time(value, minimum=None, maximum=None)[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.
Returns:	`True` if `value` is valid, `False` if it is not.
Return type:	`bool`

is_timezone¶

is_timezone(value, positive=True)[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`

Numbers¶

is_numeric¶

is_numeric(value, minimum=None, maximum=None)[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`

is_integer¶

is_integer(value, coerce_value=False, minimum=None, maximum=None, base=10)[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`

is_float¶

is_float(value, minimum=None, maximum=None)[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`

is_fraction¶

is_fraction(value, minimum=None, maximum=None)[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`

is_decimal¶

is_decimal(value, minimum=None, maximum=None)[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`

File-related¶

is_bytesIO¶

is_bytesIO(value)[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`

is_stringIO¶

is_stringIO(value)[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`

is_pathlike¶

is_pathlike(value)[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`

is_on_filesystem¶

is_on_filesystem(value)[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`

is_file¶

is_file(value)[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`

is_directory¶

is_directory(value)[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`

Internet-related¶

is_email¶

is_email(value)[source]¶

Indicate whether value is an email address.

Parameters:	value – The value to evaluate.
Returns:	`True` if `value` is valid, `False` if it is not.
Return type:	`bool`

is_url¶

is_url(value)[source]¶

Indicate whether value is a URL.

Parameters:	value – The value to evaluate.
Returns:	`True` if `value` is valid, `False` if it is not.
Return type:	`bool`

is_ip_address¶

is_ip_address(value)[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`

is_ipv4¶

is_ipv4(value)[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`

is_ipv6¶

is_ipv6(value)[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`

is_mac_address¶

is_mac_address(value)[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`