v0.4.5

Coverage badge added to the Read the Docs landing page.

v0.4.4

What's changed

• Split connect/read timeout: connect timeout now capped at min(timeout, 10) s — unreachable hosts fail fast without waiting for the full read timeout. Fully transparent; the timeout parameter is unchanged.
• Larger connection pool: HTTPAdapter always mounted with pool_connections=4, pool_maxsize=20 — improves throughput when requests are parallelised via ThreadPoolExecutor.

Full changelog: https://github.com/cnewkirk/opennms-api-wrapper/blob/main/CHANGELOG.md

v0.4.3

What's changed

• PyPI homepage now links to the Read the Docs documentation site instead of the GitHub repository.
• Package description updated to "unofficial Python 3 client" to accurately reflect the project's relationship with OpenNMS.
• Library described as an "unofficial client" throughout README and docs.
• Live-server validation qualified as read-only; write mode noted as untested against a live server (reports and contributions welcome).
• OpenNMS resources block added to README and docs: Docs · REST API reference · Community forum.

Full changelog: https://github.com/cnewkirk/opennms-api-wrapper/blob/main/CHANGELOG.md

v0.4.2

What's changed

Documentation and packaging polish — no API changes.

• Read the Docs is now the canonical documentation URL; all user-facing links use readthedocs.io (no personal username in URLs)
• Acknowledgements added to the RTD landing page (docs/index.md)
• RTD badge added to README
• CLAUDE.md removed from the source distribution

Full changelog: https://github.com/cnewkirk/opennms-api-wrapper/blob/main/CHANGELOG.md

v0.4.1

What's changed

Added

• py.typed marker (PEP 561): type checkers (mypy, pyright, Pylance) now automatically discover the package's TypedDicts and annotations. Typing :: Typed PyPI classifier added.
• Read the Docs support: versioned docs now available at https://opennms-api-wrapper.readthedocs.io
• Security policy: SECURITY.md with private disclosure via GitHub Security Advisories

Changed

• PyPI (pip install opennms-api-wrapper) is now the primary documented install method
• Smoke test environment variables documented on the MkDocs site
• Test count consolidated to a single location (README features list)

Full changelog: https://github.com/cnewkirk/opennms-api-wrapper/blob/main/CHANGELOG.md

v0.4.0

What's new in 0.4.0

Exception hierarchy

HTTP errors now raise typed exceptions — no need to import requests in calling code:

try:
    node = client.get_node(99999)
except opennms.NotFoundError:
    print("Node does not exist")
except opennms.ForbiddenError:
    print("Insufficient permissions")
except opennms.OpenNMSError:
    print("Unexpected error")

Full hierarchy: OpenNMSHTTPError (.status_code, .response) → BadRequestError (400), AuthenticationError (401), ForbiddenError (403), NotFoundError (404), ConflictError (409), ServerError (5xx).

Pagination helper

client.paginate() transparently handles limit/offset pagination and yields individual items:

for alarm in client.paginate(client.get_alarms, "alarm", severity="MAJOR"):
    print(alarm["id"], alarm["nodeLabel"])

Stops on totalCount (no extra round-trip) or partial page. Default page_size=100.

Also in this release (since v0.3.1)

• TypedDict payload schemas — 42 TypedDict classes covering all write-method arguments, exported from opennms_api_wrapper.types
• MkDocs Material docs site — https://cnewkirk.github.io/opennms-api-wrapper/api/
• Retry with exponential backoff — 3 retries on 500/502/503/504 by default (retries=0 to disable)
• 490-test suite (up from 290 in v0.3.0)

Installation

pip install https://github.com/cnewkirk/opennms-api-wrapper/archive/refs/tags/v0.4.0.tar.gz

v0.3.1

What's Changed

Added

• Retry with exponential backoff: HTTP client now retries on connection errors and transient server errors (500, 502, 503, 504) with exponential backoff (0.5s factor, up to 3 retries by default). Uses urllib3's built-in Retry — no new dependencies. Pass retries=0 to disable.
• Smoke test: deeper drill-down coverage for nodes, requisition nodes, foreign source detectors/policies, business services, enlinkd, classifications, eventconf, SCV, and config management.
• New unit tests for eventconf file upload and retry configuration (463 total, up from 456).

Changed

• Mixin methods pass empty params={} directly instead of params={} or None.
• _eventconf.py and _classifications.py refactored to use base class helpers (_post_files, _post_text, _get_text).
• ADR-010 updated from "No retry" to "Retry with exponential backoff".

Full Changelog: https://github.com/cnewkirk/opennms-api-wrapper/blob/main/CHANGELOG.md

v0.3.0

Near-complete API coverage — 24 new endpoint groups, ~150 new methods

Added

• Near-complete OpenNMS REST API coverage: 24 new endpoint groups with ~150
  new public methods, closing all Tier 1 (core ops), Tier 2
  (feature-specific), and Tier 3 (config/admin) API gaps.
• New Tier 1 mixins: monitoring locations, minions, ifservices, availability,
  health, whoami.
• New Tier 2 mixins: classifications, situation feedback, user-defined links
  (v2), applications (v2), perspective poller (v2), foreign sources config,
  requisition names, SNMP metadata (v2), provisiond (v2), event configuration
  (v2), monitoring systems, asset suggestions.
• New Tier 3 mixins: secure credentials vault (SCV), configuration management,
  SNMP trap NBI config, email NBI config, syslog NBI config, javamail config.
• Extended existing mixins: prefab graph methods (+4), flow DSCP and graph URL
  (+4), business service edges/functions/daemon reload (+10).
• _patch() HTTP helper in base class for PATCH requests (used by eventconf
  enable/disable).
• _delete() now accepts optional json_data parameter (used by eventconf
  bulk delete).
• 454-test suite (up from 301), all passing.
• Smoke test sections for all new endpoint groups (140 total checks, up from
  ~80).
• Validated against OpenNMS Meridian 2024.3.0 (106 passed, 0 failed, 25
  warned).

Install

pip install https://github.com/cnewkirk/opennms-api-wrapper/archive/refs/tags/v0.3.0.tar.gz

v0.2.0

What's Changed

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).
• Smoke test: OPENNMS_TIMEOUT env var (default 60 seconds).
• Validated against OpenNMS Meridian 2024.3.0 (65 passed, 0 failed).

Install

pip install https://github.com/cnewkirk/opennms-api-wrapper/archive/refs/tags/v0.2.0.tar.gz

Full changelog: v0.1.0...v0.2.0

v0.1.0 — Initial pre-release

Pre-release — not yet validated against a live OpenNMS server.
The 290-test suite mocks HTTP at the adapter level and verifies request
construction and response parsing against Horizon 35 response shapes, but
real-server behaviour may differ. Method signatures may change before
v1.0.0. Feedback and issue reports are very welcome.

What's included

• Single OpenNMS client class covering every v1 (/opennms/rest/) and v2
  (/opennms/api/v2/) endpoint on Horizon 35
• 30 mixin classes, 252 public methods, flat namespace
• JSON-only — no XML handling required
• One runtime dependency: requests >= 2.28
• Synchronous and straightforward — no async complexity
• 290-test suite with full method coverage (mocked HTTP — no live server required)
• smoke_test.py for validating against a live server when you have one available

Resource groups covered

Alarms · Alarm statistics · Alarm history · Events · Nodes (+ IP interfaces,
SNMP interfaces, services, categories, assets, 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) · IP interfaces (v2) · SNMP interfaces (v2)

Installation

pip install https://github.com/cnewkirk/opennms-api-wrapper/archive/refs/tags/v0.1.0.tar.gz

Known limitations

• Not yet validated against a live OpenNMS server — run smoke_test.py against
  your instance before relying on this in any environment
• No HTTP retry / backoff logic — callers must add their own if needed
• Synchronous only — concurrent workloads should use ThreadPoolExecutor