modwire-hex

Explicit dependency-injection conventions for hexagonal Django applications, built on Wireup.

Install

pip install modwire-hex

The framework keeps the container at the composition root. Domain and application code use ordinary, type-annotated constructor dependencies.

Domain code may use DomainError for business-rule failures. It must not contain HTTP status codes, response shapes, Django types, or DI concerns.

from modwire_hex import DomainError


class OrderCannotRequestCredit(DomainError):
    pass

from modwire_hex import Containers, Module, Providers


class Payments:
    def charge(self, amount: int) -> None: ...


class StripePayments(Payments):
    def charge(self, amount: int) -> None:
        ...


class PlaceOrder:
    def __init__(self, payments: Payments) -> None:
        self.payments = payments


orders = Module(
    "orders",
    providers=[
        Providers.service(PlaceOrder, None),
        Providers.bind(Payments, StripePayments, "singleton", None),
    ],
)

container = Containers.create_sync((orders,), None)
with container.enter_scope() as scope:
    place_order = scope.get(PlaceOrder)

See ADR 0001 for the architecture, conventions, and delivery sequence.

Django integration

Compose a Django process through one explicit application object:

from modwire_hex import DjangoApplication

from .orders.wiring import orders


application = DjangoApplication(modules=(orders,))

Configure the framework and its Ninja Extra API in Django settings:

INSTALLED_APPS = [
    "modwire_hex.django.apps.ModwireConfig",
]

MIDDLEWARE = [
    "modwire_hex.django.middleware.RequestScopeMiddleware",
]

MODWIRE = {
    "APPLICATION": "myproject.wiring:application",
    "NINJA": {"title": "My Project API", "version": "1.0.0"},
}

Mount the framework API once. Ninja Extra discovers controllers from installed HTTP adapter apps:

from django.urls import path

from modwire_hex.django import DjangoNinja


urlpatterns = [path("api/", DjangoNinja.api().urls)]

At an HTTP boundary, resolve only use cases from the active request scope:

from modwire_hex.django import DjangoRequest


place_order = DjangoRequest.resolve(request, PlaceOrder)

DjangoRepository is a base for outbound adapters. It centralizes generic load and create-or-update persistence mechanics; each context repository owns its key, lookup, record mapping, and absence semantics.