Metadata-Version: 2.4
Name: ulfblk-core
Version: 0.1.0
Summary: Core utilities for building web APIs: middleware, schemas, logging, health checks
Project-URL: Homepage, https://github.com/abelardodiaz/web25-991-bloques-reciclables
Project-URL: Documentation, https://github.com/abelardodiaz/web25-991-bloques-reciclables/tree/main/packages/python/ulfblk-core
Project-URL: Repository, https://github.com/abelardodiaz/web25-991-bloques-reciclables
Project-URL: Issues, https://github.com/abelardodiaz/web25-991-bloques-reciclables/issues
Author-email: Abelardo Diaz <abelardo@bloques.dev>
License-Expression: MIT
Keywords: api,fastapi,health-check,logging,middleware,schemas
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: fastapi>=0.115.0
Requires-Dist: pydantic-settings>=2.0
Requires-Dist: pydantic>=2.0
Requires-Dist: structlog>=24.0
Provides-Extra: dev
Requires-Dist: httpx>=0.27; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# ulfblk-core

Core utilities for building web APIs with FastAPI: middleware, schemas, structured logging, and health checks.

Part of [Bloques Reciclables](https://github.com/abelardodiaz/web25-991-bloques-reciclables) - an open source ecosystem of reusable code blocks.

## Installation

```bash
uv add ulfblk-core
# or
pip install ulfblk-core
```

## Features

### Middleware

**RequestIDMiddleware** - Distributed tracing via `X-Request-ID` header. Generates UUID4 if not present, propagates through contextvars for logging.

**TimingMiddleware** - Measures request duration and adds `X-Process-Time` header. Logs warnings for slow requests (>1s).

```python
from fastapi import FastAPI
from ulfblk_core.middleware import RequestIDMiddleware, TimingMiddleware

app = FastAPI()
app.add_middleware(TimingMiddleware)
app.add_middleware(RequestIDMiddleware)
```

### Schemas

Standardized Pydantic v2 schemas for API responses:

```python
from ulfblk_core.schemas import PaginatedResponse, ErrorResponse, SuccessResponse, HealthResponse

# Paginated response
response = PaginatedResponse.create(
    items=my_items,
    total=100,
    page=1,
    page_size=20,
)

# Health check
health = HealthResponse.healthy(service="my-api", version="1.0.0")
```

### Structured Logging

Structured logging with [structlog](https://www.structlog.org/), automatic request ID injection, and JSON/console output:

```python
from ulfblk_core.logging import setup_logging, get_logger

setup_logging(level="INFO", json_format=True, service_name="my-api")

logger = get_logger(__name__)
logger.info("user.created", user_id="123", tenant="acme")
# Output: {"event": "user.created", "user_id": "123", "request_id": "abc-def", ...}
```

### Health Check Router

Ready-to-use health check endpoint:

```python
from ulfblk_core.health import health_router

app.include_router(health_router)
# GET /health -> {"status": "healthy", "service": "api", "version": "0.1.0", ...}
```

## Full Example

```python
from fastapi import FastAPI
from ulfblk_core.middleware import RequestIDMiddleware, TimingMiddleware
from ulfblk_core.health import health_router
from ulfblk_core.logging import setup_logging

app = FastAPI(title="My API")
setup_logging()
app.add_middleware(TimingMiddleware)
app.add_middleware(RequestIDMiddleware)
app.include_router(health_router)

@app.get("/")
async def root():
    return {"message": "Running with ulfblk-core"}
```

See the [api-simple example](https://github.com/abelardodiaz/web25-991-bloques-reciclables/tree/main/examples/api-simple) for a runnable version.

## Requirements

- Python 3.11+
- FastAPI 0.115+
- Pydantic 2.0+

## License

[MIT](https://github.com/abelardodiaz/web25-991-bloques-reciclables/blob/main/LICENSE)
