servekat 0.1.0

servekat library

ServeKat

FastAPI server framework with batteries included. Provides route auto-discovery, exception handling, API schemas, and middleware utilities for building production-ready APIs.

Features

• Route Auto-Discovery: Automatically discover and mount routers from packages
• API Schema Base Classes: ResponseSchema, CreateSchema, UpdateSchema, PaginatedResponse
• Exception Handling: Automatic CoreKat exception → HTTP response mapping
• Middleware Stack: CORS, error handling, metrics, request timing
• Auth System: Token-based authentication with role-based access control
• Health Checks: Built-in health and info endpoints

Installation

# Core package
uv pip install servekat

# With Sentry support
uv pip install "servekat[sentry]"

# Everything
uv pip install "servekat[all]"

Quick Start

Basic Server

from fastapi import FastAPI
from servekat.server.discovery import mount_discovered_routes, mount_routers

app = FastAPI()

# Mount library routers (health, info, etc.)
mount_routers(app, [
    "servekat.server.api.health:router",
    "servekat.server.api.info:router",
])

# Auto-discover and mount your app routers
mount_discovered_routes(app, "myapp.server.routers")

Using Configuration

from servekat.config import config
from servekat.server.server import serve_from_config

conf = config("config.yaml")
app = serve_from_config(conf)

Example config.yaml:

name: myapp
server:
  host: 0.0.0.0
  port: 8080
  
  # Manual router imports
  routers:
    - "myapp.server.routers.users:router"
    - "myapp.server.routers.posts:router"
  
  # Auto-discovery (runs after manual routers)
  router_discovery:
    enabled: true
    modules:
      - "myapp.server.routers"
      - "myapp.admin.routers"
    pattern: "*_route.py"
    exclude:
      - "_internal_route.py"

Both manual routers and router_discovery work together - manual routers are mounted first, then auto-discovered routers are added.

Route Discovery

ServeKat can discover routers from:

1. File patterns in your app packages
2. Import strings from libraries
3. Multiple modules at once

Pattern 1: Discover from Files

from servekat.server.discovery import mount_discovered_routes

# Discover all *_route.py files in myapp.server.routers
mount_discovered_routes(app, "myapp.server.routers")

# Custom pattern
mount_discovered_routes(app, "myapp.api", pattern="*_api.py")

# Multiple packages
mount_discovered_routes(app, [
    "myapp.server.routers",
    "myapp.admin.routers"
])

Pattern 2: Import from Libraries

from servekat.server.discovery import mount_routers

# Import routers directly from ServeKat or other libraries
mount_routers(app, [
    "servekat.server.api.health:router",
    "servekat.server.api.info:router",
    "servekat.server.api.debug:router",
])

Pattern 3: Combined Approach

from servekat.server.discovery import mount_discovered_routes, mount_routers

# 1. Mount library routers
mount_routers(app, [
    "servekat.server.api.health:router",
    "servekat.server.api.info:router",
])

# 2. Discover and mount app routers
mount_discovered_routes(app, "myapp.server.routers")

API Schemas

Use ServeKat's base schemas for consistent API contracts:

from servekat.schemas import ResponseSchema, CreateSchema, UpdateSchema
from uuid import UUID
from datetime import datetime

class UserResponse(ResponseSchema):
    id: UUID
    name: str
    email: str
    created_at: datetime

class UserCreate(CreateSchema):
    name: str
    email: str

class UserUpdate(UpdateSchema):
    name: str | None = None
    email: str | None = None

See Schema Guide for complete documentation.

Exception Handling

ServeKat automatically maps CoreKat exceptions to HTTP responses:

from fastapi import APIRouter
from corekat.exceptions import NotFoundError

router = APIRouter()

@router.get("/users/{user_id}")
async def get_user(user_id: str):
    user = await find_user(user_id)
    if not user:
        raise NotFoundError("User not found", {"user_id": user_id})
    return user  # Automatically becomes 404 response

See Error Handling Guide for details.

Development

• Run tests: make test
• Linting: make lint
• Type checking: make pyright
• All checks: make check

License

BSD 3-Clause License - See LICENSE for details.