Contributing

Thanks for your interest in improving the Vulners Python SDK! Issues and pull requests are welcome. For substantial changes, please open an issue to discuss the approach first.

Development setup

The project uses uv for dependency management and builds (the build backend is uv_build).

# install uv: https://docs.astral.sh/uv/getting-started/installation/
uv sync            # create the venv and install the project + dev tools

Everyday commands

make test          # run the full test suite in parallel (pytest -n auto)
make lint          # ruff check + format --check
make typecheck     # mypy + basedpyright
make cov           # branch coverage of the v4 core (gated at 100%)
make check         # lint + typecheck + unasync-check + test
make build         # build sdist + wheel

Project layout

• src/vulners/ — the package.
  • _*.py, _models/, _types/, _resources/ — the v4 core (private). Async is the source of truth; the sync mirror is generated by unasyncd.
  • base.py, vscanner.py, vulners/ — the v3 legacy API, preserved for 100% backward compatibility.
• tests/ — unit tests (tests/core/), the v3 suite, and the backward-compat oracle (tests/bc/, read-only baselines recorded from the released v3).
• documentation/ — the MkDocs site.

Working on the async/sync core

Edit the async source under src/vulners/_resources/_async/ (and _ratelimit_async.py), then regenerate the sync mirror:

make unasync         # regenerate src/vulners/_resources/_sync/ etc.
make unasync-check   # CI gate: fails if the committed mirror drifted

Never edit the generated _resources/_sync/ files by hand.

Backward compatibility

The v3 public surface and its exact on-the-wire requests are pinned by the oracle in tests/bc/ against the released v3 baseline. Any change that removes a v3 symbol, alters a signature, or changes a request will fail these tests. Keep them green.

Before opening a PR

Run make check and make sure everything is green. New code should keep the v4 core at 100% branch coverage and 100% type completeness (basedpyright).

Commit style

Short, lower-case, imperative subject lines (e.g. fix: harden the retry predicate). Keep commits focused.