Metadata-Version: 2.4
Name: servekat
Version: 0.1.3
Summary: servekat library
Author-email: velocikat <velocikat@lza.sh>
Requires-Python: >=3.12
Requires-Dist: corekat>=0.1.0
Requires-Dist: fastapi[all]>=0.115.0
Requires-Dist: starlette-exporter
Provides-Extra: all
Requires-Dist: fastapi-cache2>=0.2.0; extra == 'all'
Requires-Dist: opentelemetry-instrumentation-fastapi>=0.48b0; extra == 'all'
Requires-Dist: sentry-sdk; extra == 'all'
Requires-Dist: slowapi>=0.1.9; extra == 'all'
Provides-Extra: cache
Requires-Dist: fastapi-cache2>=0.2.0; extra == 'cache'
Provides-Extra: dev
Requires-Dist: fastapi-cache2>=0.2.0; extra == 'dev'
Requires-Dist: opentelemetry-instrumentation-fastapi>=0.48b0; extra == 'dev'
Requires-Dist: slowapi>=0.1.9; extra == 'dev'
Provides-Extra: ratelimit
Requires-Dist: slowapi>=0.1.9; extra == 'ratelimit'
Provides-Extra: sentry
Requires-Dist: sentry-sdk; extra == 'sentry'
Provides-Extra: tracing
Requires-Dist: opentelemetry-instrumentation-fastapi>=0.48b0; extra == 'tracing'
Description-Content-Type: text/markdown

# 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

```bash
# Core package
uv pip install servekat

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

# Everything
uv pip install "servekat[all]"
```

## Quick Start

### Basic Server

```python
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

```python
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:**

```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

```python
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

```python
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

```python
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:

```python
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](docs/guides/schemas.md) for complete documentation.

## Exception Handling

ServeKat automatically maps CoreKat exceptions to HTTP responses:

```python
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](docs/guides/error-handling.md) 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](../../LICENSE) for details.
 
