| Name | pvframework JSON |
| Version |
0.1.2
JSON |
| download |
| home_page | None |
| Summary | This framework enables to easily create validation functions (both sync or async) and managers to easily apply this validation logic onto arbitrary object structures. |
| upload_time | 2024-09-25 08:00:22 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.11 |
| license | MIT |
| keywords |
python
structures
validation
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Pedantic Validator Framework
This package enables you to easily create functions to apply validation logic to your data. It is designed
to work with arbitrary object structures. The validation function can be `async` if you need this feature.
Validation functions take arguments which are collected from a data structure instance on validation. The way how you
collect the arguments is fully customizable. But we give some features to retrieve these data more easily.
## Features
- Functions can be `async` or synchronous.
- Function arguments can be combined from anywhere of the data structure.
- Function arguments can be optional by defining a default value. If the argument is not found in the data structure,
the default value is used instead of failing the validation test.
- Function arguments must be fully type hinted. The framework will do an implicit type check before calling the
validation function by using `typeguard`.
- Querying the data structure for those arguments is fully customizable:
- You can define the location of the data as path notation like: `field_a_of_data_structure.field_b_of_field_a`
- You can define iterators to apply validation logic e.g. on every element inside a list.
- You can define a completely customized function to retrieve the data.
- Errors raised in validation functions during the validation process are handled by an error handler.
- Basic analysis of the result of a validated data structure.
## Installation
The package is [available on PyPI](https://pypi.org/project/pvframework/):
```bash
pip install pvframework
```
## Getting started
To validate an arbitrary object structure (called data structure in the following), you have to create a
`ValidationManager` instance which is unique for the type of the data structure. This instance can
register any mapped validators you want to use for your data structure.
Note that the data structure have to be hashable at least at validation time. This is needed for proper error handling.
```python
import asyncio
from pvframework import ValidationManager, PathMappedValidator, Validator
class MySubStructure:
def __init__(self, y: str):
self.y = y
def __hash__(self):
return hash(self.y)
class MyDataStructure:
def __init__(self, x: MySubStructure):
self.x = x
def __hash__(self):
return hash(self.x)
manager = ValidationManager[MyDataStructure]()
def check_z_is_a_number(z: str):
if not z.isnumeric():
raise ValueError("y is not a number")
manager.register(PathMappedValidator(Validator(check_z_is_a_number), {"z": "x.y"}))
data = MyDataStructure(MySubStructure("123"))
result = asyncio.get_event_loop().run_until_complete(manager.validate(data))
assert result.num_fails == 0
```
First, the function `check_y_is_a_number` is a simple function which takes a string and raises an error if the value
is not numeric. The naming of the parameter is not important.
The framework ensures that the value is a string before calling the function. So you don't have to do any instance
checks in your validation functions. Similarly, if the framework can't find the value in the data structure, it will
also be treated as failed. The type checks are done via `typeguard`.
Second, we have to create a validator of this function by passing it to its constructor. It only does some basic
analysis like inspecting the signature, determining required and optional arguments, etc. You could create subclasses
of this and passing it to customized `MappedValidator`s if needed.
Third, we need to tell the framework how it should retrieve the values for the arguments from the data structure.
For this, the framework provides two predefined `MappedValidator`s: `PathMappedValidator` and `QueryMappedValidator`.
The `QueryMappedValidator` is very powerful but might be a bit overkill in most cases. The `PathMappedValidator` is
a simpler way to define the location of the data for each argument using a path notation.
Between every point the framework will invoke the `__getattr__` method to query through the data structure.
If you have any more complicated than that you can use the `QueryMappedValidator` or even create your own
`MappedValidator` subclass.
Last, you have to register the `MappedValidator` to the `ValidationManager`. You can than invoke the `validate`
method with one or more data structure instances. The `validate` method returns a `ValidationResult` instance which
provides some basic analysis of the validation result if needed. Note that these analysis are only triggered on
demand but the object will cache any results.
Note: The validate method is `async` because the validation functions can be `async` as well. Currently, we don't need
a synchronous alternative for the method but will come eventually.
## A more complex example
This example will demonstrate you how you can use the `QueryMappedValidator` which has to iterate parallel over
two dictionaries inside the data structure.
```python
import asyncio
from pvframework import (
ValidationManager,
ParallelQueryMappedValidator,
Validator,
Query,
)
from pvframework.types import SyncValidatorFunction
from pvframework.utils import param
from dataclasses import dataclass
from schwifty import IBAN
from typing import Optional, TypeAlias, Any, Generator
from frozendict import frozendict
@dataclass(frozen=True)
class BankingData:
iban: str
@dataclass(frozen=True)
class Customer:
name: str
age: int
banking_data_per_contract: frozendict[str, BankingData]
# This maps a contract ID onto its payment information
paying_through_sepa: frozendict[str, bool]
# This stores for each contract ID if the customer pays using a SEPA mandate
def check_iban(sepa_zahler: bool, iban: Optional[str] = None):
"""
If `sepa_zahler` is True `iban` is required and checked on syntax.
If `sepa_zahler` is False the test passes.
"""
if sepa_zahler:
if iban is None:
raise ValueError(f"{param('iban').param_id} is required for sepa_zahler")
IBAN(iban).validate()
ValidatorType: TypeAlias = Validator[Customer, SyncValidatorFunction]
validate_iban: ValidatorType = Validator(check_iban)
def iter_contract_id_dict(some_dict: dict[str, Any]) -> Generator[tuple[Any, str], None, None]:
return ((value, f"[contract_id={key}]") for key, value in some_dict.items())
manager = ValidationManager[Customer]()
manager.register(
ParallelQueryMappedValidator(
validate_iban,
{
"iban": Query().path("banking_data_per_contract").iter(iter_contract_id_dict).path("iban"),
"sepa_zahler": Query().path("paying_through_sepa").iter(iter_contract_id_dict),
},
)
)
data = Customer(
name="John Doe",
age=42,
banking_data_per_contract=frozendict({
"contract_1": BankingData(iban="DE52940594210000082271"),
"contract_2": BankingData(iban="DE89370400440532013000"),
"contract_3": BankingData(iban="DE89370400440532013001"),
}),
paying_through_sepa=frozendict({"1": True, "2": True, "3": False}),
)
result = asyncio.get_event_loop().run_until_complete(manager.validate(data))
assert result.num_errors_total == 1
assert "contract_2" in str(result.all_errors[0])
```
In this case we are using a specialized version of the `QueryMappedValidator`. When having to iterate through
lists, dicts or similar the `QueryMappedValidator` will apply the validation function on every element of the
cartesian product of the iterators. I.e. for every possible combination. But we want the iterators to map
parallel. This is what the `ParallelQueryMappedValidator` does. If the iterators have different lengths which are not
`1`, it will *raise* an error. I.e. the `validate` method would crash.
If you are wondering about the iterator function `iter_contract_id_dict` and why it returns a tuple of the value and
a string:
The string is used for error reporting. If the validation function fails for the set of parameters, the framework
will use those strings to define the location of the parameter inside the data structure.
## How to use this Repository on Your Machine
Follow the instructions in our [Python template repository](https://github.com/Hochfrequenz/python_template_repository#how-to-use-this-repository-on-your-machine).
## Contribute
You are very welcome to contribute to this repository by opening a pull request against the main branch.
Raw data
{
"_id": null,
"home_page": null,
"name": "pvframework",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "python, structures, validation",
"author": null,
"author_email": "Hochfrequenz Unternehmensberatung GmbH <info@hochfrequenz.de>",
"download_url": "https://files.pythonhosted.org/packages/87/b2/aa39f7490c6b8256c6c5948543e4258ca47437f8e7f2a6d94d1a2e9921cc/pvframework-0.1.2.tar.gz",
"platform": null,
"description": "# Pedantic Validator Framework\n\n\n\n\n\n\n\n\nThis package enables you to easily create functions to apply validation logic to your data. It is designed\nto work with arbitrary object structures. The validation function can be `async` if you need this feature.\n\nValidation functions take arguments which are collected from a data structure instance on validation. The way how you\ncollect the arguments is fully customizable. But we give some features to retrieve these data more easily.\n\n## Features\n- Functions can be `async` or synchronous.\n- Function arguments can be combined from anywhere of the data structure.\n- Function arguments can be optional by defining a default value. If the argument is not found in the data structure,\n the default value is used instead of failing the validation test.\n- Function arguments must be fully type hinted. The framework will do an implicit type check before calling the\n validation function by using `typeguard`.\n- Querying the data structure for those arguments is fully customizable:\n - You can define the location of the data as path notation like: `field_a_of_data_structure.field_b_of_field_a`\n - You can define iterators to apply validation logic e.g. on every element inside a list.\n - You can define a completely customized function to retrieve the data.\n- Errors raised in validation functions during the validation process are handled by an error handler.\n- Basic analysis of the result of a validated data structure.\n\n## Installation\nThe package is [available on PyPI](https://pypi.org/project/pvframework/):\n```bash\npip install pvframework\n```\n\n## Getting started\nTo validate an arbitrary object structure (called data structure in the following), you have to create a\n`ValidationManager` instance which is unique for the type of the data structure. This instance can\nregister any mapped validators you want to use for your data structure.\n\nNote that the data structure have to be hashable at least at validation time. This is needed for proper error handling.\n\n```python\nimport asyncio\nfrom pvframework import ValidationManager, PathMappedValidator, Validator\n\nclass MySubStructure:\n def __init__(self, y: str):\n self.y = y\n\n def __hash__(self):\n return hash(self.y)\n\nclass MyDataStructure:\n def __init__(self, x: MySubStructure):\n self.x = x\n\n def __hash__(self):\n return hash(self.x)\n\nmanager = ValidationManager[MyDataStructure]()\n\ndef check_z_is_a_number(z: str):\n if not z.isnumeric():\n raise ValueError(\"y is not a number\")\n\nmanager.register(PathMappedValidator(Validator(check_z_is_a_number), {\"z\": \"x.y\"}))\n\ndata = MyDataStructure(MySubStructure(\"123\"))\nresult = asyncio.get_event_loop().run_until_complete(manager.validate(data))\nassert result.num_fails == 0\n```\n\nFirst, the function `check_y_is_a_number` is a simple function which takes a string and raises an error if the value\nis not numeric. The naming of the parameter is not important.\nThe framework ensures that the value is a string before calling the function. So you don't have to do any instance\nchecks in your validation functions. Similarly, if the framework can't find the value in the data structure, it will\nalso be treated as failed. The type checks are done via `typeguard`.\n\nSecond, we have to create a validator of this function by passing it to its constructor. It only does some basic\nanalysis like inspecting the signature, determining required and optional arguments, etc. You could create subclasses\nof this and passing it to customized `MappedValidator`s if needed.\n\nThird, we need to tell the framework how it should retrieve the values for the arguments from the data structure.\nFor this, the framework provides two predefined `MappedValidator`s: `PathMappedValidator` and `QueryMappedValidator`.\nThe `QueryMappedValidator` is very powerful but might be a bit overkill in most cases. The `PathMappedValidator` is\na simpler way to define the location of the data for each argument using a path notation.\nBetween every point the framework will invoke the `__getattr__` method to query through the data structure.\nIf you have any more complicated than that you can use the `QueryMappedValidator` or even create your own\n`MappedValidator` subclass.\n\nLast, you have to register the `MappedValidator` to the `ValidationManager`. You can than invoke the `validate`\nmethod with one or more data structure instances. The `validate` method returns a `ValidationResult` instance which\nprovides some basic analysis of the validation result if needed. Note that these analysis are only triggered on\ndemand but the object will cache any results.\n\nNote: The validate method is `async` because the validation functions can be `async` as well. Currently, we don't need\na synchronous alternative for the method but will come eventually.\n\n## A more complex example\n\nThis example will demonstrate you how you can use the `QueryMappedValidator` which has to iterate parallel over\ntwo dictionaries inside the data structure.\n\n```python\nimport asyncio\nfrom pvframework import (\n ValidationManager,\n ParallelQueryMappedValidator,\n Validator,\n Query,\n)\nfrom pvframework.types import SyncValidatorFunction\nfrom pvframework.utils import param\nfrom dataclasses import dataclass\nfrom schwifty import IBAN\nfrom typing import Optional, TypeAlias, Any, Generator\nfrom frozendict import frozendict\n\n@dataclass(frozen=True)\nclass BankingData:\n iban: str\n\n@dataclass(frozen=True)\nclass Customer:\n name: str\n age: int\n banking_data_per_contract: frozendict[str, BankingData]\n # This maps a contract ID onto its payment information\n paying_through_sepa: frozendict[str, bool]\n # This stores for each contract ID if the customer pays using a SEPA mandate\n\ndef check_iban(sepa_zahler: bool, iban: Optional[str] = None):\n \"\"\"\n If `sepa_zahler` is True `iban` is required and checked on syntax.\n If `sepa_zahler` is False the test passes.\n \"\"\"\n if sepa_zahler:\n if iban is None:\n raise ValueError(f\"{param('iban').param_id} is required for sepa_zahler\")\n IBAN(iban).validate()\n\nValidatorType: TypeAlias = Validator[Customer, SyncValidatorFunction]\nvalidate_iban: ValidatorType = Validator(check_iban)\n\ndef iter_contract_id_dict(some_dict: dict[str, Any]) -> Generator[tuple[Any, str], None, None]:\n return ((value, f\"[contract_id={key}]\") for key, value in some_dict.items())\n\nmanager = ValidationManager[Customer]()\nmanager.register(\n ParallelQueryMappedValidator(\n validate_iban,\n {\n \"iban\": Query().path(\"banking_data_per_contract\").iter(iter_contract_id_dict).path(\"iban\"),\n \"sepa_zahler\": Query().path(\"paying_through_sepa\").iter(iter_contract_id_dict),\n },\n )\n)\n\ndata = Customer(\n name=\"John Doe\",\n age=42,\n banking_data_per_contract=frozendict({\n \"contract_1\": BankingData(iban=\"DE52940594210000082271\"),\n \"contract_2\": BankingData(iban=\"DE89370400440532013000\"),\n \"contract_3\": BankingData(iban=\"DE89370400440532013001\"),\n }),\n paying_through_sepa=frozendict({\"1\": True, \"2\": True, \"3\": False}),\n)\nresult = asyncio.get_event_loop().run_until_complete(manager.validate(data))\nassert result.num_errors_total == 1\nassert \"contract_2\" in str(result.all_errors[0])\n```\n\nIn this case we are using a specialized version of the `QueryMappedValidator`. When having to iterate through\nlists, dicts or similar the `QueryMappedValidator` will apply the validation function on every element of the\ncartesian product of the iterators. I.e. for every possible combination. But we want the iterators to map\nparallel. This is what the `ParallelQueryMappedValidator` does. If the iterators have different lengths which are not\n`1`, it will *raise* an error. I.e. the `validate` method would crash.\n\nIf you are wondering about the iterator function `iter_contract_id_dict` and why it returns a tuple of the value and\na string:\nThe string is used for error reporting. If the validation function fails for the set of parameters, the framework\nwill use those strings to define the location of the parameter inside the data structure.\n\n\n## How to use this Repository on Your Machine\n\nFollow the instructions in our [Python template repository](https://github.com/Hochfrequenz/python_template_repository#how-to-use-this-repository-on-your-machine).\n\n## Contribute\n\nYou are very welcome to contribute to this repository by opening a pull request against the main branch.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "This framework enables to easily create validation functions (both sync or async) and managers to easily apply this validation logic onto arbitrary object structures.",
"version": "0.1.2",
"project_urls": {
"Changelog": "https://github.com/Hochfrequenz/pedantic-validator-framework/releases",
"Homepage": "https://github.com/Hochfrequenz/pedantic-validator-framework"
},
"split_keywords": [
"python",
" structures",
" validation"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b1c8632e4cebaccc70af39e3576503c9664381699acfaa5e82609ffa96049730",
"md5": "b09e27aac1947db623fdddbd5ace67ad",
"sha256": "701711065b689d98ca20b54892c141afa8ee7e6c8f43cbd88b6d2e659cab2f85"
},
"downloads": -1,
"filename": "pvframework-0.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b09e27aac1947db623fdddbd5ace67ad",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 27681,
"upload_time": "2024-09-25T08:00:20",
"upload_time_iso_8601": "2024-09-25T08:00:20.898004Z",
"url": "https://files.pythonhosted.org/packages/b1/c8/632e4cebaccc70af39e3576503c9664381699acfaa5e82609ffa96049730/pvframework-0.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "87b2aa39f7490c6b8256c6c5948543e4258ca47437f8e7f2a6d94d1a2e9921cc",
"md5": "1496934b4c300ec747c30d2adada72b5",
"sha256": "8d2768824e4dbfcfe9f591886892902b8ed9dd727830e54e5dcaf1ce6072d420"
},
"downloads": -1,
"filename": "pvframework-0.1.2.tar.gz",
"has_sig": false,
"md5_digest": "1496934b4c300ec747c30d2adada72b5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 29238,
"upload_time": "2024-09-25T08:00:22",
"upload_time_iso_8601": "2024-09-25T08:00:22.392411Z",
"url": "https://files.pythonhosted.org/packages/87/b2/aa39f7490c6b8256c6c5948543e4258ca47437f8e7f2a6d94d1a2e9921cc/pvframework-0.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-25 08:00:22",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Hochfrequenz",
"github_project": "pedantic-validator-framework",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"tox": true,
"lcname": "pvframework"
}
