Decorated, Annotated, Validated
Project description
ValiDecor
ValiDecor is a Python library designed to facilitate robust input validation using its core decorator validecor
. It leverages Python's type annotation system to provide a seamless and intuitive interface for enforcing input constraints directly in function signatures using the special annotation type typing.Annotated
.
ValiDecor was designed with special attention for its potential use on AWS Lambda functions. AWS Lambda handlers expect a fixed signature, i.e. handler(event, context)
. This signature is uninformative and hinders code development. Refer to the Advanced Usage section for more details.
Installation (not implement yet)
Install ValiDecor via pip:
pip install ValiDecor
Usage
Basic Usage
To use ValiDecor, annotate function arguments with the desired validators wrapped inside typing.Annotated
, and apply the @validecor()
decorator to the function. Here is a basic example:
from typing import Annotated
from validecor import validecor
from validecor.validators import IsType
@validecor()
def hello(msg: Annotated[str, IsType(str)]):
print('Message:', msg)
Advanced Usage (AWS Lambda)
The validecor
decorator accepts several parameters to customized its usage. One can define the function signature expected by the caller, and automatically map the input to actually relevant arguments needed by the function. This is best explained with an example:
from typing import Annotated
from validecor import Attr, Map, validecor
# we define the source function signature
def handler(event, context):
pass
# extend the Map class for better readability later
class MapS3(Map):
def __init__(self, *nodes: int | str | Callable[..., Any]):
super().__init__('event', 'Records', 0, 's3', *nodes)
# some function to be applied during the mapping
def to_mb(size_in_bytes: float):
return size_in_bytes / 1024 / 1024
@validecor(handler)
def s3_trigger(
bucket: Annotated[str, MapS3('bucket', 'name')],
key: Annotated[str, MapS3('object', 'key')],
size: Annotated[float, MapS3('object', 'size', to_mb)],
mem: Annotated[int, Map('context', Attr('memory_limit_in_mb'))]):
...
This way we only get the arguments relevant for the function operation, with helpful type hints, and don't need to bother with extracting them from the original event
or context
inputs within the function body.
Maps will be cached internally so as not to reapeat potentially expensive operations.
Callback Hooks
The validecor
decorator supports the following hooks:
Initialization And Logging
pre_hook: Callable[[*source_args, **source_kwargs], Any] = default_log_hook
This hook is called with the same arguments as the original function. Can be used for logging or halting the rest of the function execution by returning any not None
value, which is then returned to the original caller. By default no action is performed.
Validation Handling
val_hook: Callable[[Exception, Validator | ExtendedValidator], Any] = default_val_hook
This hook is called upon validation errors (or Map failures). Use this to return a custom error message to the user. By default the exception is re-raised unchanged.
Function Errors
err_hook: Callable[[Exception, *target_args, **target_kwargs], Any] = default_err_hook
This hook is called when an exception is raised within the function body. The return value of the hook is the final value returned to the original caller. By default the exception is re-raised unchanged.
Post-Processing
map_hook: Callable[[Any], Any] = default_map_hook
This hook is called with the results of the function to enable any post-processing. The return value of the hook is the final value returned to the original caller. By default passes along the same value returned by the function.
Custom Validators
You can create custom validators in two ways: using the validators.Custom
class which accepts any Callable
, or by extending the Validator
or ExtendedValidator
classes from validecor.core
. Here's how to create a custom validator that ensures a number is positive:
from validecor.core import Validator
class IsPositive(Validator):
def __call__(self, arg):
try:
if arg <= 0:
raise ValueError(f"Invalid value: {arg}")
except ValueError:
raise
except Exception as e:
raise ValueError(f'Uncomparable value: {arg}', e)
def __desc__(self):
return "Argument must be a positive number."
@validecor()
def increment(number: Annotated[int, IsPositive()]):
return number + 1
Typically we would want the description to be general for the validation class, and the error message to contain some clue as to why the validation failed, e.g. by noting the argument value or type.
Contributing
Contributions to ValiDecor are welcome! Fork the repository, make your changes, and submit a pull request to contribute.
License
ValiDecor is released under the MIT License. See the LICENSE file for more details.
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for ValiDecor-1.0.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 4dacbdb02eba12f6d24b31e97447d72a0711808fb3b4ce9b20a3aa49cd8351e8 |
|
MD5 | c8c56d8743a820e1d367ce98cf62842b |
|
BLAKE2b-256 | 215b0535ec30676cc6adf4e96801125d99f90f0f274ec01931717744346a1da1 |