[ ~/netbox-sdk/developer ]tty0

   _   _      _   ___           ___ ___  _  __
  | \ | |__ _| |_| _ )_____ __ / __|   \| |/ /
  |  \| / -_)  _| _ \/ _ \ \ / \__ \ |) | ' <
  |_|\_\___|\__|___/\___/_\_\ |___/___/|_|\_\
   c l i  ·  t u i  ·  s d k  ·  a s y n c

emerson@netdevops:~/netbox-sdk$ ./describe.sh netbox-sdk

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

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.

›intro

emerson@netdevops:~/netbox-sdk/developer$ cat README.md | head

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

emerson@netdevops:~/netbox-sdk/developer$ tree -L 2 src/

  • ├─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).
  • ├─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

emerson@netdevops:~/netbox-sdk/developer$ ./describe-integrations

› target› protocol› library
NetBox REST APIHTTPS (REST + GraphQL)aiohttp via NetBoxApiClient
demo.netbox.devHTTPSPlaywright (netbox_sdk/demo_auth.py)
Local mock NetBoxHTTPFastAPI (netbox_sdk/mock_main.py)
proxbox-apiimporteddownstream consumer
  • › NetBox REST API: Token authentication; pagination, filter validation and lazy related-object loading handled in the client.
  • › demo.netbox.dev: Used by the demo profile to obtain a valid token without hard-coding credentials.
  • › Local mock NetBox: Spawned via the nbx-mock entry point. Same routes the SDK exercises in tests.
  • › proxbox-api: proxbox-api pins netbox-sdk==0.0.8.post1 as its NetBox write target.

›contributing

emerson@netdevops:~/netbox-sdk/developer$ ./contributing --help

# dev install

install
emerson@netdevops:~$ uv sync --dev --extra cli --extra tui --extra demo

# pre-PR checks

  • › install hooks

    shell
    uv run pre-commit install --hook-type pre-commit --hook-type pre-push

  • › all hooks

    shell
    uv run pre-commit run --all-files

  • › tests

    shell
    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).

# issue tracker https://github.com/emersonfelipesp/netbox-sdk/issues

›e2e

emerson@netdevops:~/netbox-sdk/developer$ ./run-e2e --report

› 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)

    shell
    uv run pytest -m suite_tui

  • › SDK suite (live NetBox in Docker)

    shell
    uv run pytest -m suite_sdk

  • › everything

    shell
    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: .github/workflows/test.yml × {v4.5.8, v4.5.9, v4.6.0} runs suite_sdk against a real API including auth / pagination / GraphQL.
  • ├─Hex-literal guard: tests/test_no_hardcoded_colors.py keeps theme values out of TCSS.

› ci workflow: .github/workflows/test.yml

›links

emerson@netdevops:~/netbox-sdk/developer$ links