opennms-api-wrapper 0.2.0__tar.gz

opennms_api_wrapper-0.2.0/CHANGELOG.md

@@ -0,0 +1,54 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] - 2026-03-07
+
+### Fixed
+
+- Accept header now includes `text/plain;q=0.9` to prevent 406 errors on
+  `/count` endpoints in some OpenNMS versions.
+- `get_node_count()` uses the v2 API (`GET /api/v2/nodes?limit=1`) and
+  extracts `totalCount`. The v1 `/rest/nodes` endpoint does not expose a
+  `/count` sub-resource.
+
+### Changed
+
+- Smoke test: endpoints that depend on optional plugins (alarm history,
+  hardware inventory, flows, situations) or heavy queries (resources) now
+  report as WARN instead of FAIL.  Each warning cites the required plugin
+  or feature.
+- Smoke test: events query filters by lowest-ID node to avoid full table
+  scans on large databases.
+
+### Added
+
+- Smoke test: `--skip` flag to skip tests by label prefix (e.g.,
+  `--skip get_flow` skips all flow tests).
+- Smoke test: `OPENNMS_TIMEOUT` env var (default 60 seconds).
+- Validated against OpenNMS Meridian 2024.3.0 (65 passed, 0 failed).
+
+## [0.1.0] - 2026-03-06
+
+### Added
+
+- Initial release covering all OpenNMS Horizon 35 REST API endpoints (v1
+  and v2).
+- Single `OpenNMS` client class importable as `import opennms_api_wrapper as
+  opennms`.
+- JSON-only request/response handling throughout; no XML dependency.
+- Synchronous, dependency-minimal design (only `requests` required at
+  runtime).
+- 290-test suite with full method coverage; HTTP mocked at the adapter level
+  using the `responses` library — no live server required to run tests.
+- Resource groups covered: alarms, alarm statistics, alarm history, events,
+  nodes (with IP interfaces, SNMP interfaces, monitored services, categories,
+  assets, and hardware inventory), outages, notifications, acknowledgements,
+  requisitions, foreign sources, SNMP configuration, groups, users,
+  categories, scheduled outages, KSC reports, resources, measurements,
+  heatmap, maps, topology graphs, flows, device configuration, situations
+  (v2), business services (v2), metadata (v2), server info, discovery (v2),
+  and global IP/SNMP interface views (v2).

opennms_api_wrapper-0.2.0/CLAUDE.md

@@ -0,0 +1,149 @@
+# CLAUDE.md — opennms-api-wrapper
+
+This file gives Claude Code the context needed to work on this project
+without prior conversation history.
+
+## Project purpose
+
+A thin, synchronous Python 3 wrapper for the OpenNMS REST API (Horizon 35).
+Users `import opennms_api_wrapper as opennms` and get a single `OpenNMS`
+client class with one method per API endpoint.
+
+## Repository layout
+
+```
+opennms_api_wrapper/    # installable package
+    __init__.py         # exports OpenNMS, __version__
+    client.py           # OpenNMS class (combines all mixins)
+    _base.py            # _OpenNMSBase: HTTP helpers (_get/_post/_put/_delete/_parse)
+    _alarms.py          # AlarmsMixin
+    _alarm_stats.py     # AlarmStatsMixin
+    _alarm_history.py   # AlarmHistoryMixin
+    _events.py          # EventsMixin
+    _nodes.py           # NodesMixin  (largest: nodes + sub-resources)
+    _outages.py         # OutagesMixin
+    _notifications.py   # NotificationsMixin
+    _acks.py            # AcksMixin
+    _requisitions.py    # RequisitionsMixin
+    _foreign_sources.py # ForeignSourcesMixin
+    _snmp_config.py     # SnmpConfigMixin
+    _groups.py          # GroupsMixin
+    _users.py           # UsersMixin
+    _categories.py      # CategoriesMixin
+    _sched_outages.py   # SchedOutagesMixin
+    _ksc_reports.py     # KscReportsMixin
+    _resources.py       # ResourcesMixin
+    _measurements.py    # MeasurementsMixin
+    _heatmap.py         # HeatmapMixin
+    _maps.py            # MapsMixin
+    _graphs.py          # GraphsMixin
+    _flows.py           # FlowsMixin
+    _device_config.py   # DeviceConfigMixin
+    _situations.py      # SituationsMixin  (v2)
+    _business_services.py  # BusinessServicesMixin  (v2)
+    _metadata.py        # MetadataMixin  (v2, largest: node/iface/service metadata)
+    _info.py            # InfoMixin
+    _discovery.py       # DiscoveryMixin  (v2)
+    _ipinterfaces_v2.py    # IpInterfacesV2Mixin
+    _snmpinterfaces_v2.py  # SnmpInterfacesV2Mixin
+
+tests/
+    conftest.py         # client fixture, V1/V2 URL constants, qs() helper
+    fixtures.py         # all accurate OpenNMS Horizon 35 response shapes
+    test_*.py           # one file per mixin (30 files, 290 tests total)
+
+dist/                   # built artifacts (gitignored)
+pyproject.toml          # build config + project metadata
+smoke_test.py           # live-server smoke test (read-only + --write mode)
+                        #   python smoke_test.py                 # read-only, safe for any server
+                        #   python smoke_test.py --write         # write ops, prompts for confirmation
+                        #   python smoke_test.py --write --yes   # skip prompt (CI only)
+                        #   python smoke_test.py --no-color      # plain output for log files
+                        #   python smoke_test.py --skip get_flow # skip by label prefix
+                        #   env vars: OPENNMS_URL, OPENNMS_USER, OPENNMS_PASSWORD,
+                        #            OPENNMS_VERIFY_SSL, OPENNMS_TIMEOUT
+ARCHITECTURE.md         # architecture decision records (ADRs)
+MERMAID.md              # Mermaid architecture diagrams
+CHANGELOG.md
+README.md
+CONTRIBUTING.md
+```
+
+## Architecture decisions (do not change without good reason)
+
+- **Mixin pattern**: each resource group lives in its own `_<name>.py` mixin.
+  `client.py` combines them all via multiple inheritance into `OpenNMS`.
+- **JSON only**: all request bodies are JSON. No XML anywhere.
+  The one exception: `POST /rest/acks` uses `application/x-www-form-urlencoded`
+  because the OpenNMS API requires it — handled via `form_data=` in `_post`.
+- **Synchronous only**: no async. `requests.Session` is used throughout.
+  One runtime dependency: `requests>=2.28`.
+- **v1 vs v2**: v1 endpoints live at `/opennms/rest/`, v2 at
+  `/opennms/api/v2/`. Every `_get/_post/_put/_delete` accepts `v2=True`.
+- **Accept header**: `application/json, text/plain;q=0.9`. Some OpenNMS
+  versions return 406 if the Accept header does not include `text/plain` for
+  `/count` endpoints. JSON stays preferred via implicit q=1.0.
+- **`_parse()`** handles three response types:
+  - `application/json` → `resp.json()`
+  - `text/plain` → `int(text)` if possible, else `str`
+  - empty body (204 No Content) → `None`
+- **Node count via v2**: `get_node_count()` uses `GET /api/v2/nodes?limit=1`
+  and extracts `totalCount`. The v1 `/rest/nodes` endpoint does not have a
+  `/count` sub-resource — it routes all sub-paths as node criteria.
+- **Timeout**: `_OpenNMSBase.__init__` accepts `timeout=30` (seconds). Passed
+  to every `_session.get/post/put/delete` call. `OpenNMS.__init__` exposes it
+  as a public parameter.
+- **Smoke test warn level**: endpoints that depend on optional plugins or
+  heavy server-side queries use `warn()` instead of `run()`. Warnings are
+  non-fatal and include the required plugin/feature name. Only hard `FAIL`s
+  cause a non-zero exit code.
+
+## Development environment
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"   # installs requests + pytest + responses
+pytest tests/ -v          # run full suite (290 tests, ~0.2 s)
+```
+
+Always activate the `.venv` before running any commands — never rely on the
+system Python or system pip.
+
+## Test conventions
+
+- HTTP mocking: `responses` library with `@responses.activate` decorator.
+- `conftest.py` constants:
+  - `V1 = "http://opennms:8980/opennms/rest"`
+  - `V2 = "http://opennms:8980/opennms/api/v2"`
+  - `qs(url)` parses query params from a URL into a dict of lists.
+- Fixture shapes in `tests/fixtures.py` mirror real OpenNMS Horizon 35
+  responses (singular resource name as list wrapper key, plus `totalCount`,
+  `count`, `offset`).
+- **URL encoding gotcha**: `requests` percent-encodes spaces in URL path
+  segments as `%20`, not `+`. Mock URLs for paths with spaces must use `%20`
+  explicitly, e.g. `Do%20Not%20Persist%20Discovered%20IPs`.
+- 204 responses return `None`; plain-text count endpoints return `int`.
+- Verify request bodies with `json.loads(responses.calls[0].request.body)`.
+
+## Build / release
+
+```bash
+pip install build
+python -m build          # produces dist/*.tar.gz and dist/*.whl
+pip install twine
+twine upload dist/*      # publish to PyPI
+```
+
+The build backend is `setuptools.build_meta` (in `pyproject.toml`).
+The older path `setuptools.backends.legacy:build` does not work — do not use it.
+
+## Style
+
+- PEP 8 throughout: 79-character line limit, 4-space indentation.
+- Every public method has a Google-style docstring with `Args:` and `Returns:`
+  sections where non-trivial — required for autodoc compatibility (Sphinx,
+  pdoc, mkdocstrings). Private helpers have at minimum a one-line docstring.
+- No inline comments on code that is self-evident.
+- No error handling for scenarios that cannot happen.
+- No abstractions introduced for one-off operations.

opennms_api_wrapper-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Richard "Chance" Newkirk
+
+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.

opennms_api_wrapper-0.2.0/MANIFEST.in

@@ -0,0 +1,2 @@
+include CHANGELOG.md
+include CLAUDE.md

opennms_api_wrapper-0.2.0/PKG-INFO

@@ -0,0 +1,232 @@
+Metadata-Version: 2.4
+Name: opennms-api-wrapper
+Version: 0.2.0
+Summary: A thin Python wrapper for the OpenNMS REST API (Horizon 35)
+Author-email: "Richard \"Chance\" Newkirk" <chance.newkirk+github@pm.me>
+License: MIT License
+        
+        Copyright (c) 2026 Richard "Chance" Newkirk
+        
+        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.
+        
+Project-URL: Homepage, https://github.com/cnewkirk/opennms-api-wrapper
+Project-URL: Repository, https://github.com/cnewkirk/opennms-api-wrapper
+Project-URL: Bug Tracker, https://github.com/cnewkirk/opennms-api-wrapper/issues
+Project-URL: Changelog, https://github.com/cnewkirk/opennms-api-wrapper/blob/main/CHANGELOG.md
+Keywords: opennms,network-management,rest,api,wrapper,nms
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Intended Audience :: Telecommunications Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Topic :: System :: Networking :: Monitoring
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.28
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: responses; extra == "dev"
+Dynamic: license-file
+
+# opennms-api-wrapper
+
+[![CI](https://github.com/cnewkirk/opennms-api-wrapper/actions/workflows/ci.yml/badge.svg)](https://github.com/cnewkirk/opennms-api-wrapper/actions/workflows/ci.yml)
+[![GitHub release](https://img.shields.io/github/v/release/cnewkirk/opennms-api-wrapper)](https://github.com/cnewkirk/opennms-api-wrapper/releases)
+[![Python](https://img.shields.io/badge/python-3.8%2B-blue)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+A thin, dependency-minimal Python 3 wrapper for the
+[OpenNMS](https://www.opennms.com/) REST API (Horizon 35+).
+Validated against OpenNMS Meridian 2024.3.0 with a live-server smoke test
+suite.
+
+## Features
+
+- Covers every v1 (`/opennms/rest/`) and v2 (`/opennms/api/v2/`) endpoint
+- JSON everywhere — no XML handling required
+- Single runtime dependency: [`requests`](https://docs.python-requests.org/)
+- Synchronous and straightforward — no async complexity
+- 290-test suite with full method coverage (mocked HTTP — no live server required)
+- Live-server smoke test validated against Meridian 2024.3.0
+
+## Installation
+
+**From the GitHub release** (no clone required — recommended for most users):
+
+```bash
+pip install https://github.com/cnewkirk/opennms-api-wrapper/archive/refs/tags/v0.2.0.tar.gz
+```
+
+**From source** (clone first, then install):
+
+```bash
+git clone https://github.com/cnewkirk/opennms-api-wrapper.git
+cd opennms-api-wrapper
+pip install .
+```
+
+When the package is published to PyPI, installation will simplify to
+`pip install opennms-api-wrapper`.
+
+## Quick start
+
+```python
+import opennms_api_wrapper as opennms
+
+client = opennms.OpenNMS(
+    url="https://opennms.example.com:8443",
+    username="admin",
+    password="admin",
+)
+
+# Server info
+info = client.get_info()
+print(info["displayVersion"])
+
+# List alarms
+alarms = client.get_alarms(limit=25, order_by="lastEventTime", order="desc")
+for alarm in alarms["alarm"]:
+    print(alarm["id"], alarm["severity"], alarm["nodeLabel"])
+
+# Acknowledge an alarm
+client.ack_alarm(alarm_id=42)
+
+# List alarms with FIQL filter (v2)
+alarms = client.get_alarms_v2(fiql="severity==MAJOR")
+```
+
+## API coverage
+
+| Resource group | Methods |
+|---|---|
+| Alarms (v1 + v2) | list, get, count, ack/unack/clear/escalate, bulk ops |
+| Alarm statistics | stats, stats by severity |
+| Alarm history | history, history at timestamp, state changes |
+| Events | list, get, count, create, ack/unack, bulk ack/unack |
+| Nodes | full CRUD + IP interfaces, SNMP interfaces, services, categories, assets, hardware |
+| Outages | list, get, count, node outages |
+| Notifications | list, get, count, trigger destination path |
+| Acknowledgements | list, get, count, create, ack/unack notification |
+| Requisitions | full CRUD including nodes, interfaces, services, categories, assets |
+| Foreign sources | full CRUD including detectors and policies |
+| SNMP configuration | get, set |
+| Groups | full CRUD + user and category membership |
+| Users | full CRUD + role assignment |
+| Categories | full CRUD + node and group associations |
+| Scheduled outages | full CRUD + daemon associations |
+| KSC reports | list, get, count, create, update |
+| Resources | list, get, get for node, select, delete |
+| Measurements | single attribute (GET), multi-source (POST) |
+| Heatmap | outages + alarms × categories / foreign sources / services / nodes |
+| Maps | full CRUD + map elements |
+| Topology graphs | containers, graph, graph view (POST), search suggestions, search results |
+| Flows | count, exporters, applications, conversations, hosts |
+| Device configuration | list, get, get by interface, latest, download, backup |
+| Situations (v2) | list, create, add alarms, clear, accept, remove alarms |
+| Business services (v2) | full CRUD |
+| Metadata (v2) | full CRUD for node, interface, and service metadata |
+| Server info | get |
+| Discovery (v2) | submit scan configuration |
+| IP interfaces (v2) | list with FIQL |
+| SNMP interfaces (v2) | list with FIQL |
+
+## Authentication
+
+Basic authentication is used. Pass `verify_ssl=False` to disable certificate
+verification (useful for self-signed certs in lab environments):
+
+```python
+client = opennms.OpenNMS(
+    url="https://opennms.example.com:8443",
+    username="admin",
+    password="admin",
+    verify_ssl=False,
+)
+```
+
+## Smoke testing
+
+`smoke_test.py` exercises the wrapper against a real OpenNMS server.  It is
+intended for use against a dev or staging instance before each release — not
+as a substitute for the 290-test mocked unit suite.
+
+Tests that depend on optional plugins or heavy endpoints are reported as
+**WARN** (non-fatal) rather than FAIL.  Each warning includes the specific
+plugin or feature required.
+
+**Read-only mode** (default) is safe to run against any server, including
+production.  It issues only GET requests and makes no changes.
+
+```bash
+export OPENNMS_URL="https://opennms.example.com:8443"
+export OPENNMS_USER="admin"
+export OPENNMS_PASSWORD="secret"
+export OPENNMS_VERIFY_SSL="false"   # omit or set to "true" for valid certs
+export OPENNMS_TIMEOUT="60"         # per-request timeout in seconds (default 60)
+
+python smoke_test.py
+```
+
+**Write mode** creates and then deletes objects on the server (events,
+categories, groups, requisitions, maps, etc.).  It will prompt for explicit
+confirmation and print the target URL before running a single write.
+**Only use write mode against a dev or staging instance — never production.**
+
+```bash
+python smoke_test.py --write          # interactive prompt required
+python smoke_test.py --write --yes    # skip prompt (CI pipelines only)
+python smoke_test.py --no-color       # plain output for log files
+python smoke_test.py --skip get_resources --skip get_flow  # skip slow tests
+```
+
+The `--skip` flag accepts a prefix — `--skip get_flow` skips all tests
+whose label starts with `get_flow`.
+
+## Development
+
+```bash
+git clone https://github.com/cnewkirk/opennms-api-wrapper.git
+cd opennms-api-wrapper
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+pytest tests/ -v
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at
+https://github.com/cnewkirk/opennms-api-wrapper.
+
+## Acknowledgements
+
+This library was designed and tested by a human, with implementation
+assistance from [Claude Code](https://claude.ai/code) (Anthropic). All API
+shapes are derived from the official OpenNMS Horizon 35 REST API
+documentation.

opennms_api_wrapper-0.2.0/README.md

@@ -0,0 +1,176 @@
+# opennms-api-wrapper
+
+[![CI](https://github.com/cnewkirk/opennms-api-wrapper/actions/workflows/ci.yml/badge.svg)](https://github.com/cnewkirk/opennms-api-wrapper/actions/workflows/ci.yml)
+[![GitHub release](https://img.shields.io/github/v/release/cnewkirk/opennms-api-wrapper)](https://github.com/cnewkirk/opennms-api-wrapper/releases)
+[![Python](https://img.shields.io/badge/python-3.8%2B-blue)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+A thin, dependency-minimal Python 3 wrapper for the
+[OpenNMS](https://www.opennms.com/) REST API (Horizon 35+).
+Validated against OpenNMS Meridian 2024.3.0 with a live-server smoke test
+suite.
+
+## Features
+
+- Covers every v1 (`/opennms/rest/`) and v2 (`/opennms/api/v2/`) endpoint
+- JSON everywhere — no XML handling required
+- Single runtime dependency: [`requests`](https://docs.python-requests.org/)
+- Synchronous and straightforward — no async complexity
+- 290-test suite with full method coverage (mocked HTTP — no live server required)
+- Live-server smoke test validated against Meridian 2024.3.0
+
+## Installation
+
+**From the GitHub release** (no clone required — recommended for most users):
+
+```bash
+pip install https://github.com/cnewkirk/opennms-api-wrapper/archive/refs/tags/v0.2.0.tar.gz
+```
+
+**From source** (clone first, then install):
+
+```bash
+git clone https://github.com/cnewkirk/opennms-api-wrapper.git
+cd opennms-api-wrapper
+pip install .
+```
+
+When the package is published to PyPI, installation will simplify to
+`pip install opennms-api-wrapper`.
+
+## Quick start
+
+```python
+import opennms_api_wrapper as opennms
+
+client = opennms.OpenNMS(
+    url="https://opennms.example.com:8443",
+    username="admin",
+    password="admin",
+)
+
+# Server info
+info = client.get_info()
+print(info["displayVersion"])
+
+# List alarms
+alarms = client.get_alarms(limit=25, order_by="lastEventTime", order="desc")
+for alarm in alarms["alarm"]:
+    print(alarm["id"], alarm["severity"], alarm["nodeLabel"])
+
+# Acknowledge an alarm
+client.ack_alarm(alarm_id=42)
+
+# List alarms with FIQL filter (v2)
+alarms = client.get_alarms_v2(fiql="severity==MAJOR")
+```
+
+## API coverage
+
+| Resource group | Methods |
+|---|---|
+| Alarms (v1 + v2) | list, get, count, ack/unack/clear/escalate, bulk ops |
+| Alarm statistics | stats, stats by severity |
+| Alarm history | history, history at timestamp, state changes |
+| Events | list, get, count, create, ack/unack, bulk ack/unack |
+| Nodes | full CRUD + IP interfaces, SNMP interfaces, services, categories, assets, hardware |
+| Outages | list, get, count, node outages |
+| Notifications | list, get, count, trigger destination path |
+| Acknowledgements | list, get, count, create, ack/unack notification |
+| Requisitions | full CRUD including nodes, interfaces, services, categories, assets |
+| Foreign sources | full CRUD including detectors and policies |
+| SNMP configuration | get, set |
+| Groups | full CRUD + user and category membership |
+| Users | full CRUD + role assignment |
+| Categories | full CRUD + node and group associations |
+| Scheduled outages | full CRUD + daemon associations |
+| KSC reports | list, get, count, create, update |
+| Resources | list, get, get for node, select, delete |
+| Measurements | single attribute (GET), multi-source (POST) |
+| Heatmap | outages + alarms × categories / foreign sources / services / nodes |
+| Maps | full CRUD + map elements |
+| Topology graphs | containers, graph, graph view (POST), search suggestions, search results |
+| Flows | count, exporters, applications, conversations, hosts |
+| Device configuration | list, get, get by interface, latest, download, backup |
+| Situations (v2) | list, create, add alarms, clear, accept, remove alarms |
+| Business services (v2) | full CRUD |
+| Metadata (v2) | full CRUD for node, interface, and service metadata |
+| Server info | get |
+| Discovery (v2) | submit scan configuration |
+| IP interfaces (v2) | list with FIQL |
+| SNMP interfaces (v2) | list with FIQL |
+
+## Authentication
+
+Basic authentication is used. Pass `verify_ssl=False` to disable certificate
+verification (useful for self-signed certs in lab environments):
+
+```python
+client = opennms.OpenNMS(
+    url="https://opennms.example.com:8443",
+    username="admin",
+    password="admin",
+    verify_ssl=False,
+)
+```
+
+## Smoke testing
+
+`smoke_test.py` exercises the wrapper against a real OpenNMS server.  It is
+intended for use against a dev or staging instance before each release — not
+as a substitute for the 290-test mocked unit suite.
+
+Tests that depend on optional plugins or heavy endpoints are reported as
+**WARN** (non-fatal) rather than FAIL.  Each warning includes the specific
+plugin or feature required.
+
+**Read-only mode** (default) is safe to run against any server, including
+production.  It issues only GET requests and makes no changes.
+
+```bash
+export OPENNMS_URL="https://opennms.example.com:8443"
+export OPENNMS_USER="admin"
+export OPENNMS_PASSWORD="secret"
+export OPENNMS_VERIFY_SSL="false"   # omit or set to "true" for valid certs
+export OPENNMS_TIMEOUT="60"         # per-request timeout in seconds (default 60)
+
+python smoke_test.py
+```
+
+**Write mode** creates and then deletes objects on the server (events,
+categories, groups, requisitions, maps, etc.).  It will prompt for explicit
+confirmation and print the target URL before running a single write.
+**Only use write mode against a dev or staging instance — never production.**
+
+```bash
+python smoke_test.py --write          # interactive prompt required
+python smoke_test.py --write --yes    # skip prompt (CI pipelines only)
+python smoke_test.py --no-color       # plain output for log files
+python smoke_test.py --skip get_resources --skip get_flow  # skip slow tests
+```
+
+The `--skip` flag accepts a prefix — `--skip get_flow` skips all tests
+whose label starts with `get_flow`.
+
+## Development
+
+```bash
+git clone https://github.com/cnewkirk/opennms-api-wrapper.git
+cd opennms-api-wrapper
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+pytest tests/ -v
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at
+https://github.com/cnewkirk/opennms-api-wrapper.
+
+## Acknowledgements
+
+This library was designed and tested by a human, with implementation
+assistance from [Claude Code](https://claude.ai/code) (Anthropic). All API
+shapes are derived from the official OpenNMS Horizon 35 REST API
+documentation.

opennms_api_wrapper-0.2.0/opennms_api_wrapper/__init__.py

@@ -0,0 +1,10 @@
+"""opennms_api_wrapper – a thin Python wrapper for the OpenNMS REST API."""
+from .client import OpenNMS
+from importlib.metadata import version, PackageNotFoundError
+
+__all__ = ["OpenNMS"]
+
+try:
+    __version__ = version("opennms-api-wrapper")
+except PackageNotFoundError:
+    __version__ = "unknown"