snmp-query-engine 0.1.0__tar.gz

snmp_query_engine-0.1.0/.changes/header.tpl.md

@@ -0,0 +1,3 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.

snmp_query_engine-0.1.0/.changes/v0.1.0.md

@@ -0,0 +1,5 @@
+## [v0.1.0] - 2026-07-23
+
+### Added
+
+- Initial release: sync and asyncio clients for the snmp-query-engine daemon

snmp_query_engine-0.1.0/.changie.yaml

@@ -0,0 +1,38 @@
+changesDir: .changes
+unreleasedDir: unreleased
+headerPath: header.tpl.md
+changelogPath: CHANGELOG.md
+versionExt: md
+versionFormat: '## [{{.Version}}] - {{.Time.Format "2006-01-02"}}'
+kindFormat: '### {{.Kind}}'
+changeFormat: '- {{.Body}}'
+kinds:
+  - label: Added
+    auto: minor
+  - label: Changed
+    auto: minor
+  - label: Deprecated
+    auto: minor
+  - label: Removed
+    auto: minor
+  - label: Fixed
+    auto: patch
+  - label: Security
+    auto: patch
+newlines:
+  afterChangelogHeader: 1
+  afterChangelogVersion: 1
+  endOfVersion: 1
+  beforeKind: 1
+  afterKind: 1
+envPrefix: CHANGIE_
+replacements:
+  - path: pyproject.toml
+    find: '^version = "[^"]+"'
+    replace: 'version = "{{.VersionNoPrefix}}"'
+  - path: src/sqe/__init__.py
+    find: '^__version__ = "[^"]+"'
+    replace: '__version__ = "{{.VersionNoPrefix}}"'
+  - path: uv.lock
+    find: 'name = "snmp-query-engine"\nversion = "[^"]+"'
+    replace: "name = \"snmp-query-engine\"\nversion = \"{{.VersionNoPrefix}}\""

snmp_query_engine-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,62 @@
+# ABOUTME: CI: lint (ruff, mypy), unit tests across Python 3.10-3.14, and an
+# ABOUTME: integration job against a freshly built snmp-query-engine daemon.
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v8.3.2
+      - name: Install dependencies
+        run: uv sync --locked
+      - name: ruff lint
+        run: uv run ruff check .
+      - name: ruff format
+        run: uv run ruff format --check .
+      - name: mypy
+        run: uv run mypy
+
+  unit:
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v8.3.2
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: uv sync --locked
+      - name: Run unit and transport tests
+        run: uv run pytest -m "not integration"
+
+  integration:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/checkout@v7
+        with:
+          repository: tobez/snmp-query-engine
+          path: snmp-query-engine
+      - name: Install daemon build dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y libjudy-dev libssl-dev \
+            $(apt-cache -q0 show libmsgpack-c-dev >/dev/null 2>&1 && echo libmsgpack-c-dev || echo libmsgpack-dev)
+      - name: Build the daemon
+        run: make -C snmp-query-engine snmp-query-engine
+      - uses: astral-sh/setup-uv@v8.3.2
+      - name: Install dependencies
+        run: uv sync --locked
+      - name: Run integration tests
+        env:
+          SQE_BINARY: ${{ github.workspace }}/snmp-query-engine/snmp-query-engine
+        run: uv run pytest -m integration

snmp_query_engine-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,20 @@
+# ABOUTME: Release workflow: on v* tag push, builds sdist+wheel and publishes
+# ABOUTME: to PyPI via trusted publishing (OIDC).
+name: release
+
+on:
+  push:
+    tags: ['v*']
+
+jobs:
+  pypi:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v8.3.2
+      - name: Build distributions
+        run: uv build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

snmp_query_engine-0.1.0/.gitignore

@@ -0,0 +1,23 @@
+# Hidden files and directories, except those explicitly tracked below.
+# Note: any future dotfile that should be tracked needs its own ! entry here.
+.*
+!.gitignore
+!.github/
+!.changie.yaml
+!.changes/
+!.changes/unreleased/.gitkeep
+!.python-version
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Packaging / build
+build/
+dist/
+*.egg-info/
+
+# Test / coverage
+htmlcov/
+coverage.xml

snmp_query_engine-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13

snmp_query_engine-0.1.0/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [v0.1.0] - 2026-07-23
+
+### Added
+
+- Initial release: sync and asyncio clients for the snmp-query-engine daemon
+

snmp_query_engine-0.1.0/LICENSE

@@ -0,0 +1,24 @@
+Copyright (c) 2026, Anton Berezin <tobez@tobez.org>
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice,
+   this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGE.

snmp_query_engine-0.1.0/PKG-INFO

@@ -0,0 +1,107 @@
+Metadata-Version: 2.4
+Name: snmp-query-engine
+Version: 0.1.0
+Summary: Client library for the snmp-query-engine SNMP query daemon
+Project-URL: Homepage, https://github.com/tobez/sqe-python
+Project-URL: Changelog, https://github.com/tobez/sqe-python/blob/main/CHANGELOG.md
+Author-email: Anton Berezin <tobez@tobez.org>
+License-Expression: BSD-2-Clause
+License-File: LICENSE
+Keywords: monitoring,msgpack,snmp
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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: Programming Language :: Python :: 3.14
+Classifier: Topic :: System :: Networking :: Monitoring
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: msgpack>=1.0
+Description-Content-Type: text/markdown
+
+# snmp-query-engine (Python client)
+
+Python client library for the
+[snmp-query-engine](https://github.com/tobez/snmp-query-engine) daemon — a
+multiplexing SNMP query engine that performs throttled SNMP queries towards
+many destinations on behalf of its clients.
+
+Distribution name `snmp-query-engine`, import name `sqe`.
+
+```sh
+pip install snmp-query-engine        # or: uv add snmp-query-engine
+```
+
+## Synchronous client
+
+```python
+import sqe
+
+with sqe.Client() as c:  # daemon on 127.0.0.1:7667
+    c.setopt("10.0.0.1", 161, {"community": "secret", "version": 2})
+    for vb in c.get("10.0.0.1", 161, ["1.3.6.1.2.1.1.5.0"]):
+        print(vb.oid, vb.value if vb.ok else f"error: {vb.error}")
+    for vb in c.gettable("10.0.0.1", 161, "1.3.6.1.2.1.2.2.1.2"):
+        print(vb.oid, vb.value)
+```
+
+The client is thread-safe; call it from a thread pool for concurrency.
+
+## asyncio client
+
+```python
+import asyncio
+import sqe
+
+async def main():
+    async with sqe.AsyncClient() as c:
+        vbs = await c.get("10.0.0.1", 161, ["1.3.6.1.2.1.1.5.0"])
+        print(vbs[0].value)
+
+asyncio.run(main())
+```
+
+Both clients expose the same six methods: `setopt`, `getopt`, `get`,
+`gettable`, `info`, `dest_info`. See the
+[daemon manual](https://github.com/tobez/snmp-query-engine/blob/main/manual.mdwn)
+for the available options and the semantics behind them.
+
+## Semantics worth knowing
+
+- **Values are msgpack-native.** SNMP string values arrive as `bytes`
+  (they are genuinely binary); OIDs, map keys, and error strings are `str`.
+- **Per-OID errors are values, not exceptions**: check `VarBind.ok` /
+  `VarBind.error`. Request-level daemon errors raise `sqe.RequestError`.
+- **Reconnect is automatic by default**: on connection loss, in-flight
+  requests fail with `sqe.ConnectionLost`, the client reconnects with
+  capped exponential backoff, replays your accumulated `setopt` options,
+  and only then releases new traffic. Opt out with `reconnect=False`.
+- **Per-call safety timeout**: every method takes `timeout=` (seconds) as a
+  guard against a wedged daemon; `None` (default) trusts the daemon's own
+  timeout/retry machinery, which always answers eventually.
+- **SETOPT options pass through verbatim** as a dict, named exactly as in
+  the daemon manual. Convenience: `bytes` values for the hexstring options
+  (`engineid`, `authkul`, `privkul`) are hex-encoded automatically.
+
+## Development
+
+```sh
+uv sync
+uv run pytest                  # unit + transport tiers
+uv run pytest -m integration   # live tier: needs a daemon binary
+                               # ($SQE_BINARY, PATH, or ../snmp-query-engine)
+uv run ruff check . && uv run mypy
+```
+
+The sans-I/O protocol core lives in `sqe/protocol.py`; alternative event
+loops (trio, ...) can drive it directly.
+
+## License
+
+BSD 2-clause, matching the daemon and the Perl client
+[Net::SNMP::QueryEngine::AnyEvent](https://metacpan.org/pod/Net::SNMP::QueryEngine::AnyEvent).

snmp_query_engine-0.1.0/README.md

@@ -0,0 +1,81 @@
+# snmp-query-engine (Python client)
+
+Python client library for the
+[snmp-query-engine](https://github.com/tobez/snmp-query-engine) daemon — a
+multiplexing SNMP query engine that performs throttled SNMP queries towards
+many destinations on behalf of its clients.
+
+Distribution name `snmp-query-engine`, import name `sqe`.
+
+```sh
+pip install snmp-query-engine        # or: uv add snmp-query-engine
+```
+
+## Synchronous client
+
+```python
+import sqe
+
+with sqe.Client() as c:  # daemon on 127.0.0.1:7667
+    c.setopt("10.0.0.1", 161, {"community": "secret", "version": 2})
+    for vb in c.get("10.0.0.1", 161, ["1.3.6.1.2.1.1.5.0"]):
+        print(vb.oid, vb.value if vb.ok else f"error: {vb.error}")
+    for vb in c.gettable("10.0.0.1", 161, "1.3.6.1.2.1.2.2.1.2"):
+        print(vb.oid, vb.value)
+```
+
+The client is thread-safe; call it from a thread pool for concurrency.
+
+## asyncio client
+
+```python
+import asyncio
+import sqe
+
+async def main():
+    async with sqe.AsyncClient() as c:
+        vbs = await c.get("10.0.0.1", 161, ["1.3.6.1.2.1.1.5.0"])
+        print(vbs[0].value)
+
+asyncio.run(main())
+```
+
+Both clients expose the same six methods: `setopt`, `getopt`, `get`,
+`gettable`, `info`, `dest_info`. See the
+[daemon manual](https://github.com/tobez/snmp-query-engine/blob/main/manual.mdwn)
+for the available options and the semantics behind them.
+
+## Semantics worth knowing
+
+- **Values are msgpack-native.** SNMP string values arrive as `bytes`
+  (they are genuinely binary); OIDs, map keys, and error strings are `str`.
+- **Per-OID errors are values, not exceptions**: check `VarBind.ok` /
+  `VarBind.error`. Request-level daemon errors raise `sqe.RequestError`.
+- **Reconnect is automatic by default**: on connection loss, in-flight
+  requests fail with `sqe.ConnectionLost`, the client reconnects with
+  capped exponential backoff, replays your accumulated `setopt` options,
+  and only then releases new traffic. Opt out with `reconnect=False`.
+- **Per-call safety timeout**: every method takes `timeout=` (seconds) as a
+  guard against a wedged daemon; `None` (default) trusts the daemon's own
+  timeout/retry machinery, which always answers eventually.
+- **SETOPT options pass through verbatim** as a dict, named exactly as in
+  the daemon manual. Convenience: `bytes` values for the hexstring options
+  (`engineid`, `authkul`, `privkul`) are hex-encoded automatically.
+
+## Development
+
+```sh
+uv sync
+uv run pytest                  # unit + transport tiers
+uv run pytest -m integration   # live tier: needs a daemon binary
+                               # ($SQE_BINARY, PATH, or ../snmp-query-engine)
+uv run ruff check . && uv run mypy
+```
+
+The sans-I/O protocol core lives in `sqe/protocol.py`; alternative event
+loops (trio, ...) can drive it directly.
+
+## License
+
+BSD 2-clause, matching the daemon and the Perl client
+[Net::SNMP::QueryEngine::AnyEvent](https://metacpan.org/pod/Net::SNMP::QueryEngine::AnyEvent).

snmp_query_engine-0.1.0/dist/.gitignore

@@ -0,0 +1 @@
+*

snmp_query_engine-0.1.0/pyproject.toml

@@ -0,0 +1,70 @@
+[project]
+name = "snmp-query-engine"
+version = "0.1.0"
+description = "Client library for the snmp-query-engine SNMP query daemon"
+readme = "README.md"
+authors = [{ name = "Anton Berezin", email = "tobez@tobez.org" }]
+license = "BSD-2-Clause"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+dependencies = [
+    "msgpack>=1.0",
+]
+keywords = ["snmp", "monitoring", "msgpack"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: System Administrators",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: System :: Networking :: Monitoring",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://github.com/tobez/sqe-python"
+Changelog = "https://github.com/tobez/sqe-python/blob/main/CHANGELOG.md"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/sqe"]
+
+[dependency-groups]
+dev = [
+    "mypy>=2.2.0",
+    "pysmi>=2.0.0",
+    "pytest>=9.1.1",
+    "ruff>=0.15.20",
+    "snmpsim>=1.2.2",
+]
+
+[tool.uv]
+exclude-newer = "7 days"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra"
+markers = ["integration: tests requiring a live snmp-query-engine daemon"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B"]
+
+[tool.mypy]
+strict = true
+files = ["src"]
+
+[[tool.mypy.overrides]]
+module = "msgpack"
+ignore_missing_imports = true

snmp_query_engine-0.1.0/src/sqe/__init__.py

@@ -0,0 +1,21 @@
+# ABOUTME: Public package surface for the snmp-query-engine client library.
+# ABOUTME: Re-exports the clients, VarBind, and the exception hierarchy.
+"""Python client library for the snmp-query-engine daemon."""
+
+from .aio import AsyncClient
+from .client import Client
+from .errors import ConnectionLost, ProtocolError, RequestError, SqeError
+from .protocol import VarBind
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AsyncClient",
+    "Client",
+    "ConnectionLost",
+    "ProtocolError",
+    "RequestError",
+    "SqeError",
+    "VarBind",
+    "__version__",
+]