argvalidate Module¶
Below you can find the documentation of the public API of argvalidate.
Even though more constants, decorators, exceptions and functions may be specified in the argvalidate module, only those described here form the API and are intended for public use.
Note
Do not rely on any internals of argvalidate, as these may change at any time, without further notice.
The API described here forms the public interface to argvalidate and as such will have functionality pending for removal deprecated first.
Decorators¶
-
argvalidate.
accepts
(*type_args, **type_kwargs)¶ Decorator used for checking arguments passed to a function or method.
Parameters: - start – method/function-detection override. The number of arguments defined with start are ignored in all checks.
- type_args – type definitions of non-keyword arguments.
- type_kwargs – type definitions of keyword arguments.
Raises: - DecoratorNonKeyLengthException – Raised if the number of non-keyword arguments specified in the decorator does not match the number of non-keyword arguments the function accepts.
- DecoratorKeyLengthException – Raised if the number of keyword arguments specified in the decorator does not match the number of non-keyword arguments the function accepts.
- DecoratorKeyUnspecifiedException – Raised if a keyword argument’s type has not been specified in the decorator.
- ArgumentTypeException – Raised if an argument type passed to the function does not match the type specified in the decorator.
Example:
class MyClass: @accepts(int, str) def my_method(self, x_is_int, y_is_str): [...] @accepts(int, str) def my_function(x_is_int, y_is_str): [....]
-
argvalidate.
returns
(expected_type)¶ Decorator used for checking the return value of a function or method.
Parameters: expected_type – expected type or return value Raises: ReturnValueTypeException – Raised if the return value’s type does not match the definition in the decorator’s expected_type parameter. Example:
@return_value(int) def my_func(): return 5
Note
Stacking of decorator of the same type (ie. accepts()
and accepts()
, returns()
and returns()
) is not possible
and will cause a DecoratorStackingException
to be raised.
Stacking of different types of decorators (ie. returns()
and
accepts()
)
is possible though and will neither raise an exception nor break anything.
-
argvalidate.
func_args
(*type_args, **type_kwargs)¶ Wrapper for backwards-compatibility.
Deprecated: This decorator has been replaced with accepts()
.
Helpers¶
-
argvalidate.
one_of
(*args)¶ Simple helper function to create a tuple from every argument passed to it.
Parameters: args – type definitions A tuple can be used instead of calling this function, however, the tuple returned by this function contains a customized __repr__ method, which makes Exceptions easier to read.
Example:
@func_check_args(one_of(int, str, float)) def my_func(x): pass
-
argvalidate.
raises_exceptions
()¶ Returns True if argvalidate raises exceptions, False if argvalidate creates warnings instead.
This behaviour can be controlled via the environment variable
ARGVALIDATE_WARN
.
-
argvalidate.
warns_kwarg_as_arg
()¶ Returns True if argvalidate generates warnings for keyword arguments passed as arguments.
This behaviour can be controlled via the environment variable
ARGVALIDATE_WARN_KWARG_AS_ARG
.
Exceptions¶
-
exception
argvalidate.
ArgvalidateException
¶ Base argvalidate exception.
Used as base for all exceptions.
-
exception
argvalidate.
ArgumentTypeException
(func_name, arg_name, expected_type, passed_type)¶ Exception for invalid argument type.
This exception provides the following attributes:
- func_name
Name of function that caused the exception to be raised (str, read-only).
- arg_name
Name of the keyword argument passed to the function, but not specified in the decorator (str, read-only).
- expected_type
Argument type that was expected (type, read-only).
- passed_type
Argument type that was passed to the function (type, read-only).
-
exception
argvalidate.
ReturnValueTypeException
(func_name, expected_type, passed_type)¶ Exception for invalid return value type.
This exception provides the following attributes:
- func_name
Name of function that caused the exception to be raised (string, read-only).
- expected_type
Argument type that was expected (type, read-only).
- passed_type
Type of value returned by the function (type, read-only).
-
exception
argvalidate.
DecoratorNonKeyLengthException
(func_name, expected_count, passed_count)¶ Exception for invalid decorator non-keyword argument count.
This exception provides the following attributes:
- func_name
Name of function that caused the exception to be raised (str, read-only).
- expected_count
Number of arguments that were expected (int, read-only).
- passed_count
Number of arguments that were passed to the function (int, read-only).
-
exception
argvalidate.
DecoratorKeyUnspecifiedException
(func_name, arg_name)¶ Exception for unspecified decorator keyword argument.
This exception provides the following attributes:
- func_name
Name of function that caused the exception to be raised (str, read-only).
- arg_name
Name of the keyword argument passed to the function, but not specified in the decorator (str, read-only).
-
exception
argvalidate.
DecoratorStackingException
(func_name, decorator_name)¶ Exception for stacking a decorator with itself.
This exception provides the following attributes:
- func_name
Name of function that caused the exception to be raised (str, read-only).
- decorator_name
Name of the decorator that was stacked with itself (str, read-only).