netbox-sdk v0.0.7

Release date: 2026-03-30
Commit: 864a07c (merge of PR #10)

This release focuses on SDK quality: shared error types, structured logging across SDK/CLI/TUI, tighter HTTP and config error handling, generated OpenAPI module documentation, and CI lockfile alignment after the version bump.

Installation

pip install "netbox-sdk==0.0.7"
# optional extras
pip install "netbox-sdk[cli,tui,demo]==0.0.7"

With uv:

uv add "netbox-sdk==0.0.7"

Highlights

Centralized exceptions (netbox_sdk.exceptions)

• RequestError — HTTP-layer failures (moved from client; still importable from netbox_sdk.client and netbox_sdk).
• ContentError, AllocationError, ParameterValidationError — facade-level errors (previously defined only in facade).
• JsonPayloadError — invalid or conflicting --body-json / --body-file usage (subclass of ValueError).

This makes it easier for callers and tests to branch on failure type without parsing message strings.

Logging

• Dual file logging roots in logging_runtime: both netbox_cli and netbox_sdk trees attach to the same rotating JSON log file, so logging.getLogger("netbox_sdk....") records persist like CLI/TUI logs.
• Module-level loggers added or expanded across SDK modules (config, schema, http_cache, services, plugin_discovery, django_models.store, etc.), CLI (dynamic, runtime, support), and TUI (app, django_model_app, graphql_app, ssl_verify_support).
• Policy documented in netbox_sdk/CLAUDE.md and netbox_tui/CLAUDE.md: no secrets in logs; prefer structured extra (e.g. nbx_event, request_path, http_method).

HTTP, payloads, and discovery

• NetBoxApiClient: more precise typing (CacheEntry, aiohttp.ClientSession under TYPE_CHECKING); safer OpenAPI version parsing; create_token only reads key when JSON body is an object.
• load_json_payload: FileNotFoundError for missing --body-file; JSONDecodeError preserved for malformed inline JSON (security tests); logging on decode/read issues.
• plugin_discovery: logs DEBUG for request/JSON failures; catches typed transport errors plus a final Exception path with DEBUG + exc_info so strict test mocks do not break the TUI.
• http_ssl: accurate return type for connector_for_config; narrowed import guard when classifying TLS errors.

CLI runtime

• _VERIFY_REQUEST_ERRORS for status checks (RuntimeError, OSError, aiohttp.ClientError) with ERROR logs before re-raise where appropriate.
• Demo token repair: narrower catches for refresh/save with structured logging.
• dynamic: return types ApiResponse / ApiResponse | None; registration and dispatch logging.

TUI

• graphql_app: parse failures narrowed to TypeError, ValueError, json.JSONDecodeError with DEBUG logging.
• django_model_app: DEBUG/WARNING logs instead of silent pass in several optional UI paths.
• ssl_verify_support: logs when syncing SSL choice to CLI runtime cache fails.

Codegen and bundled OpenAPI artifacts

• scripts/generate_typed_sdk.py: module docstring for generated typed bindings; docstrings on generated app/endpoint/root classes; _prepend_models_module_doc after datamodel-codegen.
• Committed models/v4_* and typed_versions/v4_*: top-level module docstrings for generated files.

Packaging and CI

• pyproject.toml / netbox_sdk.__version__: 0.0.7.
• uv.lock: refreshed so uv sync --locked (used in GitHub Actions) succeeds after the version bump.
• Ruff format: http_cache.py adjusted for pre-commit.

Upgrade notes

• Imports such as from netbox_sdk import RequestError and from netbox_sdk.client import RequestError continue to work.
• Code that relied on load_json_payload raising only ValueError for missing files should expect FileNotFoundError for a non-existent --body-file path.
• Mutual exclusion and wrong-shape payloads may raise JsonPayloadError (still a ValueError subclass where applicable).

Verification (upstream CI)

For commit 864a07cff6aaa4ea058b9b3d5b51fdc322421687, the following workflows completed successfully:

• Lint and Format
• Tests
• Security Tests
• Main Post-Merge Validation
• Build and deploy documentation
• Dependabot Updates (workflow run associated with the push)

Links

• PyPI: https://pypi.org/project/netbox-sdk/
• Documentation: https://emersonfelipesp.github.io/netbox-sdk/
• Repository: https://github.com/emersonfelipesp/netbox-sdk
• Full changelog (compare): v0.0.6...v0.0.7

Thanks

Thanks to everyone reporting issues and trying the SDK, CLI, and Textual TUIs. Feedback on logging noise levels and exception ergonomics is welcome for the next patch release.