validator_collection.errors
Tip
By design, checkers <checker> never raise exceptions. If a given value fails, a checker will just return False.
Validators <validator> always raise exceptions when validation fails.
When validators <validator> 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 ... exceptblocks, 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.
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 <python:ValueError>, TypeError <python: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 <python: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 errorLooking at the documentation for validators.decimal() <validator_collection.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 validators you use. Each validator precisely documents which exceptions it raises, and each exception's documentation shows what built-in exceptions it inherits from.
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."
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.
EmptyValueError
CannotCoerceError
MinimumValueError
MaximumValueError
ValidatorUsageError
CoercionFunctionEmptyError
CoercionFunctionError
MinimumLengthError
MaximumLengthError
NotNoneError
NotADictError
NotJSONError
NotJSONSchemaError
JSONValidationError
NotAnIterableError
NotCallableError
InvalidVariableNameError
UTCOffsetError
NegativeOffsetMismatchError
PositiveOffsetMismatchError
NotAnIntegerError
NotPathlikeError
PathExistsError
NotAFileError
NotADirectoryError
NotReadableError
NotWriteableError
NotExecutableError
NotBytesIOError
NotStringIOError
InvalidEmailError
InvalidURLError
InvalidDomainError
SlashInDomainError
AtInDomainError
ColonInDomainError
WhitespaceInDomainError
InvalidIPAddressError
InvalidMACAddressError