Litestar does not include any decorator as part of the Router or Litestar instances.
Instead, all routes are declared using :doc:`route handlers </usage/routing/handlers>`, either as standalone functions or
controller methods. The handler can then be registered on an application or router instance.
.. tab-set::
.. tab-item:: FastAPI
:sync: fastapi
.. code-block:: python
from fastapi import FastAPI
app = FastAPI()
@app.get("/")
async def index() -> dict[str, str]: ...
.. tab-item:: Starlette
:sync: starlette
.. code-block:: python
from starlette.applications import Starlette
from starlette.routing import Route
async def index(request): ...
routes = [Route("/", endpoint=index)]
app = Starlette(routes=routes)
.. tab-item:: Litestar
:sync: litestar
.. code-block:: python
from litestar import Litestar, get
@get("/")
async def index() -> dict[str, str]: ...
app = Litestar([index])
.. seealso::
To learn more about registering routes, check out this chapter
in the documentation:
* :ref:`Routing - Registering Routes <usage/routing/overview:registering routes>`
There are a few key differences between Litestar’s and Starlette’s Router class:
- The Litestar version is not an ASGI app
- The Litestar version does not include decorators: Use :doc:`route handlers </usage/routing/handlers>`.
- The Litestar version does not support lifecycle hooks: Those have to be handled on the application layer. See :doc:`lifecycle hooks </usage/lifecycle-hooks>`
If you are using Starlette’s Routes, you will need to replace these with :doc:`route handlers </usage/routing/handlers>`.
Host based routing class is intentionally unsupported. If your application relies on Host you will have to separate
the logic into different services and handle this part of request dispatching with a proxy server like nginx
or traefik.
The Litestar dependency injection system is different from the one used by FastAPI. You can read about it in the :doc:`dependency injection </usage/dependency-injection>` section of the documentation.
In FastAPI you declare dependencies either as a list of functions passed to the Router or FastAPI instances, or as a
default function argument value wrapped in an instance of the Depends class.
In Litestar dependencies are always declared using a dictionary with a string key and the value wrapped in an
instance of the Provide class. This also allows to transparently override dependencies on every level of the application,
and to easily access dependencies from higher levels.
.. tab-set::
.. tab-item:: FastAPI
:sync: fastapi
.. code-block:: python
from fastapi import FastAPI, Depends, APIRouter
async def route_dependency() -> bool: ...
async def nested_dependency() -> str: ...
async def router_dependency() -> int: ...
async def app_dependency(data: str = Depends(nested_dependency)) -> int: ...
router = APIRouter(dependencies=[Depends(router_dependency)])
app = FastAPI(dependencies=[Depends(nested_dependency)])
app.include_router(router)
@app.get("/")
async def handler(
val_route: bool = Depends(route_dependency),
val_router: int = Depends(router_dependency),
val_nested: str = Depends(nested_dependency),
val_app: int = Depends(app_dependency),
) -> None: ...
.. tab-item:: Litestar
:sync: litestar
.. code-block:: python
from litestar import Litestar, get, Router
from litestar.di import Provide
async def route_dependency() -> bool: ...
async def nested_dependency() -> str: ...
async def router_dependency() -> int: ...
async def app_dependency(nested: str) -> int: ...
@get("/", dependencies={"val_route": Provide(route_dependency)})
async def handler(
val_route: bool, val_router: int, val_nested: str, val_app: int
) -> None: ...
router = Router(dependencies={"val_router": Provide(router_dependency)})
app = Litestar(
route_handlers=[handler],
dependencies={
"val_app": Provide(app_dependency),
"val_nested": Provide(nested_dependency),
},
)
.. seealso::
To learn more about dependency injection, check out this chapter
in the documentation:
* :doc:`/usage/dependency-injection`
Litestar uses the same async context manager style as FastAPI, so the code does not need to be changed:
.. tab-set::
.. tab-item:: FastAPI
:sync: fastapi
.. code-block:: python
@asynccontextmanager
async def lifespan(app: FastAPI):
# Setup code here
yield
# Teardown code here
.. tab-item:: Litestar
:sync: litestar
.. code-block:: python
@asynccontextmanager
async def lifespan(app: Litestar):
# Setup code here
yield
# Teardown code here
While with FastAPI you usually set cookies on the response Response object, in Litestar there are two options: At the decorator level, using the response_cookies keyword argument, or dynamically at the response level (see: :ref:`Setting Cookies dynamically <usage/responses:setting cookies dynamically>`)
.. tab-set::
.. tab-item:: FastAPI
:sync: fastapi
.. code-block:: python
@app.get("/")
async def index(response: Response) -> dict[str, str]:
response.set_cookie(key="my_cookie", value="cookie_value")
...
.. tab-item:: Litestar
:sync: litestar
.. code-block:: python
@get(response_cookies={"my-cookie": "cookie-value"})
async def handler() -> str: ...
The way dependencies parameters are passed differs between FastAPI and Litestar, note the state: State parameter in the Litestar example.
You can get the state either with the state kwarg in the handler or request.state (which point to the same object, a request local state, inherited from the application's state), or via request.app.state, the application's state.
.. tab-set::
.. tab-item:: FastAPI
:sync: fastapi
.. code-block:: python
from fastapi import Request
async def get_arqredis(request: Request) -> ArqRedis:
return request.state.arqredis
.. tab-item:: Litestar
:sync: litestar
.. code-block:: python
from litestar import State
async def get_arqredis(state: State) -> ArqRedis:
return state.arqredis
In FastAPI, you pass the JSON object directly as a parameter to the endpoint, which will then be validated by Pydantic. In Litestar, you use the data keyword argument. The data will be parsed and validated by the associated modelling library.
.. tab-set::
.. tab-item:: FastAPI
:sync: fastapi
.. code-block:: python
class ObjectType(BaseModel):
name: str
@app.post("/items/")
async def create_item(object_name: ObjectType) -> dict[str, str]:
return {"name": object_name.name}
.. tab-item:: Litestar
:sync: litestar
.. code-block:: python
from litestar import Litestar, post
from pydantic import BaseModel
class ObjectType(BaseModel):
name: str
@post("/items/")
async def create_item(data: ObjectType) -> dict[str, str]:
return {"name": data.name}
Post defaults to 200 in FastApi and 201 in Litestar.
In FastAPI, you use TemplateResponse to render templates. In Litestar, you use the Template class. Also FastAPI let you pass a dictionary while in Litestar you need to explicitly pass the context kwarg.
.. tab-set::
.. tab-item:: FastAPI
:sync: fastapi
.. code-block:: python
@app.get("/uploads")
async def get_uploads(request: Request):
return templates.TemplateResponse(
"uploads.html", {"request": request, "debug": app.state.debug}
)
.. tab-item:: Litestar
:sync: litestar
.. code-block:: python
@get("/uploads")
async def get_uploads(app_settings) -> Template:
return Template(name="uploads.html", context={"debug": app_settings.debug})
In FastAPI, you use the File class to handle file uploads. In Litestar, you use the data keyword argument with Body and specify the media_type as RequestEncodingType.MULTI_PART. While this is more verbose, it's also more explicit and communicates the intent more clearly.
.. tab-set::
.. tab-item:: FastAPI
:sync: fastapi
.. code-block:: python
@app.post("/upload/")
async def upload_file(files: list[UploadFile] = File(...)) -> dict[str, str]:
return {"file_names": [file.filename for file in files]}
.. tab-item:: Litestar
:sync: litestar
.. code-block:: python
@post("/upload/")
async def upload_file(
data: Annotated[
list[UploadFile], Body(media_type=RequestEncodingType.MULTI_PART)
],
) -> dict[str, str]:
return {"file_names": [file.filename for file in data]}
app = Litestar([upload_file])
In FastAPI, status code and exception details can be passed to HTTPException as positional arguments, while in Litestar they are set with keywords arguments, e.g. status_code. Positional arguments to HTTPException in Litestar will be added to the exception detail. If migrating you just change your HTTPException import this will break.
.. tab-set::
.. tab-item:: FastAPI
:sync: fastapi
.. code-block:: python
from fastapi import FastAPI, HTTPException
app = FastAPI()
@app.get("/")
async def index() -> None:
response_fields = {"array": "value"}
raise HTTPException(
400, detail=f"can't get that field: {response_fields.get('array')}"
)
.. tab-item:: Litestar
:sync: litestar
.. code-block:: python
from litestar import Litestar, get
from litestar.exceptions import HTTPException
@get("/")
async def index() -> None:
response_fields = {"array": "value"}
raise HTTPException(
status_code=400,
detail=f"can't get that field: {response_fields.get('array')}",
)
app = Litestar([index])
FastAPI promotes a pattern of using dependency injection for authentication. You can do the same in Litestar, but the preferred way of handling this is extending :doc:`/usage/security/abstract-authentication-middleware`.
.. tab-set::
.. tab-item:: FastAPI
:sync: fastapi
.. code-block:: python
from fastapi import FastAPI, Depends, Request
async def authenticate(request: Request) -> None: ...
app = FastAPI()
@app.get("/", dependencies=[Depends(authenticate)])
async def index() -> dict[str, str]: ...
.. tab-item:: Litestar
:sync: litestar
.. code-block:: python
from litestar import Litestar, get, ASGIConnection, BaseRouteHandler
async def authenticate(
connection: ASGIConnection, route_handler: BaseRouteHandler
) -> None: ...
@get("/", guards=[authenticate])
async def index() -> dict[str, str]: ...
.. seealso::
To learn more about security and authentication, check out this chapter in the
documentation:
* :doc:`/usage/security/index`
While FastAPI includes a mechanism to override dependencies on an existing application object, Litestar promotes architectural solutions to the issue this is aimed to solve. Therefore, overriding dependencies in Litestar is strictly supported at definition time, i.e. when you’re defining handlers, controllers, routers, and applications. Dependency overrides are fundamentally the same idea as mocking and should be approached with the same caution and used sparingly instead of being the default.
To achieve the same effect there are three general approaches:
- Structuring the application with different environments in mind. This could mean for example connecting to a different database depending on the environment, which in turn is set via and env-variable. This is sufficient and most cases and designing your application around this principle is a general good practice since it facilitates configurability and integration-testing capabilities
- Isolating tests for unit testing and using
create_test_client - Resort to mocking if none of the above approaches can be made to work
Pure ASGI middleware is fully compatible, and can be used with any ASGI framework. Middlewares that make use of FastAPI/Starlette specific middleware features such as Starlette’s BaseHTTPMiddleware are not compatible, but can be easily replaced by :doc:`Creating Middlewares </usage/middleware/creating-middleware>`.