test-python-binding

Build And Test Python Binding

Companion Guidance

Use karpathy-guidelines alongside this skill for implementation or review work. Keep changes scoped, surface assumptions, and define focused validation before editing.

Use this skill when the change is primarily in python/nemo_relay, python/plugin, python/tests, crates/python, or Python-facing docs/examples.

Default Path

1. Format changed Python wrapper and test files with uv run ruff format python python/plugin.
2. Run focused pytest first when you know the affected area.
3. Run just test-python-plugin when the Python worker SDK changed.
4. Run the full Python suite with just test-python before review.
5. If any Rust files changed as part of the Python work, also run cargo fmt --all, just test-rust, and cargo clippy --workspace --all-targets -- -D warnings.
6. Use just build-python when you want an explicit build-only pass.
7. Use just build-python-plugin when the Python worker SDK changed.
8. If the native Rust bridge changed, add the Rust crate tests for nemo-relay-python.

Python Test Style

• Pytest is used to run tests.
• Do not add @pytest.mark.asyncio to any test. Async tests are automatically detected and run by the async runner; the decorator is unnecessary clutter.
• Do not add a -> None return type annotation to test functions. This is not a common convention in pytest and adds unnecessary verbosity.
• When mocking a class, do not define a new class. Use unittest.mock.MagicMock or unittest.mock.AsyncMock, with the spec constructor argument when necessary.
• The name of the mocked class should be prefixed with mock, not fake.
• Prefer pytest fixtures over helper methods.
• Do not repeat fixtures, if a fixture is needed in multiple test files, place it in a conftest.py file.
• When creating a fixture follow this pattern:

  @pytest.fixture(name="<fixture_name>"[, scope="<scope>"])
  def <fixture_name>_fixture() -> <return_type>:
      ...
  

  Only specify the scope argument when the value is something other than "function".
• Prefer pytest.mark.parametrize over creating individual tests for different input types.

Common Commands

# Focused test loop
uv run pytest -k "<pattern>"

# Required first for focused dynamic-plugin host tests
just build-test-plugin-fixtures
uv run pytest python/tests/test_dynamic_plugin_host.py

# Focused Python worker plugin SDK suite
just test-python-plugin

# Format Python files
uv run ruff format python python/plugin

# Full Python suite
just test-python

# Required when the Python change also touched Rust code
cargo fmt --all
just test-rust
cargo clippy --workspace --all-targets -- -D warnings

# Rebuild the editable package plus native extension
just build-python

# Rebuild/install the Python worker plugin SDK
just build-python-plugin

# Native extension crate when crates/python changed
cargo test -p nemo-relay-python

When To Escalate

• If crates/core, crates/adaptive, or shared runtime semantics changed, also use validate-change.
• If python/plugin or worker protocol behavior changed, also use maintain-dynamic-plugins.
• If the change is actually about docs only, prefer contribute-docs plus targeted command checks.

References

• pyproject.toml
• crates/python/Cargo.toml
• crates/python/README.md
• python/nemo_relay/README.md
• python/plugin/pyproject.toml
• python/plugin/src/nemo_relay_plugin
• python/tests/plugin
• docs/getting-started/quick-start/python.mdx
• docs/contribute/testing-and-docs.mdx
• validate-change