magni.utils.validation._util module¶
Module providing functionality for disabling validation.
The disabling functionality is provided through a decorator for validation
functions and a function for disabling validation. Furthermore, the present
module provides functionality which is internal to magni.utils.validation
.
Routine listings¶
- decorate_validation(func)
- Decorate a validation function to allow disabling of validation checks.
- disable_validation()
- Disable validation checks in
magni
. - enable_validate_once()
- Enable validating inputs only once in certain functions in
magni
. - get_var(name)
- Retrieve the value of a variable through call stack inspection.
- report(type, description, format_args=(), var_name=None, var_value=None,
- expr=’{}’, prepend=’‘) Raise an exception.
- validate_once(func)
- Decorate a function to allow for a one-time input validation only.
-
magni.utils.validation._util.
decorate_validation
(func)[source]¶ Decorate a validation function to allow disabling of validation checks.
Parameters: func (function) – The validation function to be decorated. Returns: func (function) – The decorated validation function. See also
disable_validation()
- Disabling of validation checks.
Notes
This decorater wraps the validation function in another function which checks if validation has been disabled. If validation has been disabled, the validation function is not called. Otherwise, the validation function is called.
Examples
See
disable_validation
for an example.
-
magni.utils.validation._util.
disable_validation
()[source]¶ Disable validation checks in
magni
.See also
decorate_validation()
- Decoration of validation functions.
Notes
This function merely sets a global flag and relies on
decorate_validation
to perform the actual disabling.Examples
An example of a function which accepts only an integer as argument:
>>> import magni >>> def test(arg): ... @magni.utils.validation.decorate_validation ... def validate_input(): ... magni.utils.validation.validate_numeric('arg', 'integer') ... validate_input()
If the function is called with anything but an integer, it fails:
>>> try: ... test('string') ... except BaseException: ... print('An exception occured') ... else: ... print('No exception occured') An exception occured
However, if validation is disabled, the same call does not fail:
>>> from magni.utils.validation import disable_validation >>> disable_validation() >>> try: ... test('string') ... except BaseException: ... print('An exception occured') ... else: ... print('No exception occured') No exception occured
Although strongly discouraged, validation can be re-enabled after being disabled in the following way:
>>> import magni.utils.validation._util >>> magni.utils.validation._util._disabled = False
As this interface is not public it may be subject to changes in future releases without further notice.
-
magni.utils.validation._util.
enable_validate_once
()[source]¶ Enable validating inputs only once in certain functions in
magni
.See also
validate_once()
- Decoration of functions.
Notes
This function merely sets a global flag and relies on
validate_once
to implement the actual “validate once” functionality.Examples
An example of a function which accepts only an integer as argument:
>>> import magni >>> @magni.utils.validation.validate_once ... def test(arg): ... @magni.utils.validation.decorate_validation ... def validate_input(): ... magni.utils.validation.validate_numeric('arg', 'integer') ... validate_input()
If “validate once” is enabled, the function validation is only called on its first run:
>>> magni.utils.validation.enable_validate_once() >>> try: ... test('string') ... except BaseException: ... print('An exception occured') ... else: ... print('No exception occured') An exception occured
>>> try: ... test('string') ... except BaseException: ... print('An exception occured') ... else: ... print('No exception occured') No exception occured
-
magni.utils.validation._util.
get_var
(name)[source]¶ Retrieve the value of a variable through call stack inspection.
name must refer to a variable in the parent scope of the function or method decorated by
magni.utils.validation.decorate_validation
which is closest to the top of the call stack. If name is a string then there must be a variable of that name in that scope. If name is a set-like object then there must be a variable having the first value in that set-like object as name. The remaining values are used as keys/indices on the variable to obtain the variable to be validated. For example, the name (‘name’, 0, ‘key’) refers to the variable “name[0][‘key’]”.Parameters: name (None) – The name of the variable to be retrieved. Returns: var (None) – The value of the retrieved variable. Notes
The present function searches the call stack from top to bottom until it finds a function named ‘wrapper’ defined in this file. That is, until it finds a decorated validation function. The present function then looks up the variable indicated by name in the parent scope of that decorated validation function.
-
magni.utils.validation._util.
report
(type_, description, format_args=(), var_name=None, var_value=None, expr='{}', prepend='')[source]¶ Raise an exception.
The type of the exception is given by type_, and the message can take on many forms. This ranges from a single description to a description formatted using a number of arguments, prepended by an expression using a variable name followed by the variable value, prepended by another description.
Parameters: - type_ (type) – The exception type.
- description (str) – The core description.
- format_args (list or tuple) – The arguments which description is formatted with. (the default is (), which implies no arguments)
- var_name (None) – The name of the variable which the description concerns. (the default is None, which implies that no variable name and value is prepended to the description)
- var_value (None) – The value of the variable which the description concerns. (the default is None, which implies that the value is looked up from the var_name in the call stack if var_name is not None)
- expr (str) – The expression to evaluate with the variable name. (the default is ‘{}’, which implies that the variable value is used directly)
- prepend (str) – The text to prepend to the message generated by the previous arguments. (the default is ‘’)
Notes
name must refer to a variable in the parent scope of the function or method decorated by
magni.utils.validation.decorate_validation
which is closest to the top of the call stack. If name is a string then there must be a variable of that name in that scope. If name is a set-like object then there must be a variable having the first value in that set-like object as name. The remaining values are used as keys/indices on the variable to obtain the variable to be validated. For example, the name (‘name’, 0, ‘key’) refers to the variable “name[0][‘key’]”.
-
magni.utils.validation._util.
validate_once
(func)[source]¶ Decorate a function to allow for a one-time input validation only.
Parameters: func (function) – The validation function to be decorated. Returns: func (function) – The decorated validation function. See also
enable_validate_once()
- Enabling allow validate once functionality.
Notes
This decorater wraps any function. It checks if the “validate once” has been enabled. If it has been enabled, the validation function is only called on the first run. Otherwise, the validation function is always called if not otherwise disabled.