# Overview
This project contains classes and decorators to use FastAPI with "class based routing". In particular this allows you to
construct an **instance** of a class and have methods of that instance be route handlers. For example:
```py
from dao import Dao
# Some fictional dao
from classy_fastapi import Routable, get, delete
def parse_arg() -> argparse.Namespace:
"""parse command line arguments."""
...
class UserRoutes(Routable):
"""Inherits from Routable."""
# Note injection here by simply passing values to the constructor. Other injection frameworks also
# supported as there's nothing special about this __init__ method.
def __init__(self, dao: Dao) -> None:
"""Constructor. The Dao is injected here."""
super().__init__()
self.__dao = Dao
@get('/user/{name}')
def get_user_by_name(self, name: str) -> User:
# Use our injected DAO instance.
return self.__dao.get_user_by_name(name)
@delete('/user/{name}')
def delete_user(self, name: str) -> None:
self.__dao.delete(name)
def main():
args = parse_args()
# Configure the DAO per command line arguments
dao = Dao(args.url, args.user, args.password)
# Simple intuitive injection
user_routes = UserRoutes(dao)
app = FastAPI()
# router member inherited from cr.Routable and configured per the annotations.
app.include_router(user_routes.router)
```
Note that there are no global variables and dependency injection is accomplished by simply passing arguments to the
constructor.
# Why
FastAPI generally has one define routes like:
```py
app = FastAPI()
@app.get('/echo/{x}')
def echo(x: int) -> int:
return x
```
Note that `app` is a global. Furthermore, [FastAPI's suggested way of doing dependency
injection](https://fastapi.tiangolo.com/tutorial/dependencies/classes-as-dependencies/) is handy for things like pulling
values out of header in the HTTP request. However, they don't work well for more standard dependency injection scenarios
where we'd like to do something like inject a DAO or database connection. For that, FastAPI suggests [their
parameterized dependencies](https://fastapi.tiangolo.com/advanced/advanced-dependencies/) which might look something
like:
```py
app = FastAPI()
class ValueToInject:
def __init__(self, y: int) -> None:
self.y = y
def __call__(self) -> int:
return self.y
to_add = ValueToInject(2)
@app.get('/add/{x}')
def add(x: int, y: Depends(to_add)) -> int:
return x + y
```
This works but there's a few issues:
* The `Dependency` must be a callable which requires an unfortunate amount of boilerplate.
* If we want to use the same dependency on several routes, as we would with something like a database connection, we
have to repeat the `Dependency(to_add)` bit on each endpoint. Note that FastAPI lets you group endpoints your we can
[include the dependency on all of them]( https://fastapi.tiangolo.com/tutorial/bigger-applications) but then there's
no way to access the dependency from the router code so this really only works for things like authentication where
the dependency can do some route handling (e.g. return a 402 if an auth header is missing).
* `to_add` is a global variable which is limiting.
Let's consider an expanded, more realistic example where we have a group of routes that operate on users to add them,
delete them, change the password, etc. Those routes will need to access a database so we have a DAO that helps set that
up. We're going to take the database URL, password, etc. via command line arguments and then set up our routes.
Furthermore, we'll split up our application into a few separate files. Doing this without class routing looks like the
following:
```py
# main.py
import .user
from .deps import dao
def parse_arg() -> argparse.Namespace:
"""parse command line arguments."""
...
def main():
args = parse_args()
global dao
dao = Dao(args.url, args.user, args.password)
app = FastAPI()
app.include_router(user.router)
####
# dao.py
from dao import Dao
# DAO for injection. We don't know the command line arguments yet but we need to make this global as we need to be able
# to access it in user.py below so it's None here and gets set in main()
dao: Optional[Dao] = None
#####
# user.py
from .deps import dao
from dao import Dao
from fastapi.routing import APIRouter
@router.get('/user/{name}')
def get_user_by_name(name: str, dao: Dao = Depends(dao)) -> User:
return dao.get_user_by_name(name)
@router.delete('/user/{name}')
def delete_user(name: str, dao: Dao = Depends(dao)) -> None:
dao.delete(name)
# ... additional user methods ...
```
That works but it's a bit verbose. Additionally, as noted above, it has some limitations. For example, suppose we've
updated our API in a breaking way so we've added a `/v2` set of routes. However, the `users.py` routes haven't changed
at all except that we've changed how we store users (e.g. a new password hashing algorithm) so `/v2` user routes need to
use a different DAO. Ideally you'd call `app.include_router` twice with different prefixes but that won't work because
the dependency on the DAO is to _a specific DAO instance_ in `user.py`. You can add [dependency
overrides](https://fastapi.tiangolo.com/advanced/testing-dependencies/) but it feels awkward.
By contrast the class based routing in this package does not have any global variables at all and injection can be
performed by simply passing values to a constructor or via any other dependency injection framework.
## Alternatives
[FastAPI-utils](https://fastapi-utils.davidmontague.xyz/user-guide/class-based-views/) has a class based views
implementation but the routes are on the class itself rather than on **instances** of the class.
There's demand for this feature so a number of alternatives have been proposed [in an open
bug](https://github.com/tiangolo/fastapi/issues/270) and [on
StackOverflow](https://stackoverflow.com/q/63853813/1431244) but all seem to require global injection or hacks like
defining all the routes inside the constructor.
# Older Versions of Python
Unfortunately this does not work with `async` routes with Python versions less than 3.8 [due to bugs in
`inspect.iscoroutinefunction`](https://stackoverflow.com/a/52422903/1431244). Specifically with older versions of Python
`iscoroutinefunction` incorrectly returns false so `async` routes aren't `await`'d. We therefore only support Python
versions >= 3.8
Raw data
{
"_id": null,
"home_page": "https://gitlab.com/companionlabs-opensource/classy-fastapi",
"name": "classy-fastapi",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "FastAPI,Class,Instance,Routing",
"author": "Oliver Dain",
"author_email": "oliver@dains.org",
"download_url": "https://files.pythonhosted.org/packages/5a/2f/03f98e1755e0d0470e4ace453c51bb70add716d501d67cb7a5ab648a16dd/classy-fastapi-0.6.1.tar.gz",
"platform": null,
"description": "# Overview\n\nThis project contains classes and decorators to use FastAPI with \"class based routing\". In particular this allows you to\nconstruct an **instance** of a class and have methods of that instance be route handlers. For example:\n\n```py\nfrom dao import Dao\n# Some fictional dao\nfrom classy_fastapi import Routable, get, delete\n\ndef parse_arg() -> argparse.Namespace:\n \"\"\"parse command line arguments.\"\"\"\n ...\n\n\nclass UserRoutes(Routable):\n \"\"\"Inherits from Routable.\"\"\"\n\n # Note injection here by simply passing values to the constructor. Other injection frameworks also\n # supported as there's nothing special about this __init__ method.\n def __init__(self, dao: Dao) -> None:\n \"\"\"Constructor. The Dao is injected here.\"\"\"\n super().__init__()\n self.__dao = Dao\n\n @get('/user/{name}')\n def get_user_by_name(self, name: str) -> User:\n # Use our injected DAO instance.\n return self.__dao.get_user_by_name(name)\n\n @delete('/user/{name}')\n def delete_user(self, name: str) -> None:\n self.__dao.delete(name)\n\n\ndef main():\n args = parse_args()\n # Configure the DAO per command line arguments\n dao = Dao(args.url, args.user, args.password)\n # Simple intuitive injection\n user_routes = UserRoutes(dao)\n\n app = FastAPI()\n # router member inherited from cr.Routable and configured per the annotations.\n app.include_router(user_routes.router)\n```\n\nNote that there are no global variables and dependency injection is accomplished by simply passing arguments to the\nconstructor.\n\n# Why\n\nFastAPI generally has one define routes like:\n\n```py\napp = FastAPI()\n\n@app.get('/echo/{x}')\ndef echo(x: int) -> int:\n return x\n```\n\nNote that `app` is a global. Furthermore, [FastAPI's suggested way of doing dependency\ninjection](https://fastapi.tiangolo.com/tutorial/dependencies/classes-as-dependencies/) is handy for things like pulling\nvalues out of header in the HTTP request. However, they don't work well for more standard dependency injection scenarios\nwhere we'd like to do something like inject a DAO or database connection. For that, FastAPI suggests [their\nparameterized dependencies](https://fastapi.tiangolo.com/advanced/advanced-dependencies/) which might look something\nlike:\n\n```py\napp = FastAPI()\n\nclass ValueToInject:\n def __init__(self, y: int) -> None:\n self.y = y\n\n def __call__(self) -> int:\n return self.y\n\nto_add = ValueToInject(2)\n\n@app.get('/add/{x}')\ndef add(x: int, y: Depends(to_add)) -> int:\n return x + y\n```\n\nThis works but there's a few issues:\n\n* The `Dependency` must be a callable which requires an unfortunate amount of boilerplate.\n* If we want to use the same dependency on several routes, as we would with something like a database connection, we\n have to repeat the `Dependency(to_add)` bit on each endpoint. Note that FastAPI lets you group endpoints your we can\n [include the dependency on all of them]( https://fastapi.tiangolo.com/tutorial/bigger-applications) but then there's\n no way to access the dependency from the router code so this really only works for things like authentication where\n the dependency can do some route handling (e.g. return a 402 if an auth header is missing).\n* `to_add` is a global variable which is limiting.\n\nLet's consider an expanded, more realistic example where we have a group of routes that operate on users to add them,\ndelete them, change the password, etc. Those routes will need to access a database so we have a DAO that helps set that\nup. We're going to take the database URL, password, etc. via command line arguments and then set up our routes.\nFurthermore, we'll split up our application into a few separate files. Doing this without class routing looks like the\nfollowing:\n\n```py\n# main.py\n\nimport .user\nfrom .deps import dao\n\ndef parse_arg() -> argparse.Namespace:\n \"\"\"parse command line arguments.\"\"\"\n ...\n\ndef main():\n args = parse_args()\n global dao\n dao = Dao(args.url, args.user, args.password)\n\n app = FastAPI()\n app.include_router(user.router)\n\n####\n# dao.py\n\nfrom dao import Dao\n\n# DAO for injection. We don't know the command line arguments yet but we need to make this global as we need to be able\n# to access it in user.py below so it's None here and gets set in main()\ndao: Optional[Dao] = None\n\n#####\n# user.py\nfrom .deps import dao\nfrom dao import Dao\nfrom fastapi.routing import APIRouter\n\n@router.get('/user/{name}')\ndef get_user_by_name(name: str, dao: Dao = Depends(dao)) -> User:\n return dao.get_user_by_name(name)\n\n@router.delete('/user/{name}')\ndef delete_user(name: str, dao: Dao = Depends(dao)) -> None:\n dao.delete(name)\n\n# ... additional user methods ...\n```\n\nThat works but it's a bit verbose. Additionally, as noted above, it has some limitations. For example, suppose we've\nupdated our API in a breaking way so we've added a `/v2` set of routes. However, the `users.py` routes haven't changed\nat all except that we've changed how we store users (e.g. a new password hashing algorithm) so `/v2` user routes need to\nuse a different DAO. Ideally you'd call `app.include_router` twice with different prefixes but that won't work because\nthe dependency on the DAO is to _a specific DAO instance_ in `user.py`. You can add [dependency\noverrides](https://fastapi.tiangolo.com/advanced/testing-dependencies/) but it feels awkward.\n\nBy contrast the class based routing in this package does not have any global variables at all and injection can be\nperformed by simply passing values to a constructor or via any other dependency injection framework.\n\n## Alternatives\n\n[FastAPI-utils](https://fastapi-utils.davidmontague.xyz/user-guide/class-based-views/) has a class based views\nimplementation but the routes are on the class itself rather than on **instances** of the class.\n\nThere's demand for this feature so a number of alternatives have been proposed [in an open\nbug](https://github.com/tiangolo/fastapi/issues/270) and [on\nStackOverflow](https://stackoverflow.com/q/63853813/1431244) but all seem to require global injection or hacks like\ndefining all the routes inside the constructor.\n\n# Older Versions of Python\n\nUnfortunately this does not work with `async` routes with Python versions less than 3.8 [due to bugs in\n`inspect.iscoroutinefunction`](https://stackoverflow.com/a/52422903/1431244). Specifically with older versions of Python\n`iscoroutinefunction` incorrectly returns false so `async` routes aren't `await`'d. We therefore only support Python\nversions >= 3.8\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Class based routing for FastAPI",
"version": "0.6.1",
"project_urls": {
"Homepage": "https://gitlab.com/companionlabs-opensource/classy-fastapi",
"Repository": "https://gitlab.com/companionlabs-opensource/classy-fastapi"
},
"split_keywords": [
"fastapi",
"class",
"instance",
"routing"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "14b42f3a605d9d54bccb7c2851c9f70991f453e3cac0d1de5c18e60a3d42cd34",
"md5": "4dead8cd737fc20b0d89af3aeb5b3221",
"sha256": "196e5c2890269627d52851f3f86001a0dfda0070053d38f8a7bd896ac2f67737"
},
"downloads": -1,
"filename": "classy_fastapi-0.6.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4dead8cd737fc20b0d89af3aeb5b3221",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 9698,
"upload_time": "2023-10-20T18:41:19",
"upload_time_iso_8601": "2023-10-20T18:41:19.873193Z",
"url": "https://files.pythonhosted.org/packages/14/b4/2f3a605d9d54bccb7c2851c9f70991f453e3cac0d1de5c18e60a3d42cd34/classy_fastapi-0.6.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "5a2f03f98e1755e0d0470e4ace453c51bb70add716d501d67cb7a5ab648a16dd",
"md5": "c368f4c4c4ce31f0fc59454ccba3b087",
"sha256": "5dfc33bab8e01e07c56855b78ce9a8152c871ab544a565d0d3d05a5c1ca4ed68"
},
"downloads": -1,
"filename": "classy-fastapi-0.6.1.tar.gz",
"has_sig": false,
"md5_digest": "c368f4c4c4ce31f0fc59454ccba3b087",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 11026,
"upload_time": "2023-10-20T18:41:18",
"upload_time_iso_8601": "2023-10-20T18:41:18.474773Z",
"url": "https://files.pythonhosted.org/packages/5a/2f/03f98e1755e0d0470e4ace453c51bb70add716d501d67cb7a5ab648a16dd/classy-fastapi-0.6.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-10-20 18:41:18",
"github": false,
"gitlab": true,
"bitbucket": false,
"codeberg": false,
"gitlab_user": "companionlabs-opensource",
"gitlab_project": "classy-fastapi",
"lcname": "classy-fastapi"
}
JSON