docs: move internal code-blocks to docs/examples/**/*.py files to be automatically tested

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,9 @@
+from setuptools import setup
+
+setup(
+    name="my-litestar-plugin",
+    # ..., other setup arguments
+    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, 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,16 @@
+from litestar import get
+
+
+@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,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/paginated_return_data_2.py

@@ -0,0 +1,19 @@
+from litestar import get
+from litestar.pagination import ClassicPagination
+
+
+@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,14 @@
+from litestar import Response, get
+
+
+@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)

docs/examples/debugging/running_litestar_with_pdb_on_exception.py

@@ -0,0 +1 @@
+app = Litestar(pdb_on_exception=True)

docs/examples/dependency_injection/dependency_base.py

@@ -0,0 +1,42 @@
+from litestar import Controller, Litestar, Router, get
+from litestar.di import Provide
+
+
+async def bool_fn() -> bool: ...
+
+
+async def dict_fn() -> dict: ...
+
+
+async def list_fn() -> list: ...
+
+
+async def int_fn() -> int: ...
+
+
+class MyController(Controller):
+    path = "/controller"
+    # on the controller
+    dependencies = {"controller_dependency": Provide(list_fn)}
+
+    # on the route handler
+    @get(path="/handler", dependencies={"local_dependency": Provide(int_fn)})
+    def my_route_handler(
+        self,
+        app_dependency: bool,
+        router_dependency: dict,
+        controller_dependency: list,
+        local_dependency: int,
+    ) -> None: ...
+
+    # on the router
+
+
+my_router = Router(
+    path="/router",
+    dependencies={"router_dependency": Provide(dict_fn)},
+    route_handlers=[MyController],
+)
+
+# on the app
+app = Litestar(route_handlers=[my_router], dependencies={"app_dependency": Provide(bool_fn)})

docs/examples/dependency_injection/dependency_connection.py

@@ -0,0 +1,7 @@
+from dependencies import CONNECTION, app
+
+from litestar.testing import TestClient
+
+with TestClient(app=app) as client:
+    print(client.get("/").json())  # {"open": True}
+    print(CONNECTION)  # {"open": False}

docs/examples/dependency_injection/dependency_keyword_arguments.py

@@ -0,0 +1,20 @@
+from pydantic import UUID4, BaseModel
+
+from litestar import Controller, patch
+from litestar.di import Provide
+
+
+class User(BaseModel):
+    id: UUID4
+    name: str
+
+
+async def retrieve_db_user(user_id: UUID4) -> User: ...
+
+
+class UserController(Controller):
+    path = "/user"
+    dependencies = {"user": Provide(retrieve_db_user)}
+
+    @patch(path="/{user_id:uuid}")
+    async def get_user(self, user: User) -> User: ...