Metadata-Version: 2.5
Name: python-neva
Version: 4.1.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: opentelemetry-instrumentation-sqlalchemy>=0.62b0
Requires-Dist: pwdlib[argon2,bcrypt]>=0.3.0
Requires-Dist: pydantic>=2.7
Requires-Dist: pyinstrument>=5.1.1
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: fastapi
Requires-Dist: neva-fastapi>=1.1.1; extra == 'fastapi'
Provides-Extra: faststream
Requires-Dist: faststream>=0.6.6; extra == 'faststream'
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, observability, 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-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).

## 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`)
- Finish cleaning up the core package (moving any remaining ASGI-dependent code into the appropriate integration packages)
- Improved router registration (auto-discovery OR provider-based? both?)
- Improved security tooling (performance improvements, better defaults, etc.)
- Better OpenTelemetry integration
- Improved factory module (based on Polyfactory)
- Queue/Jobs system
- CLI integration
