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), 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; 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)
`neva-fastapi`	`neva-fastapi/`	FastAPI integration — `App` extends `FastAPI` and wires dishka into routes. Pulled in via the `python-neva[fastapi]` extra.	published (PyPI)
`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)
`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)
`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)
`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.

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

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 with gitmoji prefixes, enforced by cz_gitmoji. Commitizen is provided as a dev dependency — no separate install needed. Run the guided wizard:

cz commit

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

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

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

Metadata

Release files for python-neva 5.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for python-neva 5.1.0
File	Size	Uploaded
python_neva-5.1.0.tar.gz	212.3 kB	Sep 2, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for python-neva 5.1.0
File	Interpreter	ABI	Platform	Reset
python_neva-5.1.0-py3-none-any.whl 101.3 kB Sep 2, 2026	Python 3	none	any	Details

Total release size: 313.6 kB

Release files / python_neva-5.1.0.tar.gz

Download URL	python_neva-5.1.0.tar.gz
Size	212.3 kB
Tags	Source
SHA-256 checksum How to use checksums	`b3db0449933da01db4eb79968bb8f600292257a28303121b506ef18463313ee0`
BLAKE2b-256 checksum How to use checksums	`7d7da5f1dc253cb823dec4ff2a837a7c7ca4778866af77bc5e54e3711666428c`
Upload date	Sep 2, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.8.22`

Release files / python_neva-5.1.0-py3-none-any.whl

Download URL	python_neva-5.1.0-py3-none-any.whl
Size	101.3 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`8a5f7484978ab712107d45b7577d4952168956b06a2a31843c0c15338669dade`
BLAKE2b-256 checksum How to use checksums	`733a483996f7e547195e9d4ea33673eb5152f9195ae8bfe3128c5d7626bed441`
Upload date	Sep 2, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.8.22`