Dj Services

Services + svcs Dependency Injection

This project separates Django's framework concerns from business logic using a plain service layer, wired with the svcs service locator. The result:

• Views are one-liners. They pull a wired service and call a method.
• Services contain the business logic. They take repositories (and other services) via __init__, call methods on them, and return DTOs.
• Services never import Django ORM or models. Every test can run without a database.
• One registry, one get[T]() helper. The same call works in views, tasks, commands, anywhere.

Why svcs Instead of Module-Level Singletons or a Custom Container

• svcs is a tiny, typed, well-maintained service locator — no metaclasses, no decorators, no framework coupling.
• Factories are lazy: a service is constructed only when something asks for it.
• Generic get[T](type[T]) -> T preserves types through IDE/type-checker inference.
• Swapping an implementation in tests is a one-line factory override.
• No import-order gymnastics: the registry is populated once at startup and then used by name.

The Registry — src/project/services.py

import svcs

from products.repositories.product import ProductRepository
from products.services.product import ProductService
from orders.repositories.order import OrderRepository
from orders.services.order import OrderService

registry = svcs.Registry()


# --- Services (factories pull repos from the container) ------------------
def _product_service_factory(container: svcs.Container) -> ProductService:
    repo = container.get(ProductRepository)
    return ProductService(repo)


def _order_service_factory(container: svcs.Container) -> OrderService:
    repo = container.get(OrderRepository)
    product_repo = container.get(ProductRepository)
    return OrderService(repo, product_repo)


def register_services(registry: svcs.Registry) -> None:
    """Register every real factory. Tests re-run this to restore overrides."""
    # --- Repositories -----------------------------------------------------
    registry.register_factory(ProductRepository, ProductRepository)
    registry.register_factory(OrderRepository, OrderRepository)
    # --- Services ---------------------------------------------------------
    registry.register_factory(ProductService, _product_service_factory)
    registry.register_factory(OrderService, _order_service_factory)


register_services(registry)


def get[T](service_type: type[T]) -> T:
    """Resolve a service from the registry. Works anywhere — views, tasks, commands, tests."""
    return svcs.Container(registry).get(service_type)

Patterns to follow:

• All registrations live in register_services(registry). Called once at import; tests re-run it on teardown to restore any overridden factories through the public API.
• Repositories register themselves. Use register_factory(Repo, Repo) — the class is its own factory because repositories take no constructor arguments.
• Services register via a named factory. _<entity>_service_factory(container) resolves every dependency from the container and hands it to the service's __init__. No hidden imports, no module-level singletons.
• Register in dependency order. Repos before services, lower-level services before higher-level ones. svcs doesn't enforce this, but it keeps the file readable.
• One registry per project. Don't create ad-hoc registries — everything goes through project.services.registry.

Writing a Service

File: src/<app>/services/<entity>.py

from decimal import Decimal
from typing import List

from ..dtos.product import ProductDTO
from ..repositories.product import ProductRepository


class ProductService:
    def __init__(self, repo: ProductRepository):
        self.repo = repo

    def create_product(self, name: str, price: Decimal, stock: int) -> ProductDTO:
        return self.repo.create(name=name, price=price, stock=stock)

    def get_product(self, product_id: str) -> ProductDTO:
        return self.repo.get_by_id(product_id)

    def list_products(self) -> List[ProductDTO]:
        return self.repo.list_all()

Rules:

• Dependencies come in through __init__. The service never instantiates its own repositories or services. If a service needs another service, pass it in.
• Zero ORM. No .objects, no F() / Q(), no model imports, no select_related. All database access goes through a repository.
• Every public method returns a DTO or list[DTO]. Never a model instance, never a queryset.
• ID arguments are str. See the dj-prefixed-ulids skill.
• Business rules live here. Validation, orchestration across repositories, invariant checks, error raising — all of it.
• Services are stateless. They hold references to their dependencies and nothing else. No caches, no counters, no module-level state.
• Raise plain exceptions. Use ValueError, PermissionError, domain-specific exceptions — not Http404 or anything Django-flavored. The view layer turns them into HTTP responses.

Cross-Entity Logic

When a service method touches more than one aggregate — e.g. creating an order that decrements product stock — inject both repositories and orchestrate them. Example from OrderService:

class OrderService:
    def __init__(self, repo: OrderRepository, product_repo: ProductRepository):
        self.repo = repo
        self.product_repo = product_repo

    def create_order(self, items: List[Dict[str, Any]]) -> OrderDTO:
        for item in items:
            product = self.product_repo.get_by_id(item["product_id"])
            if product.stock < item["quantity"]:
                raise ValueError(
                    f"Insufficient stock for product {product.name}: "
                    f"requested {item['quantity']}, available {product.stock}"
                )

        order = self.repo.create(items=items)

        for item in items:
            self.product_repo.decrement_stock(item["product_id"], item["quantity"])

        return order

Notes:

• The service orchestrates two repositories but touches zero ORM.
• If a multi-repo write needs atomicity, wrap it in with transaction.atomic(): — that's one of the very few django.db imports allowed in a service.
• Never call another service from inside a service unless that service is explicitly injected. No hidden get(...) calls inside service methods.

Resolving a Service