csrd.service
Service-layer boilerplate for the CSRD pattern (Controller → Service → Repository / Delegate).
What it provides
| Component | Purpose |
|---|---|
BaseService |
Lightweight base class with per-class logger and request-context accessors (current_user(), current_request_id()) |
ServiceError |
Base domain exception — keeps business logic free of HTTPException |
NotFoundError |
404 — resource doesn't exist |
ConflictError |
409 — duplicate, version mismatch, etc. |
ValidationError |
422 — business-rule validation (not schema validation) |
AuthorizationError |
403 — authenticated user lacks permission |
DownstreamError |
502 — a delegate call to another service failed |
service_exception_handler |
FastAPI handler that maps ServiceError and all other unhandled exceptions → structured APIErrorResponse JSON |
Consumer Feature Matrix (BaseService + ServiceError)
| Capability area | Common expectation | Actual support | How to use / notes |
|---|---|---|---|
| Request context access | Service can read current user and request id | ✅ Built-in | BaseService.current_user() and BaseService.current_request_id() |
| Service base class | Lightweight base for domain services | ✅ Built-in | Inherit from BaseService; inject repo/delegate dependencies in your constructor |
| Domain error taxonomy | Business errors map to consistent HTTP statuses | ✅ Built-in | Use NotFoundError (404), ConflictError (409), ValidationError (422), AuthorizationError (403), DownstreamError (502) |
| Structured API error responses | Service and unhandled exceptions become API error payloads | ✅ Built-in (with registration) | Register service_exception_handler for Exception |
| Per-error status override | Override default status code per raise | ✅ Built-in | raise ValidationError(..., status_code=409) |
| Error metadata | Include detail/code fields for clients | ✅ Built-in | detail and code are preserved by the handler |
| Logging integration | Auto logging from service methods | ⚙️ Via composition | Mix in csrd.logging.LoggingMixin; not part of BaseService itself |
| Transport-agnostic domain logic | Avoid HTTPException in business layer |
✅ Built-in pattern | Raise ServiceError subclasses and keep HTTP concerns in handler layer |
| Dependency injection wiring | FastAPI DI helper exists in package | ⚙️ Pattern-based | Use your own factory + Depends; package documents the pattern |
| Transactions / unit-of-work | Automatic transactional boundaries | ❌ Not built-in | Handle in repository/DB layer |
| Idempotency utilities | Built-in idempotency keys/replay protection | ❌ Not built-in | Implement per endpoint/service policy |
| Policy engine / RBAC framework | Full authorization policy runtime | ❌ Not built-in | Use claim checks in service code and/or external policy layer |
Dependency tier
Tier 1 (standalone) csrd.models · csrd.lifespan · csrd.context
Tier 2 (uses Tier 1) csrd.delegate csrd.repository csrd.service
Tier 3 (uses Tier 1+2) csrd.versioning
csrd.service depends on csrd.context and csrd.models only. It does not import csrd.repository or csrd.delegate — your services accept those as constructor params.
Quick start
from csrd.service import BaseService, NotFoundError, DownstreamError
class OrderService(BaseService):
def __init__(self, repo: OrderRepository, payments: PaymentsDelegate):
super().__init__()
self._repo = repo
self._payments = payments
async def get_order(self, order_id: int) -> Order:
order = await self._repo.get_by_id(order_id)
if order is None:
raise NotFoundError("Order not found", detail=f"order_id={order_id}")
return order
async def place_order(self, cart: Cart) -> Order:
order = await self._repo.create(cart)
try:
await self._payments.charge(order)
except Exception as exc:
raise DownstreamError("Payment failed", cause=exc) from exc
return order
Register the exception handler
With csrd.versioning:
from csrd.service import service_exception_handler
from csrd.versioning import VersionedApiConfig
configure_versioned_api(
app,
version_mapping=VERSIONS,
config=VersionedApiConfig(
ex_handlers=[(Exception, service_exception_handler)],
),
)
Or on a plain FastAPI app:
app.add_exception_handler(Exception, service_exception_handler)
Wire into FastAPI DI
from functools import cache
from typing import Annotated
from fastapi import Depends
@cache
def order_service_factory(repo: OrderRepository, payments: PaymentsDelegate):
return OrderService(repo, payments)
OrderServiceDep = Annotated[OrderService, Depends(order_service_factory)]
# In your endpoint:
@router.get("/orders/{order_id}")
async def get_order(service: OrderServiceDep, order_id: int):
return await service.get_order(order_id)
Installation
uv add csrd-service # or: pip install csrd-service
1 maintainer
Metadata
1 maintainer
Release files for csrd-service 0.5.30
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| csrd_service-0.5.30.tar.gz | 8.7 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| csrd_service-0.5.30-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 16.2 kB
Release files / csrd_service-0.5.30.tar.gz
| Download URL | csrd_service-0.5.30.tar.gz |
|---|---|
| Size | 8.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
8e824c807117ab5eb46c1518d2992de5845b9722c92b13dd3c8a433997f028de
|
|
BLAKE2b-256 checksum How to use checksums |
f882b4e341d01f656afe1d064981e5438348a37bcd28cace4c372d033a595107
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 26, 2026.
Transparency logRelease files / csrd_service-0.5.30-py3-none-any.whl
| Download URL | csrd_service-0.5.30-py3-none-any.whl |
|---|---|
| Size | 7.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
5f63df748240be394bac0a08fce677aa2b0dab42dde3acc5419dbcaedd2b9db5
|
|
BLAKE2b-256 checksum How to use checksums |
316eee98c4eeea543595be503e56000f1c98920ea7bb8c1bb57753026e3e1f42
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 26, 2026.
Transparency log
