Error Reference

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:

  1. 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.
  2. 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.
  3. 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

CannotCoerceError (from TypeError)

class CannotCoerceError[source]

Exception raised when a value cannot be coerced to an expected type.

INHERITS FROM: TypeError

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

IterationFailedError (from NotAnIterableError)

class IterationFailedError[source]

Exception raised when a value conforms to one of Python’s supported iterable protocols, but iterating across the object produced an unexpected Exception.

INHERITS FROM: TypeError -> CannotCoerceError -> NotAnIterableError

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