Reference docs

Author: p1c2u

.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/

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.

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.

docs/customizations/extra_format_unmarshallers.md

@@ -1,17 +1,17 @@
 # Format unmarshallers
 
-Based on `format` keyword, openapi-core can also unmarshal values to specific formats.
+Based on the `format` keyword, openapi-core can also unmarshal values to specific formats.
 
-Openapi-core comes with a set of built-in format unmarshallers, but it's also possible to add custom ones.
+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 date object:
+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
+     return datetime.strptime(value, "%m/%d/%y").date()
 
   extra_format_unmarshallers = {
      'usdate': unmarshal_usdate,

docs/customizations/extra_format_validators.md

@@ -1,10 +1,10 @@
 # Format validators
 
-OpenAPI defines a `format` keyword that hints at how a value should be interpreted, e.g. a `string` with the type `date` should conform to the RFC 3339 date format.
+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 could add support for a `usdate` format that handles dates of the form MM/DD/YYYY:
+Here's how you can add support for a `usdate` format that handles dates in the form MM/DD/YYYY:
 
 ``` python hl_lines="11"
 

docs/customizations/extra_media_type_deserializers.md

@@ -1,10 +1,10 @@
-# Media type deserializers
+# Media Type Deserializers
 
-OpenAPI comes with a set of built-in media type deserializers such as: `application/json`, `application/xml`, `application/x-www-form-urlencoded` or `multipart/form-data`.
+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 ones. Pass custom defined media type deserializers dictionary with supported mimetypes as a key to `unmarshal_response` function:
+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"
+```python hl_lines="11"
 def protobuf_deserializer(message):
     feature = route_guide_pb2.Feature()
     feature.ParseFromString(message)

docs/customizations/index.md

@@ -1,3 +1,3 @@
 # Customizations
 
-OpenAPI accepts `Config` object that allows users to customize the behavior validation and unmarshalling processes.
+OpenAPI accepts a `Config` object that allows users to customize the behavior of validation and unmarshalling processes.

docs/customizations/request_unmarshaller_cls.md

@@ -1,8 +1,8 @@
-# Request unmarshaller
+# Request Unmarshaller
 
-By default, request unmarshaller is selected based on detected specification version.
+By default, the request unmarshaller is selected based on the detected specification version.
 
-In order to explicitly validate and unmarshal a:
+To explicitly validate and unmarshal a request for:
 
 - OpenAPI 3.0 spec, import `V30RequestUnmarshaller`
 - OpenAPI 3.1 spec, import `V31RequestUnmarshaller` or `V31WebhookRequestUnmarshaller`
@@ -17,4 +17,4 @@ 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.
+You can also explicitly import `V3RequestUnmarshaller`, which is a shortcut to the latest OpenAPI v3 version.

docs/customizations/request_validator_cls.md

@@ -1,8 +1,8 @@
-# Request validator
+# Request Validator
 
-By default, request validator is selected based on detected specification version.
+By default, the request validator is selected based on the detected specification version.
 
-In order to explicitly validate a:
+To explicitly validate a:
 
 - OpenAPI 3.0 spec, import `V30RequestValidator`
 - OpenAPI 3.1 spec, import `V31RequestValidator` or `V31WebhookRequestValidator`
@@ -17,4 +17,4 @@ 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.
+You can also explicitly import `V3RequestValidator`, which is a shortcut to the latest OpenAPI v3 version.

docs/customizations/response_unmarshaller_cls.md

@@ -1,9 +1,9 @@
-# Response unmarshaller
+# Response Unmarshaller
 
-In order to explicitly validate and unmarshal a:
+To explicitly validate and unmarshal a response:
 
-- OpenAPI 3.0 spec, import `V30ResponseUnmarshaller`
-- OpenAPI 3.1 spec, import `V31ResponseUnmarshaller` or `V31WebhookResponseUnmarshaller`
+- 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
@@ -15,4 +15,4 @@ 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.
+You can also explicitly import `V3ResponseUnmarshaller`, which is a shortcut to the latest OpenAPI v3 version.