servicekit 2.0.0__tar.gz → 2.0.2__tar.gz

{servicekit-2.0.0 → servicekit-2.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: servicekit
-Version: 2.0.0
+Version: 2.0.2
 Summary: Async SQLAlchemy framework with FastAPI integration - reusable foundation for building data services
 Keywords: fastapi,sqlalchemy,async,database,rest-api,crud,framework
 Author: Morten Hansen
@@ -179,9 +179,10 @@ router = CrudRouter.create(
 )
 ```
 
-`POST` creates only and returns `409 Conflict` for an ID that already exists. `PUT` applies the fields sent: an
-omitted field keeps its value, an explicit `null` clears a nullable field. Collection listings are ordered by ID,
-and pagination is opt-in through `page` (>= 1) and `size` (1-100), which return `422` when out of range.
+`POST` creates only and returns `409 Conflict` for an ID that already exists or for any other database constraint
+violation. `PUT` applies the fields sent: an omitted field keeps its value, an explicit `null` clears a nullable
+field. Collection listings are ordered by ID, and pagination is opt-in through `page` (>= 1) and `size` (1-100),
+which return `422` when out of range.
 
 
 ## Examples

{servicekit-2.0.0 → servicekit-2.0.2}/README.md

@@ -143,9 +143,10 @@ router = CrudRouter.create(
 )
 ```
 
-`POST` creates only and returns `409 Conflict` for an ID that already exists. `PUT` applies the fields sent: an
-omitted field keeps its value, an explicit `null` clears a nullable field. Collection listings are ordered by ID,
-and pagination is opt-in through `page` (>= 1) and `size` (1-100), which return `422` when out of range.
+`POST` creates only and returns `409 Conflict` for an ID that already exists or for any other database constraint
+violation. `PUT` applies the fields sent: an omitted field keeps its value, an explicit `null` clears a nullable
+field. Collection listings are ordered by ID, and pagination is opt-in through `page` (>= 1) and `size` (1-100),
+which return `422` when out of range.
 
 
 ## Examples

{servicekit-2.0.0 → servicekit-2.0.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "servicekit"
-version = "2.0.0"
+version = "2.0.2"
 description = "Async SQLAlchemy framework with FastAPI integration - reusable foundation for building data services"
 readme = "README.md"
 requires-python = ">=3.13,<3.14"

{servicekit-2.0.0 → servicekit-2.0.2}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "servicekit"
-version = "2.0.0"
+version = "2.0.2"
 description = "Async SQLAlchemy framework with FastAPI integration - reusable foundation for building data services"
 readme = "README.md"
 authors = [{ name = "Morten Hansen", email = "morten@dhis2.org" }]

{servicekit-2.0.0 → servicekit-2.0.2}/src/servicekit/__init__.py

@@ -22,6 +22,7 @@ from .exceptions import (
     ServicekitException,
     UnauthorizedError,
     ValidationError,
+    classify_integrity_error,
 )
 from .logging import add_request_context, clear_request_context, configure_logging, get_logger, reset_request_context
 from .manager import BaseManager, LifecycleHooks, Manager
@@ -76,6 +77,7 @@ __all__ = [
     "NotFoundError",
     "ValidationError",
     "ConflictError",
+    "classify_integrity_error",
     "InvalidULIDError",
     "BadRequestError",
     "UnauthorizedError",

{servicekit-2.0.0 → servicekit-2.0.2}/src/servicekit/api/__init__.py

@@ -8,7 +8,7 @@ from .middleware import add_error_handlers, add_logging_middleware, database_err
 from .pagination import PaginationParams, create_paginated_response
 from .router import Router
 from .routers import HealthRouter, HealthState, HealthStatus, JobRouter, MetricsRouter, SystemInfo, SystemRouter
-from .service_builder import BaseServiceBuilder, ServiceInfo
+from .service_builder import BaseServiceBuilder, JobOptions, ServiceInfo
 from .sse import SSE_HEADERS, format_sse_event, format_sse_model_event
 from .utilities import build_location_url, run_app
 
@@ -19,6 +19,7 @@ __all__ = [
     "CrudPermissions",
     # Service builder
     "BaseServiceBuilder",
+    "JobOptions",
     "ServiceInfo",
     # App system
     "App",

{servicekit-2.0.0 → servicekit-2.0.2}/src/servicekit/api/crud.py

@@ -9,7 +9,22 @@ from ulid import ULID
 
 from servicekit.api.router import Router
 from servicekit.manager import Manager
-from servicekit.schemas import PaginatedResponse
+from servicekit.schemas import PaginatedResponse, ProblemDetail
+
+# OpenAPI response documentation shared by CRUD routes
+_CONFLICT_RESPONSES: dict[int | str, dict[str, Any]] = {
+    status.HTTP_409_CONFLICT: {
+        "model": ProblemDetail,
+        "description": "An entity with the supplied id already exists or a database constraint was violated",
+    }
+}
+
+_NOT_FOUND_RESPONSES: dict[int | str, dict[str, Any]] = {
+    status.HTTP_404_NOT_FOUND: {
+        "model": ProblemDetail,
+        "description": "No entity exists with the supplied id",
+    }
+}
 
 # Type alias for manager factory function
 type ManagerFactory[InSchemaT: BaseModel, OutSchemaT: BaseModel] = Callable[..., Manager[InSchemaT, OutSchemaT, ULID]]
@@ -171,7 +186,12 @@ class CrudRouter[InSchemaT: BaseModel, OutSchemaT: BaseModel](Router):
         entity_out_annotation: Any = self.entity_out_type
         router_prefix = self.router.prefix
 
-        @self.router.post("", status_code=status.HTTP_201_CREATED, response_model=entity_out_annotation)
+        @self.router.post(
+            "",
+            status_code=status.HTTP_201_CREATED,
+            response_model=entity_out_annotation,
+            responses=_CONFLICT_RESPONSES,
+        )
         async def create(
             entity_in: InSchemaT,
             request: Request,
@@ -218,7 +238,7 @@ class CrudRouter[InSchemaT: BaseModel, OutSchemaT: BaseModel](Router):
         entity_out_annotation: Any = self.entity_out_type
         router_prefix = self.router.prefix
 
-        @self.router.get("/{entity_id}", response_model=entity_out_annotation)
+        @self.router.get("/{entity_id}", response_model=entity_out_annotation, responses=_NOT_FOUND_RESPONSES)
         async def find_by_id(
             entity_id: str,
             manager: Manager[InSchemaT, OutSchemaT, ULID] = manager_dependency,
@@ -242,7 +262,7 @@ class CrudRouter[InSchemaT: BaseModel, OutSchemaT: BaseModel](Router):
         entity_out_annotation: Any = self.entity_out_type
         router_prefix = self.router.prefix
 
-        @self.router.put("/{entity_id}", response_model=entity_out_annotation)
+        @self.router.put("/{entity_id}", response_model=entity_out_annotation, responses=_NOT_FOUND_RESPONSES)
         async def update(
             entity_id: str,
             entity_in: InSchemaT,
@@ -266,7 +286,7 @@ class CrudRouter[InSchemaT: BaseModel, OutSchemaT: BaseModel](Router):
     def _register_delete_route(self, manager_dependency: Any, manager_annotation: Any) -> None:
         router_prefix = self.router.prefix
 
-        @self.router.delete("/{entity_id}", status_code=status.HTTP_204_NO_CONTENT)
+        @self.router.delete("/{entity_id}", status_code=status.HTTP_204_NO_CONTENT, responses=_NOT_FOUND_RESPONSES)
         async def delete_by_id(
             entity_id: str,
             manager: Manager[InSchemaT, OutSchemaT, ULID] = manager_dependency,

{servicekit-2.0.0 → servicekit-2.0.2}/src/servicekit/api/middleware.py

@@ -5,12 +5,13 @@ from typing import Any, Awaitable, Callable
 
 from fastapi import Request, Response, status
 from fastapi.encoders import jsonable_encoder
+from fastapi.exceptions import RequestValidationError
 from fastapi.responses import JSONResponse
 from pydantic import ValidationError as PydanticValidationError
 from starlette.middleware.base import BaseHTTPMiddleware
 from ulid import ULID
 
-from servicekit.exceptions import ErrorType, ServicekitException
+from servicekit.exceptions import ErrorType, ServicekitException, classify_integrity_error
 from servicekit.logging import add_request_context, get_logger, reset_request_context
 from servicekit.schemas import ProblemDetail
 
@@ -112,6 +113,8 @@ async def database_error_handler(request: Request, exc: Exception) -> JSONRespon
     )
 
     if isinstance(exc, IntegrityError):
+        constraint = classify_integrity_error(exc)
+        constraint_extension: dict[str, Any] = {"constraint": constraint} if constraint is not None else {}
         problem = ProblemDetail(
             type=ErrorType.CONFLICT,
             title="Conflict",
@@ -119,6 +122,7 @@ async def database_error_handler(request: Request, exc: Exception) -> JSONRespon
             detail="The request conflicts with existing data",
             instance=str(request.url),
             trace_id=trace_id,
+            **constraint_extension,
         )
     else:
         problem = ProblemDetail(
@@ -138,9 +142,11 @@ async def database_error_handler(request: Request, exc: Exception) -> JSONRespon
 
 
 async def validation_error_handler(request: Request, exc: Exception) -> JSONResponse:
-    """Handle validation errors and return RFC 9457 Problem Details with structured errors."""
+    """Handle Pydantic and FastAPI request validation errors as RFC 9457 Problem Details with structured errors."""
     trace_id = str(ULID())
-    errors = jsonable_encoder(exc.errors()) if isinstance(exc, PydanticValidationError) else None
+    errors = (
+        jsonable_encoder(exc.errors()) if isinstance(exc, (PydanticValidationError, RequestValidationError)) else None
+    )
 
     logger.warning(
         "validation.error",
@@ -213,6 +219,7 @@ def add_error_handlers(app: Any) -> None:
     app.add_exception_handler(SQLAlchemyError, database_error_handler)
     app.add_exception_handler(IntegrityError, database_error_handler)
     app.add_exception_handler(PydanticValidationError, validation_error_handler)
+    app.add_exception_handler(RequestValidationError, validation_error_handler)
 
 
 def add_logging_middleware(app: Any) -> None:

{servicekit-2.0.0 → servicekit-2.0.2}/src/servicekit/api/routers/job.py

@@ -7,12 +7,13 @@ from collections.abc import AsyncGenerator, Callable
 from typing import Annotated, Any
 
 import ulid
-from fastapi import Depends, HTTPException, Query, status
+from fastapi import Depends, Query, status
 from fastapi.responses import Response, StreamingResponse
 from pydantic import TypeAdapter
 
 from servicekit.api.router import Router
 from servicekit.api.sse import SSE_HEADERS, format_sse_model_event
+from servicekit.exceptions import InvalidULIDError, NotFoundError
 from servicekit.scheduler import Scheduler
 from servicekit.schemas import JobRecord, JobStatus
 
@@ -57,23 +58,23 @@ class JobRouter(Router):
             job_id: str,
             scheduler: Scheduler = scheduler_dependency,
         ) -> JobRecord:
+            ulid_id = self._parse_job_id(job_id)
             try:
-                ulid_id = ULID.from_str(job_id)
                 return await scheduler.get_record(ulid_id)
-            except (ValueError, KeyError):
-                raise HTTPException(status_code=404, detail="Job not found")
+            except KeyError as error:
+                raise self._job_not_found(job_id) from error
 
         @self.router.delete("/{job_id}", summary="Cancel and delete job", status_code=status.HTTP_204_NO_CONTENT)
         async def delete_job(
             job_id: str,
             scheduler: Scheduler = scheduler_dependency,
         ) -> Response:
+            ulid_id = self._parse_job_id(job_id)
             try:
-                ulid_id = ULID.from_str(job_id)
                 await scheduler.delete(ulid_id)
-                return Response(status_code=status.HTTP_204_NO_CONTENT)
-            except (ValueError, KeyError):
-                raise HTTPException(status_code=404, detail="Job not found")
+            except KeyError as error:
+                raise self._job_not_found(job_id) from error
+            return Response(status_code=status.HTTP_204_NO_CONTENT)
 
         @self.router.get(
             "/{job_id}/$stream",
@@ -87,16 +88,13 @@ class JobRouter(Router):
         ) -> StreamingResponse:
             """Stream real-time job status updates using Server-Sent Events."""
             # Validate job_id format
-            try:
-                ulid_id = ULID.from_str(job_id)
-            except ValueError:
-                raise HTTPException(status_code=400, detail="Invalid job ID format")
+            ulid_id = self._parse_job_id(job_id)
 
             # Check job exists before starting stream
             try:
                 await scheduler.get_record(ulid_id)
-            except KeyError:
-                raise HTTPException(status_code=404, detail="Job not found")
+            except KeyError as error:
+                raise self._job_not_found(job_id) from error
 
             # SSE event generator
             async def event_stream() -> AsyncGenerator[bytes, None]:
@@ -124,3 +122,17 @@ class JobRouter(Router):
                 media_type="text/event-stream",
                 headers=SSE_HEADERS,
             )
+
+    def _parse_job_id(self, job_id: str) -> ULID:
+        """Parse a job ID as a ULID, raising InvalidULIDError when malformed."""
+        try:
+            return ULID.from_str(job_id)
+        except ValueError as error:
+            raise InvalidULIDError(
+                f"Invalid job ID format: {job_id}",
+                instance=f"{self.router.prefix}/{job_id}",
+            ) from error
+
+    def _job_not_found(self, job_id: str) -> NotFoundError:
+        """Build the not-found error for a missing job."""
+        return NotFoundError(f"Job with id {job_id} not found", instance=f"{self.router.prefix}/{job_id}")

{servicekit-2.0.0 → servicekit-2.0.2}/src/servicekit/api/service_builder.py

@@ -54,7 +54,7 @@ class _SystemOptions:
 
 
 @dataclass(frozen=True)
-class _JobOptions:
+class JobOptions:
     """Configuration for job scheduler endpoints."""
 
     prefix: str
@@ -63,6 +63,10 @@ class _JobOptions:
     shutdown_timeout: float
 
 
+# Backwards-compatible alias for the previously private name
+_JobOptions = JobOptions
+
+
 @dataclass(frozen=True)
 class _AuthOptions:
     """Configuration for API key authentication."""
@@ -153,7 +157,7 @@ class BaseServiceBuilder:
         self._include_logging = include_logging
         self._health_options: _HealthOptions | None = None
         self._system_options: _SystemOptions | None = None
-        self._job_options: _JobOptions | None = None
+        self._job_options: JobOptions | None = None
         self._auth_options: _AuthOptions | None = None
         self._monitoring_options: _MonitoringOptions | None = None
         self._registration_options: _RegistrationOptions | None = None
@@ -247,7 +251,7 @@ class BaseServiceBuilder:
         shutdown_timeout: float = 10.0,
     ) -> Self:
         """Add job scheduler endpoints."""
-        self._job_options = _JobOptions(
+        self._job_options = JobOptions(
             prefix=prefix,
             tags=list(tags) if tags is not None else ["Jobs"],
             max_concurrency=max_concurrency,
@@ -776,7 +780,7 @@ class BaseServiceBuilder:
 
         return lifespan
 
-    def _create_scheduler(self, job_options: _JobOptions) -> Scheduler:
+    def _create_scheduler(self, job_options: JobOptions) -> Scheduler:
         """Create the scheduler used by the application (override in subclasses)."""
         from servicekit.scheduler import InMemoryScheduler
 

{servicekit-2.0.0 → servicekit-2.0.2}/src/servicekit/exceptions.py

@@ -137,3 +137,18 @@ class ForbiddenError(ServicekitException):
             instance=instance,
             **extensions,
         )
+
+
+def classify_integrity_error(error: Exception) -> str | None:
+    """Classify a database integrity error as a safe constraint name, or None when unrecognized."""
+    driver_error = getattr(error, "orig", None)
+    message = str(driver_error if driver_error is not None else error).upper()
+    if "FOREIGN KEY" in message:
+        return "foreign_key"
+    if "UNIQUE" in message:
+        return "unique"
+    if "NOT NULL" in message:
+        return "not_null"
+    if "CHECK" in message:
+        return "check"
+    return None

{servicekit-2.0.0 → servicekit-2.0.2}/src/servicekit/manager.py

@@ -8,7 +8,7 @@ from typing import TYPE_CHECKING, Iterable, Sequence
 from pydantic import BaseModel
 from sqlalchemy.exc import IntegrityError
 
-from servicekit.exceptions import ConflictError
+from servicekit.exceptions import ConflictError, classify_integrity_error
 from servicekit.repository import BaseRepository
 
 if TYPE_CHECKING:
@@ -154,7 +154,11 @@ class BaseManager[ModelT, InSchemaT: BaseModel, OutSchemaT: BaseModel, IdT](
             await self.repo.commit()
         except IntegrityError as e:
             await self.repo.rollback()
-            raise ConflictError(f"Entity with id {entity_id} already exists") from e
+            if entity_id is not None and await self.repo.exists_by_id(entity_id):
+                raise ConflictError(f"Entity with id {entity_id} already exists") from e
+            constraint = classify_integrity_error(e)
+            extensions = {"constraint": constraint} if constraint is not None else {}
+            raise ConflictError("Entity violates a database constraint", **extensions) from e
         await self.repo.refresh_many([entity])
         await self.post_save(entity)
         return self._to_output_schema(entity)