Restructure documentation

docs/handler.rst

@@ -1,5 +1,5 @@
-Handling Incoming Requests
-==========================
+Handler
+=======
 
 .. automodule:: tornado_openapi3.handler
    :members:

docs/handling_incoming_requests.rst

@@ -0,0 +1,44 @@
+Handling Incoming Requests
+==========================
+
+Adding custom deserializers
+---------------------------
+
+.. code-block:: python
+
+   import json
+
+   from tornado_openapi3.handler import OpenAPIRequestHandler
+
+
+   class ResourceHandler(OpenAPIRequestHandler):
+       custom_media_type_deserializers = {
+           "application/vnd.example.resource+json": json.loads,
+       }
+
+       ...
+
+Adding custom formatters
+------------------------
+
+.. code-block:: python
+
+   import datetime
+
+   from tornado_openapi3.handler import OpenAPIRequestHandler
+
+
+   class USDateFormatter:
+       def validate(self, value: str) -> bool:
+           return bool(re.match(r"^\d{1,2}/\d{1,2}/\d{4}$", value))
+
+       def unmarshal(self, value: str) -> datetime.date:
+           return datetime.datetime.strptime(value, "%m/%d/%Y").date()
+
+
+   class ResourceHandler(OpenAPIRequestHandler):
+       custom_formatters = {
+           "usdate": USDateFormatter(),
+       }
+
+       ...

docs/index.rst

@@ -30,14 +30,18 @@ specification.
    :maxdepth: 2
    :caption: Usage
 
-   handler
-   testing
+   handling_incoming_requests
+   testing_api_responses
 
 .. toctree::
    :maxdepth: 2
-   :caption: Validators
+   :caption: Modules
 
-   validators
+   handler
+   testing
+   requests
+   responses
+   types
 
 
 Indices and tables

docs/requests.rst

@@ -0,0 +1,5 @@
+Requests
+==========
+
+.. automodule:: tornado_openapi3.requests
+   :members:

docs/responses.rst

@@ -1,9 +1,3 @@
-Requests
-==========
-
-.. automodule:: tornado_openapi3.requests
-   :members:
-
 Responses
 =========
 

docs/testing.rst

@@ -1,5 +1,5 @@
-Testing API Responses
-=====================
+Testing
+=======
 
 .. automodule:: tornado_openapi3.testing
    :members:

docs/testing_api_responses.rst

@@ -0,0 +1,44 @@
+Testing API Responses
+=====================
+
+Adding custom deserializers
+---------------------------
+
+.. code-block:: python
+
+   import json
+
+   from tornado_openapi3.testing import AsyncOpenAPITestCase
+
+
+   class TestCase(AsyncOpenAPITestCase):
+       custom_media_type_deserializers = {
+           "application/vnd.example.resource+json": json.loads,
+       }
+
+       ...
+
+Adding custom formatters
+------------------------
+
+.. code-block:: python
+
+   import datetime
+
+   from tornado_openapi3.testing import AsyncOpenAPITestCase
+
+
+   class USDateFormatter:
+       def validate(self, value: str) -> bool:
+           return bool(re.match(r"^\d{1,2}/\d{1,2}/\d{4}$", value))
+
+       def unmarshal(self, value: str) -> datetime.date:
+           return datetime.datetime.strptime(value, "%m/%d/%Y").date()
+
+
+   class TestCase(AsyncOpenAPITestCase):
+       custom_formatters = {
+           "usdate": USDateFormatter(),
+       }
+
+       ...

docs/types.rst

@@ -0,0 +1,5 @@
+Types
+===========
+
+.. automodule:: tornado_openapi3.types
+  :members:

tornado_openapi3/handler.py

@@ -1,6 +1,6 @@
 import asyncio
 import logging
-import typing
+from typing import Mapping
 
 from openapi_core import create_spec  # type: ignore
 from openapi_core.casting.schemas.exceptions import CastError  # type: ignore
@@ -64,24 +64,28 @@ class OpenAPIRequestHandler(tornado.web.RequestHandler):
         return create_spec(self.spec_dict, validate_spec=False)
 
     @property
-    def custom_formatters(self) -> typing.Mapping[str, Formatter]:
+    def custom_formatters(self) -> Mapping[str, Formatter]:
         """A dictionary mapping value formats to formatter objects.
 
-        A formatter object must provide:
-        - validate(self, value) -> bool
-        - unmarshal(self, value) -> Any
+        If your schemas make use of format modifiers, you may specify them in
+        this dictionary paired with a Formatter object that provides methods to
+        validate values and unmarshal them into Python objects.
+
+        :rtype: Mapping[str, :py:class:`tornado_openapi3.types.Formatter`]
+
         """
 
         return dict()
 
     @property
-    def custom_media_type_deserializers(self) -> typing.Mapping[str, Deserializer]:
+    def custom_media_type_deserializers(self) -> Mapping[str, Deserializer]:
         """A dictionary mapping media types to deserializing functions.
 
         If your endpoints make use of content types beyond ``application/json``,
         you must add them to this dictionary with a deserializing method that
         converts the raw body (as ``bytes`` or ``str``) to Python objects.
 
+        :rtype: Mapping[str, :py:attr:`tornado_openapi3.types.Deserializer`]
         """
         return dict()
 

tornado_openapi3/types.py

@@ -1,6 +1,7 @@
 import typing
 import typing_extensions
 
+#: A type representing an OpenAPI deserializer.
 Deserializer = typing.Callable[[typing.Union[bytes, str]], typing.Any]
 
 
@@ -8,7 +9,9 @@ class Formatter(typing_extensions.Protocol):
     """A type representing an OpenAPI formatter."""
 
     def validate(self, value: str) -> bool:  # pragma: no cover
+        """Validate that the value matches the expected format."""
         ...
 
     def unmarshal(self, value: str) -> typing.Any:  # pragma: no cover
+        """Translate the value into a Python object."""
         ...