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.4.1

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.4.1
File	Size	Uploaded
python_neva-5.4.1.tar.gz	232.7 kB	Sep 9, 2026	Details

Built distribution (wheel)

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

Total release size: 346.9 kB

Release files / python_neva-5.4.1.tar.gz

Download URL	python_neva-5.4.1.tar.gz
Size	232.7 kB
Tags	Source
SHA-256 checksum How to use checksums	`6fe44426ce9cfead53250405410816ce794ec403737f756377a892140e1897b5`
BLAKE2b-256 checksum How to use checksums	`475b452b22e4dc0e5443ec50700448850e4c022ceb75958bbd10b94a344e266c`
Upload date	Sep 9, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.8.22`

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

Download URL	python_neva-5.4.1-py3-none-any.whl
Size	114.2 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`d29e9737edceda58128a80604bc334be20e1f7adbc709247f2e56f25dbcb8861`
BLAKE2b-256 checksum How to use checksums	`addc29eee712cd59918df22a6eefc67e887a4ee36cc2919d535bc1d988a45ce1`
Upload date	Sep 9, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.8.22`