netbox-sdk developer guide

# netbox-sdk developer guide

Developer guide — three packages, one async runtime, OpenAPI-driven CLI, and a Textual TUI test harness.

| Field |Value |
| --- | --- |
| Canonical URL | https://emersonfelipesp.com/netbox-sdk/developer |
| Showcase | https://emersonfelipesp.com/netbox-sdk |
| GitHub | https://github.com/emersonfelipesp/netbox-sdk |
| Releases | https://emersonfelipesp.com/netbox-sdk/releases |
| Release snapshot synced | 2026-11-13T23:16:38.876Z |

## Intro

netbox-sdk is a single-repo, three-package toolkit: an async Python SDK, a Typer-powered CLI (nbx), and a Textual TUI. They share one runtime and a strict import boundary.

This page documents the layout, the OpenAPI-driven dynamic command system, the contribution workflow, and the headless Textual pilot harness used to run the TUI suite end-to-end without a real terminal.

## Architecture

- Three co-published packages: netbox_sdk/ (standalone API layer, no CLI/TUI deps), netbox_cli/ (Typer CLI, entry point nbx), netbox_tui/ (Textual TUI, lazy-loaded). Build backend: setuptools.
- Import boundary (enforced by convention + tests): netbox_sdk must NOT import netbox_cli or netbox_tui. Absolute imports only.
- SDK core: netbox_sdk/client.py wraps aiohttp.ClientSession and exposes three layers — raw NetBoxApiClient, async facade api(), versioned typed client typed_api() (4.3 / 4.4 / 4.5 / 4.6 / 4.7).
- Bundled OpenAPI: netbox_sdk/reference/openapi/*.json holds shipped schemas for every supported NetBox release.
- CLI dynamic command generation: netbox_cli/dynamic.py registers Typer commands at import time from the OpenAPI schema. netbox_cli/runtime.py owns config / index / client factories. Docs are generated by netbox_cli/docgen*.
- TUI: netbox_tui/app.py is the main app. netbox_tui/theme_registry.py auto-discovers JSON themes from netbox_tui/themes/*.json. TCSS files are runtime assets; tests/test_no_hardcoded_colors.py forbids hex literals in TCSS.
- Mock layer: netbox_sdk/mock_main.py serves a local FastAPI mock (entry point nbx-mock) for offline tests and demos. CRUD-complete in-memory state.
- Demo flow: netbox_sdk/demo_auth.py uses Playwright to authenticate against demo.netbox.dev so portfolio captures (DemoInitRunner / DemoDevicesListRunner on the showcase site) reflect real CLI output.

## Integrations

| Target |Protocol |Library |Notes |
| --- | --- | --- | --- |
| NetBox REST API | HTTPS (REST + GraphQL) | aiohttp via NetBoxApiClient | Token authentication; pagination, filter validation and lazy related-object loading handled in the client. |
| demo.netbox.dev | HTTPS | Playwright (netbox_sdk/demo_auth.py) | Used by the demo profile to obtain a valid token without hard-coding credentials. |
| Local mock NetBox | HTTP | FastAPI (netbox_sdk/mock_main.py) | Spawned via the nbx-mock entry point. Same routes the SDK exercises in tests. |
| proxbox-api | imported | downstream consumer | proxbox-api pins netbox-sdk==0.0.13 as its NetBox REST write target; this dependency is separate from the semantic MCP bridge. |

## Contributing

Development install:

```shell
uv sync --dev --extra cli --extra tui --extra demo
```

Pre-PR checks:

- install hooks: `uv run pre-commit install --hook-type pre-commit --hook-type pre-push`
- all hooks: `uv run pre-commit run --all-files`
- tests: `uv run pytest`

Code style:

- Linter: ruff (select E/F/I/UP/W/ANN201/ANN202).
- Type checker: ty.
- Pre-commit gates both pre-commit and pre-push events — install both hook types.
- Hard rule: no hex color literals in TCSS (enforced by tests/test_no_hardcoded_colors.py).

Issues: https://github.com/emersonfelipesp/netbox-sdk/issues

## End-to-end tests

Framework: pytest + pytest-asyncio (asyncio_mode=auto) + Textual's App.run_test() Pilot — TUI tests run headless, no real terminal needed.

TUI tests mount each app in a virtual terminal via async with App.run_test() as pilot, then drive keys/mouse with the Pilot API. SDK tests run the live API matrix on push to main against a NetBox Docker container.

The two test suites are separated by pytest markers so each can be run in isolation in CI.

Commands:

- TUI suite (headless): `uv run pytest -m suite_tui`
- SDK suite (live NetBox in Docker): `uv run pytest -m suite_sdk`
- everything: `uv run pytest`

Coverage:

- Spec files: tests/test_cli_tui.py (NbxCliTuiApp navigation + command execution), test_tui_interaction.py (breadcrumb, filtering, cable trace, theme tokens), test_dev_tui.py, test_graphql_tui.py.
- Screenshot harness: test_tui_screenshots.py captures fixtures used by the portfolio site's docgen pipeline.
- Live NetBox matrix: 4.7.0, 4.6.6, 4.6.3, 4.6.2, and 4.5.10 run the SDK against a real API; bundled-schema jobs cover every 4.3–4.7 release line.
- Hex-literal guard: tests/test_no_hardcoded_colors.py keeps theme values out of TCSS.

CI workflow: .github/workflows/test.yml (https://github.com/emersonfelipesp/netbox-sdk/blob/main/.github/workflows/test.yml)

## Links

| Label |URL |
| --- | --- |
| repo | https://github.com/emersonfelipesp/netbox-sdk |
| pypi | https://pypi.org/project/netbox-sdk/ |
| docs | https://emersonfelipesp.com/netbox-sdk/docs/ |
| issues | https://github.com/emersonfelipesp/netbox-sdk/issues |