servicekit 1.0.0__tar.gz → 2.0.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: servicekit
-Version: 1.0.0
+Version: 2.0.0
 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
@@ -89,7 +89,7 @@ servicekit/
 ├── repository.py     # Repository, BaseRepository
 ├── manager.py        # Manager, BaseManager
 ├── schemas.py        # EntityIn, EntityOut, PaginatedResponse
-├── scheduler.py      # JobScheduler, AIOJobScheduler
+├── scheduler.py      # Scheduler, InMemoryScheduler
 ├── exceptions.py     # Error classes
 ├── logging.py        # Structured logging
 ├── types.py          # ULIDType, JsonSafe
@@ -122,6 +122,32 @@ app = (
 )
 ```
 
+### Database Migrations
+
+File-based databases run Alembic migrations on `init()` by default; in-memory databases create tables
+directly from the ORM metadata. The migration bundled with servicekit is a framework baseline: it creates
+only the `alembic_version` table and no application tables. Applications that define their own entities must
+either point migrations at their own migration directory or disable migrations and create tables directly.
+
+```python
+from pathlib import Path
+
+from servicekit import SqliteDatabaseBuilder, get_alembic_dir
+
+# Application-owned migrations
+database = (
+    SqliteDatabaseBuilder.from_file("app.db")
+    .with_migrations(enabled=True, alembic_dir=Path("alembic"))
+    .build()
+)
+
+# No migrations - create tables directly from ORM metadata
+database = SqliteDatabaseBuilder.from_file("app.db").with_migrations(enabled=False).build()
+
+# Path to the migration environment shipped inside the servicekit package
+bundled_migrations = get_alembic_dir()
+```
+
 ### Repository Pattern
 
 ```python
@@ -153,6 +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.
+
 
 ## Examples
 
@@ -172,7 +202,8 @@ See `docs/` for comprehensive guides and API reference.
 
 ```bash
 make test      # Run tests
-make lint      # Run linter
+make format    # Format code and apply lint fixes
+make lint      # Check formatting, linting and types
 make coverage  # Test coverage
 ```
 

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

@@ -53,7 +53,7 @@ servicekit/
 ├── repository.py     # Repository, BaseRepository
 ├── manager.py        # Manager, BaseManager
 ├── schemas.py        # EntityIn, EntityOut, PaginatedResponse
-├── scheduler.py      # JobScheduler, AIOJobScheduler
+├── scheduler.py      # Scheduler, InMemoryScheduler
 ├── exceptions.py     # Error classes
 ├── logging.py        # Structured logging
 ├── types.py          # ULIDType, JsonSafe
@@ -86,6 +86,32 @@ app = (
 )
 ```
 
+### Database Migrations
+
+File-based databases run Alembic migrations on `init()` by default; in-memory databases create tables
+directly from the ORM metadata. The migration bundled with servicekit is a framework baseline: it creates
+only the `alembic_version` table and no application tables. Applications that define their own entities must
+either point migrations at their own migration directory or disable migrations and create tables directly.
+
+```python
+from pathlib import Path
+
+from servicekit import SqliteDatabaseBuilder, get_alembic_dir
+
+# Application-owned migrations
+database = (
+    SqliteDatabaseBuilder.from_file("app.db")
+    .with_migrations(enabled=True, alembic_dir=Path("alembic"))
+    .build()
+)
+
+# No migrations - create tables directly from ORM metadata
+database = SqliteDatabaseBuilder.from_file("app.db").with_migrations(enabled=False).build()
+
+# Path to the migration environment shipped inside the servicekit package
+bundled_migrations = get_alembic_dir()
+```
+
 ### Repository Pattern
 
 ```python
@@ -117,6 +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.
+
 
 ## Examples
 
@@ -136,7 +166,8 @@ See `docs/` for comprehensive guides and API reference.
 
 ```bash
 make test      # Run tests
-make lint      # Run linter
+make format    # Format code and apply lint fixes
+make lint      # Check formatting, linting and types
 make coverage  # Test coverage
 ```
 

servicekit-2.0.0/pyproject.toml

@@ -0,0 +1,180 @@
+[project]
+name = "servicekit"
+version = "2.0.0"
+description = "Async SQLAlchemy framework with FastAPI integration - reusable foundation for building data services"
+readme = "README.md"
+requires-python = ">=3.13,<3.14"
+keywords = [
+    "fastapi",
+    "sqlalchemy",
+    "async",
+    "database",
+    "rest-api",
+    "crud",
+    "framework",
+]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.13",
+    "Framework :: FastAPI",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Database",
+]
+dependencies = [
+    "aiosqlite>=0.21.0",
+    "alembic>=1.17.0",
+    "fastapi[standard]>=0.136.3",
+    "gunicorn>=23.0.0",
+    "opentelemetry-api>=1.37.0",
+    "opentelemetry-exporter-prometheus>=0.58b0",
+    "opentelemetry-instrumentation-fastapi>=0.58b0",
+    "opentelemetry-instrumentation-sqlalchemy>=0.58b0",
+    "opentelemetry-sdk>=1.37.0",
+    "pydantic>=2.12.0",
+    "python-ulid>=3.1.0",
+    "sqlalchemy[asyncio]>=2.0.43",
+    "starlette>=1.0.1",
+    "structlog>=24.4.0",
+]
+
+[[project.authors]]
+name = "Morten Hansen"
+email = "morten@dhis2.org"
+
+[project.license]
+text = "AGPL-3.0-or-later"
+
+[project.optional-dependencies]
+
+[project.urls]
+Homepage = "https://github.com/dhis2-chap/servicekit"
+Repository = "https://github.com/dhis2-chap/servicekit"
+Issues = "https://github.com/dhis2-chap/servicekit/issues"
+Documentation = "https://dhis2-chap.github.io/servicekit"
+
+[dependency-groups]
+dev = [
+    "coverage[toml]>=7.13.2",
+    "mypy>=1.19.1",
+    "pytest>=9.0.2",
+    "pytest-cov>=5.0.0",
+    "pytest-asyncio>=1.2.0",
+    "ruff>=0.14.14",
+    "pyright>=1.1.408",
+    "mkdocs>=1.6.0",
+    "mkdocs-material>=9.7.1",
+    "mkdocstrings[python]>=1.0.2",
+    "httpx2>=2.4.0",
+]
+
+[build-system]
+requires = ["uv_build>=0.9.0,<0.12.0"]
+build-backend = "uv_build"
+
+[tool.ruff]
+target-version = "py313"
+line-length = 120
+
+[tool.ruff.lint]
+fixable = ["ALL"]
+select = [
+    "E",
+    "W",
+    "F",
+    "I",
+    "D",
+]
+ignore = [
+    "D203",
+    "D213",
+]
+
+[tool.ruff.lint.isort]
+known-third-party = ["alembic"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = ["D"]
+"**/__init__.py" = ["D104"]
+"src/**/*.py" = [
+    "D102",
+    "D105",
+    "D107",
+]
+"examples/**/*.py" = []
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+skip-magic-trailing-comma = false
+docstring-code-format = true
+docstring-code-line-length = "dynamic"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+norecursedirs = [
+    "examples",
+    ".git",
+    ".venv",
+    "__pycache__",
+]
+
+[tool.coverage.run]
+branch = true
+dynamic_context = "test_function"
+relative_files = true
+source = ["servicekit"]
+
+[tool.coverage.report]
+exclude_also = ["if TYPE_CHECKING:"]
+precision = 2
+show_missing = true
+skip_covered = true
+
+[tool.mypy]
+python_version = "3.13"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+check_untyped_defs = true
+disallow_any_unimported = true
+no_implicit_optional = true
+warn_unused_ignores = true
+strict_equality = true
+mypy_path = ["src"]
+
+[[tool.mypy.overrides]]
+module = "tests.*"
+disallow_untyped_defs = false
+
+[[tool.mypy.overrides]]
+module = "examples.*"
+ignore_missing_imports = true
+disallow_untyped_defs = false
+ignore_errors = true
+
+[tool.pyright]
+include = [
+    "src",
+    "tests",
+    "examples",
+]
+pythonVersion = "3.13"
+typeCheckingMode = "strict"
+useLibraryCodeForTypes = true
+reportPrivateUsage = false
+reportUnusedFunction = false
+reportUnknownMemberType = false
+reportUnknownArgumentType = false
+reportUnknownLambdaType = false
+reportUnknownParameterType = false
+reportUnknownVariableType = false
+reportMissingTypeArgument = false
+reportMissingTypeStubs = false
+reportMissingImports = "none"
+reportMissingModuleSource = "none"

servicekit-1.0.0/pyproject.toml → servicekit-2.0.0/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "servicekit"
-version = "1.0.0"
+version = "2.0.0"
 description = "Async SQLAlchemy framework with FastAPI integration - reusable foundation for building data services"
 readme = "README.md"
 authors = [{ name = "Morten Hansen", email = "morten@dhis2.org" }]
@@ -77,6 +77,9 @@ fixable = ["ALL"]
 select = ["E", "W", "F", "I", "D"]
 ignore = ["D203", "D213"]
 
+[tool.ruff.lint.isort]
+known-third-party = ["alembic"]
+
 [tool.ruff.lint.pydocstyle]
 convention = "google"
 

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

@@ -11,7 +11,7 @@ except Exception:
     __version__ = "unknown"
 
 # Base infrastructure (framework-agnostic)
-from .database import Database, SqliteDatabase, SqliteDatabaseBuilder
+from .database import Database, SqliteDatabase, SqliteDatabaseBuilder, get_alembic_dir
 from .exceptions import (
     BadRequestError,
     ConflictError,
@@ -47,6 +47,7 @@ __all__ = [
     "Database",
     "SqliteDatabase",
     "SqliteDatabaseBuilder",
+    "get_alembic_dir",
     "Repository",
     "BaseRepository",
     "Manager",

servicekit-2.0.0/src/servicekit/alembic/env.py

@@ -0,0 +1,76 @@
+"""Alembic environment configuration for async SQLAlchemy migrations."""
+
+import asyncio
+from logging.config import fileConfig
+
+from alembic import context
+from sqlalchemy import pool
+from sqlalchemy.engine import Connection
+from sqlalchemy.ext.asyncio import async_engine_from_config
+
+# Import the Base metadata from servicekit models
+from servicekit.models import Base
+
+# This is the Alembic Config object
+config = context.config
+
+# Interpret the config file for Python logging (if present)
+if config.config_file_name is not None:
+    fileConfig(config.config_file_name)
+
+# Set target metadata for 'autogenerate' support
+target_metadata = Base.metadata
+
+
+def run_migrations_offline() -> None:
+    """Run migrations in 'offline' mode (generates SQL scripts)."""
+    url = config.get_main_option("sqlalchemy.url")
+    context.configure(
+        url=url,
+        target_metadata=target_metadata,
+        literal_binds=True,
+        dialect_opts={"paramstyle": "named"},
+    )
+
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+def do_run_migrations(connection: Connection) -> None:
+    """Run migrations with a connection."""
+    context.configure(connection=connection, target_metadata=target_metadata)
+
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+async def run_async_migrations() -> None:
+    """Run migrations in async mode using async engine."""
+    connectable = async_engine_from_config(
+        config.get_section(config.config_ini_section, {}),
+        prefix="sqlalchemy.",
+        poolclass=pool.NullPool,
+    )
+
+    async with connectable.connect() as connection:
+        await connection.run_sync(do_run_migrations)
+
+    await connectable.dispose()
+
+
+def run_migrations_online() -> None:
+    """Run migrations in 'online' mode (connects to database)."""
+    # Since we're being called from Database.init() via run_in_executor,
+    # we're in a separate thread and can safely create a new event loop
+    loop = asyncio.new_event_loop()
+    asyncio.set_event_loop(loop)
+    try:
+        loop.run_until_complete(run_async_migrations())
+    finally:
+        loop.close()
+
+
+if context.is_offline_mode():
+    run_migrations_offline()
+else:
+    run_migrations_online()

servicekit-2.0.0/src/servicekit/alembic/script.py.mako

@@ -0,0 +1,26 @@
+"""${message}
+
+Revision ID: ${up_revision}
+Revises: ${down_revision | comma,n}
+Create Date: ${create_date}
+
+"""
+from alembic import op
+import sqlalchemy as sa
+${imports if imports else ""}
+
+# revision identifiers, used by Alembic.
+revision = ${repr(up_revision)}
+down_revision = ${repr(down_revision)}
+branch_labels = ${repr(branch_labels)}
+depends_on = ${repr(depends_on)}
+
+
+def upgrade() -> None:
+    """Apply database schema changes."""
+    ${upgrades if upgrades else "pass"}
+
+
+def downgrade() -> None:
+    """Revert database schema changes."""
+    ${downgrades if downgrades else "pass"}

servicekit-2.0.0/src/servicekit/alembic/versions/20251010_0927_4d869b5fb06e_initial_schema.py

@@ -0,0 +1,27 @@
+"""Initial database schema migration - no tables for pure framework.
+
+Note: While servicekit is a pure framework without domain tables,
+the Entity base class includes common fields (id, created_at, updated_at, tags)
+that all domain entities inherit. These fields are defined in the ORM models
+and automatically included when domain tables are created.
+"""
+
+# revision identifiers, used by Alembic.
+revision = "4d869b5fb06e"
+down_revision = None
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    """Apply database schema changes."""
+    # Servicekit is a pure framework - no domain-specific tables
+    # Domain tables (tasks, artifacts, configs) are provided by chapkit
+    # Entity base class fields (id, created_at, updated_at, tags) are
+    # automatically included in all domain entity tables via ORM inheritance
+    pass
+
+
+def downgrade() -> None:
+    """Revert database schema changes."""
+    pass

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

@@ -1,17 +1,9 @@
 """FastAPI framework layer - routers, middleware, utilities."""
 
-from .app import App, AppInfo, AppLoader, AppManager, AppManifest
+from .app import App, AppInfo, AppLoader, AppManager, AppManifest, EntryStaticFiles
 from .auth import APIKeyMiddleware, load_api_keys_from_env, load_api_keys_from_file, validate_api_key_format
 from .crud import CrudPermissions, CrudRouter
-from .dependencies import (
-    get_app_manager,
-    get_database,
-    get_scheduler,
-    get_session,
-    set_app_manager,
-    set_database,
-    set_scheduler,
-)
+from .dependencies import get_app_manager, get_database, get_scheduler, get_session
 from .middleware import add_error_handlers, add_logging_middleware, database_error_handler, validation_error_handler
 from .pagination import PaginationParams, create_paginated_response
 from .router import Router
@@ -34,6 +26,7 @@ __all__ = [
     "AppLoader",
     "AppManifest",
     "AppManager",
+    "EntryStaticFiles",
     # Authentication
     "APIKeyMiddleware",
     "load_api_keys_from_env",
@@ -41,12 +34,9 @@ __all__ = [
     "validate_api_key_format",
     # Dependencies
     "get_app_manager",
-    "set_app_manager",
     "get_database",
-    "set_database",
     "get_session",
     "get_scheduler",
-    "set_scheduler",
     # Middleware
     "add_error_handlers",
     "add_logging_middleware",

{servicekit-1.0.0 → servicekit-2.0.0}/src/servicekit/api/app.py

@@ -6,8 +6,12 @@ import importlib.util
 import json
 from dataclasses import dataclass
 from pathlib import Path
+from typing import Any
 
 from pydantic import BaseModel, ConfigDict, Field, field_validator
+from starlette.responses import Response
+from starlette.staticfiles import StaticFiles
+from starlette.types import Scope
 
 from servicekit.logging import get_logger
 
@@ -63,6 +67,21 @@ class App:
     is_package: bool  # True if loaded from package resources
 
 
+class EntryStaticFiles(StaticFiles):
+    """Static file server that serves an app's configured entry file at the mount root."""
+
+    def __init__(self, *args: Any, entry: str = "index.html", **kwargs: Any) -> None:
+        """Initialize static files with the entry filename served for the mount root."""
+        super().__init__(*args, **kwargs)
+        self.entry = entry
+
+    async def get_response(self, path: str, scope: Scope) -> Response:
+        """Serve the configured entry file for the mount root, other paths unchanged."""
+        if path in ("", "."):
+            return await super().get_response(self.entry, scope)
+        return await super().get_response(path, scope)
+
+
 class AppLoader:
     """Loads and validates apps from filesystem or package resources."""
 

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

@@ -1,9 +1,9 @@
 """CRUD router base class for standard REST operations."""
 
 from dataclasses import dataclass
-from typing import Any, Callable
+from typing import Annotated, Any, Callable, cast
 
-from fastapi import Depends, Request, Response, status
+from fastapi import Depends, Query, Request, Response, status
 from pydantic import BaseModel
 from ulid import ULID
 
@@ -180,7 +180,7 @@ class CrudRouter[InSchemaT: BaseModel, OutSchemaT: BaseModel](Router):
         ) -> OutSchemaT:
             from .utilities import build_location_url
 
-            created_entity = await manager.save(entity_in)
+            created_entity = await manager.create(entity_in)
             entity_id = getattr(created_entity, "id")
             response.headers["Location"] = build_location_url(request, f"{router_prefix}/{entity_id}")
             return created_entity
@@ -190,19 +190,23 @@ class CrudRouter[InSchemaT: BaseModel, OutSchemaT: BaseModel](Router):
         create.__annotations__["return"] = entity_out_annotation
 
     def _register_find_all_route(self, manager_dependency: Any, manager_annotation: Any) -> None:
+        from .pagination import PaginationParams, create_paginated_response
+
         entity_out_annotation: Any = self.entity_out_type
         collection_response_model: Any = list[entity_out_annotation] | PaginatedResponse[entity_out_annotation]
 
         @self.router.get("", response_model=collection_response_model)
         async def find_all(
-            page: int | None = None,
-            size: int | None = None,
+            pagination: Annotated[PaginationParams, Query()],
             manager: Manager[InSchemaT, OutSchemaT, ULID] = manager_dependency,
         ) -> list[OutSchemaT] | PaginatedResponse[OutSchemaT]:
-            from .pagination import create_paginated_response
+            """List entities; pagination is opt-in and requires both page (>= 1) and size (1-100).
 
-            # Pagination is opt-in: both page and size must be provided
-            if page is not None and size is not None:
+            Supplying only one of them returns the plain unpaginated list.
+            """
+            if pagination.is_paginated():
+                page = cast(int, pagination.page)
+                size = cast(int, pagination.size)
                 items, total = await manager.find_paginated(page, size)
                 return create_paginated_response(items, total, page, size)
             return await manager.find_all()
@@ -234,8 +238,7 @@ class CrudRouter[InSchemaT: BaseModel, OutSchemaT: BaseModel](Router):
         find_by_id.__annotations__["return"] = entity_out_annotation
 
     def _register_update_route(self, manager_dependency: Any, manager_annotation: Any) -> None:
-        entity_in_type = self.entity_in_type
-        entity_in_annotation: Any = entity_in_type
+        entity_in_annotation: Any = self.entity_in_type
         entity_out_annotation: Any = self.entity_out_type
         router_prefix = self.router.prefix
 
@@ -253,9 +256,7 @@ class CrudRouter[InSchemaT: BaseModel, OutSchemaT: BaseModel](Router):
                     f"Entity with id {entity_id} not found",
                     instance=f"{router_prefix}/{entity_id}",
                 )
-            entity_dict = entity_in.model_dump(exclude_unset=True)
-            entity_dict["id"] = ulid_id
-            entity_with_id = entity_in_type.model_validate(entity_dict)
+            entity_with_id = entity_in.model_copy(update={"id": ulid_id})
             return await manager.save(entity_with_id)
 
         self._annotate_manager(update, manager_annotation)

servicekit-2.0.0/src/servicekit/api/dependencies.py

@@ -0,0 +1,55 @@
+"""Request-scoped FastAPI dependencies resolved from ``request.app.state``.
+
+Every dependency here is per application: two apps running in the same process each
+resolve their own database, scheduler, and app manager. Library code that runs outside
+a request (for example inside a lifespan) should capture the objects it needs directly
+instead of calling these getters.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from typing import Annotated
+
+from fastapi import Depends, Request
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from servicekit import Database
+from servicekit.scheduler import Scheduler
+
+from .app import AppManager
+
+
+def get_database(request: Request) -> Database:
+    """Get the database bound to the current application."""
+    database: Database | None = getattr(request.app.state, "database", None)
+    if database is None:
+        raise RuntimeError(
+            "Database not available on app.state.database. "
+            "The application lifespan must run before requests are served."
+        )
+    return database
+
+
+async def get_session(database: Annotated[Database, Depends(get_database)]) -> AsyncIterator[AsyncSession]:
+    """Get a database session for dependency injection."""
+    async with database.session() as session:
+        yield session
+
+
+def get_scheduler(request: Request) -> Scheduler:
+    """Get the scheduler bound to the current application."""
+    scheduler: Scheduler | None = getattr(request.app.state, "scheduler", None)
+    if scheduler is None:
+        raise RuntimeError(
+            "Scheduler not available on app.state.scheduler. Enable jobs with .with_jobs() and run the lifespan."
+        )
+    return scheduler
+
+
+def get_app_manager(request: Request) -> AppManager:
+    """Get the app manager bound to the current application."""
+    app_manager: AppManager | None = getattr(request.app.state, "app_manager", None)
+    if app_manager is None:
+        raise RuntimeError("AppManager not available on app.state.app_manager. Build the app with a ServiceBuilder.")
+    return app_manager