Checker Reference¶
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 theCHECKERS_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 intype_
.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 inisinstance()
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 whetherobj
is of a type or inherits from a type whose name matches the string you passed.Parameters: Returns: True
ifobj
is a type intype_
. Otherwise,False
.Return type: 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. Returns: True
ifargs
are equivalent, andFalse
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. Returns: True
ifargs
have identical keys/values, andFalse
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 suppliedminimum
and/or less than or equal tomaximum
.Note
This function works on any
value
that support comparison operators, whether they are numbers or not. Technically, this means thatvalue
,minimum
, ormaximum
need to implement the Python magic methods__lte__
and__gte__
.If
value
,minimum
, ormaximum
do not support comparison operators, they will raiseNotImplemented
.Parameters: - value (anything that supports comparison operators) – The
value
to check. - minimum (anything that supports comparison operators /
None
) – If supplied, will returnTrue
ifvalue
is greater than or equal to this value. - maximum (anything that supports comparison operators /
None
) – If supplied, will returnTrue
ifvalue
is less than or equal to this value.
Returns: True
ifvalue
is greater than or equal to a suppliedminimum
and less than or equal to a suppliedmaximum
. Otherwise, returnsFalse
.Return type: Raises: - SyntaxError – if
kwargs
contains duplicate keyword parameters or duplicates keyword parameters passed to the underlying validator - NotImplemented – if
value
,minimum
, ormaximum
do not support comparison operators - ValueError – if both
minimum
andmaximum
areNone
- value (anything that supports comparison operators) – The
has_length¶
-
has_length
(value, minimum=None, maximum=None, **kwargs)[source]¶ Indicate whether
value
has a length greater than or equal to a suppliedminimum
and/or less than or equal tomaximum
.Note
This function works on any
value
that supports thelen()
operation. This means thatvalue
must implement the__len__
magic method.If
value
does not support length evaluation, the checker will raiseNotImplemented
.Parameters: - value (anything that supports length evaluation) – The
value
to check. - minimum (numeric) – If supplied, will return
True
ifvalue
is greater than or equal to this value. - maximum (numeric) – If supplied, will return
True
ifvalue
is less than or equal to this value.
Returns: True
ifvalue
has length greater than or equal to a suppliedminimum
and less than or equal to a suppliedmaximum
. Otherwise, returnsFalse
.Return type: 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
andmaximum
areNone
- value (anything that supports length evaluation) – The
is_dict¶
-
is_dict
(value, **kwargs)[source]¶ Indicate whether
value
is a validdict
Note
This will return
True
even ifvalue
is an emptydict
.Parameters: value – The value to evaluate. Returns: True
ifvalue
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: Returns: True
ifvalue
is valid,False
if it is not.Return type: 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
) – IfTrue
, will check whethervalue
can be coerced to a string if it is not already. Defaults toFalse
. - 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
) – IfTrue
and the value is below theminimum_length
, pad the value with spaces. Defaults toFalse
.
Returns: True
ifvalue
is valid,False
if it is not.Return type: 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
containingstr
andbytes
. - 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
ifobj
is a valid iterable,False
if not.Return type: Raises: SyntaxError – if
kwargs
contains duplicate keyword parameters or duplicates keyword parameters passed to the underlying validator- forbid_literals (iterable) – A collection of literals that will be considered invalid
even if they are (actually) iterable. Defaults to a
is_not_empty¶
-
is_not_empty
(value, **kwargs)[source]¶ Indicate whether
value
is empty.Parameters: value – The value to evaluate. Returns: True
ifvalue
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
isNone
.Parameters: Returns: True
ifvalue
isNone
,False
if it is not.Return type: 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
ifvalue
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
ifvalue
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 aUUID
Parameters: value – The value to evaluate. Returns: True
ifvalue
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 adate
.Parameters: - value – The value to evaluate.
- minimum (
datetime
/date
/ compliantstr
/None
) – If supplied, will make sure thatvalue
is on or after this value. - maximum (
datetime
/date
/ compliantstr
/None
) – If supplied, will make sure thatvalue
is on or before this value. - coerce_value (
bool
) – IfTrue
, will returnTrue
ifvalue
can be coerced to adate
. IfFalse
, will only returnTrue
ifvalue
is a date value only. Defaults toFalse
.
Returns: True
ifvalue
is valid,False
if it is not.Return type: 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 adatetime
.Parameters: - value – The value to evaluate.
- minimum (
datetime
/date
/ compliantstr
/None
) – If supplied, will make sure thatvalue
is on or after this value. - maximum (
datetime
/date
/ compliantstr
/None
) – If supplied, will make sure thatvalue
is on or before this value. - coerce_value (
bool
) – IfTrue
, will returnTrue
ifvalue
can be coerced to adatetime
. IfFalse
, will only returnTrue
ifvalue
is a complete timestamp. Defaults toFalse
.
Returns: True
ifvalue
is valid,False
if it is not.Return type: 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 atime
.Parameters: - value – The value to evaluate.
- minimum (
datetime
ortime
-compliantstr
/datetime
/time
) – If supplied, will make sure thatvalue
is on or after this value. - maximum (
datetime
ortime
-compliantstr
/datetime
/time
) – If supplied, will make sure thatvalue
is on or before this value. - coerce_value (
bool
) – IfTrue
, will returnTrue
ifvalue
can be coerced to atime
. IfFalse
, will only returnTrue
ifvalue
is a valid time. Defaults toFalse
.
Returns: True
ifvalue
is valid,False
if it is not.Return type: 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 atzinfo
.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 thevalue
is positive or negative (only has meaning ifvalue
is a string). Defaults toTrue
.
Returns: True
ifvalue
is valid,False
if it is not.Return type: 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
ifvalue
is valid,False
if it is not.Return type: 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
) – IfTrue
, will returnTrue
ifvalue
can be coerced to whole number. IfFalse
, will only returnTrue
ifvalue
is already a whole number (regardless of type). Defaults toFalse
. - 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 with0b/0B
,0o/0O/0
, or0x/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 to10
.
Returns: True
ifvalue
is valid,False
if it is not.Return type: 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 afloat
.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
ifvalue
is valid,False
if it is not.Return type: 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 aFraction
.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
ifvalue
is valid,False
if it is not.Return type: 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 aDecimal
.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
ifvalue
is valid,False
if it is not.Return type: Raises: SyntaxError – if
kwargs
contains duplicate keyword parameters or duplicates keyword parameters passed to the underlying validator