Skip to content

Latest commit

 

History

History
259 lines (164 loc) · 8.2 KB

getting-started.rst

File metadata and controls

259 lines (164 loc) · 8.2 KB

Getting Started

Installation

pip install litestar

Tip

litestar[standard] includes commonly used extras like CLI, uvicorn and jinja2 (for templating).

.. dropdown:: Extras
    :icon: star

    `Pydantic <https://docs.pydantic.dev/latest/>`_
        :code:`pip install 'litestar[pydantic]'`

    `Attrs <https://www.attrs.org>`_
        :code:`pip install 'litestar[attrs]'`

    :ref:`Brotli Compression Middleware <usage/middleware/builtin-middleware:brotli>`
        :code:`pip install 'litestar[brotli]'`

   :ref:`Zstd Compression Middleware <usage/middleware/builtin-middleware:zstd>`
        :code:`pip install 'litestar[zstd]'`

    :ref:`Cookie Based Sessions <usage/middleware/builtin-middleware:client-side sessions>`
        :code:`pip install 'litestar[cryptography]'`

    :doc:`JWT </usage/security/jwt>`
        :code:`pip install 'litestar[jwt]'`

    :doc:`RedisStore </usage/stores>`
        :code:`pip install 'litestar[redis]'`

    :ref:`StructLog <usage/logging:Structlog integration>`
        :code:`pip install 'litestar[structlog]'`

    :doc:`Prometheus Instrumentation </usage/metrics/prometheus>`
        :code:`pip install 'litestar[prometheus]'`

    :doc:`Open Telemetry Instrumentation </usage/metrics/open-telemetry>`
        :code:`pip install 'litestar[opentelemetry]'`

    :doc:`SQLAlchemy </usage/databases/sqlalchemy/index>` (via `Advanced-Alchemy <https://advanced-alchemy.litestar.dev/latest/>`_)
        :code:`pip install 'litestar[sqlalchemy]'`

    :doc:`Jinja Templating </usage/templating>`
        :code:`pip install 'litestar[jinja]'`

    :doc:`Mako Templating </usage/templating>`
        :code:`pip install 'litestar[mako]'`

    :ref:`Better OpenAPI examples generation <usage/openapi/schema_generation:Generating examples>` with `Polyfactory <https://github.com/litestar-org/polyfactory>`_
        :code:`pip install 'litestar[polyfactory]'`

    :doc:`HTMX plugin </usage/htmx>`
        :code:`pip install 'litestar[htmx]'`

    :ref:`OpenAPI YAML rendering <usage/openapi/ui_plugins:Using OpenAPI UI Plugins>`
        :code:`pip install 'litestar[yaml]'`

    Standard Installation (includes CLI, Uvicorn, and Jinja2 templating):
        :code:`pip install 'litestar[standard]'`

    All Extras:
        :code:`pip install 'litestar[full]'`

    .. note:: The full extras is not recommended because it will add a lot of unnecessary extras.

Minimal Example

At a minimum, make sure you have installed litestar[standard], which includes uvicorn.

First, create a file named app.py with the following contents:

from litestar import Litestar, get


@get("/")
async def index() -> str:
    return "Hello, world!"


@get("/books/{book_id:int}")
async def get_book(book_id: int) -> dict[str, int]:
    return {"book_id": book_id}


app = Litestar([index, get_book])

Then, run the following command:

litestar run
# Or you can run Uvicorn directly:
uvicorn app:app --reload

You can now visit http://localhost:8000/ and http://localhost:8000/books/1 in your browser and you should see the responses of your two endpoints:

"Hello, world!"

and

{"book_id": 1}

Tip

You can also check out the automatically generated OpenAPI-based documentation at:

  • http://localhost:8000/schema (for ReDoc),
  • http://localhost:8000/schema/swagger (for Swagger UI),
  • http://localhost:8000/schema/elements (for Stoplight Elements)
  • http://localhost:8000/schema/rapidoc (for RapiDoc)

You can check out a more in-depth tutorial in the :doc:`/tutorials/todo-app/index` section!

Expanded Example

Define your data model using pydantic or any library based on it (for example ormar, beanie, SQLModel):

from pydantic import BaseModel, UUID4


class User(BaseModel):
    first_name: str
    last_name: str
    id: UUID4

You can also use dataclasses (standard library and Pydantic), :class:`typing.TypedDict`, or :class:`msgspec.Struct`.

from uuid import UUID

from dataclasses import dataclass
from litestar.dto import DTOConfig, DataclassDTO


@dataclass
class User:
    first_name: str
    last_name: str
    id: UUID


class PartialUserDTO(DataclassDTO[User]):
    config = DTOConfig(exclude={"id"}, partial=True)

Define a Controller for your data model:

from typing import List

from litestar import Controller, get, post, put, patch, delete
from litestar.dto import DTOData
from pydantic import UUID4

from my_app.models import User, PartialUserDTO


class UserController(Controller):
    path = "/users"

    @post()
    async def create_user(self, data: User) -> User: ...

    @get()
    async def list_users(self) -> List[User]: ...

    @patch(path="/{user_id:uuid}", dto=PartialUserDTO)
    async def partial_update_user(
        self, user_id: UUID4, data: DTOData[User]
    ) -> User: ...

    @put(path="/{user_id:uuid}")
    async def update_user(self, user_id: UUID4, data: User) -> User: ...

    @get(path="/{user_id:uuid}")
    async def get_user(self, user_id: UUID4) -> User: ...

    @delete(path="/{user_id:uuid}")
    async def delete_user(self, user_id: UUID4) -> None: ...

When instantiating your app, import your controller into your application's entry-point and pass it to Litestar:

from litestar import Litestar

from my_app.controllers.user import UserController

app = Litestar(route_handlers=[UserController])

To run your application, use an ASGI server such as uvicorn :

uvicorn my_app.main:app --reload

Philosophy

  • Litestar is a community-driven project. This means not a single author, but rather a core team of maintainers is leading the project, supported by a community of contributors. Litestar currently has 5 maintainers and is being very actively developed.
  • Litestar draws inspiration from NestJS - a contemporary TypeScript framework - which places opinions and patterns at its core.
  • While still allowing for function-based endpoints, Litestar seeks to build on Python's powerful and versatile OOP, by placing class-based controllers at its core.
  • Litestar is not a microframework. Unlike frameworks such as FastAPI, Starlette, or Flask, Litestar includes a lot of functionalities out of the box needed for a typical modern web application, such as ORM integration, client- and server-side sessions, caching, OpenTelemetry integration, and many more. It's not aiming to be "the next Django" (for example, it will never feature its own ORM), but its scope is not micro either.

Feature comparison with similar frameworks

Example Applications

  • litestar-pg-redis-docker : In addition to Litestar, this demonstrates a pattern of application modularity, SQLAlchemy 2.0 ORM, Redis cache connectivity, and more. Like all Litestar projects, this application is open to contributions, big and small.
  • litestar-fullstack : A fully-capable, production-ready fullstack Litestar web application configured with best practices. It includes SQLAlchemy 2.0, ReactJS, Vite, SAQ job queue, Jinja templates and more. Read more.
  • litestar-hello-world: A bare-minimum application setup. Great for testing and POC work.