docs: 📚 Add a proper README

Author: ddanier

README.md

@@ -1,3 +1,189 @@
 # `pydantic-async-validation`
 
-TODO
+Add async validation to your pydantic models 🥳. This allows you to add validation that actually checks the database
+or makes an API call or just use any code you did write async.
+
+Note that validation cannot happen during model creation, so you have to call `await model.model_async_validate()`
+yourself. This is due to the fact that `__init__()` will always be a sync method and you cannot sanely call async
+methods from sync methods.
+
+## Example usage
+
+```python
+import pydantic
+from pydantic_async_validation import async_field_validator, AsyncValidationModelMixin
+
+
+class SomethingModel(AsyncValidationModelMixin, pydantic.BaseModel):
+    name: str
+
+    @async_field_validator('name')
+    async def validate_name(self, value: str) -> None:
+        if value == "invalid":
+            raise ValueError("Invalid name")
+
+
+valid_instance = SomethingModel(name="valid")
+await valid_instance.model_async_validate()
+
+invalid_instance = SomethingModel(name="invalid")
+await invalid_instance.model_async_validate()  # will raise normal pydantic ValidationError
+```
+
+## Field validators
+
+You can use `async_field_validator` to add async validators to your model. The first argument is the name of the field
+to validate. You may also pass additional field names, the validator will then be called for all fields. As validation
+is happening after the instance was created, you can access all fields of the model and the validator should just be a
+normal instance method (accepting `self` as its first parameter).
+
+Field validators may use any combination of the following arguments:
+* `value`: The value of the field to validate (same as `getattr(self, field)`)
+* `field`: The name of the field being validated, can be useful if you use the same validator for multiple fields
+* `config`: The config of the validator, see `ValidationInfo` for details
+
+You may also pass additional keyword arguments to `async_field_validator`, they will be passed to the validator config
+(`ValidationInfo` instance) and be available in the validator config as `config.extra`.
+
+Example:
+
+```python
+import pydantic
+from pydantic_async_validation import async_field_validator, AsyncValidationModelMixin, ValidationInfo
+
+
+class SomethingModel(AsyncValidationModelMixin, pydantic.BaseModel):
+    name: str
+    other_name: str
+
+    @async_field_validator('name', 'other_name', some_extra='value')
+    async def validate_name(self, value: str, field: str, config: ValidationInfo) -> None:
+        if value == "invalid":
+            # Using ValueError 
+            raise ValueError(f"Invalid {field} with extra {config.extra['some_extra']}")
+```
+
+## Model validators
+
+You can use `async_model_validator` to add async validators to your model. The validator will be called after all field
+validators have been called. The validator should be a normal instance method (accepting `self` as its first parameter).
+
+Model validators may use any combination of the following arguments:
+* `config`: The config of the validator, see `ValidationInfo` for details
+
+
+Example:
+
+```python
+import pydantic
+from pydantic_async_validation import async_model_validator, AsyncValidationModelMixin, ValidationInfo
+
+
+class SomethingModel(AsyncValidationModelMixin, pydantic.BaseModel):
+    name: str
+    other_name: str
+
+    @async_model_validator(some_extra='value')
+    async def validate_names(self, config: ValidationInfo) -> None:
+        # Using assertion 
+        assert self.name != self.other_name, f"Names are equal with extra {config.extra['some_extra']}"
+```
+
+## When to use field vs. model validators
+
+As validation happens after the model instance was created, you can access all fields  just using `self` anyways. So
+field vs. model validation is kind of the same thing. However field validators allow you to get the `value` of the
+field as its parameter, so this is perfect when you reuse validators or want to validate multiple fields with the same
+validator. Also field validators will tie the `ValidationError` to the field, so it will contain the detail about which
+field failed to validate. In general you should use field validators when you want to validate a single field. I also
+suggest using the `value` parameter to have a clean and consistent interface for your validators.
+
+Model validators on the other hand should be used when you need to validate multiple fields at once. This is especially
+useful when you want to validate that multiple fields are consistent with each other. For example you might want to
+validate that a start date is before an end date. In this case you would use a model validator and access both fields
+using `self`. Note that model validators will be tied to `"__root__"` in the `ValidationError` as there is no specific
+field to tie it to.
+
+## Handling validation errors
+
+Like with normal pydantic validation, you can catch `ValidationError` and access the `errors()` method to get a list of
+all errors. Like pydantic errors will be collected and be raised as one `ValidationError` at the end of validation,
+including all errors that occurred.
+
+`model_async_validate()` will also try to validate child model instances, that are also using the
+`AsyncValidationModelMixin`. This means the following example code will work as expected:
+
+```python
+import pydantic
+from pydantic_async_validation import async_field_validator, AsyncValidationModelMixin, ValidationInfo
+
+
+class SomethingModel(AsyncValidationModelMixin, pydantic.BaseModel):
+    name: str
+
+    @async_field_validator('name')
+    async def validate_name(self, value: str, field: str, config: ValidationInfo) -> None:
+        if value == "invalid":
+            raise ValueError(f"Value may not be 'invalid'")
+
+
+class ParentModel(AsyncValidationModelMixin, pydantic.BaseModel):
+    child: SomethingModel
+
+
+invalid_instance = ParentModel(child=SomethingModel(name="invalid"))
+await invalid_instance.model_async_validate()  # will raise normal pydantic ValidationError
+```
+
+Note the `ValidationError` will not have the location of the error set to `"child.name"`.
+
+Recursive validation will happen in those cases:
+* Child models as direct instance variables (see example above)
+* Child models in list items
+* Child models in dict values
+
+## FastAPI support
+
+When using FastAPI you also can use the `AsyncValidationModelMixin`, note however that FastAPI will see any
+`ValidationError` risen in endpoint methods as unhandled exceptions and thus will return a HTTP 500 error. FastAPI
+will only handle the validation errors happening during handling the endpoint parameters in as special way and
+convert those to `RequestValidationError` - which will then be handled by the default exception handler for
+`RequestValidationError` FastAPI provides. This will then result in a HTTP 422 return code.
+
+When using `pydantic_async_validation` this would be a major drawback, as using `model_async_validate` for
+validating input (/request) data is a totally fine use case. To solve this issue you can use the
+`ensure_request_validation_errors` context manager provided in `pydantic_async_validation.fastapi`. This will
+ensure that any `ValidationError` risen during the context manager will be converted to a `RequestValidationError`.
+Those `RequestValidationError`s will then be handled by the default exception handler for `RequestValidationError`
+FastAPI provides. This will then again result in a HTTP 422 return code.
+
+Example for usage with FastAPI:
+
+```python
+import fastapi
+import pydantic
+from pydantic_async_validation import AsyncValidationModelMixin
+from pydantic_async_validation.fastapi import ensure_request_validation_errors
+
+
+class SomethingModel(AsyncValidationModelMixin, pydantic.BaseModel): ...
+
+
+app = fastapi.FastAPI()
+
+@app.get("/return-http-422-on-async-validation-error")
+async def return_http_422_on_async_validation_error():
+    instance = SomethingModel(...)
+    with ensure_request_validation_errors():
+        await instance.model_async_validate()
+```
+
+You may also use `ensure_request_validation_errors` to do additional validation on the request data using normal
+pydantic validation and converting those `ValidationError`s to `RequestValidationError`s. 😉
+
+# Contributing
+
+If you want to contribute to this project, feel free to just fork the project,
+create a dev branch in your fork and then create a pull request (PR). If you
+are unsure about whether your changes really suit the project please create an
+issue first, to talk about this.

pydantic_async_validation/__init__.py

@@ -1,2 +1,2 @@
 from pydantic_async_validation.mixins import AsyncValidationModelMixin
-from pydantic_async_validation.validators import async_field_validator, async_model_validator
+from pydantic_async_validation.validators import ValidationInfo, async_field_validator, async_model_validator

tests/test_field_validators.py

@@ -19,6 +19,11 @@ async def validate_name(self, value: str) -> None:
         if value == "invalid":
             raise ValueError("Invalid name")
 
+    @async_field_validator('age')
+    async def validate_age(self, value: int) -> None:
+        assert value == self.age
+        assert value > 0
+
 
 @pytest.mark.asyncio
 async def test_async_validation_raises_no_issues():
@@ -33,6 +38,13 @@ async def test_async_validation_raises_when_validation_fails():
         await instance.model_async_validate()
 
 
+@pytest.mark.asyncio
+async def test_async_validation_raises_when_validation_fails_by_assertion():
+    instance = SomethingModel(name="valid", age=0)
+    with pytest.raises(pydantic.ValidationError):
+        await instance.model_async_validate()
+
+
 @pytest.mark.asyncio
 async def test_all_field_validator_combinations_are_valid():
     class OtherModel(AsyncValidationModelMixin, pydantic.BaseModel):

tests/test_model_validators.py

@@ -17,6 +17,10 @@ async def validate_name(self) -> None:
         if self.name == "invalid":
             raise ValueError("Invalid name")
 
+    @async_model_validator()
+    async def validate_age(self) -> None:
+        assert self.age > 0
+
 
 @pytest.mark.asyncio
 async def test_async_validation_raises_no_issues():
@@ -31,6 +35,13 @@ async def test_async_validation_raises_when_validation_fails():
         await instance.model_async_validate()
 
 
+@pytest.mark.asyncio
+async def test_async_validation_raises_when_validation_fails():
+    instance = SomethingModel(name="invalid", age=1)
+    with pytest.raises(pydantic.ValidationError):
+        await instance.model_async_validate()
+
+
 @pytest.mark.asyncio
 async def test_all_field_validator_combinations_are_valid():
     class OtherModel(AsyncValidationModelMixin, pydantic.BaseModel):