Skip to content

Latest commit

 

History

History
435 lines (343 loc) · 52.2 KB

README.md

File metadata and controls

435 lines (343 loc) · 52.2 KB

Litestar Logo - Light Litestar Logo - Dark

ci PyPI - Version PyPI - License PyPI - Support Python Versions

Coverage Quality Gate Status Maintainability Rating Reliability Rating Security Rating

All Contributors

Reddit Discord Matrix Medium

Starlite → Litestar

Starlite has been renamed to Litestar


Litestar is a powerful, performant, flexible and opinionated ASGI framework, offering first class typing support and a full Pydantic integration.

Check out the documentation 📚.

Installation

pip install litestar

Litestar 2.0 is coming out soon, bringing many new features and improvements. You can check out the alpha version by instead running

pip install litestar==2.0.0alpha7

Quick Start

from litestar import Litestar, get


@get("/")
def hello_world() -> dict[str, str]:
    """Keeping the tradition alive with hello world."""
    return {"hello": "world"}


app = Litestar(route_handlers=[hello_world])

Core Features

Example Applications

  • starlite-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-hello-world: A bare-minimum application setup. Great for testing and POC work.

Performance

Litestar is fast. It is on par with, or significantly faster than comparable ASGI frameworks.

You can see and run the benchmarks here, or read more about it here in our documentation.

JSON Benchmarks

JSON benchmarks

Plaintext Benchmarks

Plaintext benchmarks

Features

Class Based Controllers

While supporting function based route handlers, Litestar also supports and promotes python OOP using class based controllers:

from typing import List, Optional

from pydantic import UUID4
from litestar import Controller, get, post, put, patch, delete
from litestar.partial import Partial
from datetime import datetime

from my_app.models import User


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

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

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

    @get(path="/{date:int}")
    async def list_new_users(self, date: datetime) -> List[User]:
        ...

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

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

    @get(path="/{user_name:str}")
    async def get_user_by_name(self, user_name: str) -> Optional[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:
        ...

Data Parsing, Type Hints and Pydantic

Litestar is rigorously typed, and it enforces typing. For example, if you forget to type a return value for a route handler, an exception will be raised. The reason for this is that Litestar uses typing data to generate OpenAPI specs, as well as to validate and parse data. Thus typing is absolutely essential to the framework.

Furthermore, Litestar allows extending its support using plugins.

Plugin System, ORM support and DTOs

Litestar has a plugin system that allows the user to extend serialization/deserialization, OpenAPI generation and other features. It ships with a builtin plugin for SQL Alchemy, which allows the user to use SQLAlchemy declarative classes "natively", i.e. as type parameters that will be serialized/deserialized and to return them as values from route handlers.

Litestar also supports the programmatic creation of DTOs with a DTOFactory class, which also supports the use of plugins.

OpenAPI

Litestar has custom logic to generate OpenAPI 3.1.0 schema, include optional generation of examples using the pydantic-factories library.

ReDoc, Swagger-UI and Stoplight Elements API Documentation

Litestar serves the documentation from the generated OpenAPI schema with:

All these are available and enabled by default.

Dependency Injection

Litestar has a simple but powerful DI system inspired by pytest. You can define named dependencies - sync or async - at different levels of the application, and then selective use or overwrite them.

from litestar import Litestar, get
from litestar.di import Provide


async def my_dependency() -> str:
    ...


@get("/")
async def index(injected: str) -> str:
    return injected


app = Litestar([index], dependencies={"injected": Provide(my_dependency)})

Middleware

Litestar supports typical ASGI middleware and ships with middlewares to handle things such as

  • CORS
  • CSRF
  • Rate limiting
  • GZip and Brotli compression
  • Client- and server-side sessions

Route Guards

Litestar has an authorization mechanism called guards, which allows the user to define guard functions at different level of the application (app, router, controller etc.) and validate the request before hitting the route handler function.

from litestar import Litestar, get

from litestar.connection import ASGIConnection
from litestar.handlers.base import BaseRouteHandler
from litestar.exceptions import NotAuthorizedException


async def is_authorized(connection: ASGIConnection, handler: BaseRouteHandler) -> None:
    # validate authorization
    # if not authorized, raise NotAuthorizedException
    raise NotAuthorizedException()


@get("/", guards=[is_authorized])
async def index() -> None:
    ...


app = Litestar([index])

Request Life Cycle Hooks

Litestar supports request life cycle hooks, similarly to Flask - i.e. before_request and after_request

Contributing

Litestar is open to contributions big and small. You can always join our discord server or join our Matrix space to discuss contributions and project maintenance. For guidelines on how to contribute, please see the contribution guide.

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Na'aman Hirschfeld
Na'aman Hirschfeld

🚧 💻 📖 ⚠️ 🤔 💡 🐛
Peter Schutt
Peter Schutt

🚧 💻 📖 ⚠️ 🤔 💡 🐛
Ashwin Vinod
Ashwin Vinod

💻 📖
Damian
Damian

📖
Vincent Sarago
Vincent Sarago

💻
Jonas Krüger Svensson
Jonas Krüger Svensson

📦
Sondre Lillebø Gundersen
Sondre Lillebø Gundersen

📦
Lev
Lev

💻 🤔
Tim Wedde
Tim Wedde

💻
Tory Clasen
Tory Clasen

💻
Arseny Boykov
Arseny Boykov

💻 🤔
Jacob Rodgers
Jacob Rodgers

💡
Dane Solberg
Dane Solberg

💻
madlad33
madlad33

💻
Matthew Aylward
Matthew Aylward

💻
Jan Klima
Jan Klima

💻
C2D
C2D

⚠️
to-ph
to-ph

💻
imbev
imbev

📖
cătălin
cătălin

💻
Seon82
Seon82

📖
Slava
Slava

💻
Harry
Harry

💻 📖
Cody Fincher
Cody Fincher

🚧 💻 📖 ⚠️ 🤔 💡 🐛
Christian Clauss
Christian Clauss

📖
josepdaniel
josepdaniel

💻
devtud
devtud

🐛
Nicholas Ramos
Nicholas Ramos

💻
seladb
seladb

📖 💻
Simon Wienhöfer
Simon Wienhöfer

💻
MobiusXS
MobiusXS

💻
Aidan Simard
Aidan Simard

📖
wweber
wweber

💻
Samuel Colvin
Samuel Colvin

💻
Mateusz Mikołajczyk
Mateusz Mikołajczyk

💻
Alex
Alex

💻
Odiseo
Odiseo

📖
Javier  Pinilla
Javier Pinilla

💻
Chaoying
Chaoying

📖
infohash
infohash

💻
John Ingles
John Ingles

💻
Eugene
Eugene

⚠️ 💻
Jon Daly
Jon Daly

📖 💻
Harshal Laheri
Harshal Laheri

💻 📖
Téva KRIEF
Téva KRIEF

💻
Konstantin Mikhailov
Konstantin Mikhailov

🚧 💻 📖 ⚠️ 🤔 💡 🐛
Mitchell Henry
Mitchell Henry

📖
chbndrhnns
chbndrhnns

📖
nielsvanhooy
nielsvanhooy

💻
provinzkraut
provinzkraut

🚧 💻 📖 ⚠️ 🤔 💡 🐛 🎨
Joshua Bronson
Joshua Bronson

📖
Roman Reznikov
Roman Reznikov

📖
mookrs
mookrs

📖
Mike DePalatis
Mike DePalatis

📖
Carlos Alberto Pérez-Molano
Carlos Alberto Pérez-Molano

📖
ThinksFast
ThinksFast

⚠️ 📖
Christopher Krause
Christopher Krause

💻
Kyle Smith
Kyle Smith

💻 📖 🐛
Scott Bradley
Scott Bradley

🐛
Srikanth Chekuri
Srikanth Chekuri

⚠️ 📖
Michael Bosch
Michael Bosch

📖
sssssss340
sssssss340

🐛
ste-pool
ste-pool

💻 🚇
Alc-Alc
Alc-Alc

📖 💻
asomethings
asomethings

💻
Garry Bullock
Garry Bullock

📖
Niclas Haderer
Niclas Haderer

💻
Diego Alvarez
Diego Alvarez

📖 💻
Jason Nance
Jason Nance

📖
Igor Kapadze
Igor Kapadze

📖
Somraj Saha
Somraj Saha

📖
Magnús Ágúst Skúlason
Magnús Ágúst Skúlason

💻 📖
Alessio Parma
Alessio Parma

📖
Peter Brunner
Peter Brunner

💻
Jacob Coffee
Jacob Coffee

📖 💻 ⚠️ 🚇 🤔 🚧 💼 🎨
Gamazic
Gamazic

💻
Kareem Mahlees
Kareem Mahlees

💻
Abdulhaq Emhemmed
Abdulhaq Emhemmed

💻
Jenish
Jenish

💻 📖
chris-telemetry
chris-telemetry

💻
Ward
Ward

🐛
Stephan Fitzpatrick
Stephan Fitzpatrick

🐛
Eric Kennedy
Eric Kennedy

📖
wassaf shahzad
wassaf shahzad

💻
Nils Olsson
Nils Olsson

💻
Riley Chase
Riley Chase

💻
arl
arl

🚧
Antoine van der Horst
Antoine van der Horst

📖
Nick Groenen
Nick Groenen

📖
Giorgio Vilardo
Giorgio Vilardo

📖
Nicholas Bollweg
Nicholas Bollweg

💻
Tomas Jonsson
Tomas Jonsson

⚠️ 💻
Khiem Doan
Khiem Doan

📖
kedod
kedod

📖
sonpro1296
sonpro1296

💻 ⚠️ 🚇 📖
Patrick Armengol
Patrick Armengol

📖
Sander
Sander

📖
疯人院主任
疯人院主任

📖
aviral-nayya
aviral-nayya

💻
whiskeyriver
whiskeyriver

💻
Phyo Arkar Lwin
Phyo Arkar Lwin

💻
MatthewNewland
MatthewNewland

🐛
Tom Kuo
Tom Kuo

🐛
LeckerenSirupwaffeln
LeckerenSirupwaffeln

🐛
Daniel González Fernández
Daniel González Fernández

📖
01EK98
01EK98

📖
Sarbo Roy
Sarbo Roy

💻

This project follows the all-contributors specification. Contributions of any kind welcome!