netbox-inventory-toolkit 0.1.6__tar.gz

netbox_inventory_toolkit-0.1.6/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Blalange
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

netbox_inventory_toolkit-0.1.6/PKG-INFO

@@ -0,0 +1,186 @@
+Metadata-Version: 2.4
+Name: netbox-inventory-toolkit
+Version: 0.1.6
+Summary: Collect, validate and reconcile a YAML inventory into NetBox
+Author: Blalange
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Blalange/netbox-inventory-toolkit
+Project-URL: Issues, https://github.com/Blalange/netbox-inventory-toolkit/issues
+Keywords: netbox,inventory,dcim,ipam,snmp,ipmi,yaml
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: <3.14,>=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pynetbox>=7.9.0
+Requires-Dist: PyYAML>=6.0.3
+Requires-Dist: requests>=2.32.5
+Provides-Extra: snmp
+Requires-Dist: pysnmp==7.1.22; extra == "snmp"
+Provides-Extra: lsp
+Requires-Dist: pygls<3,>=2.1; extra == "lsp"
+Requires-Dist: lsprotocol; extra == "lsp"
+Provides-Extra: all
+Requires-Dist: pysnmp==7.1.22; extra == "all"
+Requires-Dist: pygls<3,>=2.1; extra == "all"
+Requires-Dist: lsprotocol; extra == "all"
+Dynamic: license-file
+
+# netbox-inventory-toolkit
+
+Collect a declarative YAML inventory from optional live sources, validate it,
+and reconcile it into [NetBox](https://netbox.dev).
+
+The toolkit is deliberately source-agnostic. UniFi, SNMP, Talos, Redfish and
+IPMI are optional adapters; an inventory that only uses SNMP and IPMI works
+without UniFi, and a manual-only inventory works without any live source.
+
+## What it includes
+
+- **Collector** — merges live observations into a generated inventory layer.
+- **Sync** — reconciles the manual + generated layers into NetBox over the REST
+  API, with optional Device Type Library enrichment and image uploads.
+- **Language server** — diagnostics, completion, go-to-definition, hover and
+  rename for inventory YAML.
+- **VS Code extension** — a thin client for the language server.
+
+## Install
+
+Use `uv` to run a pinned revision without installing anything globally:
+
+```sh
+uvx --from "netbox-inventory-toolkit[all] @ git+https://github.com/Blalange/netbox-inventory-toolkit@v0.1.6" \
+  netbox-inventory-toolkit --help
+```
+
+Or install it as a package from [PyPI](https://pypi.org/project/netbox-inventory-toolkit/):
+
+```sh
+pip install "netbox-inventory-toolkit[all]"
+```
+
+Tagged releases are published to PyPI from the `release.yml` workflow using
+PyPI trusted publishing. The trusted publisher is configured for this
+repository, workflow `release.yml`, and environment `pypi`.
+
+## Quick start: SNMP + IPMI only
+
+The repository contains a minimal example inventory with one SNMP switch and
+one IPMI server:
+
+```sh
+netbox-inventory-toolkit check --inventory examples/minimal --no-dtl
+netbox-inventory-toolkit collect --inventory examples/minimal --sources snmp,ipmi
+netbox-inventory-toolkit sync --inventory examples/minimal --check --no-dtl
+```
+
+The collector reads `snmp_ip` and `ipmi_ip` from manual device entries. No
+UniFi controller or Kubernetes cluster is required.
+
+## Commands
+
+```text
+netbox-inventory-toolkit collect --inventory inventory [--sources auto|all|none|list]
+netbox-inventory-toolkit sync --inventory inventory --check
+netbox-inventory-toolkit sync --inventory inventory --dry-run --prune
+netbox-inventory-toolkit lsp --inventory inventory
+```
+
+`--sources auto` enables a source only when its configuration and credentials
+are present. Explicitly selecting a source that is not configured is an error;
+`auto` and `all` skip it with a warning.
+
+## Optional sources
+
+| Source | Configuration |
+|---|---|
+| UniFi | `UNIFI_URL`, `UNIFI_USER`, `UNIFI_PASS` or `--unifi-secret NAMESPACE/NAME` |
+| SNMP | manual devices with `snmp_ip`; optional `--snmp-community` |
+| Talos | a working `kubectl`, `--nodes-json`, and optional `--talosctl` |
+| Redfish | manual devices with `redfish_ip`; `REDFISH_USER` / `REDFISH_PASS` |
+| IPMI | manual devices with `ipmi_ip`; `ipmitool` and `IPMI_USER` / `IPMI_PASS` |
+
+Optional Python extras:
+
+- `snmp` adds `pysnmp`.
+- `lsp` adds `pygls` and `lsprotocol`.
+- `all` adds both.
+
+## Inventory model
+
+The inventory root contains:
+
+```text
+inventory/
+├── manual/       # hand-maintained objects; wins over generated values
+├── generated/    # collector output; do not edit
+└── images/       # device-type images referenced from manual device types
+```
+
+See [docs/inventory-schema.md](docs/inventory-schema.md) for the schema,
+natural keys and provenance tags.
+
+## Container image
+
+The release workflow publishes:
+
+```text
+ghcr.io/blalange/netbox-inventory-toolkit:v0.1.6
+```
+
+The release workflow tries to make the GHCR package public. If it remains
+private, either change the package visibility in the GitHub package settings or
+add an `imagePullSecrets` entry with a token that has `read:packages`.
+
+The image entrypoint is `netbox-inventory-toolkit` and the default command is
+`sync`. Mount the inventory at `/inventory`, images at `/images`, and a writable
+cache/media volume at `/media`:
+
+```yaml
+containers:
+  - name: sync
+    image: ghcr.io/blalange/netbox-inventory-toolkit:v0.1.6
+    command: ["netbox-inventory-toolkit", "sync"]
+    env:
+      - name: NETBOX_URL
+        value: http://netbox.netbox.svc.cluster.local
+      - name: NETBOX_TOKEN
+        valueFrom:
+          secretKeyRef:
+            name: netbox-secrets
+            key: api_token_full
+      - name: NETBOX_INVENTORY_DIR
+        value: /inventory
+      - name: NETBOX_IMAGES_DIR
+        value: /images
+      - name: DTL_CACHE_DIR
+        value: /media/dtl-cache
+```
+
+See [docs/sync.md](docs/sync.md) for the full CronJob example and options.
+
+## Development
+
+```sh
+uv sync --extra all --group dev
+uv run ruff check .
+uv run pytest
+```
+
+Package the VS Code extension:
+
+```sh
+cd editors/vscode/netbox-inventory-toolkit
+npm ci
+npm run package
+```
+
+## License
+
+MIT

netbox_inventory_toolkit-0.1.6/README.md

@@ -0,0 +1,152 @@
+# netbox-inventory-toolkit
+
+Collect a declarative YAML inventory from optional live sources, validate it,
+and reconcile it into [NetBox](https://netbox.dev).
+
+The toolkit is deliberately source-agnostic. UniFi, SNMP, Talos, Redfish and
+IPMI are optional adapters; an inventory that only uses SNMP and IPMI works
+without UniFi, and a manual-only inventory works without any live source.
+
+## What it includes
+
+- **Collector** — merges live observations into a generated inventory layer.
+- **Sync** — reconciles the manual + generated layers into NetBox over the REST
+  API, with optional Device Type Library enrichment and image uploads.
+- **Language server** — diagnostics, completion, go-to-definition, hover and
+  rename for inventory YAML.
+- **VS Code extension** — a thin client for the language server.
+
+## Install
+
+Use `uv` to run a pinned revision without installing anything globally:
+
+```sh
+uvx --from "netbox-inventory-toolkit[all] @ git+https://github.com/Blalange/netbox-inventory-toolkit@v0.1.6" \
+  netbox-inventory-toolkit --help
+```
+
+Or install it as a package from [PyPI](https://pypi.org/project/netbox-inventory-toolkit/):
+
+```sh
+pip install "netbox-inventory-toolkit[all]"
+```
+
+Tagged releases are published to PyPI from the `release.yml` workflow using
+PyPI trusted publishing. The trusted publisher is configured for this
+repository, workflow `release.yml`, and environment `pypi`.
+
+## Quick start: SNMP + IPMI only
+
+The repository contains a minimal example inventory with one SNMP switch and
+one IPMI server:
+
+```sh
+netbox-inventory-toolkit check --inventory examples/minimal --no-dtl
+netbox-inventory-toolkit collect --inventory examples/minimal --sources snmp,ipmi
+netbox-inventory-toolkit sync --inventory examples/minimal --check --no-dtl
+```
+
+The collector reads `snmp_ip` and `ipmi_ip` from manual device entries. No
+UniFi controller or Kubernetes cluster is required.
+
+## Commands
+
+```text
+netbox-inventory-toolkit collect --inventory inventory [--sources auto|all|none|list]
+netbox-inventory-toolkit sync --inventory inventory --check
+netbox-inventory-toolkit sync --inventory inventory --dry-run --prune
+netbox-inventory-toolkit lsp --inventory inventory
+```
+
+`--sources auto` enables a source only when its configuration and credentials
+are present. Explicitly selecting a source that is not configured is an error;
+`auto` and `all` skip it with a warning.
+
+## Optional sources
+
+| Source | Configuration |
+|---|---|
+| UniFi | `UNIFI_URL`, `UNIFI_USER`, `UNIFI_PASS` or `--unifi-secret NAMESPACE/NAME` |
+| SNMP | manual devices with `snmp_ip`; optional `--snmp-community` |
+| Talos | a working `kubectl`, `--nodes-json`, and optional `--talosctl` |
+| Redfish | manual devices with `redfish_ip`; `REDFISH_USER` / `REDFISH_PASS` |
+| IPMI | manual devices with `ipmi_ip`; `ipmitool` and `IPMI_USER` / `IPMI_PASS` |
+
+Optional Python extras:
+
+- `snmp` adds `pysnmp`.
+- `lsp` adds `pygls` and `lsprotocol`.
+- `all` adds both.
+
+## Inventory model
+
+The inventory root contains:
+
+```text
+inventory/
+├── manual/       # hand-maintained objects; wins over generated values
+├── generated/    # collector output; do not edit
+└── images/       # device-type images referenced from manual device types
+```
+
+See [docs/inventory-schema.md](docs/inventory-schema.md) for the schema,
+natural keys and provenance tags.
+
+## Container image
+
+The release workflow publishes:
+
+```text
+ghcr.io/blalange/netbox-inventory-toolkit:v0.1.6
+```
+
+The release workflow tries to make the GHCR package public. If it remains
+private, either change the package visibility in the GitHub package settings or
+add an `imagePullSecrets` entry with a token that has `read:packages`.
+
+The image entrypoint is `netbox-inventory-toolkit` and the default command is
+`sync`. Mount the inventory at `/inventory`, images at `/images`, and a writable
+cache/media volume at `/media`:
+
+```yaml
+containers:
+  - name: sync
+    image: ghcr.io/blalange/netbox-inventory-toolkit:v0.1.6
+    command: ["netbox-inventory-toolkit", "sync"]
+    env:
+      - name: NETBOX_URL
+        value: http://netbox.netbox.svc.cluster.local
+      - name: NETBOX_TOKEN
+        valueFrom:
+          secretKeyRef:
+            name: netbox-secrets
+            key: api_token_full
+      - name: NETBOX_INVENTORY_DIR
+        value: /inventory
+      - name: NETBOX_IMAGES_DIR
+        value: /images
+      - name: DTL_CACHE_DIR
+        value: /media/dtl-cache
+```
+
+See [docs/sync.md](docs/sync.md) for the full CronJob example and options.
+
+## Development
+
+```sh
+uv sync --extra all --group dev
+uv run ruff check .
+uv run pytest
+```
+
+Package the VS Code extension:
+
+```sh
+cd editors/vscode/netbox-inventory-toolkit
+npm ci
+npm run package
+```
+
+## License
+
+MIT

netbox_inventory_toolkit-0.1.6/pyproject.toml

@@ -0,0 +1,60 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "netbox-inventory-toolkit"
+version = "0.1.6"
+description = "Collect, validate and reconcile a YAML inventory into NetBox"
+readme = "README.md"
+requires-python = ">=3.12,<3.14"
+license = "MIT"
+authors = [{ name = "Blalange" }]
+keywords = ["netbox", "inventory", "dcim", "ipam", "snmp", "ipmi", "yaml"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Intended Audience :: System Administrators",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: System :: Systems Administration",
+]
+dependencies = [
+  "pynetbox>=7.9.0",
+  "PyYAML>=6.0.3",
+  "requests>=2.32.5",
+]
+
+[project.optional-dependencies]
+snmp = ["pysnmp==7.1.22"]
+lsp = ["pygls>=2.1,<3", "lsprotocol"]
+all = ["pysnmp==7.1.22", "pygls>=2.1,<3", "lsprotocol"]
+
+[project.scripts]
+netbox-inventory-toolkit = "netbox_inventory_toolkit.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/Blalange/netbox-inventory-toolkit"
+Issues = "https://github.com/Blalange/netbox-inventory-toolkit/issues"
+
+[dependency-groups]
+dev = [
+  "pytest>=8",
+  "ruff>=0.8",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+ignore = ["E501"]

netbox_inventory_toolkit-0.1.6/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

netbox_inventory_toolkit-0.1.6/src/netbox_inventory_toolkit/__init__.py

@@ -0,0 +1,8 @@
+"""NetBox inventory toolkit."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("netbox-inventory-toolkit")
+except PackageNotFoundError:  # running from a source tree without installed metadata
+    __version__ = "0.1.6"

netbox_inventory_toolkit-0.1.6/src/netbox_inventory_toolkit/__main__.py

@@ -0,0 +1,6 @@
+from __future__ import annotations
+
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

netbox_inventory_toolkit-0.1.6/src/netbox_inventory_toolkit/cli.py

@@ -0,0 +1,49 @@
+"""Command line entry point for the NetBox inventory toolkit."""
+
+from __future__ import annotations
+
+import sys
+
+from . import __version__
+
+USAGE = """\
+usage: netbox-inventory-toolkit <command> [options]
+
+commands:
+  collect   collect live source data into the generated inventory layer
+  sync      reconcile the inventory into NetBox
+  check     validate the inventory without contacting NetBox
+  lsp       run the inventory language server (stdio)
+  version   print the package version
+"""
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = list(sys.argv[1:] if argv is None else argv)
+    if not args or args[0] in {"-h", "--help", "help"}:
+        print(USAGE, end="")
+        return 0
+    if args[0] in {"--version", "version"}:
+        print(f"netbox-inventory-toolkit {__version__}")
+        return 0
+
+    command, rest = args[0], args[1:]
+    if command == "collect":
+        from .collect.cli import main as collect_main
+
+        return collect_main(rest)
+    if command in {"sync", "check"}:
+        from .sync.cli import main as sync_main
+
+        return sync_main([*rest, "--check"] if command == "check" else rest)
+    if command == "lsp":
+        from .lsp import main as lsp_main
+
+        return lsp_main(rest)
+
+    print(f"error: unknown command {command!r}\n\n{USAGE}", file=sys.stderr, end="")
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

netbox_inventory_toolkit-0.1.6/src/netbox_inventory_toolkit/collect/__init__.py

@@ -0,0 +1 @@
+"""Inventory collection pipeline."""

netbox_inventory_toolkit-0.1.6/src/netbox_inventory_toolkit/collect/__main__.py

@@ -0,0 +1,6 @@
+from __future__ import annotations
+
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())