litestar-autowire 0.1.0

Package-based route, listener, and task discovery for Litestar

Litestar Autowire

Domain package discovery for Litestar applications.

litestar-autowire lets a Litestar app treat each feature or bounded context as a small Python package. Group the domain's controllers, listeners, and jobs together, then wire the domain root into the app once.

Use it when your app has a domains/ package and each domain owns its Litestar surface:

my_app/
  domains/
    accounts/
      controllers.py
      events.py
      jobs.py
    billing/
      controllers.py

Installation

pip install litestar-autowire

Optional integrations:

pip install "litestar-autowire[dishka]"
pip install "litestar-autowire[queues]"

Quick Start

Define normal Litestar controllers inside a domain package:

# my_app/domains/accounts/controllers.py
from litestar import Controller, get


class AccountController(Controller):
    path = "/accounts"

    @get("/", sync_to_thread=False)
    def list_accounts(self) -> dict[str, str]:
        return {"status": "ok"}

Register the domain root once:

from litestar import Litestar
from litestar_autowire import AutowireConfig, AutowirePlugin

app = Litestar(
    plugins=[
        AutowirePlugin(
            AutowireConfig(domain_packages=["my_app.domains"]),
        )
    ],
)

Autowire checks the configured domain package root and its direct child domain packages for these module names:

• controllers: controllers, routes, controller, route
• listeners: events, listeners
• queue tasks: jobs

With log_discovered=True, startup logs include the number of loaded controllers, domains, listeners, and tasks. Debug logs include the controller inventory grouped by domain.

Extensions

Built-in integrations use string aliases:

AutowireConfig(
    domain_packages=["my_app.domains"],
    extensions=["dishka", "queues"],
)

• dishka: wrap discovered controllers in Dishka's Litestar router. Configure Dishka separately with setup_dishka(...).
• queues: import task modules through litestar_queues.discover_tasks. Configure QueuePlugin separately in the Litestar app.

Unknown string aliases raise ValueError so typos do not silently disable an integration. For custom behavior, pass an extension object instead:

from litestar.config.app import AppConfig
from litestar_autowire import AutowireConfig


class InventoryExtension:
    name = "inventory"

    def on_autowire(self, app_config: AppConfig, config: AutowireConfig) -> AppConfig:
        app_config.state["autowire_domain_packages"] = config.domain_packages
        return app_config


config = AutowireConfig(
    domain_packages=["my_app.domains"],
    extensions=[InventoryExtension()],
)

Custom extension names cannot reuse built-in names.

Development

uv sync --all-extras --dev
make lint
make test
make docs