Package: microcosm-fastapi
microcosm-fastapiA bridge between FastAPI and microcosm. Provide state-of-the-art speed of hosting microservices in Python along with dependency injection.Top FeaturesAsync compliant protocol to add new microservice functionsSpecify API requests and responses with business-logic typehinting, while following strongly conventioned CRUD operations to access the databaseAsync postgres support using the latest SQLAlchemy 1.4 (still in beta), to support more concurrent client users with fewer CPU blocking requestsAutomatic generation of interactive documentation, available on localhost:5000/docs when doing development workNo telemetry: locally hosted documentation and other fastapi dependenciesMigration from microcosm-flaskIf you're using microcosm already, there's a high chance you're usingmicrocosm-flaskas your communication layer. This library attempts to give a relatively straightforward migration path from microcosm-flask by using the same abstraction and function names where possible. In order to truly leverage the best design decisions that went into FastAPI, however, we also need to refactor some of our logic into the new FastAPI paradigm.ResourcesWhen defining resources in flask, you're likely used to defining a schema for everything that you'll ever need to serialize from client users. This includesNewschemas for creating new objects,Standardschemas for retrieving objects from the database, andSearchschemas for extracting the URL parameters that can search against the database layer. These are defined viamarshmallowwhich provides the serialization layer to convert from json->python and python->json. Something like this:from microcosm_flask.paging import PageSchema
from marshmallow import Schema, fields

class NewPizzaSchema(Schema):
    toppings = fields.String(required=True)

class PizzaSchema(NewPizzaSchema):
    id: fields.UUID(required=True)

class PizzaSearchSchema(PageSchema):
    toppings = fields.String(required=False)Instead of marshmallow, FastAPI makes extensive use ofpydanticto provide the validation layers. Pydantic is a more modern library in comparison. It uses python typehints in order to define expected field types and has more built-in functionality when compared to marshmallow. It's straightforward to convert the above definitions into ones that are pydantic compatible. Note that we remove thePizzaSearchSchemaentirely because this definition will be specified in another file.from microcosm_fastapi.conventions.schemas import BaseSchema
from uuid import UUID

class NewPizza(BaseSchema):
    toppings: str

class Pizza(NewPizza)
    id: UUIDJust like typehinting in standard python functions, arguments are required unless you specify anOptionalflag alongside their type. This will enforce that client callers providetoppingswhen creating a newPizza.RoutesIn microcosm-flask, your routes are usually split between two files. You'll havepizza/crud.pyandpizza/controller.py. The crud file specifies the supported operations and resources for the given namespace. The controller will implement any relevant business logic to transform the input client request before passing it to the backing store. Something like:@binding("pizza_v1_routes")
def configure_pizza_routes(graph):
    controller = graph.credential_pack_controller

    mappings = {
        Operation.Create: EndpointDefinition(
            func=transactional(controller.create),
            request_schema=NewPizzaSchema(),
            response_schema=PizzaSchema(),
        ),
        Operation.Retrieve: EndpointDefinition(
            func=controller.retrieve, 
            response_schema=PizzaSchema(),
        ),
        Operation.Search: EndpointDefinition(
            func=controller.search,
            request_schema=SearchPizzaSchema(),
            response_schema=PizzaSchema(),
        ),
    }
    configure_crud(graph, controller.ns, mappings)

    return controller.ns@binding("pizza_controller")
class PizzaController(CRUDStoreAdapter):
    def __init__(self, graph):
        super().__init__(graph, graph.pizza_store)
        self.ns = Namespace(subject=Pizza, version="v1")One drawback with this approach is that a lot of the logic is abstracted away into theCRUDStoreAdapterandconfigure_crudcode. It's not immediately transparent to new team members what the API functions will actually look like when they're created.The goal in our new routing convention is to have one file the provides the full source of truth. This route will contain an explicit definition of all APIs that are available for the given database object. The typehinting of both the function and the response signatures are parsed bymicrocosm-fastapifor you - requests are validated against the function types and responses are serialized to fit within the return type annotation.from microcosm_fastapi.conventions.crud import configure_crud
from microcosm_fastapi.conventions.crud_adapter import CRUDStoreAdapter
from microcosm_fastapi.conventions.schemas import SearchSchema

@binding("pizza_route")
class PizzaController(CRUDStoreAdapter):
    def __init__(self, graph):
        super().__init__(graph, graph.pizza_store)

        ns = Namespace(
            subject=Pizza,
            version="v1",
        )

        mappings = {
            Operation.Create: self.create,
            Operation.Retrieve: self.retrieve,
            Operation.Search: self.search,
        }
        configure_crud(graph, ns, mappings)

    async def create(self, pizza: NewPizzaSchema) -> PizzaSchema:
        return await super()._create(pizza)

    async def retrieve(self, pizza_id: UUID) -> PizzaSchema:
        return await super()._retrieve(pizza_id)

    async def search(self, limit: int = 20, offset: int = 0) -> SearchSchema(PizzaSchema):
        return await super()._search(limit=limit, offset=offset)By convention, edge operations (ie. retrieve / patch / etc) will be passed the object UUID of interest automatically by microcosm-fastapi. This keyword argument is expected to be in the format of{snake_case(namespace object)}_id. Seeretrievefor an example here. Clients are still expected to typehint this accordingly as a UUID.StoresWe bundle an async-compatible postgres client alongsidemicrocosm-fastapi. To see the maximum performance boosts, you'll need to upgrade your Store instances as well to be async compliant.Any custom implemented functions must beawaitwhen calling the superclass.from microcosm_fastapi.database.store import StoreAsync

@binding("pizza_store")
class PizzaStore(StoreAsync):
    def __init__(self, graph):
        super().__init__(graph, Pizza)

    async def create(self, pizza):
        pizza.delivery_date = datetime.now()
        return await super().create(pizza)Include the following dependencies in your graph:app.use(
    "postgres",
    "session_maker_async",
    "postgres_async",
)Other Application ChangesCreate two new fileswsgiandwsgi_debugto host the production and development graphs separately:from annotation_jobs.app import create_app
graph = create_app()
app = graph.appfrom annotation_jobs.app import create_app
graph = create_app(debug=True)
app = graph.appUpdate yourmain.pyto host:from microcosm_fastapi.runserver import main as runserver_main

def runserver():
    # This graph is just used for config parameters
    graph = create_app(debug=True, model_only=True)

    runserver_main("{application_bundle}.wsgi_debug:app", graph)Misc LookupQueryStringList -> microcosm_fastapi.conventions.parsers.SeparatedListTest ProjectWe have set up a test project to demonstrate how the new API would look like when deployed within a service. To get started create a new DB:createuser test_project
createdb -O test_project test_project_db
createdb -O test_project test_project_test_dbRunning Testspip install pytest pytest-cov pytest-asyncio

cd test-project
pytest test_projectBumping VersionsWhen you're ready to merge your PR, you'll need to bump the version of package.
There are two files that you need to update with the new version you're bumping to:setup.py
.bumpversion.cfgAs soon as you've bumped your version and pushed your changes, then merge your PR.Once the PR has been merged, checkout the latest from master then tag and push:gitcheckoutmaster
gitpull
gittagX.X.Xgitpush--tags