servicekit 1.0.1__tar.gz → 2.0.1__tar.gz

{servicekit-1.0.1 → servicekit-2.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: servicekit
-Version: 1.0.1
+Version: 2.0.1
 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,11 @@ router = CrudRouter.create(
 )
 ```
 
+`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
 
@@ -172,7 +203,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.1 → servicekit-2.0.1}/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,11 @@ router = CrudRouter.create(
 )
 ```
 
+`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
 
@@ -136,7 +167,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.1/pyproject.toml

@@ -0,0 +1,180 @@
+[project]
+name = "servicekit"
+version = "2.0.1"
+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.1/pyproject.toml → servicekit-2.0.1/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "servicekit"
-version = "1.0.1"
+version = "2.0.1"
 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.1 → servicekit-2.0.1}/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,
@@ -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
@@ -47,6 +48,7 @@ __all__ = [
     "Database",
     "SqliteDatabase",
     "SqliteDatabaseBuilder",
+    "get_alembic_dir",
     "Repository",
     "BaseRepository",
     "Manager",
@@ -75,6 +77,7 @@ __all__ = [
     "NotFoundError",
     "ValidationError",
     "ConflictError",
+    "classify_integrity_error",
     "InvalidULIDError",
     "BadRequestError",
     "UnauthorizedError",

servicekit-2.0.1/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.1/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.1/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.1 → servicekit-2.0.1}/src/servicekit/api/__init__.py

@@ -1,22 +1,14 @@
 """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
 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
 
@@ -27,6 +19,7 @@ __all__ = [
     "CrudPermissions",
     # Service builder
     "BaseServiceBuilder",
+    "JobOptions",
     "ServiceInfo",
     # App system
     "App",
@@ -34,6 +27,7 @@ __all__ = [
     "AppLoader",
     "AppManifest",
     "AppManager",
+    "EntryStaticFiles",
     # Authentication
     "APIKeyMiddleware",
     "load_api_keys_from_env",
@@ -41,12 +35,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.1 → servicekit-2.0.1}/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."""