Metadata-Version: 2.1
Name: ValiDecor
Version: 1.0.4
Summary: Decorated, Annotated, Validated
Author-email: giladooshlon <giladrv@gmail.com>
License: MIT License
        
        Copyright (c) 2024 giladrv
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/giladrv/validecor
Keywords: validation,decorator,lambda
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE

# 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](#advanced) section for more details.

## Installation

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)<a name="advanced"></a>

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.
