Metadata-Version: 2.4
Name: bluefox-core
Version: 0.4.1
Summary: The foundation of every Bluefox app — settings, database, logging, health, and app factory.
Project-URL: Homepage, https://bluefox-core.bluefox.software
Project-URL: Documentation, https://bluefox-core.bluefox.software/docs/
Project-URL: Repository, https://github.com/blue-fox-software/bluefox-core
License-Expression: MIT
Requires-Python: >=3.12
Requires-Dist: alembic>=1.13
Requires-Dist: asyncpg>=0.29
Requires-Dist: fastapi>=0.111
Requires-Dist: jinja2>=3.1
Requires-Dist: pydantic-settings>=2.0
Requires-Dist: pydantic>=2.0
Requires-Dist: redis>=5.0
Requires-Dist: sqlalchemy[asyncio]>=2.0
Requires-Dist: structlog>=24.0
Requires-Dist: uvicorn>=0.30
Description-Content-Type: text/markdown

# bluefox-core

The foundation of every Bluefox app — settings, database, logging, health endpoints, and app factory for FastAPI.

## Quick start

```bash
uv init my-app && cd my-app
uv add bluefox-core
```

```python
# main.py
from bluefox_core import BluefoxSettings, create_bluefox_app

settings = BluefoxSettings()
app = create_bluefox_app(settings)
```

```bash
uv run uvicorn main:app --reload
```

## What you get

- **Settings** — Typed configuration via pydantic-settings. Reads from environment variables and `.env` files.
- **Async database** — SQLAlchemy 2.x with asyncpg. Engine lifecycle, session dependency, URL normalization.
- **Structured logging** — structlog with JSON in production, colored console in development. Request IDs via contextvars.
- **Health endpoints** — `/health` for liveness, `/readiness` for dependency checks.
- **Request ID middleware** — Generates or preserves `X-Request-ID` headers, bound to log context.
- **App factory** — One function wires everything together and returns a standard FastAPI app.

## Demo app

Pass `demo=True` to get a working Todo CRUD app:

```python
app = create_bluefox_app(settings, demo=True)
# Visit /docs to interact with the Todo API
```

## Links

- [Documentation](https://bluefox-core.bluefox.software/docs/)
- [PyPI](https://pypi.org/project/bluefox-core/)
- [Bluefox Stack](https://bluefox.software)
