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.	planned
`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.

config = {
    "logging": {
        "default": "stdout",
        "channels": {
            "stdout": {"driver": "console", "level": "DEBUG"},
            "json":   {"driver": "json", "stream": "stderr", "level": "INFO"},
            "audit":  {"driver": "file", "path": "var/audit.log"},
            "both":   {"driver": "stack", "channels": ["json", "audit"]},
        },
    },
}

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.

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.)
OpenTelemetry as a plugin (neva-otel) — the core keeps logging and takes no OTel dependency
Improved factory module (based on Polyfactory)
Queue/Jobs system
CLI integration

Metadata

Release files for python-neva 5.0.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.0.0
File	Size	Uploaded
python_neva-5.0.0.tar.gz	200.2 kB	Sep 1, 2026	Details

Built distribution (wheel)

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

Total release size: 293.6 kB

Release files / python_neva-5.0.0.tar.gz

Download URL	python_neva-5.0.0.tar.gz
Size	200.2 kB
Tags	Source
SHA-256 checksum How to use checksums	`f2acb479f3cf496001f80779c0b7fef6ba169e5660ff071557e81eb76050f483`
BLAKE2b-256 checksum How to use checksums	`764a0233c6b48d70172322ade596432f9e9c250cb65004d6135d2f1b687fdaf7`
Upload date	Sep 1, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.8.22`

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

Download URL	python_neva-5.0.0-py3-none-any.whl
Size	93.4 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`af3e14370fa2757ae8b5a49c99b0bc0ed92a1d27ca118072cb6c4c49452a62e8`
BLAKE2b-256 checksum How to use checksums	`36e3cea940af7051030de3b18e91ff9323af0e38f02f9141ca48fe9552fe4a7d`
Upload date	Sep 1, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.8.22`