Validator Reference¶
Core | Date/Time | Numbers | File-related | Internet-related |
---|---|---|---|---|
dict |
date |
numeric |
bytesIO |
email |
string |
datetime |
integer |
stringIO |
url |
iterable |
time |
float |
path |
ip_address |
none |
timezone |
fraction |
path_exists |
ipv4 |
not_empty |
decimal |
file_exists |
ipv6 |
|
uuid |
directory_exists |
mac_address |
||
variable_name |
Core¶
dict¶
-
dict
(value, allow_empty=False, json_serializer=None)[source]¶ Validate that
value
is adict
.Hint
If
value
is a string, this validator will assume it is a JSON object and try to convert it into adict
You can override the JSON serializer used by passing it to the
json_serializer
property. By default, will utilize the Pythonjson
encoder/decoder.Parameters: - value – The value to validate.
- allow_empty (
bool
) – IfTrue
, returnsNone
ifvalue
is empty. IfFalse
, raises aValueError
ifvalue
is empty. Defaults toFalse
. - json_serializer (callable) – The JSON encoder/decoder to use to deserialize a
string passed in
value
. If not supplied, will default to the Pythonjson
encoder/decoder.
Returns: value
/None
Return type: dict
/None
Raises: - ValueError – if
value
is empty andallow_empty
isFalse
- ValueError – if
value
is not adict
string¶
-
string
(value, allow_empty=False, coerce_value=False, minimum_length=None, maximum_length=None, whitespace_padding=False)[source]¶ Validate that
value
is a valid string.Parameters: - value (
str
/None
) – The value to validate. - allow_empty (
bool
) – IfTrue
, returnsNone
ifvalue
is empty. IfFalse
, raises aValueError
ifvalue
is empty. Defaults toFalse
. - coerce_value (
bool
) – IfTrue
, will attempt to coercevalue
to a string if it is not already. IfFalse
, will raise aValueError
ifvalue
is not a string. 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: value
/None
Return type: str
/None
Raises: - ValueError – if
value
is empty andallow_empty
isFalse
- ValueError – if
value
is not a valid string andcoerce_value
isFalse
- ValueError – if
minimum_length
is supplied and the length ofvalue
is less thanminimum_length
andwhitespace_padding
isFalse
- ValueError – if
maximum_length
is supplied and the length ofvalue
is more than themaximum_length
- value (
iterable¶
-
iterable
(value, allow_empty=False, forbid_literals=(<class 'str'>, <class 'bytes'>), minimum_length=None, maximum_length=None)[source]¶ Validate that
value
is a valid iterable.Parameters: - value – The value to validate.
- allow_empty (
bool
) – IfTrue
, returnsNone
ifvalue
is empty. IfFalse
, raises aValueError
ifvalue
is empty. Defaults toFalse
. - forbid_literals (iterable) – A collection of literals that will be considered invalid
even if they are (actually) iterable. Defaults to
str
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: value
/None
Return type: iterable /
None
Raises: - ValueError – if
value
is empty andallow_empty
isFalse
- ValueError – if
value
is not a valid iterable orNone
- ValueError – if
minimum_length
is supplied and the length ofvalue
is less thanminimum_length
andwhitespace_padding
isFalse
- ValueError – if
maximum_length
is supplied and the length ofvalue
is more than themaximum_length
none¶
-
none
(value, allow_empty=False)[source]¶ Validate that
value
isNone
.Parameters: - value – The value to validate.
- allow_empty (
bool
) – IfTrue
, returnsNone
ifvalue
is empty but notNone
. IfFalse
, raises aValueError
ifvalue
is empty but notNone
. Defaults toFalse
.
Returns: None
Raises: ValueError – if
allow_empty
isFalse
andvalue
is empty but notNone
and
not_empty¶
-
not_empty
(value, allow_empty=False)[source]¶ Validate that
value
is not empty.Parameters: - value – The value to validate.
- allow_empty (
bool
) – IfTrue
, returnsNone
ifvalue
is empty. IfFalse
, raises aValueError
ifvalue
is empty. Defaults toFalse
.
Returns: value
/None
Raises: ValueError – if
value
is empty andallow_empty
isFalse
uuid¶
-
uuid
(value, allow_empty=False)[source]¶ Validate that
value
is a validUUID
.Parameters: - value – The value to validate.
- allow_empty (
bool
) – IfTrue
, returnsNone
ifvalue
is empty. IfFalse
, raises aValueError
ifvalue
is empty. Defaults toFalse
.
Returns: value
coerced to aUUID
object /None
Return type: UUID
/None
Raises: - ValueError – if
value
is empty andallow_empty
isFalse
- TypeError – if
value
cannot be coerced to aUUID
variable_name¶
-
variable_name
(value, allow_empty=False)[source]¶ Validate that the value is a valid Python variable name.
Caution
This function does NOT check whether the variable exists. It only checks that the
value
would work as a Python variable (or class, or function, etc.) name.Parameters: - value – The value to validate.
- allow_empty (
bool
) – IfTrue
, returnsNone
ifvalue
is empty. IfFalse
, raises aValueError
ifvalue
is empty. Defaults toFalse
.
Returns: value
/None
Return type: str
orNone
Raises: ValueError – if
allow_empty
isFalse
andvalue
is empty
Date / Time¶
date¶
-
date
(value, allow_empty=False, minimum=None, maximum=None)[source]¶ Validate that
value
is a valid date.Parameters: - value (
str
/datetime
/date
/None
) – The value to validate. - allow_empty (
bool
) – IfTrue
, returnsNone
ifvalue
is empty. IfFalse
, raises aValueError
ifvalue
is empty. Defaults toFalse
. - 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.
Returns: value
/None
Return type: date
/None
Raises: - ValueError – if
value
is empty andallow_empty
isFalse
- ValueError – if
value
is not a valid value type orNone
- ValueError – if
minimum
is supplied butvalue
occurs beforeminimum
- ValueError – if
maximum
is supplied butvalue
occurs afterminimum
- value (
datetime¶
-
datetime
(value, allow_empty=False, minimum=None, maximum=None)[source]¶ Validate that
value
is a valid datetime.Caution
If supplying a string, the string needs to be in an ISO 8601-format to pass validation. If it is not in an ISO 8601-format, validation will fail.
Parameters: - value (
str
/datetime
/date
/None
) – The value to validate. - allow_empty (
bool
) – IfTrue
, returnsNone
ifvalue
is empty. IfFalse
, raises aValueError
ifvalue
is empty. Defaults toFalse
. - 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.
Returns: value
/None
Return type: datetime
/None
Raises: - ValueError – if
value
is empty andallow_empty
isFalse
- ValueError – if
minimum
is supplied butvalue
occurs beforeminimum
- ValueError – if
maximum
is supplied butvalue
occurs afterminimum
- value (
time¶
-
time
(value, allow_empty=False, minimum=None, maximum=None)[source]¶ Validate that
value
is a validtime
.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
ortime
-compliantstr
/datetime
/time
) – The value to validate. - allow_empty (
bool
) – IfTrue
, returnsNone
ifvalue
is empty. IfFalse
, raises aValueError
ifvalue
is empty. Defaults toFalse
. - 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.
Returns: value
in UTC time /None
Return type: time
/None
Raises: - ValueError – if
value
is empty andallow_empty
isFalse
- ValueError – if
value
is not a valid value type orNone
- ValueError – if
minimum
is supplied butvalue
occurs beforeminimum
- ValueError – if
maximum
is supplied butvalue
occurs afterminimum
- value (
timezone¶
-
timezone
(value, allow_empty=False, positive=True)[source]¶ Validate that
value
is a validtzinfo
.Caution
This does not validate whether the value is a timezone that actually exists, nor can it resolve timzone names (e.g.
'Eastern'
or'CET'
).For that kind of functionality, we recommend you utilize: pytz
Parameters: - value (
str
/tzinfo
/ numeric /None
) – The value to validate. - allow_empty (
bool
) – IfTrue
, returnsNone
ifvalue
is empty. IfFalse
, raises aValueError
ifvalue
is empty. Defaults toFalse
. - positive (
bool
) – Indicates whether thevalue
is positive or negative (only has meaning ifvalue
is a string). Defaults toTrue
.
Returns: value
/None
Return type: tzinfo
/None
Raises: - ValueError – if
value
is empty andallow_empty
isFalse
- ValueError – if
value
is not a valid value type orNone
- value (
Numbers¶
Note
Because Python’s None
is implemented as an integer
value, numeric validators do not check “falsiness”. Doing so would find
false positives if value
were set to 0
.
Instead, all numeric validators explicitly check for the Python global singleton
None
.
numeric¶
-
numeric
(value, allow_empty=False, minimum=None, maximum=None)[source]¶ Validate that
value
is a numeric value.Parameters: - value – The value to validate.
- allow_empty (
bool
) – IfTrue
, returnsNone
ifvalue
isNone
. IfFalse
, raises aValueError
ifvalue
isNone
. 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.
Returns: value
/None
Raises: - ValueError – if
value
isNone
andallow_empty
isFalse
- ValueError – if
minimum
is supplied andvalue
is less than theminimum
- ValueError – if
maximum
is supplied andvalue
is more than themaximum
integer¶
-
integer
(value, allow_empty=False, coerce_value=False, minimum=None, maximum=None, base=10)[source]¶ Validate that
value
is anint
.Parameters: - value – The value to validate.
- allow_empty (
bool
) – IfTrue
, returnsNone
ifvalue
isNone
. IfFalse
, raises aValueError
ifvalue
isNone
. Defaults toFalse
. - coerce_value (
bool
) – IfTrue
, will force any numericvalue
to an integer (always rounding up). IfFalse
, will raise an error ifvalue
is numeric but not a whole number. 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 – 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
, 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: value
/None
Raises: - ValueError – if
value
isNone
andallow_empty
isFalse
- ValueError – if
minimum
is supplied andvalue
is less than theminimum
- ValueError – if
maximum
is supplied andvalue
is more than themaximum
float¶
-
float
(value, allow_empty=False, minimum=None, maximum=None)[source]¶ Validate that
value
is afloat
.Parameters: - value – The value to validate.
- allow_empty (
bool
) – IfTrue
, returnsNone
ifvalue
isNone
. IfFalse
, raises aValueError
ifvalue
isNone
. Defaults toFalse
.
Returns: value
/None
Return type: float
/None
Raises: - ValueError – if
value
isNone
andallow_empty
isFalse
- ValueError – if
minimum
is supplied andvalue
is less than theminimum
- ValueError – if
maximum
is supplied andvalue
is more than themaximum
fraction¶
-
fraction
(value, allow_empty=False, minimum=None, maximum=None)[source]¶ Validate that
value
is aFraction
.Parameters: - value – The value to validate.
- allow_empty (
bool
) – IfTrue
, returnsNone
ifvalue
isNone
. IfFalse
, raises aValueError
ifvalue
isNone
. Defaults toFalse
.
Returns: value
/None
Return type: Fraction
/None
Raises: - ValueError – if
value
isNone
andallow_empty
isFalse
- ValueError – if
minimum
is supplied andvalue
is less than theminimum
- ValueError – if
maximum
is supplied andvalue
is more than themaximum
decimal¶
-
decimal
(value, allow_empty=False, minimum=None, maximum=None)[source]¶ Validate that
value
is aDecimal
.Parameters: - value – The value to validate.
- allow_empty (
bool
) – IfTrue
, returnsNone
ifvalue
isNone
. IfFalse
, raises aValueError
ifvalue
isNone
. 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.
Returns: value
/None
Return type: Decimal
/None
Raises: - ValueError – if
value
isNone
andallow_empty
isFalse
- ValueError – if
minimum
is supplied andvalue
is less than theminimum
- ValueError – if
maximum
is supplied andvalue
is more than themaximum