Error Reference¶
- Handling Errors
- Standard Errors
- Core
- MinimumLengthError (from
ValueError
) - MaximumLengthError (from
ValueError
) - NotNoneError (from
ValueError
) - NotADictError (from
ValueError
) - NotJSONError (from
ValueError
) - NotJSONSchemaError (from
ValueError
) - JSONValidationError (from
ValueError
) - NotAnIterableError (from
CannotCoerceError
) - NotCallableError (from
ValueError
) - InvalidVariableNameError (from
ValueError
)
- MinimumLengthError (from
- Date / Time
- Numbers
- File-related
- Internet-related
- InvalidEmailError (from
ValueError
) - InvalidURLError (from
ValueError
) - InvalidDomainError (from
ValueError
) - SlashInDomainError (from
InvalidDomainError
) - AtInDomainError (from
InvalidDomainError
) - ColonInDomainError (from
InvalidDomainError
) - WhitespaceInDomainError (from
InvalidDomainError
) - InvalidIPAddressError (from
ValueError
) - InvalidMACAddressError (from
ValueError
)
- InvalidEmailError (from
Handling Errors¶
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:
- 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. - 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.
- 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.
Validator Names/Types¶
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:
from validator_collection import validators
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:
from validator_collection import validators
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:
- when an empty/false value is passed with
allow_empty = False
,- when a value is less than the allowed minimum,
- when a value is more than the allowed maximum
But maybe we want to handle each of these situations a little differently? In that case, we can use the custom exceptions defined by the Validator-Collection:
from validator_collection import validators, errors
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.
Validator Messages¶
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.”
Stack Traces¶
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.
Standard Errors¶
EmptyValueError (from ValueError
)¶
-
class
EmptyValueError
[source]¶ 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.
INHERITS FROM:
ValueError
MinimumValueError (from ValueError
)¶
-
class
MinimumValueError
[source]¶ Exception raised when a value has a lower or earlier value than the minimum allowed.
INHERITS FROM:
ValueError
MaximumValueError (from ValueError
)¶
-
class
MaximumValueError
[source]¶ Exception raised when a value exceeds a maximum allowed value.
INHERITS FROM:
ValueError
ValidatorUsageError (from ValueError
)¶
-
class
ValidatorUsageError
[source]¶ Exception raised when the validator was used incorrectly.
INHERITS FROM:
ValueError
CoercionFunctionEmptyError (from ValidatorUsageError
)¶
-
class
CoercionFunctionEmptyError
[source]¶ Exception raised when a coercion function was empty.
INHERITS FROM:
ValueError
->ValidatorUsageError
CoercionFunctionError (from ValueError
)¶
-
class
CoercionFunctionError
[source]¶ Exception raised when a Coercion Function produces an
Exception
.INHERITS FROM:
ValueError
Core¶
MinimumLengthError (from ValueError
)¶
-
class
MinimumLengthError
[source]¶ Exception raised when a value has a lower length than the minimum allowed.
INHERITS FROM:
ValueError
MaximumLengthError (from ValueError
)¶
-
class
MaximumLengthError
[source]¶ Exception raised when a value exceeds a maximum allowed length.
INHERITS FROM:
ValueError
NotNoneError (from ValueError
)¶
-
class
NotNoneError
[source]¶ Exception raised when a value of
None
is expected, but a different empty value was detected.INHERITS FROM:
ValueError
NotADictError (from ValueError
)¶
-
class
NotADictError
[source]¶ Exception raised when a value is not a
dict
.INHERITS FROM:
ValueError
NotJSONError (from ValueError
)¶
-
class
NotJSONError
[source]¶ Exception raised when a value cannot be serialized/de-serialized to a JSON object.
INHERITS FROM:
ValueError
NotJSONSchemaError (from ValueError
)¶
-
class
NotJSONSchemaError
[source]¶ Exception raised when a schema supplied is not a valid JSON Schema.
INHERITS FROM:
ValueError
JSONValidationError (from ValueError
)¶
-
class
JSONValidationError
[source]¶ Exception raised when a value fails validation against a JSON Schema.
INHERITS FROM:
ValueError
NotAnIterableError (from CannotCoerceError
)¶
-
class
NotAnIterableError
[source]¶ Exception raised when a value is not an iterable.
INHERITS FROM:
TypeError
->CannotCoerceError
NotCallableError (from ValueError
)¶
-
class
NotCallableError
[source]¶ Exception raised when a given value is not callable.
INHERITS FROM:
ValueError
InvalidVariableNameError (from ValueError
)¶
-
class
InvalidVariableNameError
[source]¶ Exception raised when a value is not a valid Python variable name.
INHERITS FROM:
ValueError
Date / Time¶
UTCOffsetError (from ValueError
)¶
-
class
UTCOffsetError
[source]¶ Exception raised when the UTC offset exceeds +/- 24 hours.
INHERITS FROM:
ValueError
NegativeOffsetMismatchError (from ValueError
)¶
-
class
NegativeOffsetMismatchError
[source]¶ Exception raised when a negative offset is expected, but the value indicates a positive offset.
INHERITS FROM:
ValueError
PositiveOffsetMismatchError (from ValueError
)¶
-
class
PositiveOffsetMismatchError
[source]¶ Exception raised when a positive offset is expected, but the value indicates a negative offset.
INHERITS FROM:
ValueError
Numbers¶
NotAnIntegerError (from ValueError
)¶
-
class
NotAnIntegerError
[source]¶ Exception raised when a value is not being coerced and is not an integer type.
INHERITS FROM:
ValueError