python-openapi · p1c2u · Mar 11, 2025 · Sep 15, 2024
diff --git a/.gitignore b/.gitignore
@@ -1,5 +1,5 @@
 # Byte-compiled / optimized / DLL files
-__pycache__/
+**/__pycache__/
 *.py[cod]
 *$py.class
 .pytest_cache/
@@ -63,7 +63,7 @@ instance/
 .scrapy
 
 # Sphinx documentation
-docs/_build/
+docs_build/
 
 # PyBuilder
 target/

diff --git a/README.md b/README.md
@@ -21,17 +21,17 @@
 
 ## About
 
-Openapi-core is a Python library that adds client-side and server-side support
+Openapi-core is a Python library that provides client-side and server-side support
 for the [OpenAPI v3.0](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md)
-and [OpenAPI v3.1](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md) specification.
+and [OpenAPI v3.1](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md) specifications.
 
 
 ## Key features
 
 - **Validation** and **unmarshalling** of request and response data (including webhooks)
 - **Integration** with popular libraries (Requests, Werkzeug) and frameworks (Django, Falcon, Flask, Starlette)
 - Customization with media type **deserializers** and format **unmarshallers**
-- **Security** data providers (API keys, Cookie, Basic and Bearer HTTP authentications)
+- **Security** data providers (API keys, Cookie, Basic, and Bearer HTTP authentications)
 
 
 ## Documentation
@@ -56,7 +56,7 @@ pip install -e git+https://github.com/python-openapi/openapi-core.git#egg=openap
 
 ## First steps
 
-Firstly create your OpenAPI object.
+First, create your OpenAPI object.
 
 ``` python
 from openapi_core import OpenAPI
@@ -67,11 +67,11 @@ openapi = OpenAPI.from_file_path('openapi.json')
 Now you can use it to validate and unmarshal against requests and/or responses. 
 
 ``` python
-# raises error if request is invalid
+# raises an error if the request is invalid
 result = openapi.unmarshal_request(request)
 ```
 
-Retrieve validated and unmarshalled request data
+Retrieve validated and unmarshalled request data.
 
 ``` python
 # get parameters
@@ -85,19 +85,19 @@ body = result.body
 security = result.security
 ```
 
-Request object should implement OpenAPI Request protocol. Check [Integrations](https://openapi-core.readthedocs.io/en/latest/integrations.html) to find officially supported implementations.
+The request object should implement the OpenAPI Request protocol. Check [Integrations](https://openapi-core.readthedocs.io/en/latest/integrations.html) to find officially supported implementations.
 
-For more details read about [Unmarshalling](https://openapi-core.readthedocs.io/en/latest/unmarshalling.html) process.
+For more details read about the [Unmarshalling](https://openapi-core.readthedocs.io/en/latest/unmarshalling.html) process.
 
 If you just want to validate your request/response data without unmarshalling, read about [Validation](https://openapi-core.readthedocs.io/en/latest/validation.html) instead.
 
 
 ## Related projects
 
 - [openapi-spec-validator](https://github.com/python-openapi/openapi-spec-validator)
-  : Python library that validates OpenAPI Specs against the OpenAPI 2.0 (aka Swagger), OpenAPI 3.0 and OpenAPI 3.1 specification. The validator aims to check for full compliance with the Specification.
+  : A Python library that validates OpenAPI Specs against the OpenAPI 2.0 (aka Swagger), OpenAPI 3.0, and OpenAPI 3.1 specification. The validator aims to check for full compliance with the Specification.
 - [openapi-schema-validator](https://github.com/python-openapi/openapi-schema-validator)
-  : Python library that validates schema against the OpenAPI Schema Specification v3.0 and OpenAPI Schema Specification v3.1.
+  : A Python library that validates schema against the OpenAPI Schema Specification v3.0 and OpenAPI Schema Specification v3.1.
 - [bottle-openapi-3](https://github.com/cope-systems/bottle-openapi-3)
   : OpenAPI 3.0 Support for the Bottle Web Framework
 - [pyramid_openapi3](https://github.com/niteoweb/pyramid_openapi3)
@@ -107,4 +107,4 @@ If you just want to validate your request/response data without unmarshalling, r
 
 ## License
 
-The project is under the terms of BSD 3-Clause License.
+The project is under the terms of the BSD 3-Clause License.
diff --git a/docs/configuration.md b/docs/configuration.md
@@ -0,0 +1,181 @@
+---
+hide:
+  - navigation
+---
+
+# Configuration
+
+OpenAPI accepts a `Config` object that allows users to customize the behavior of validation and unmarshalling processes.
+
+## Specification Validation
+
+By default, when creating an OpenAPI instance, the provided specification is also validated.
+
+If you know that you have a valid specification already, disabling the validator can improve performance.
+
+``` python hl_lines="1 4 6"
+from openapi_core import Config
+
+config = Config(
+    spec_validator_cls=None,
+)
+openapi = OpenAPI.from_file_path('openapi.json', config=config)
+```
+
+## Request Validator
+
+By default, the request validator is selected based on the detected specification version.
+
+To explicitly validate a:
+
+- OpenAPI 3.0 spec, import `V30RequestValidator`
+- OpenAPI 3.1 spec, import `V31RequestValidator` or `V31WebhookRequestValidator`
+
+``` python hl_lines="1 4"
+from openapi_core import V31RequestValidator
+
+config = Config(
+    request_validator_cls=V31RequestValidator,
+)
+openapi = OpenAPI.from_file_path('openapi.json', config=config)
+openapi.validate_request(request)
+```
+
+You can also explicitly import `V3RequestValidator`, which is a shortcut to the latest OpenAPI v3 version.
+
+## Response Validator
+
+By default, the response validator is selected based on the detected specification version.
+
+To explicitly validate a:
+
+- OpenAPI 3.0 spec, import `V30ResponseValidator`
+- OpenAPI 3.1 spec, import `V31ResponseValidator` or `V31WebhookResponseValidator`
+
+``` python hl_lines="1 4"
+from openapi_core import V31ResponseValidator
+
+config = Config(
+    response_validator_cls=V31ResponseValidator,
+)
+openapi = OpenAPI.from_file_path('openapi.json', config=config)
+openapi.validate_response(request, response)
+```
+
+You can also explicitly import `V3ResponseValidator`, which is a shortcut to the latest OpenAPI v3 version.
+
+## Request Unmarshaller
+
+By default, the request unmarshaller is selected based on the detected specification version.
+
+To explicitly validate and unmarshal a request for:
+
+- OpenAPI 3.0 spec, import `V30RequestUnmarshaller`
+- OpenAPI 3.1 spec, import `V31RequestUnmarshaller` or `V31WebhookRequestUnmarshaller`
+
+``` python hl_lines="1 4"
+from openapi_core import V31RequestUnmarshaller
+
+config = Config(
+    request_unmarshaller_cls=V31RequestUnmarshaller,
+)
+openapi = OpenAPI.from_file_path('openapi.json', config=config)
+result = openapi.unmarshal_request(request)
+```
+
+You can also explicitly import `V3RequestUnmarshaller`, which is a shortcut to the latest OpenAPI v3 version.
+
+## Response Unmarshaller
+
+To explicitly validate and unmarshal a response:
+
+- For OpenAPI 3.0 spec, import `V30ResponseUnmarshaller`
+- For OpenAPI 3.1 spec, import `V31ResponseUnmarshaller` or `V31WebhookResponseUnmarshaller`
+
+``` python hl_lines="1 4"
+from openapi_core import V31ResponseUnmarshaller
+
+config = Config(
+    response_unmarshaller_cls=V31ResponseUnmarshaller,
+)
+openapi = OpenAPI.from_file_path('openapi.json', config=config)
+result = openapi.unmarshal_response(request, response)
+```
+
+You can also explicitly import `V3ResponseUnmarshaller`, which is a shortcut to the latest OpenAPI v3 version.
+
+## Extra Media Type Deserializers
+
+The library comes with a set of built-in media type deserializers for formats such as `application/json`, `application/xml`, `application/x-www-form-urlencoded`, and `multipart/form-data`.
+
+You can also define your own deserializers. To do this, pass a dictionary of custom media type deserializers with the supported MIME types as keys to the `unmarshal_response` function:
+
+```python hl_lines="11"
+def protobuf_deserializer(message):
+    feature = route_guide_pb2.Feature()
+    feature.ParseFromString(message)
+    return feature
+
+extra_media_type_deserializers = {
+    'application/protobuf': protobuf_deserializer,
+}
+
+config = Config(
+    extra_media_type_deserializers=extra_media_type_deserializers,
+)
+openapi = OpenAPI.from_file_path('openapi.json', config=config)
+
+result = openapi.unmarshal_response(request, response)
+```
+
+## Extra Format Validators
+
+OpenAPI defines a `format` keyword that hints at how a value should be interpreted. For example, a `string` with the format `date` should conform to the RFC 3339 date format.
+
+OpenAPI comes with a set of built-in format validators, but it's also possible to add custom ones.
+
+Here's how you can add support for a `usdate` format that handles dates in the form MM/DD/YYYY:
+
+``` python hl_lines="11"
+import re
+
+def validate_usdate(value):
+    return bool(re.match(r"^\d{1,2}/\d{1,2}/\d{4}$", value))
+
+extra_format_validators = {
+    'usdate': validate_usdate,
+}
+
+config = Config(
+    extra_format_validators=extra_format_validators,
+)
+openapi = OpenAPI.from_file_path('openapi.json', config=config)
+
+openapi.validate_response(request, response)
+```
+
+## Extra Format Unmarshallers
+
+Based on the `format` keyword, openapi-core can also unmarshal values to specific formats.
+
+The library comes with a set of built-in format unmarshallers, but it's also possible to add custom ones.
+
+Here's an example with the `usdate` format that converts a value to a date object:
+
+``` python hl_lines="11"
+from datetime import datetime
+
+def unmarshal_usdate(value):
+    return datetime.strptime(value, "%m/%d/%Y").date()
+
+extra_format_unmarshallers = {
+    'usdate': unmarshal_usdate,
+}
+
+config = Config(
+    extra_format_unmarshallers=extra_format_unmarshallers,
+)
+openapi = OpenAPI.from_file_path('openapi.json', config=config)
+
+result = openapi.unmarshal_response(request, response)
+```
diff --git a/docs/contributing.md b/docs/contributing.md
@@ -5,24 +5,24 @@ hide:
 
 # Contributing
 
-Firstly, thank you all for taking the time to contribute.
+Firstly, thank you for taking the time to contribute.
 
 The following section describes how you can contribute to the openapi-core project on GitHub.
 
 ## Reporting bugs
 
 ### Before you report
 
-- Check whether your issue does not already exist in the [Issue tracker](https://github.com/python-openapi/openapi-core/issues).
-- Make sure it is not a support request or question better suited for [Discussion board](https://github.com/python-openapi/openapi-core/discussions).
+- Check whether your issue already exists in the [Issue tracker](https://github.com/python-openapi/openapi-core/issues).
+- Make sure it is not a support request or question better suited for the [Discussion board](https://github.com/python-openapi/openapi-core/discussions).
 
 ### How to submit a report
 
-- Include clear title.
-- Describe your runtime environment with exact versions you use.
-- Describe the exact steps which reproduce the problem, including minimal code snippets.
-- Describe the behavior you observed after following the steps, pasting console outputs.
-- Describe expected behavior to see and why, including links to documentations.
+- Include a clear title.
+- Describe your runtime environment with the exact versions you use.
+- Describe the exact steps to reproduce the problem, including minimal code snippets.
+- Describe the behavior you observed after following the steps, including console outputs.
+- Describe the expected behavior and why, including links to documentation.
 
 ## Code contribution
 
@@ -50,9 +50,9 @@ poetry shell
 
 ### Static checks
 
-The project uses static checks using fantastic [pre-commit](https://pre-commit.com/). Every change is checked on CI and if it does not pass the tests it cannot be accepted. If you want to check locally then run following command to install pre-commit.
+The project uses static checks with the fantastic [pre-commit](https://pre-commit.com/). Every change is checked on CI, and if it does not pass the tests, it cannot be accepted. If you want to check locally, run the following command to install pre-commit.
 
-To turn on pre-commit checks for commit operations in git, enter:
+To enable pre-commit checks for commit operations in git, enter:
 
 ```console
 pre-commit install
@@ -70,4 +70,4 @@ To run all checks on all files, enter:
 pre-commit run --all-files
 ```
 
-Pre-commit check results are also attached to your PR through integration with Github Action.
+Pre-commit check results are also attached to your PR through integration with GitHub Actions.
diff --git a/docs/customizations/extra_format_unmarshallers.md b/docs/customizations/extra_format_unmarshallers.md
diff --git a/docs/customizations/extra_format_validators.md b/docs/customizations/extra_format_validators.md