{"id":13424711,"url":"https://github.com/identixone/fastapi_contrib","last_synced_at":"2025-05-15T10:05:27.701Z","repository":{"id":35112915,"uuid":"203662623","full_name":"identixone/fastapi_contrib","owner":"identixone","description":"Opinionated set of utilities on top of FastAPI","archived":false,"fork":false,"pushed_at":"2022-09-12T13:55:21.000Z","size":220,"stargazers_count":636,"open_issues_count":15,"forks_count":29,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-05-15T10:04:12.650Z","etag":null,"topics":["fastapi","fastapi-template","mongodb","pydantic","python","starlette","ujson"],"latest_commit_sha":null,"homepage":"https://fastapi-contrib.readthedocs.io","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/identixone.png","metadata":{"files":{"readme":"README.rst","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.rst","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-08-21T20:51:35.000Z","updated_at":"2025-05-05T20:37:01.000Z","dependencies_parsed_at":"2022-07-08T13:30:50.772Z","dependency_job_id":null,"html_url":"https://github.com/identixone/fastapi_contrib","commit_stats":null,"previous_names":[],"tags_count":34,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/identixone%2Ffastapi_contrib","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/identixone%2Ffastapi_contrib/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/identixone%2Ffastapi_contrib/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/identixone%2Ffastapi_contrib/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/identixone","download_url":"https://codeload.github.com/identixone/fastapi_contrib/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254319718,"owners_count":22051072,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["fastapi","fastapi-template","mongodb","pydantic","python","starlette","ujson"],"created_at":"2024-07-31T00:00:58.188Z","updated_at":"2025-05-15T10:05:27.582Z","avatar_url":"https://github.com/identixone.png","language":"Python","readme":"===============\nFastAPI Contrib\n===============\n\n\n.. image:: https://img.shields.io/pypi/v/fastapi_contrib.svg\n        :target: https://pypi.python.org/pypi/fastapi_contrib\n\n.. image:: https://img.shields.io/travis/identixone/fastapi_contrib.svg\n        :target: https://travis-ci.org/identixone/fastapi_contrib\n\n.. image:: https://readthedocs.org/projects/fastapi-contrib/badge/?version=latest\n        :target: https://fastapi-contrib.readthedocs.io/en/latest/?badge=latest\n        :alt: Documentation Status\n\n\n.. image:: https://pyup.io/repos/github/identixone/fastapi_contrib/shield.svg\n     :target: https://pyup.io/repos/github/identixone/fastapi_contrib/\n     :alt: Updates\n\n\n\nOpinionated set of utilities on top of FastAPI\n\n\n* Free software: MIT license\n* Documentation: https://fastapi-contrib.readthedocs.io.\n\n\nFeatures\n--------\n\n* Auth Backend \u0026 Middleware (User or None in every request object)\n* Permissions: reusable class permissions, specify multiple as FastAPI Dependency\n* ModelSerializers: serialize (pydantic) incoming request, connect data with DB model and save\n* UJSONResponse: correctly show slashes in fields with URLs\n* Limit-Offset Pagination: use it as FastAPI Dependency (works only with ModelSerializers for now)\n* MongoDB integration: Use models as if it was Django (based on pydantic models)\n* MongoDB indices verification on startup of the app\n* Custom Exceptions and Custom Exception Handlers\n* Opentracing middleware \u0026 setup utility with Jaeger tracer + root span available in every Request's state\n* StateRequestIDMiddleware: receives configurable header and saves it in request state\n\nRoadmap\n--------\n\nSee GitHub Project `Roadmap \u003chttps://github.com/identixone/fastapi_contrib/projects/2\u003e`_.\n\nInstallation\n------------\n\nTo install just Contrib (without mongodb, pytz, ujson):\n\n.. code-block:: console\n\n    $ pip install fastapi_contrib\n\nTo install contrib with mongodb support:\n\n.. code-block:: console\n\n    $ pip install fastapi_contrib[mongo]\n\nTo install contrib with ujson support:\n\n.. code-block:: console\n\n    $ pip install fastapi_contrib[ujson]\n\nTo install contrib with pytz support:\n\n.. code-block:: console\n\n    $ pip install fastapi_contrib[pytz]\n\nTo install contrib with opentracing \u0026 Jaeger tracer:\n\n.. code-block:: console\n\n    $ pip install fastapi_contrib[jaegertracing]\n\nTo install everything:\n\n.. code-block:: console\n\n    $ pip install fastapi_contrib[all]\n\nUsage\n-----\n\nTo use Limit-Offset pagination:\n\n.. code-block:: python\n\n    from fastapi import FastAPI\n    from fastapi_contrib.pagination import Pagination\n    from fastapi_contrib.serializers.common import ModelSerializer\n    from yourapp.models import SomeModel\n\n    app = FastAPI()\n\n    class SomeSerializer(ModelSerializer):\n        class Meta:\n            model = SomeModel\n\n    @app.get(\"/\")\n    async def list(pagination: Pagination = Depends()):\n        filter_kwargs = {}\n        return await pagination.paginate(\n            serializer_class=SomeSerializer, **filter_kwargs\n        )\n\nSubclass this pagination to define custom default \u0026 maximum values for offset \u0026 limit:\n\n.. code-block:: python\n\n    class CustomPagination(Pagination):\n        default_offset = 90\n        default_limit = 1\n        max_offset = 100\n        max_limit = 2000\n\n\nTo use State Request ID Middleware:\n\n.. code-block:: python\n\n    from fastapi import FastAPI\n    from fastapi_contrib.common.middlewares import StateRequestIDMiddleware\n\n    app = FastAPI()\n\n    @app.on_event('startup')\n    async def startup():\n        app.add_middleware(StateRequestIDMiddleware)\n\n\nTo use Authentication Middleware:\n\n.. code-block:: python\n\n    from fastapi import FastAPI\n    from fastapi_contrib.auth.backends import AuthBackend\n    from fastapi_contrib.auth.middlewares import AuthenticationMiddleware\n\n    app = FastAPI()\n\n    @app.on_event('startup')\n    async def startup():\n        app.add_middleware(AuthenticationMiddleware, backend=AuthBackend())\n\n\nDefine \u0026 use custom permissions based on FastAPI Dependency framework:\n\n.. code-block:: python\n\n    from fastapi import FastAPI\n    from fastapi_contrib.permissions import BasePermission, PermissionsDependency\n\n    class TeapotUserAgentPermission(BasePermission):\n\n        def has_required_permissions(self, request: Request) -\u003e bool:\n            return request.headers.get('User-Agent') == \"Teapot v1.0\"\n\n    app = FastAPI()\n\n    @app.get(\n        \"/teapot/\",\n        dependencies=[Depends(\n            PermissionsDependency([TeapotUserAgentPermission]))]\n    )\n    async def teapot() -\u003e dict:\n        return {\"teapot\": True}\n\n\nSetup uniform exception-handling:\n\n.. code-block:: python\n\n    from fastapi import FastAPI\n    from fastapi_contrib.exception_handlers import setup_exception_handlers\n\n    app = FastAPI()\n\n    @app.on_event('startup')\n    async def startup():\n        setup_exception_handlers(app)\n\n\nIf you want to correctly handle scenario when request is an empty body (IMPORTANT: non-multipart):\n\n.. code-block:: python\n\n    from fastapi import FastAPI\n    from fastapi_contrib.routes import ValidationErrorLoggingRoute\n\n    app = FastAPI()\n    app.router.route_class = ValidationErrorLoggingRoute\n\n\nOr if you use multiple routes for handling different namespaces (IMPORTANT: non-multipart):\n\n.. code-block:: python\n\n    from fastapi import APIRouter, FastAPI\n    from fastapi_contrib.routes import ValidationErrorLoggingRoute\n\n    app = FastAPI()\n\n    my_router = APIRouter(route_class=ValidationErrorLoggingRoute)\n\n\nTo correctly show slashes in fields with URLs + ascii locking:\n\n.. code-block:: python\n\n    from fastapi import FastAPI\n    from fastapi_contrib.common.responses import UJSONResponse\n\n    app = FastAPI()\n\n    @app.get(\"/\", response_class=UJSONResponse)\n    async def root():\n        return {\"a\": \"b\"}\n\n\nOr specify it as default response class for the whole app (FastAPI \u003e= 0.39.0):\n\n.. code-block:: python\n\n    from fastapi import FastAPI\n    from fastapi_contrib.common.responses import UJSONResponse\n\n    app = FastAPI(default_response_class=UJSONResponse)\n\n\nTo setup Jaeger tracer and enable Middleware that captures every request in opentracing span:\n\n.. code-block:: python\n\n    from fastapi import FastAPI\n    from fastapi_contrib.tracing.middlewares import OpentracingMiddleware\n    from fastapi_contrib.tracing.utils import setup_opentracing\n\n    app = FastAPI()\n\n    @app.on_event('startup')\n    async def startup():\n        setup_opentracing(app)\n        app.add_middleware(OpentracingMiddleware)\n\n\n\nTo setup mongodb connection at startup and never worry about it again:\n\n.. code-block:: python\n\n    from fastapi import FastAPI\n    from fastapi_contrib.db.utils import setup_mongodb\n\n    app = FastAPI()\n\n    @app.on_event('startup')\n    async def startup():\n        setup_mongodb(app)\n\n\nUse models to map data to MongoDB:\n\n.. code-block:: python\n\n    from fastapi_contrib.db.models import MongoDBModel\n\n    class MyModel(MongoDBModel):\n        additional_field1: str\n        optional_field2: int = 42\n\n        class Meta:\n            collection = \"mymodel_collection\"\n\n\n    mymodel = MyModel(additional_field1=\"value\")\n    mymodel.save()\n\n    assert mymodel.additional_field1 == \"value\"\n    assert mymodel.optional_field2 == 42\n    assert isinstance(mymodel.id, int)\n\n\nOr use TimeStamped model with creation datetime:\n\n.. code-block:: python\n\n    from fastapi_contrib.db.models import MongoDBTimeStampedModel\n\n    class MyTimeStampedModel(MongoDBTimeStampedModel):\n\n        class Meta:\n            collection = \"timestamped_collection\"\n\n\n    mymodel = MyTimeStampedModel()\n    mymodel.save()\n\n    assert isinstance(mymodel.id, int)\n    assert isinstance(mymodel.created, datetime)\n\n\nUse serializers and their response models to correctly show Schemas and convert from JSON/dict to models and back:\n\n.. code-block:: python\n\n    from fastapi import FastAPI\n    from fastapi_contrib.db.models import MongoDBModel\n    from fastapi_contrib.serializers import openapi\n    from fastapi_contrib.serializers.common import Serializer\n\n    from yourapp.models import SomeModel\n\n    app = FastAPI()\n\n\n    class SomeModel(MongoDBModel):\n        field1: str\n\n\n    @openapi.patch\n    class SomeSerializer(Serializer):\n        read_only1: str = \"const\"\n        write_only2: int\n        not_visible: str = \"42\"\n\n        class Meta:\n            model = SomeModel\n            exclude = {\"not_visible\"}\n            write_only_fields = {\"write_only2\"}\n            read_only_fields = {\"read_only1\"}\n\n\n    @app.get(\"/\", response_model=SomeSerializer.response_model)\n    async def root(serializer: SomeSerializer):\n        model_instance = await serializer.save()\n        return model_instance.dict()\n\n\nPOST-ing to this route following JSON:\n\n.. code-block:: json\n\n    {\"read_only1\": \"a\", \"write_only2\": 123, \"field1\": \"b\"}\n\n\nShould return following response:\n\n.. code-block:: json\n\n    {\"id\": 1, \"field1\": \"b\", \"read_only1\": \"const\"}\n\n\nAuto-creation of MongoDB indexes\n----------------------------------------------------------------\n\nSuppose we have this directory structure:\n\n.. code-block:: console\n\n    -- project_root/\n         -- apps/\n              -- app1/\n                   -- models.py (with MongoDBModel inside with indices declared)\n              -- app2/\n                   -- models.py (with MongoDBModel inside with indices declared)\n\nBased on this, your name of the folder with all the apps would be \"apps\". This is the default name for fastapi_contrib package to pick up your structure automatically. You can change that by setting ENV variable `CONTRIB_APPS_FOLDER_NAME` (by the way, all the setting of this package are overridable via ENV vars with `CONTRIB_` prefix before them).\n\nYou also need to tell fastapi_contrib which apps to look into for your models. This is controlled by `CONTRIB_APPS` ENV variable, which is list of str names of the apps with models. In the example above, this would be `CONTRIB_APPS=[\"app1\",\"app2\"]`.\n\nJust use create_indexes function after setting up mongodb:\n\n.. code-block:: python\n\n    from fastapi import FastAPI\n    from fastapi_contrib.db.utils import setup_mongodb, create_indexes\n\n    app = FastAPI()\n\n    @app.on_event(\"startup\")\n    async def startup():\n        setup_mongodb(app)\n        await create_indexes()\n\n\nThis will scan all the specified `CONTRIB_APPS` in the `CONTRIB_APPS_FOLDER_NAME` for models, that are subclassed from either MongoDBModel or MongoDBTimeStampedModel and create indices for any of them that has Meta class with indexes attribute:\n\nmodels.py:\n\n.. code-block:: python\n\n    import pymongo\n    from fastapi_contrib.db.models import MongoDBTimeStampedModel\n\n\n    class MyModel(MongoDBTimeStampedModel):\n\n        class Meta:\n            collection = \"mymodel\"\n            indexes = [\n                pymongo.IndexModel(...),\n                pymongo.IndexModel(...),\n            ]\n\n\nThis would not create duplicate indices because it relies on pymongo and motor to do all the job.\n\n\nCredits\n-------\n\nThis package was created with Cookiecutter_ and the `audreyr/cookiecutter-pypackage`_ project template.\n\n.. _Cookiecutter: https://github.com/audreyr/cookiecutter\n.. _`audreyr/cookiecutter-pypackage`: https://github.com/audreyr/cookiecutter-pypackage\n","funding_links":[],"categories":["Third-Party Extensions","Python","Packages"],"sub_categories":["Utils"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fidentixone%2Ffastapi_contrib","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fidentixone%2Ffastapi_contrib","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fidentixone%2Ffastapi_contrib/lists"}