ignore: test

docs/examples/application_state/injecting_application_state.py

@@ -0,0 +1,6 @@
+from litestar import get
+from litestar.datastructures import State
+
+
+@get("/")
+def handler(state: State) -> None: ...

docs/examples/caching/caching_duration.py

@@ -0,0 +1,5 @@
+from litestar import get
+
+
+@get("/cached-path", cache=120)  # seconds
+def my_cached_handler() -> str: ...

docs/examples/caching/caching_forever.py

@@ -0,0 +1,6 @@
+from litestar import get
+from litestar.config.response_cache import CACHE_FOREVER
+
+
+@get("/cached-path", cache=CACHE_FOREVER)  # seconds
+def my_cached_handler() -> str: ...

docs/examples/caching/caching_key_builder.py

@@ -0,0 +1,9 @@
+from litestar import Litestar, Request
+from litestar.config.cache import ResponseCacheConfig
+
+
+def key_builder(request: Request) -> str:
+    return request.url.path + request.headers.get("my-header", "")
+
+
+app = Litestar([], cache_config=ResponseCacheConfig(key_builder=key_builder))

docs/examples/caching/caching_key_builder_specific_route.py

@@ -0,0 +1,9 @@
+from litestar import Request, get
+
+
+def key_builder(request: Request) -> str:
+    return request.url.path + request.headers.get("my-header", "")
+
+
+@get("/cached-path", cache=True, cache_key_builder=key_builder)
+def cached_handler() -> str: ...

docs/examples/caching/caching_response.py

@@ -0,0 +1,5 @@
+from litestar import get
+
+
+@get("/cached-path", cache=True)
+def my_cached_handler() -> str: ...

docs/examples/caching/caching_storage_redis.py

@@ -0,0 +1,6 @@
+from litestar.config.cache import ResponseCacheConfig
+from litestar.stores.redis import RedisStore
+
+redis_store = RedisStore(url="redis://localhost/", port=6379, db=0)
+
+cache_config = ResponseCacheConfig(store=redis_store)

docs/examples/channels/allowing_arbitrary_channels.py

@@ -0,0 +1,3 @@
+from litestar.channels import ChannelsPlugin
+
+channels_plugin = ChannelsPlugin(..., arbitrary_channels_allowed=True)

docs/examples/channels/backoff_strategy.py

@@ -0,0 +1,8 @@
+from litestar.channels import ChannelsPlugin
+from litestar.channels.memory import MemoryChannelsBackend
+
+channels = ChannelsPlugin(
+    backend=MemoryChannelsBackend(),
+    max_backlog=1000,
+    backlog_strategy="backoff",
+)

docs/examples/channels/eviction_strategy.py

@@ -0,0 +1,8 @@
+from litestar.channels import ChannelsPlugin
+from litestar.channels.memory import MemoryChannelsBackend
+
+channels = ChannelsPlugin(
+    backend=MemoryChannelsBackend(),
+    max_backlog=1000,
+    backlog_strategy="dropleft",
+)

docs/examples/channels/passing_channels_explicitly.py

@@ -0,0 +1,3 @@
+from litestar.channels import ChannelsPlugin
+
+channels_plugin = ChannelsPlugin(..., channels=["foo", "bar"])

docs/examples/channels/publish_data.py

@@ -0,0 +1 @@
+channels.publish({"message": "Hello"}, "general")

docs/examples/channels/subscribe_method_context_manager.py

@@ -0,0 +1,2 @@
+async with channels.start_subscription(["foo", "bar"]) as subscriber:
+    ...  # do some stuff here

docs/examples/channels/subscribe_method_manually.py

@@ -0,0 +1,5 @@
+subscriber = await channels.subscribe(["foo", "bar"])
+try:
+    ...  # do some stuff here
+finally:
+    await channels.unsubscribe(subscriber)

docs/examples/channels/unsubscribe_method_context_manager.py

@@ -0,0 +1,3 @@
+async with channels.start_subscription(["foo", "bar"]) as subscriber:
+    # do some stuff here
+    await channels.unsubscribe(subscriber, ["foo"])

docs/examples/channels/unsubscribe_method_manually.py

@@ -0,0 +1,3 @@
+subscriber = await channels.subscribe(["foo", "bar"])
+# do some stuff here
+await channels.unsubscribe(subscriber, ["foo"])

docs/examples/cli/app_instance.py

@@ -0,0 +1,7 @@
+import click
+
+from litestar import Litestar
+
+
+@click.command()
+def my_command(app: Litestar) -> None: ...

docs/examples/cli/entry_points.py

@@ -0,0 +1,8 @@
+from setuptools import setup
+
+setup(
+    name="my-litestar-plugin",
+    entry_points={
+        "litestar.commands": ["my_command=my_litestar_plugin.cli:main"],
+    },
+)

docs/examples/cli/info.sh

@@ -0,0 +1 @@
+litestar info

docs/examples/cli/openapi_schema.sh

@@ -0,0 +1 @@
+litestar schema openapi --output my-specs.yml

docs/examples/cli/plugin.py

@@ -0,0 +1,14 @@
+from click import Group
+
+from litestar import Litestar
+from litestar.plugins import CLIPluginProtocol
+
+
+class CLIPlugin(CLIPluginProtocol):
+    def on_cli_init(self, cli: Group) -> None:
+        @cli.command()
+        def is_debug_mode(app: Litestar):
+            print(app.debug)
+
+
+app = Litestar(plugins=[CLIPlugin()])

docs/examples/cli/poetry.toml

@@ -0,0 +1,2 @@
+[tool.poetry.plugins."litestar.commands"]
+my_command = "my_litestar_plugin.cli:main"

docs/examples/cli/reload_dir.sh

@@ -0,0 +1 @@
+litestar run --reload-dir=. --reload-dir=../other-library/src

docs/examples/cli/reload_dir_multiple_directories.sh

@@ -0,0 +1 @@
+ LITESTAR_RELOAD_DIRS=.,../other-library/src

docs/examples/cli/reload_exclude.sh

@@ -0,0 +1 @@
+ litestar run --reload-exclude="*.py" --reload-exclude="*.yml"

docs/examples/cli/reload_exclude_multiple_directories.sh

@@ -0,0 +1 @@
+LITESTAR_RELOAD_EXCLUDES=*.py,*.yml

docs/examples/cli/reload_include.sh

@@ -0,0 +1 @@
+litestar run --reload-include="*.rst" --reload-include="*.yml"

docs/examples/cli/reload_include_multiple_directories.sh

@@ -0,0 +1 @@
+LITESTAR_RELOAD_INCLUDES=*.rst,*.yml

docs/examples/cli/routes.sh

@@ -0,0 +1 @@
+litestar routes

docs/examples/cli/run.sh

@@ -0,0 +1 @@
+litestar run

docs/examples/cli/sessions_clear.sh

@@ -0,0 +1 @@
+litestar sessions clear

docs/examples/cli/sessions_delete.sh

@@ -0,0 +1 @@
+litestar sessions delete cc3debc7-1ab6-4dc8-a220-91934a473717

docs/examples/cli/ssl.sh

@@ -0,0 +1 @@
+litestar run --ssl-certfile=certs/cert.pem --ssl-keyfile=certs/key.pem

docs/examples/cli/ssl_self_signed.sh

@@ -0,0 +1 @@
+litestar run --ssl-certfile=certs/cert.pem --ssl-keyfile=certs/key.pem --create-self-signed-cert

docs/examples/cli/typescript_schema.sh

@@ -0,0 +1 @@
+litestar schema typescript

docs/examples/cli/typescript_schema.ts

@@ -0,0 +1,3 @@
+export namespace API {
+   // ...
+}

docs/examples/cli/typescript_schema_namespace.sh

@@ -0,0 +1 @@
+litestar schema typescript --namespace MyNamespace

docs/examples/cli/typescript_schema_namespace.ts

@@ -0,0 +1,3 @@
+export namespace MyNamespace {
+   // ...
+}

docs/examples/cli/typescript_schema_path.sh

@@ -0,0 +1 @@
+litestar schema typescript --output my-types.ts

docs/examples/data_transfer_objects/define_dto_from_dataclass.py

@@ -0,0 +1,19 @@
+from dataclasses import dataclass
+
+from litestar import get
+from litestar.dto import DataclassDTO, DTOConfig
+
+
+@dataclass
+class MyType:
+    some_field: str
+    another_field: int
+
+
+class MyDTO(DataclassDTO[MyType]):
+    config = DTOConfig(exclude={"another_field"})
+
+
+@get(dto=MyDTO)
+async def handler() -> MyType:
+    return MyType(some_field="some value", another_field=42)

docs/examples/data_transfer_objects/disable_backend_selectively.py

@@ -0,0 +1,12 @@
+from dataclasses import dataclass
+
+from litestar.dto import DataclassDTO, DTOConfig
+
+
+@dataclass
+class Foo:
+    name: str
+
+
+class FooDTO(DataclassDTO[Foo]):
+    config = DTOConfig(experimental_codegen_backend=False)

docs/examples/data_transfer_objects/enabling_backend.py

@@ -0,0 +1,4 @@
+from litestar import Litestar
+from litestar.config.app import ExperimentalFeatures
+
+app = Litestar(experimental_features=[ExperimentalFeatures.DTO_CODEGEN])

docs/examples/data_transfer_objects/factory/enveloping_return_data_1.py

@@ -0,0 +1,10 @@
+from dataclasses import dataclass
+from typing import Generic, List, TypeVar
+
+T = TypeVar("T")
+
+
+@dataclass
+class WithCount(Generic[T]):
+    count: int
+    data: List[T]

docs/examples/data_transfer_objects/factory/enveloping_return_data_2.py

@@ -0,0 +1,7 @@
+from advanced_alchemy.dto import SQLAlchemyDTO
+
+from litestar.dto import DTOConfig
+
+
+class UserDTO(SQLAlchemyDTO[User]):
+    config = DTOConfig(exclude={"password", "created_at"})

docs/examples/data_transfer_objects/factory/enveloping_return_data_3.py

@@ -0,0 +1,44 @@
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Generic, TypeVar
+
+from sqlalchemy.orm import Mapped
+
+from litestar import get
+from litestar.contrib.sqlalchemy.dto import SQLAlchemyDTO
+from litestar.dto import DTOConfig
+
+from .my_lib import Base
+
+T = TypeVar("T")
+
+
+@dataclass
+class WithCount(Generic[T]):
+    count: int
+    data: list[T]
+
+
+class User(Base):
+    name: Mapped[str]
+    password: Mapped[str]
+    created_at: Mapped[datetime]
+
+
+class UserDTO(SQLAlchemyDTO[User]):
+    config = DTOConfig(exclude={"password", "created_at"})
+
+
+@get("/users", dto=UserDTO, sync_to_thread=False)
+def get_users() -> WithCount[User]:
+    return WithCount(
+        count=1,
+        data=[
+            User(
+                id=1,
+                name="Litestar User",
+                password="xyz",
+                created_at=datetime.now(),
+            ),
+        ],
+    )

docs/examples/data_transfer_objects/factory/excluding_fields_2.py

@@ -0,0 +1,9 @@
+config = DTOConfig(
+    exclude={
+        "id",
+        "address.id",
+        "address.street",
+        "pets.0.id",
+        "pets.0.user_id",
+    }
+)

docs/examples/data_transfer_objects/factory/paginated_return_data_1.py

@@ -0,0 +1,18 @@
+from datetime import datetime
+
+from advanced_alchemy.dto import SQLAlchemyDTO
+from sqlalchemy.orm import Mapped
+
+from litestar.dto import DTOConfig
+
+from .my_lib import Base
+
+
+class User(Base):
+    name: Mapped[str]
+    password: Mapped[str]
+    created_at: Mapped[datetime]
+
+
+class UserDTO(SQLAlchemyDTO[User]):
+    config = DTOConfig(exclude={"password", "created_at"})

docs/examples/data_transfer_objects/factory/paginated_return_data_2.py

@@ -0,0 +1,37 @@
+from datetime import datetime
+
+from sqlalchemy.orm import Mapped
+
+from litestar import get
+from litestar.contrib.sqlalchemy.dto import SQLAlchemyDTO
+from litestar.dto import DTOConfig
+from litestar.pagination import ClassicPagination
+
+from .my_lib import Base
+
+
+class User(Base):
+    name: Mapped[str]
+    password: Mapped[str]
+    created_at: Mapped[datetime]
+
+
+class UserDTO(SQLAlchemyDTO[User]):
+    config = DTOConfig(exclude={"password", "created_at"})
+
+
+@get("/users", dto=UserDTO, sync_to_thread=False)
+def get_users() -> ClassicPagination[User]:
+    return ClassicPagination(
+        page_size=10,
+        total_pages=1,
+        current_page=1,
+        items=[
+            User(
+                id=1,
+                name="Litestar User",
+                password="xyz",
+                created_at=datetime.now(),
+            ),
+        ],
+    )

docs/examples/data_transfer_objects/factory/response_return_data_1.py

@@ -0,0 +1,7 @@
+from advanced_alchemy.dto import SQLAlchemyDTO
+
+from litestar.dto import DTOConfig
+
+
+class UserDTO(SQLAlchemyDTO[User]):
+    config = DTOConfig(exclude={"password", "created_at"})

docs/examples/data_transfer_objects/factory/response_return_data_2.py

@@ -0,0 +1,32 @@
+from datetime import datetime
+
+from sqlalchemy.orm import Mapped
+
+from litestar import Response, get
+from litestar.contrib.sqlalchemy.dto import SQLAlchemyDTO
+from litestar.dto import DTOConfig
+
+from .my_lib import Base
+
+
+class User(Base):
+    name: Mapped[str]
+    password: Mapped[str]
+    created_at: Mapped[datetime]
+
+
+class UserDTO(SQLAlchemyDTO[User]):
+    config = DTOConfig(exclude={"password", "created_at"})
+
+
+@get("/users", dto=UserDTO, sync_to_thread=False)
+def get_users() -> Response[User]:
+    return Response(
+        content=User(
+            id=1,
+            name="Litestar User",
+            password="xyz",
+            created_at=datetime.now(),
+        ),
+        headers={"X-Total-Count": "1"},
+    )

docs/examples/data_transfer_objects/individual_dto.py

@@ -0,0 +1,12 @@
+from dataclasses import dataclass
+
+from litestar.dto import DataclassDTO, DTOConfig
+
+
+@dataclass
+class Foo:
+    name: str
+
+
+class FooDTO(DataclassDTO[Foo]):
+    config = DTOConfig(experimental_codegen_backend=True)