# Servicekit
[](https://github.com/winterop-com/servicekit/actions/workflows/ci.yml)
[](https://codecov.io/gh/winterop-com/servicekit)
[](https://www.python.org/downloads/)
[](https://www.gnu.org/licenses/agpl-3.0)
[](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))
Raw data
{
"_id": null,
"home_page": null,
"name": "servicekit",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.14,>=3.13",
"maintainer_email": null,
"keywords": "fastapi, sqlalchemy, async, database, rest-api, crud, framework",
"author": "Morten Hansen",
"author_email": "Morten Hansen <morten@winterop.com>",
"download_url": "https://files.pythonhosted.org/packages/08/89/4b536ef85b4cdafc849b456d5a4c6c7bc3a93fb4a12e595c2ec4f822b82a/servicekit-0.5.1.tar.gz",
"platform": null,
"description": "# Servicekit\n\n[](https://github.com/winterop-com/servicekit/actions/workflows/ci.yml)\n[](https://codecov.io/gh/winterop-com/servicekit)\n[](https://www.python.org/downloads/)\n[](https://www.gnu.org/licenses/agpl-3.0)\n[](https://winterop-com.github.io/servicekit/)\n\n> Async SQLAlchemy framework with FastAPI integration - reusable foundation for building data services\n\nServicekit is a framework-agnostic core library providing foundational infrastructure for building async Python services with FastAPI and SQLAlchemy.\n\n## Features\n\n- **Database Layer**: Async SQLAlchemy with SQLite support, connection pooling, and automatic migrations\n- **Repository Pattern**: Generic repository base classes for data access\n- **Manager Pattern**: Business logic layer with lifecycle hooks\n- **CRUD API**: Auto-generated REST endpoints with full CRUD operations\n- **Authentication**: API key middleware with file and environment variable support\n- **Job Scheduling**: Async job scheduler with concurrency control\n- **App Hosting**: Mount static web applications alongside your API\n- **Monitoring**: Prometheus metrics and OpenTelemetry integration\n- **Health Checks**: Flexible health check system with SSE streaming support\n- **Error Handling**: RFC 9457 Problem Details for HTTP APIs\n- **Logging**: Structured logging with request context\n\n## Installation\n\n```bash\npip install servicekit\n```\n\n## Quick Start\n\n```python\nfrom servicekit.api import BaseServiceBuilder, ServiceInfo\n\napp = (\n BaseServiceBuilder(info=ServiceInfo(display_name=\"My Service\"))\n .with_health()\n .with_database(\"sqlite+aiosqlite:///./data.db\")\n .build()\n)\n```\n\n## Architecture\n\n```\nservicekit/\n\u251c\u2500\u2500 database.py # Database, SqliteDatabase, SqliteDatabaseBuilder\n\u251c\u2500\u2500 models.py # Base, Entity ORM classes\n\u251c\u2500\u2500 repository.py # Repository, BaseRepository\n\u251c\u2500\u2500 manager.py # Manager, BaseManager\n\u251c\u2500\u2500 schemas.py # EntityIn, EntityOut, PaginatedResponse\n\u251c\u2500\u2500 scheduler.py # JobScheduler, AIOJobScheduler\n\u251c\u2500\u2500 exceptions.py # Error classes\n\u251c\u2500\u2500 logging.py # Structured logging\n\u251c\u2500\u2500 types.py # ULIDType, JsonSafe\n\u2514\u2500\u2500 api/ # FastAPI framework layer\n \u251c\u2500\u2500 router.py # Router base class\n \u251c\u2500\u2500 crud.py # CrudRouter, CrudPermissions\n \u251c\u2500\u2500 auth.py # API key authentication\n \u251c\u2500\u2500 app.py # Static app hosting\n \u251c\u2500\u2500 middleware.py # Error handlers, logging\n \u2514\u2500\u2500 routers/ # Health, Jobs, System, Metrics\n```\n\n## Key Components\n\n### BaseServiceBuilder\n\n```python\nfrom servicekit.api import BaseServiceBuilder, ServiceInfo\n\napp = (\n BaseServiceBuilder(info=ServiceInfo(display_name=\"My Service\"))\n .with_health() # Health check endpoint\n .with_database(url) # Database configuration\n .with_jobs(max_concurrency=10) # Job scheduler\n .with_auth() # API key authentication\n .with_monitoring() # Prometheus metrics\n .with_app(\"./webapp\") # Static web app\n .include_router(custom_router) # Custom routes\n .build()\n)\n```\n\n### Repository Pattern\n\n```python\nfrom servicekit import BaseRepository, Entity\nfrom sqlalchemy.orm import Mapped, mapped_column\n\nclass User(Entity):\n __tablename__ = \"users\"\n name: Mapped[str] = mapped_column()\n email: Mapped[str] = mapped_column()\n\nclass UserRepository(BaseRepository[User, ULID]):\n def __init__(self, session: AsyncSession):\n super().__init__(session, User)\n```\n\n### CRUD Router\n\n```python\nfrom servicekit.api import CrudRouter, CrudPermissions\n\nrouter = CrudRouter.create(\n prefix=\"/api/v1/users\",\n tags=[\"Users\"],\n entity_in_type=UserIn,\n entity_out_type=UserOut,\n manager_factory=get_user_manager,\n permissions=CrudPermissions(create=True, read=True, update=True, delete=False)\n)\n```\n\n\n## Examples\n\nSee the `examples/` directory for complete working examples:\n\n- `core_api.py` - Basic CRUD service\n- `job_scheduler_api.py` - Background job execution\n- `app_hosting_api.py` - Hosting static web apps\n- `auth_basic.py` - API key authentication\n- `monitoring_api.py` - Prometheus metrics\n\n## Documentation\n\nSee `docs/` for comprehensive guides and API reference.\n\n## Testing\n\n```bash\nmake test # Run tests\nmake lint # Run linter\nmake coverage # Test coverage\n```\n\n## License\n\nAGPL-3.0-or-later\n\n## Related Projects\n\n- **[chapkit](https://github.com/dhis2-chap/chapkit)** - Domain modules (artifacts, configs, tasks, ML workflows) built on servicekit ([docs](https://dhis2-chap.github.io/chapkit))\n",
"bugtrack_url": null,
"license": "AGPL-3.0-or-later",
"summary": "Async SQLAlchemy framework with FastAPI integration - reusable foundation for building data services",
"version": "0.5.1",
"project_urls": {
"Documentation": "https://winterop-com.github.io/servicekit",
"Homepage": "https://github.com/winterop-com/servicekit",
"Issues": "https://github.com/winterop-com/servicekit/issues",
"Repository": "https://github.com/winterop-com/servicekit"
},
"split_keywords": [
"fastapi",
" sqlalchemy",
" async",
" database",
" rest-api",
" crud",
" framework"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "379cf4e99685b3233eddce7bf1c99b42dac67d83d6a3a7e8ac081ee2ea879673",
"md5": "651e834168d97ff55003bc5457124230",
"sha256": "a502565f3626060b55b6447c2d668c1eb852dd439f3499e3d78f082916e74f2b"
},
"downloads": -1,
"filename": "servicekit-0.5.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "651e834168d97ff55003bc5457124230",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.14,>=3.13",
"size": 53139,
"upload_time": "2025-11-03T09:15:36",
"upload_time_iso_8601": "2025-11-03T09:15:36.607133Z",
"url": "https://files.pythonhosted.org/packages/37/9c/f4e99685b3233eddce7bf1c99b42dac67d83d6a3a7e8ac081ee2ea879673/servicekit-0.5.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "08894b536ef85b4cdafc849b456d5a4c6c7bc3a93fb4a12e595c2ec4f822b82a",
"md5": "10d4f8ed964d4b5dff8d5ee99e1b2e39",
"sha256": "38a424f6c247991997ba0ec5896c0c0ee0ae8a9674e221b4d753488e33c90256"
},
"downloads": -1,
"filename": "servicekit-0.5.1.tar.gz",
"has_sig": false,
"md5_digest": "10d4f8ed964d4b5dff8d5ee99e1b2e39",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.14,>=3.13",
"size": 40760,
"upload_time": "2025-11-03T09:15:37",
"upload_time_iso_8601": "2025-11-03T09:15:37.906669Z",
"url": "https://files.pythonhosted.org/packages/08/89/4b536ef85b4cdafc849b456d5a4c6c7bc3a93fb4a12e595c2ec4f822b82a/servicekit-0.5.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-11-03 09:15:37",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "winterop-com",
"github_project": "servicekit",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "servicekit"
}
JSON
