Merge pull request #35 from starlite-api/doc-update

Doc update

Author: Goldziher

CHANGELOG.md

@@ -40,7 +40,14 @@
 
 [0.3.0]
 - updated openapi configuration:
-1. OpenAPI schema generation is now enabled by default
-2. The `OpenAPIController` is now part of the `OpenAPIConfig`
-3. The default schema download path changed from `/schema` to `/schema/openapi.json`
-4. Added a `/schema/openapi.yaml` route to the `OpenAPIController`
+  1. OpenAPI schema generation is now enabled by default
+  2. The `OpenAPIController` is now part of the `OpenAPIConfig`
+  3. The default schema download path changed from `/schema` to `/schema/openapi.json`
+  4. Added a `/schema/openapi.yaml` route to the `OpenAPIController`
+
+
+[0.4.0]
+- fix orjson compatibility @vincentsarago
+- added plugin support
+- added `SQLAlchemyPlugin`
+- added `DTOFactory`

docs/usage/0-the-starlite-app.md

@@ -39,7 +39,7 @@ You can additionally pass the following kwargs to the Starlite constructor:
 - `on_shutdown`: A list of callables that are called during the application shutdown. See [life-cycle](#lifecycle).
 - `on_startup`: A list of callables that are called during the application startup. See [life-cycle](#lifecycle).
 - `openapi_config`: An instance of `starlite.config.OpenAPIConfig`. Defaults to the baseline config.
-  See [open-api](10-openapi.md).
+  See [open-api](12-openapi.md).
 - `redirect_slashes`: A boolean flag dictating whether to redirect urls ending with a trailing slash to urls without a
   trailing slash if no match is found. Defaults to `True`.
 - `response_class`: A custom response class to be used as the app default.

docs/usage/10-plugins.md

@@ -0,0 +1,106 @@
+# Plugins
+
+You can extend Starlite to support non-pydantic / dataclass types using plugins.
+
+Using plugins, you can have Starlite parse and validate inbound values (e.g. request-body data or parameters) as if they
+were pydantic models, and then serialize the data into the desired model type, or list thereof. Plugins also allow you
+to return an instance or list of instances of a model, and have it serialized correctly.
+
+## Builtin Plugins
+
+Currently, Starlite includes a single plugin `starlite.plugins.sql_alchemy.SQLAlchemyPlugin`, with other plugins being
+planned / discussed - see the pinned issues in github for the current state of these.
+
+### SQLAlchemyPlugin
+
+To use the `SQLAlchemyPlugin` simply import it and pass it to the `Starlite` constructor:
+
+```python title="my_app/main.py"
+from starlite import Starlite, SQLAlchemyPlugin
+
+app = Starlite(route_handlers=[...], plugins=[SQLAlchemyPlugin()])
+```
+
+!!! note
+    The `SQLAlchemyPlugin` *will not* create a DB connection, a sessionmaker or anything of this kind. This
+    you will need to implement on your own according to the pattern of your choice, or using a 3rd party solution of some
+    sort. The reason for this is that SQL Alchemy is very flexible and allows you to interact with it in various ways.
+    We cannot decide upon the pattern that will fit your architecture in advance, and hence it is left to the user to decide.
+
+You can now use SQL alchemy declarative classes as route handler parameters or return values:
+
+```python title="my_app/company/models/company.py"
+from sqlalchemy import Column, Float, Integer, String
+from sqlalchemy.orm import declarative_base
+
+Base = declarative_base()
+
+class Company(Base):
+    id = Column(Integer, primary_key=True)
+    name = Column(String)
+    worth = Column(Float)
+```
+
+```python title="my_app/company/endpoints.py"
+from starlite import post, get
+
+from my_app.company.models import Company
+
+@post(path="/companies")
+def create_company(data: Company) -> Company:
+    ...
+
+
+@get(path="/companies")
+def get_companies() -> List[Company]:
+    ...
+```
+
+!!! important
+    The `SQLAlchemyPlugin` supports only `declarative` style classes, it does not support the older `imperative` style
+    because this style does not use classes, and is very hard to convert to pydantic correctly.
+
+
+## Creating Plugins
+
+A plugin is a class the implements the `starlite.plugins.base.PluginProtocol` class, which expects a generic `T`
+representing the model type to be used.
+
+To create a plugin you must implement the following methods:
+
+```python
+def to_pydantic_model_class(
+    self, model_class: Type[T], **kwargs: Any
+) -> Type[BaseModel]:
+    """
+    Given a model_class T, convert it to a subclass of the pydantic BaseModel
+    """
+    ...
+
+
+@staticmethod
+def is_plugin_supported_type(value: Any) -> bool:
+    """
+    Given a value of indeterminate type, determine if this value is supported by the plugin by returning a bool.
+    """
+    ...
+
+
+def from_pydantic_model_instance(
+    self, model_class: Type[T], pydantic_model_instance: BaseModel
+) -> T:
+    """
+    Given an instance of a pydantic model created using a plugin's 'to_pydantic_model_class',
+    return an instance of the class from which that pydantic model has been created.
+
+    This class is passed in as the 'model_class' kwarg.
+    """
+    ...
+
+
+def to_dict(self, model_instance: T) -> Dict[str, Any]:
+    """
+    Given an instance of a model supported by the plugin, return a dictionary of serilizable values.
+    """
+    ...
+```

docs/usage/11-data-transfer-objects.md

@@ -0,0 +1,90 @@
+# Data Transfer Objects (DTOs)
+
+Starlite includes a `DTOFactory` class that allows you to create DTOs from pydantic models, dataclasses and any other
+class supported via plugins.
+
+An instance of the factory must first be created, optionally passing plugins to it as a kwarg. It can then be used to
+create a DTO by calling the instance like a function. Additionally, it can exclude (drop) attributes specifies in the '
+exclude' list and remap field names and/or field types.
+
+The created DTO can be used for data parsing, validation and OpenAPI schema generation like a regularly declared
+pydantic model.
+
+!!! important
+    Although the value generated is a pydantic factory, because it is being generated programmatically, it's
+    currently impossible to extend editor auto-complete for the DTO properties - it will be typed as `Any`.
+
+For example, given a pydantic model
+
+```python
+from pydantic import BaseModel
+from starlite import DTOFactory
+
+
+class MyClass(BaseModel):
+    first: int
+    second: int
+
+
+MyClassDTOFactory = DTOFactory()
+
+MyClassDTO = MyClassDTOFactory(
+    "MyClassDTO", MyClass, exclude=["first"], field_mapping={"second": ("third", float)}
+)
+```
+
+`MyClassDTO` is now equal to this:
+
+```python
+from pydantic import BaseModel
+
+
+class MyClassDTO(BaseModel):
+    third: float
+```
+
+It can be used as a regular pydantic model, e.g.:
+
+```python
+from pydantic import BaseModel
+from starlite import DTOFactory, post
+
+
+class MyClass(BaseModel):
+    first: int
+    second: int
+
+
+MyClassDTOFactory = DTOFactory()
+
+MyClassDTO = MyClassDTOFactory(
+    "MyClassDTO", MyClass, exclude=["first"], field_mapping={"second": ("third", float)}
+)
+
+
+@post(path="/my-path")
+def create_obj(data: MyClassDTO) -> MyClass:
+    ...
+```
+
+The `DTOFactory` class can also be instantiated with [plugins](10-plugins.md), for example - here is a factory that
+support SQL Alchemy declarative classes:
+
+```python
+from sqlalchemy import Column, Float, Integer, String
+from sqlalchemy.orm import declarative_base
+from starlite import DTOFactory, SQLAlchemyPlugin
+
+SQLAlchemyDTOFactory = DTOFactory(plugins=[SQLAlchemyPlugin()])
+
+Base = declarative_base()
+
+
+class Company(Base):
+    id = Column(Integer, primary_key=True)
+    name = Column(String)
+    worth = Column(Float)
+
+
+CompanyDTO = SQLAlchemyDTOFactory("CompanyDTO", Company, exclude=["id"])
+```

docs/usage/10-openapi.md docs/usage/12-openapi.mddocs/usage/10-openapi.md renamed to docs/usage/12-openapi.md

@@ -2,6 +2,10 @@
 
 Testing is a first class citizen in Starlite, which offers several powerful testing utilities out of the box.
 
+!!! tip
+    Starlite bundles the library [pydantic-factories](https://github.com/Goldziher/pydantic-factories), which offers an
+    easy and powerful way to generate mock data from pydantic models and dataclasses.
+
 ## Test Client
 
 Starlite extends the Starlette testing client, which in turn is built using

docs/usage/11-testing.md docs/usage/13-testing.mddocs/usage/11-testing.md renamed to docs/usage/13-testing.md

@@ -54,7 +54,7 @@ Additionally, you can pass the following optional kwargs:
 - `dependencies`: A dictionary mapping dependency providers. See [dependency-injection](6-dependency-injection.md).
 - `opt`: String keyed dictionary of arbitrary value that can be used by [guards](9-guards.md).
 
-And the following kwargs, which affect [OpenAPI schema generation](10-openapi.md#route-handler-configuration)
+And the following kwargs, which affect [OpenAPI schema generation](12-openapi.md#route-handler-configuration)
 
 - `include_in_schema`: A boolean flag dictating whether the given route handler will appear in the generated OpenAPI
   schema. Defaults to `True`.

docs/usage/2-route-handlers.md

@@ -42,8 +42,10 @@ nav:
       - usage/7-middleware.md
       - usage/8-authentication.md
       - usage/9-guards.md
-      - usage/10-openapi.md
-      - usage/11-testing.md
+      - usage/10-plugins.md
+      - usage/11-data-transfer-objects.md
+      - usage/12-openapi.md
+      - usage/13-testing.md
   - migration.md
   - contributing.md
   - license.md

mkdocs.yml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "starlite"
-version = "0.3.0"
+version = "0.4.0"
 description = "Light-weight and flexible ASGI API Framework"
 authors = ["Na'aman Hirschfeld <nhirschfeld@gmail.com>"]
 maintainers = ["Na'aman Hirschfeld <nhirschfeld@gmail.com>"]

pyproject.toml

@@ -10,7 +10,7 @@
 class PluginProtocol(Protocol[T]):  # pragma: no cover
     def to_pydantic_model_class(self, model_class: Type[T], **kwargs: Any) -> Type[BaseModel]:  # pragma: no cover
         """
-        Given a model_class T, convert it to a pydantic model class
+        Given a model_class T, convert it to a subclass of the pydantic BaseModel
         """
         ...
 
@@ -23,13 +23,16 @@ def is_plugin_supported_type(value: Any) -> bool:
 
     def from_pydantic_model_instance(self, model_class: Type[T], pydantic_model_instance: BaseModel) -> T:
         """
-        Given a dict of parsed values, create an instance of the plugin's model class
+        Given an instance of a pydantic model created using a plugin's 'to_pydantic_model_class',
+        return an instance of the class from which that pydantic model has been created.
+
+        This class is passed in as the 'model_class' kwarg.
         """
         ...
 
     def to_dict(self, model_instance: T) -> Dict[str, Any]:
         """
-        Given an instance of the model, return a dictionary of values that can be serialized
+        Given an instance of a model supported by the plugin, return a dictionary of serilizable values.
         """
         ...