Metadata-Version: 2.5
Name: python-neva
Version: 5.3.0
Summary: Add your description here
Requires-Python: >=3.12
Requires-Dist: aiosqlite>=0.20.0
Requires-Dist: asyncpg>=0.30.0
Requires-Dist: cryptography>=46.0.3
Requires-Dist: dishka>=1.10.0
Requires-Dist: pwdlib[argon2,bcrypt]>=0.3.0
Requires-Dist: pydantic>=2.7
Requires-Dist: sqlalchemy[asyncio]>=2.0.0
Requires-Dist: structlog>=25.5.0
Requires-Dist: typing-extensions>=4.13
Provides-Extra: asgi
Requires-Dist: neva-asgi>=0.1.1; extra == 'asgi'
Provides-Extra: boost
Requires-Dist: neva-boost>=0.2.1; extra == 'boost'
Provides-Extra: fastapi
Requires-Dist: neva-fastapi>=1.1.1; extra == 'fastapi'
Provides-Extra: faststream
Requires-Dist: faststream>=0.6.6; extra == 'faststream'
Provides-Extra: otel
Requires-Dist: neva-otel>=0.2.0; extra == 'otel'
Provides-Extra: polyfactory
Requires-Dist: polyfactory>=3.1.0; extra == 'polyfactory'
Provides-Extra: testing
Requires-Dist: pytest-asyncio>=0.25.3; extra == 'testing'
Requires-Dist: pytest>=9.0.2; extra == 'testing'
Description-Content-Type: text/markdown

# python-neva

The core of the **Neva** framework — a Laravel-inspired toolkit for Python that
brings Laravel's philosophy, terminology, and conventions to the Python
ecosystem: service providers, facades, `bind`/`make` dependency injection (on
[dishka](https://github.com/reagento/dishka)), `Hash`/`Crypt`/`Config`/`Log`/`Event`
facades, a transaction-aware event system, and Result/Option error handling.

`python-neva` is the **framework-agnostic core**. Web- and protocol-specific
concerns live in separate integration packages (the plugins below) so the core
never depends on a particular HTTP or messaging framework.

## Plugins & ecosystem

Neva is split into one repository per package. The core is published as
[`python-neva`](https://pypi.org/project/python-neva/); each plugin is an
independent repo, independently versioned and published.

| Package           | Repo / directory   | Role                                                                                  | Status                          |
| ----------------- | ------------------ | ------------------------------------------------------------------------------------- | ------------------------------- |
| `python-neva`     | `neva/`            | **Core, framework-agnostic.** DI, service providers, facades, Result/Option, events, security, structured logging, SQLAlchemy database layer. | published ([PyPI](https://pypi.org/project/python-neva/)) |
| `neva-fastapi`    | `neva-fastapi/`    | FastAPI integration — `App` extends `FastAPI` and wires dishka into routes. Pulled in via the `python-neva[fastapi]` extra. | published ([PyPI](https://pypi.org/project/neva-fastapi/)) |
| `neva-asgi`       | `neva-asgi/`       | **ASGI middleware** — correlation IDs and per-request profiling. Pure ASGI, so both the HTTP and messaging integrations can consume it. Pulled in via the `python-neva[asgi]` extra. | published ([PyPI](https://pypi.org/project/neva-asgi/)) |
| `neva-faststream` | `neva-faststream/` | FastStream (messaging) integration.                                                   | scaffolded, early placeholder   |
| `neva-auth`       | `neva-auth/`       | Authentication & identity toolkit — token-issuance engine, OAuth2 grants, guards, pluggable formats/backends. | core complete, OAuth-server slice in progress |
| `neva-otel`       | `neva-otel/`       | **OpenTelemetry** — SDK wiring, tracer and meter providers, exporters, samplers and instrumentors. Kept out of the core so nothing is committed to an observability backend. Pulled in via the `python-neva[otel]` extra. | published ([PyPI](https://pypi.org/project/neva-otel/)) |
| `neva-boost`      | `neva-boost/`      | **Agent guidelines** — composes each installed package's versioned guideline fragments into a project's agent configuration (Claude Code skills or `AGENTS.md`). Dev-time tooling; pulled in via the `python-neva[boost]` extra. | published ([PyPI](https://pypi.org/project/neva-boost/)) |
| `neva-example`    | `neva-example/`    | Reference application consuming `python-neva[fastapi]`. Not published; demonstration + integration test bed. | unpublished                     |

> When working across packages locally, each repo can be cloned as a sibling
> directory; integration packages depend on `python-neva` from PyPI (or an
> editable local path during development).

## Logging

Logging is a set of named channels, each with its own driver, level and output —
Laravel's `Log`, configured from one `config/obs.py` namespace.

```python
from neva.support.facade import Log

Log.info("order placed", order_id=42)                    # default channel
Log.channel("audit").warning("role granted", actor="root")
Log.bind(tenant="acme")                                  # every channel, this context
```

Drivers are `console`, `json`, `file`, `stack` and `null`. With no `config/obs.py`
at all, logging still works: a console channel on stdout at `DEBUG`.

Each channel carries its own structlog processor chain rather than going through
the process-global `structlog.configure()`, so one application's renderer cannot
leak into another in the same interpreter. `LogManager.processor(fn)` lets a
plugin add a processor to every chain — the seam `neva-otel` uses to put the
current span's ids on every record.

**Tracing and metrics are deliberately not here.** They live in `neva-otel`, so
the core carries no OpenTelemetry dependency and commits no application to an
observability backend.

Channel configuration, the driver keys and the failure modes are documented in
`neva/guidelines/fragments/observability.md`, which CI checks against the tests.

## Develop

```bash
uv sync          # install/refresh deps from uv.lock
poe lint         # ruff check
poe fmt          # ruff format
poe tc           # type-check (pyrefly)
poe test         # pytest
poe test-cov     # tests with coverage

# Run a single test
pytest tests/test_file.py::TestClass::test_method -v
```

`asyncio_mode = "auto"` is set, so async tests need no `@pytest.mark.asyncio`.

## Contributing

**Commits** follow [Conventional Commits](https://www.conventionalcommits.org/)
with [gitmoji](https://gitmoji.dev/) prefixes, enforced by
[`cz_gitmoji`](https://github.com/ljnsn/cz-conventional-gitmoji). Commitizen is
provided as a dev dependency — no separate install needed. Run the guided
wizard:

```bash
cz commit
```

or format manually as `:gitmoji: type(scope): subject`.

**Releases** are cut per-repo with commitizen, from the repo root:

```bash
cz bump                              # bump version in pyproject, write CHANGELOG, tag v<version>
git push --follow-tags origin main
uv build && uv publish               # build + publish the wheel/sdist
```

`cz bump` derives the bump level (major/minor/patch) from the commits since the
last tag, updates `CHANGELOG.md`, and runs `scripts/retag-with-changelog.sh` to
rewrite the new tag with the rendered changelog as its annotation.

## Feature ideas

- Feature-parity FastStream integration (now scaffolded as `neva-faststream`)
- Improved router registration (auto-discovery OR provider-based? both?)
- Improved security tooling (performance improvements, better defaults, etc.)
- Improved factory module (based on Polyfactory)
- Queue/Jobs system
- CLI integration
