forward-sdk 0.1.1__tar.gz

forward_sdk-0.1.1/.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+coverage.xml
+htmlcov/
+site/
+.env

forward_sdk-0.1.1/CHANGELOG.md

@@ -0,0 +1,64 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/) and the project uses SemVer.
+
+## [0.1.1] - 2026-09-07
+
+### Added
+
+- **Forward AI** (`client.ai`). Ask a question about a network in plain language
+  and get an answer grounded in one snapshot, with the tools Forward used to
+  reach it. A conversation stays pinned to its snapshot, so follow-up questions
+  are answered against the same model as the first.
+
+  This reverses an earlier decision to leave Forward AI out of scope. It is
+  unpublished and gated twice over: absent from Forward's published API, and
+  requiring the `AI_ALLOWED` organization property, so most organizations are
+  refused with a 403. That refusal arrives as an ordinary
+  `ForwardPermissionError` carrying Forward's own sentence rather than a status
+  invented here.
+
+- `client.nqe.repo.source(path)` returns a query's committed source, fetching
+  with the flag a caller would otherwise have to remember, and failing loudly
+  when Forward returns none. Previously `RepositoryQuery.source` was simply
+  `None` when `with_source=True` had been forgotten, which reads like an empty
+  query rather than a missing argument.
+
+## [0.1.0] - 2026-09-07
+
+First release.
+
+### Added
+
+- Every operation in Forward's API: 208 published, plus 11 endpoints Forward
+  does not publish that real integrations depend on. All of them described, so
+  responses are validated against a declared shape rather than read by hand.
+- Synchronous and asynchronous clients with identical surfaces. The async one is
+  the source; the sync one is generated from it, so their retry rules, poll
+  loops and paging cannot diverge.
+- NQE as the most developed surface: running a query inline or in the
+  background, paging or streaming results, diffing across snapshots, and
+  publishing queries to the library. Paging carries guard rails for the ways it
+  fails in production: a result set that ends before its promised total, a
+  server that stops advancing, a query larger than expected.
+- Per-execution telemetry retained on the client, and request counters split by
+  failure cause with an observed request rate.
+- 364 models generated from the API description, tolerant of fields and enum
+  values a newer Forward adds.
+- Helpers for the work integrations were each doing themselves: loading `.nqe`
+  files, stripping `@primaryKey`, inlining local imports, reading a query's
+  column contract, and building escaped predicates.
+
+### Notes
+
+- Licensing, deployment and role-based denials arrive as the same status codes,
+  so the SDK does not claim to tell them apart. It surfaces Forward's own
+  explanation and a documented hint about what gates each group. See
+  `docs/gating.md`.
+- NQE result rows are `dict[str, Any]`. A query's columns are defined by the
+  query, and column names are frequently not valid Python identifiers.
+- Unpublished endpoints are isolated, described in `spec/unpublished.yaml` and
+  marked in the operation table. They are stable and used in production, but a
+  change to one would not appear in a spec diff, so this SDK's own tests are
+  what guard them. See `docs/unpublished.md`.

forward_sdk-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Forward Networks, Inc.
+
+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.

forward_sdk-0.1.1/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.5
+Name: forward-sdk
+Version: 0.1.1
+Summary: Python SDK for the Forward Networks REST API. A Forward Networks Field Integration.
+Project-URL: Homepage, https://github.com/forwardnetworks/forward-python-sdk
+Project-URL: Documentation, https://forwardnetworks.github.io/forward-python-sdk/
+Project-URL: Repository, https://github.com/forwardnetworks/forward-python-sdk
+Project-URL: Changelog, https://github.com/forwardnetworks/forward-python-sdk/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/forwardnetworks/forward-python-sdk/issues
+Author-email: Forward Networks <support@forwardnetworks.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,forward,forward-networks,network,nqe,sdk
+Classifier: Development Status :: 3 - Alpha
+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
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: pydantic<3,>=2.6
+Requires-Dist: typing-extensions>=4.8; python_version < '3.11'
+Description-Content-Type: text/markdown
+
+# forward-sdk
+
+Python SDK for the [Forward Networks](https://www.forwardnetworks.com/) REST API.
+
+> **A Forward Networks Field Integration.** Built and maintained by the field
+> team to make integration work easier. It is not a supported Forward Networks
+> product: it carries no SLA, and issues are handled on a best-effort basis
+> rather than through Forward Support.
+>
+> Status: pre-release. The public API is not yet stable.
+
+```bash
+pip install forward-sdk
+```
+
+```python
+from forward_sdk import ForwardClient
+
+with ForwardClient.from_env() as client:
+    for network in client.networks.list():
+        print(network.id, network.name)
+
+    rows = client.nqe.query(
+        "foreach device in network.devices select {name: device.name}",
+        network_id="101",
+    )
+```
+
+Authentication is HTTP basic with an API token: its access key is the username
+and its secret is the password.
+
+## What it covers
+
+Every operation in Forward's API. The groups integrations use most -- NQE,
+snapshots, networks, devices and device tags -- are hand-written with curated
+names and behaviour such as waiting for a snapshot to finish processing. The
+rest are generated from the OpenAPI description Forward produces from its own
+server code.
+
+Both a synchronous and an asynchronous client, with identical surfaces.
+
+## Notable
+
+**NQE first.** Running a query, paging or streaming the results, diffing a query
+across snapshots, and publishing queries to the library are all first-class.
+Paging carries guard rails for the ways it can go wrong in production: a result
+set that ends early, a server that stops advancing, a query far larger than
+expected.
+
+**Typed, but tolerant.** Responses are pydantic models. Unknown fields and
+unknown enum values are preserved rather than rejected, so a Forward release
+that adds either does not break an older SDK. NQE rows stay `dict[str, Any]`,
+because a query's columns are defined by the query.
+
+**Honest about refusals.** A missing licence, a feature absent from your
+deployment, and a role-based denial all arrive as the same status codes, so the
+SDK does not pretend to tell them apart. It gives you Forward's own explanation
+and a documented hint about what gates that operation.
+
+## Documentation
+
+<https://forwardnetworks.github.io/forward-python-sdk/>
+
+- [Quickstart](docs/quickstart.md)
+- [Configuration](docs/configuration.md)
+- [NQE guide](docs/nqe/index.md)
+- [Availability and gating](docs/gating.md)
+- [Migrating from the NetBox plugin](docs/migration/netbox.md) or
+  [the Nautobot plugin](docs/migration/nautobot.md)
+
+## Requirements
+
+Python 3.10 or newer.
+
+## Licence
+
+MIT.

forward_sdk-0.1.1/README.md

@@ -0,0 +1,77 @@
+# forward-sdk
+
+Python SDK for the [Forward Networks](https://www.forwardnetworks.com/) REST API.
+
+> **A Forward Networks Field Integration.** Built and maintained by the field
+> team to make integration work easier. It is not a supported Forward Networks
+> product: it carries no SLA, and issues are handled on a best-effort basis
+> rather than through Forward Support.
+>
+> Status: pre-release. The public API is not yet stable.
+
+```bash
+pip install forward-sdk
+```
+
+```python
+from forward_sdk import ForwardClient
+
+with ForwardClient.from_env() as client:
+    for network in client.networks.list():
+        print(network.id, network.name)
+
+    rows = client.nqe.query(
+        "foreach device in network.devices select {name: device.name}",
+        network_id="101",
+    )
+```
+
+Authentication is HTTP basic with an API token: its access key is the username
+and its secret is the password.
+
+## What it covers
+
+Every operation in Forward's API. The groups integrations use most -- NQE,
+snapshots, networks, devices and device tags -- are hand-written with curated
+names and behaviour such as waiting for a snapshot to finish processing. The
+rest are generated from the OpenAPI description Forward produces from its own
+server code.
+
+Both a synchronous and an asynchronous client, with identical surfaces.
+
+## Notable
+
+**NQE first.** Running a query, paging or streaming the results, diffing a query
+across snapshots, and publishing queries to the library are all first-class.
+Paging carries guard rails for the ways it can go wrong in production: a result
+set that ends early, a server that stops advancing, a query far larger than
+expected.
+
+**Typed, but tolerant.** Responses are pydantic models. Unknown fields and
+unknown enum values are preserved rather than rejected, so a Forward release
+that adds either does not break an older SDK. NQE rows stay `dict[str, Any]`,
+because a query's columns are defined by the query.
+
+**Honest about refusals.** A missing licence, a feature absent from your
+deployment, and a role-based denial all arrive as the same status codes, so the
+SDK does not pretend to tell them apart. It gives you Forward's own explanation
+and a documented hint about what gates that operation.
+
+## Documentation
+
+<https://forwardnetworks.github.io/forward-python-sdk/>
+
+- [Quickstart](docs/quickstart.md)
+- [Configuration](docs/configuration.md)
+- [NQE guide](docs/nqe/index.md)
+- [Availability and gating](docs/gating.md)
+- [Migrating from the NetBox plugin](docs/migration/netbox.md) or
+  [the Nautobot plugin](docs/migration/nautobot.md)
+
+## Requirements
+
+Python 3.10 or newer.
+
+## Licence
+
+MIT.

forward_sdk-0.1.1/examples/README.md

@@ -0,0 +1,20 @@
+# Examples
+
+Runnable scripts. Each reads its connection settings from the environment:
+
+```bash
+export FORWARD_URL=https://fwd.app
+export FORWARD_USERNAME=your-token-access-key
+export FORWARD_PASSWORD=your-token-secret
+export FORWARD_NETWORK_ID=101
+```
+
+| Script | Shows |
+| --- | --- |
+| `list_networks.py` | Connecting, and listing networks and snapshots |
+| `run_query.py` | Running an NQE query and reading rows |
+| `stream_large_query.py` | Streaming a large result set without buffering it |
+| `device_inventory.py` | Paging through devices and writing a CSV |
+| `publish_queries.py` | Publishing `.nqe` files to the query library |
+| `ask_forward_ai.py` | Asking Forward AI a question, and handling not having it |
+| `async_client.py` | The same work with the asynchronous client |

forward_sdk-0.1.1/pyproject.toml

@@ -0,0 +1,114 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "forward-sdk"
+dynamic = ["version"]
+description = "Python SDK for the Forward Networks REST API. A Forward Networks Field Integration."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+authors = [{ name = "Forward Networks", email = "support@forwardnetworks.com" }]
+keywords = ["forward", "forward-networks", "network", "nqe", "sdk", "api"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "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",
+  "Typing :: Typed",
+]
+dependencies = [
+  "httpx>=0.27,<1",
+  "pydantic>=2.6,<3",
+  "typing_extensions>=4.8; python_version < '3.11'",
+]
+
+[project.urls]
+Homepage = "https://github.com/forwardnetworks/forward-python-sdk"
+Documentation = "https://forwardnetworks.github.io/forward-python-sdk/"
+Repository = "https://github.com/forwardnetworks/forward-python-sdk"
+Changelog = "https://github.com/forwardnetworks/forward-python-sdk/blob/main/CHANGELOG.md"
+Issues = "https://github.com/forwardnetworks/forward-python-sdk/issues"
+
+[dependency-groups]
+dev = [
+  "pytest>=8.3",
+  "pytest-cov>=5",
+  "anyio>=4",
+  "ruff>=0.9",
+  "mypy>=1.13",
+  "pyyaml>=6",
+  "types-PyYAML",
+  "openapi-core>=0.19",
+  # Upper bound tracks what openapi-core allows; without it a dependency update
+  # proposes a version the two cannot satisfy together.
+  "openapi-spec-validator>=0.7,<0.9",
+  "pre-commit>=4",
+]
+codegen = [
+  "datamodel-code-generator[http]>=0.28",
+  "pyyaml>=6",
+]
+docs = [
+  "mkdocs>=1.6",
+  "mkdocs-material>=9.5",
+  "mkdocstrings[python]>=0.27",
+  "pymdown-extensions>=10",
+]
+
+[tool.hatch.version]
+path = "src/forward_sdk/_version.py"
+
+[tool.hatch.build.targets.sdist]
+include = ["src/forward_sdk", "spec", "scripts", "tests", "README.md", "CHANGELOG.md", "LICENSE"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/forward_sdk"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+src = ["src", "tests", "scripts"]
+extend-exclude = ["src/forward_sdk/_generated", "src/forward_sdk/_sync", "tests/_sync"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "RUF", "PL"]
+ignore = ["PLR0913", "PLR2004", "PLR0912", "PLR0915", "PLR0911", "RUF012"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["PLR", "B011"]
+"scripts/**" = ["PLR"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+warn_unreachable = true
+plugins = ["pydantic.mypy"]
+files = ["src", "tests", "scripts", "examples"]
+exclude = ["src/forward_sdk/_generated/models.py"]
+
+[[tool.mypy.overrides]]
+module = ["forward_sdk._generated.models"]
+ignore_errors = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = [
+  "live: tests that hit a real Forward instance (need FORWARD_URL/USERNAME/PASSWORD/NETWORK_ID)",
+]
+addopts = "-m 'not live' -ra"
+pythonpath = ["."]
+filterwarnings = ["error::DeprecationWarning:forward_sdk"]
+
+[tool.coverage.run]
+source = ["forward_sdk"]
+omit = ["src/forward_sdk/_generated/*"]

forward_sdk-0.1.1/scripts/_tidy.py

@@ -0,0 +1,52 @@
+"""Format generated Python before it is written.
+
+Generators emit correct but unpolished code: imports that a particular module
+turns out not to need, lines past the limit. Formatting the text *before*
+comparing it with what is on disk keeps generation idempotent, which the CI
+freshness check depends on.
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+
+__all__ = ["tidy"]
+
+# Import sorting, unused-import removal, and __all__ sorting. Letting the linter
+# apply its own ordering avoids generators guessing at it and drifting.
+FIX_RULES = "I,F401,RUF022"
+
+
+def tidy(source: str, filename: str) -> str:
+    """Return ``source`` with imports sorted and the file formatted."""
+    if shutil.which("ruff") is None:
+        return source
+
+    fixed = subprocess.run(
+        [
+            "ruff",
+            "check",
+            "--fix-only",
+            "--quiet",
+            "--select",
+            FIX_RULES,
+            "--stdin-filename",
+            filename,
+            "-",
+        ],
+        input=source,
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    body = fixed.stdout if fixed.returncode == 0 and fixed.stdout else source
+
+    formatted = subprocess.run(
+        ["ruff", "format", "--quiet", "--stdin-filename", filename, "-"],
+        input=body,
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    return formatted.stdout if formatted.returncode == 0 and formatted.stdout else body

forward_sdk-0.1.1/scripts/check_generated.py

@@ -0,0 +1,79 @@
+"""Fail if checked-in generated code is stale.
+
+Regenerates everything derived from the vendored spec and reports any file that
+changed. CI runs this so a hand-edit of generated code, or a spec sync whose
+generators were never re-run, cannot land.
+"""
+
+from __future__ import annotations
+
+import argparse
+import subprocess
+import sys
+from pathlib import Path
+
+GENERATED = (
+    Path("spec/forward-openapi-3.1.json"),
+    Path("src/forward_sdk/_generated/models.py"),
+    Path("src/forward_sdk/_generated/operations.py"),
+    Path("src/forward_sdk/models/__init__.py"),
+    Path("src/forward_sdk/_async/services/_generated"),
+    Path("src/forward_sdk/_sync"),
+    Path("tests/_sync"),
+)
+
+# Ordered: services are generated from the operation table, and the sync tree
+# from everything above it.
+STEPS = (
+    ("down-convert", ["scripts/downconvert_spec.py"]),
+    ("models", ["scripts/gen_models.py"]),
+    ("operations", ["scripts/gen_operations.py"]),
+    ("services", ["scripts/gen_services.py"]),
+    ("public models", ["scripts/gen_public_models.py"]),
+    ("unasync", ["scripts/unasync.py"]),
+)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--fast",
+        action="store_true",
+        help="only run the unasync step (used as a pre-commit hook)",
+    )
+    args = parser.parse_args(argv)
+
+    steps = [s for s in STEPS if not args.fast or s[0] == "unasync"]
+    for name, argv_step in steps:
+        script = Path(argv_step[0])
+        if not script.exists():
+            print(f"skipping {name}: {script} does not exist yet")
+            continue
+        result = subprocess.run(
+            [sys.executable, *argv_step], capture_output=True, text=True, check=False
+        )
+        if result.returncode != 0:
+            print(result.stdout)
+            print(result.stderr, file=sys.stderr)
+            raise SystemExit(f"generator {name} failed")
+
+    existing = [str(p) for p in GENERATED if p.exists()]
+    # `git status --porcelain` rather than `git diff`: a newly generated file is
+    # untracked, and a diff would not mention it at all.
+    status = subprocess.run(
+        ["git", "status", "--porcelain", "--", *existing],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if status.stdout.strip():
+        print("Generated code is stale. Re-run the generators and commit the result:\n")
+        print(status.stdout)
+        return 1
+
+    print("generated code is up to date")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())