servicekit 0.3.5__tar.gz

servicekit-0.3.5/PKG-INFO

@@ -0,0 +1,184 @@
+Metadata-Version: 2.3
+Name: servicekit
+Version: 0.3.5
+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
+Author-email: Morten Hansen <morten@winterop.com>
+License: AGPL-3.0-or-later
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Framework :: FastAPI
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Database
+Requires-Dist: aiosqlite>=0.21.0
+Requires-Dist: alembic>=1.17.0
+Requires-Dist: fastapi[standard]>=0.119.1
+Requires-Dist: gunicorn>=23.0.0
+Requires-Dist: opentelemetry-api>=1.37.0
+Requires-Dist: opentelemetry-exporter-prometheus>=0.58b0
+Requires-Dist: opentelemetry-instrumentation-fastapi>=0.58b0
+Requires-Dist: opentelemetry-instrumentation-sqlalchemy>=0.58b0
+Requires-Dist: opentelemetry-sdk>=1.37.0
+Requires-Dist: pydantic>=2.12.0
+Requires-Dist: python-ulid>=3.1.0
+Requires-Dist: sqlalchemy[asyncio]>=2.0.43
+Requires-Dist: structlog>=24.4.0
+Requires-Python: >=3.13, <3.14
+Project-URL: Documentation, https://winterop-com.github.io/servicekit
+Project-URL: Homepage, https://github.com/winterop-com/servicekit
+Project-URL: Issues, https://github.com/winterop-com/servicekit/issues
+Project-URL: Repository, https://github.com/winterop-com/servicekit
+Description-Content-Type: text/markdown
+
+# Servicekit
+
+[![CI](https://github.com/winterop-com/servicekit/actions/workflows/ci.yml/badge.svg)](https://github.com/winterop-com/servicekit/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/winterop-com/servicekit/branch/main/graph/badge.svg)](https://codecov.io/gh/winterop-com/servicekit)
+[![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)
+[![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
+[![Documentation](https://img.shields.io/badge/docs-mkdocs-blue.svg)](https://winterop-com.github.io/servicekit/)
+
+> Async SQLAlchemy framework with FastAPI integration - reusable foundation for building data services
+
+Servicekit is a framework-agnostic core library providing foundational infrastructure for building async Python services with FastAPI and SQLAlchemy.
+
+## Features
+
+- **Database Layer**: Async SQLAlchemy with SQLite support, connection pooling, and automatic migrations
+- **Repository Pattern**: Generic repository base classes for data access
+- **Manager Pattern**: Business logic layer with lifecycle hooks
+- **CRUD API**: Auto-generated REST endpoints with full CRUD operations
+- **Authentication**: API key middleware with file and environment variable support
+- **Job Scheduling**: Async job scheduler with concurrency control
+- **App Hosting**: Mount static web applications alongside your API
+- **Monitoring**: Prometheus metrics and OpenTelemetry integration
+- **Health Checks**: Flexible health check system with SSE streaming support
+- **Error Handling**: RFC 9457 Problem Details for HTTP APIs
+- **Logging**: Structured logging with request context
+
+## Installation
+
+```bash
+pip install servicekit
+```
+
+## Quick Start
+
+```python
+from servicekit.api import BaseServiceBuilder, ServiceInfo
+
+app = (
+    BaseServiceBuilder(info=ServiceInfo(display_name="My Service"))
+    .with_health()
+    .with_database("sqlite+aiosqlite:///./data.db")
+    .build()
+)
+```
+
+## Architecture
+
+```
+servicekit/
+├── database.py       # Database, SqliteDatabase, SqliteDatabaseBuilder
+├── models.py         # Base, Entity ORM classes
+├── repository.py     # Repository, BaseRepository
+├── manager.py        # Manager, BaseManager
+├── schemas.py        # EntityIn, EntityOut, PaginatedResponse
+├── scheduler.py      # JobScheduler, AIOJobScheduler
+├── exceptions.py     # Error classes
+├── logging.py        # Structured logging
+├── types.py          # ULIDType, JsonSafe
+└── api/              # FastAPI framework layer
+    ├── router.py     # Router base class
+    ├── crud.py       # CrudRouter, CrudPermissions
+    ├── auth.py       # API key authentication
+    ├── app.py        # Static app hosting
+    ├── middleware.py # Error handlers, logging
+    └── routers/      # Health, Jobs, System, Metrics
+```
+
+## Key Components
+
+### BaseServiceBuilder
+
+```python
+from servicekit.api import BaseServiceBuilder, ServiceInfo
+
+app = (
+    BaseServiceBuilder(info=ServiceInfo(display_name="My Service"))
+    .with_health()                    # Health check endpoint
+    .with_database(url)               # Database configuration
+    .with_jobs(max_concurrency=10)   # Job scheduler
+    .with_auth()                      # API key authentication
+    .with_monitoring()                # Prometheus metrics
+    .with_app("./webapp")             # Static web app
+    .include_router(custom_router)   # Custom routes
+    .build()
+)
+```
+
+### Repository Pattern
+
+```python
+from servicekit import BaseRepository, Entity
+from sqlalchemy.orm import Mapped, mapped_column
+
+class User(Entity):
+    __tablename__ = "users"
+    name: Mapped[str] = mapped_column()
+    email: Mapped[str] = mapped_column()
+
+class UserRepository(BaseRepository[User, ULID]):
+    def __init__(self, session: AsyncSession):
+        super().__init__(session, User)
+```
+
+### CRUD Router
+
+```python
+from servicekit.api import CrudRouter, CrudPermissions
+
+router = CrudRouter.create(
+    prefix="/api/v1/users",
+    tags=["Users"],
+    entity_in_type=UserIn,
+    entity_out_type=UserOut,
+    manager_factory=get_user_manager,
+    permissions=CrudPermissions(create=True, read=True, update=True, delete=False)
+)
+```
+
+
+## Examples
+
+See the `examples/` directory for complete working examples:
+
+- `core_api.py` - Basic CRUD service
+- `job_scheduler_api.py` - Background job execution
+- `app_hosting_api.py` - Hosting static web apps
+- `auth_basic.py` - API key authentication
+- `monitoring_api.py` - Prometheus metrics
+
+## Documentation
+
+See `docs/` for comprehensive guides and API reference.
+
+## Testing
+
+```bash
+make test      # Run tests
+make lint      # Run linter
+make coverage  # Test coverage
+```
+
+## License
+
+AGPL-3.0-or-later
+
+## Related Projects
+
+- **[chapkit](https://github.com/dhis2-chap/chapkit)** - Domain modules (artifacts, configs, tasks, ML workflows) built on servicekit ([docs](https://dhis2-chap.github.io/chapkit))

servicekit-0.3.5/README.md

@@ -0,0 +1,148 @@
+# Servicekit
+
+[![CI](https://github.com/winterop-com/servicekit/actions/workflows/ci.yml/badge.svg)](https://github.com/winterop-com/servicekit/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/winterop-com/servicekit/branch/main/graph/badge.svg)](https://codecov.io/gh/winterop-com/servicekit)
+[![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)
+[![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
+[![Documentation](https://img.shields.io/badge/docs-mkdocs-blue.svg)](https://winterop-com.github.io/servicekit/)
+
+> Async SQLAlchemy framework with FastAPI integration - reusable foundation for building data services
+
+Servicekit is a framework-agnostic core library providing foundational infrastructure for building async Python services with FastAPI and SQLAlchemy.
+
+## Features
+
+- **Database Layer**: Async SQLAlchemy with SQLite support, connection pooling, and automatic migrations
+- **Repository Pattern**: Generic repository base classes for data access
+- **Manager Pattern**: Business logic layer with lifecycle hooks
+- **CRUD API**: Auto-generated REST endpoints with full CRUD operations
+- **Authentication**: API key middleware with file and environment variable support
+- **Job Scheduling**: Async job scheduler with concurrency control
+- **App Hosting**: Mount static web applications alongside your API
+- **Monitoring**: Prometheus metrics and OpenTelemetry integration
+- **Health Checks**: Flexible health check system with SSE streaming support
+- **Error Handling**: RFC 9457 Problem Details for HTTP APIs
+- **Logging**: Structured logging with request context
+
+## Installation
+
+```bash
+pip install servicekit
+```
+
+## Quick Start
+
+```python
+from servicekit.api import BaseServiceBuilder, ServiceInfo
+
+app = (
+    BaseServiceBuilder(info=ServiceInfo(display_name="My Service"))
+    .with_health()
+    .with_database("sqlite+aiosqlite:///./data.db")
+    .build()
+)
+```
+
+## Architecture
+
+```
+servicekit/
+├── database.py       # Database, SqliteDatabase, SqliteDatabaseBuilder
+├── models.py         # Base, Entity ORM classes
+├── repository.py     # Repository, BaseRepository
+├── manager.py        # Manager, BaseManager
+├── schemas.py        # EntityIn, EntityOut, PaginatedResponse
+├── scheduler.py      # JobScheduler, AIOJobScheduler
+├── exceptions.py     # Error classes
+├── logging.py        # Structured logging
+├── types.py          # ULIDType, JsonSafe
+└── api/              # FastAPI framework layer
+    ├── router.py     # Router base class
+    ├── crud.py       # CrudRouter, CrudPermissions
+    ├── auth.py       # API key authentication
+    ├── app.py        # Static app hosting
+    ├── middleware.py # Error handlers, logging
+    └── routers/      # Health, Jobs, System, Metrics
+```
+
+## Key Components
+
+### BaseServiceBuilder
+
+```python
+from servicekit.api import BaseServiceBuilder, ServiceInfo
+
+app = (
+    BaseServiceBuilder(info=ServiceInfo(display_name="My Service"))
+    .with_health()                    # Health check endpoint
+    .with_database(url)               # Database configuration
+    .with_jobs(max_concurrency=10)   # Job scheduler
+    .with_auth()                      # API key authentication
+    .with_monitoring()                # Prometheus metrics
+    .with_app("./webapp")             # Static web app
+    .include_router(custom_router)   # Custom routes
+    .build()
+)
+```
+
+### Repository Pattern
+
+```python
+from servicekit import BaseRepository, Entity
+from sqlalchemy.orm import Mapped, mapped_column
+
+class User(Entity):
+    __tablename__ = "users"
+    name: Mapped[str] = mapped_column()
+    email: Mapped[str] = mapped_column()
+
+class UserRepository(BaseRepository[User, ULID]):
+    def __init__(self, session: AsyncSession):
+        super().__init__(session, User)
+```
+
+### CRUD Router
+
+```python
+from servicekit.api import CrudRouter, CrudPermissions
+
+router = CrudRouter.create(
+    prefix="/api/v1/users",
+    tags=["Users"],
+    entity_in_type=UserIn,
+    entity_out_type=UserOut,
+    manager_factory=get_user_manager,
+    permissions=CrudPermissions(create=True, read=True, update=True, delete=False)
+)
+```
+
+
+## Examples
+
+See the `examples/` directory for complete working examples:
+
+- `core_api.py` - Basic CRUD service
+- `job_scheduler_api.py` - Background job execution
+- `app_hosting_api.py` - Hosting static web apps
+- `auth_basic.py` - API key authentication
+- `monitoring_api.py` - Prometheus metrics
+
+## Documentation
+
+See `docs/` for comprehensive guides and API reference.
+
+## Testing
+
+```bash
+make test      # Run tests
+make lint      # Run linter
+make coverage  # Test coverage
+```
+
+## License
+
+AGPL-3.0-or-later
+
+## Related Projects
+
+- **[chapkit](https://github.com/dhis2-chap/chapkit)** - Domain modules (artifacts, configs, tasks, ML workflows) built on servicekit ([docs](https://dhis2-chap.github.io/chapkit))

servicekit-0.3.5/pyproject.toml

@@ -0,0 +1,161 @@
+[project]
+name = "servicekit"
+version = "0.3.5"
+description = "Async SQLAlchemy framework with FastAPI integration - reusable foundation for building data services"
+readme = "README.md"
+authors = [{ name = "Morten Hansen", email = "morten@winterop.com" }]
+license = { text = "AGPL-3.0-or-later" }
+requires-python = ">=3.13,<3.14"
+keywords = [
+  "fastapi",
+  "sqlalchemy",
+  "async",
+  "database",
+  "rest-api",
+  "crud",
+  "framework",
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)",
+  "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.119.1",
+  "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",
+  "structlog>=24.4.0",
+]
+
+[project.optional-dependencies]
+
+[project.urls]
+Homepage = "https://github.com/winterop-com/servicekit"
+Repository = "https://github.com/winterop-com/servicekit"
+Issues = "https://github.com/winterop-com/servicekit/issues"
+Documentation = "https://winterop-com.github.io/servicekit"
+
+[dependency-groups]
+dev = [
+  "coverage[toml]>=7.6.0",
+  "mypy>=1.18.2",
+  "pandas-stubs>=2.3.2.250926",
+  "pytest>=8.4.2",
+  "pytest-cov>=5.0.0",
+  "pytest-asyncio>=1.2.0",
+  "ruff>=0.14.0",
+  "pyright>=1.1.407",
+  "mkdocs>=1.6.0",
+  "mkdocs-material>=9.5.0",
+  "mkdocstrings[python]>=0.26.0",
+  "pandas>=2.3.3",
+  "polars>=1.34.0",
+  "xarray>=2025.10.1",
+  "numpy>=2.3.4",
+]
+
+[build-system]
+requires = ["uv_build>=0.9.0,<0.10.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.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", "typings"]
+
+[[tool.mypy.overrides]]
+module = "tests.*"
+disallow_untyped_defs = false
+
+[[tool.mypy.overrides]]
+module = "polars.*"
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = "xarray.*"
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = "examples.*"
+ignore_missing_imports = true
+disallow_untyped_defs = false
+
+[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-0.3.5/src/servicekit/__init__.py

@@ -0,0 +1,78 @@
+"""Core framework components - generic interfaces and base classes."""
+
+# ruff: noqa: F401
+
+# Base infrastructure (framework-agnostic)
+from .database import Database, SqliteDatabase, SqliteDatabaseBuilder
+from .exceptions import (
+    BadRequestError,
+    ConflictError,
+    ErrorType,
+    ForbiddenError,
+    InvalidULIDError,
+    NotFoundError,
+    ServicekitException,
+    UnauthorizedError,
+    ValidationError,
+)
+from .logging import add_request_context, clear_request_context, configure_logging, get_logger, reset_request_context
+from .manager import BaseManager, LifecycleHooks, Manager
+from .models import Base, Entity
+from .repository import BaseRepository, Repository
+from .scheduler import AIOJobScheduler, JobScheduler
+from .schemas import (
+    BulkOperationError,
+    BulkOperationResult,
+    EntityIn,
+    EntityOut,
+    JobRecord,
+    JobStatus,
+    PaginatedResponse,
+    ProblemDetail,
+)
+from .types import JsonSafe, ULIDType
+
+__all__ = [
+    # Base infrastructure
+    "Database",
+    "SqliteDatabase",
+    "SqliteDatabaseBuilder",
+    "Repository",
+    "BaseRepository",
+    "Manager",
+    "LifecycleHooks",
+    "BaseManager",
+    # ORM and types
+    "Base",
+    "Entity",
+    "ULIDType",
+    "JsonSafe",
+    # Schemas
+    "EntityIn",
+    "EntityOut",
+    "PaginatedResponse",
+    "BulkOperationResult",
+    "BulkOperationError",
+    "ProblemDetail",
+    "JobRecord",
+    "JobStatus",
+    # Job scheduling
+    "JobScheduler",
+    "AIOJobScheduler",
+    # Exceptions
+    "ErrorType",
+    "ServicekitException",
+    "NotFoundError",
+    "ValidationError",
+    "ConflictError",
+    "InvalidULIDError",
+    "BadRequestError",
+    "UnauthorizedError",
+    "ForbiddenError",
+    # Logging
+    "configure_logging",
+    "get_logger",
+    "add_request_context",
+    "clear_request_context",
+    "reset_request_context",
+]

servicekit-0.3.5/src/servicekit/api/__init__.py

@@ -0,0 +1,72 @@
+"""FastAPI framework layer - routers, middleware, utilities."""
+
+from .app import App, AppInfo, AppLoader, AppManager, AppManifest
+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 .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, SystemInfo, SystemRouter
+from .service_builder import BaseServiceBuilder, ServiceInfo
+from .sse import SSE_HEADERS, format_sse_event, format_sse_model_event
+from .utilities import build_location_url, run_app
+
+__all__ = [
+    # Base router classes
+    "Router",
+    "CrudRouter",
+    "CrudPermissions",
+    # Service builder
+    "BaseServiceBuilder",
+    "ServiceInfo",
+    # App system
+    "App",
+    "AppInfo",
+    "AppLoader",
+    "AppManifest",
+    "AppManager",
+    # Authentication
+    "APIKeyMiddleware",
+    "load_api_keys_from_env",
+    "load_api_keys_from_file",
+    "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",
+    "database_error_handler",
+    "validation_error_handler",
+    # Pagination
+    "PaginationParams",
+    "create_paginated_response",
+    # System routers
+    "HealthRouter",
+    "HealthState",
+    "HealthStatus",
+    "JobRouter",
+    "SystemRouter",
+    "SystemInfo",
+    # SSE utilities
+    "SSE_HEADERS",
+    "format_sse_event",
+    "format_sse_model_event",
+    # Utilities
+    "build_location_url",
+    "run_app",
+]