forward-sdk 0.1.0__py3-none-any.whl

forward_sdk/__init__.py

@@ -0,0 +1,53 @@
+"""Python SDK for the Forward Networks REST API.
+
+A Forward Networks Field Integration: built and maintained by the field team,
+not a supported Forward Networks product. See the README for what that means.
+"""
+
+from __future__ import annotations
+
+from forward_sdk._async.client import AsyncForwardClient
+from forward_sdk._sync.client import ForwardClient
+from forward_sdk._version import __version__
+from forward_sdk.errors import (
+    ForwardAPIError,
+    ForwardAuthError,
+    ForwardBadRequestError,
+    ForwardConfigurationError,
+    ForwardConflictError,
+    ForwardError,
+    ForwardExecutionError,
+    ForwardNotFoundError,
+    ForwardNqeQueryError,
+    ForwardPaginationError,
+    ForwardPermissionError,
+    ForwardRateLimitError,
+    ForwardServerError,
+    ForwardTimeoutError,
+    ForwardTransportError,
+)
+from forward_sdk.nqe import LATEST_PROCESSED, PageGuards, QueryRef
+
+__all__ = [
+    "LATEST_PROCESSED",
+    "AsyncForwardClient",
+    "ForwardAPIError",
+    "ForwardAuthError",
+    "ForwardBadRequestError",
+    "ForwardClient",
+    "ForwardConfigurationError",
+    "ForwardConflictError",
+    "ForwardError",
+    "ForwardExecutionError",
+    "ForwardNotFoundError",
+    "ForwardNqeQueryError",
+    "ForwardPaginationError",
+    "ForwardPermissionError",
+    "ForwardRateLimitError",
+    "ForwardServerError",
+    "ForwardTimeoutError",
+    "ForwardTransportError",
+    "PageGuards",
+    "QueryRef",
+    "__version__",
+]

forward_sdk/_async/__init__.py

@@ -0,0 +1,7 @@
+"""Asynchronous client. The synchronous twin is generated from this package."""
+
+from __future__ import annotations
+
+from forward_sdk._async.client import AsyncForwardClient
+
+__all__ = ["AsyncForwardClient"]

forward_sdk/_async/client.py

@@ -0,0 +1,152 @@
+"""The Forward client."""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+import httpx
+
+from forward_sdk._async.services._generated import AsyncGeneratedServices
+from forward_sdk._async.services.device_tags import AsyncDeviceTagsService
+from forward_sdk._async.services.devices import AsyncDevicesService
+from forward_sdk._async.services.networks import AsyncNetworksService
+from forward_sdk._async.services.nqe import AsyncNqeService
+from forward_sdk._async.services.snapshots import AsyncSnapshotsService
+from forward_sdk._async.throttle import Throttle
+from forward_sdk._async.transport import AsyncTransport
+from forward_sdk.config import ClientConfig, RetryPolicy, build_config, config_from_env
+from forward_sdk.telemetry import Counters, CounterSnapshot, Hooks
+
+__all__ = ["AsyncForwardClient"]
+
+
+class AsyncForwardClient(AsyncGeneratedServices):
+    """Talks to a Forward Networks instance.
+
+    Authentication is HTTP basic. Use an API token: its access key is the
+    username and its secret is the password. A login name and password also
+    work, but are subject to two-factor authentication and account lockout.
+
+    One client holds one connection pool, so reuse it rather than creating one
+    per call. It is bound to the event loop it was created on.
+
+    Services hang off the client by group: ``client.networks``,
+    ``client.snapshots``, ``client.devices``, ``client.device_tags`` and
+    ``client.nqe`` are hand-written for the paths integrations use most; the
+    remaining groups (``client.checks``, ``client.path_search``,
+    ``client.aliases`` and so on) are generated from Forward's API description,
+    and their method names are the operation ids in Python casing.
+
+    Example:
+        >>> async with AsyncForwardClient.from_env() as client:
+        ...     networks = await client.networks.list()
+
+    Args:
+        base_url: The instance URL, with or without a trailing ``/api``.
+        username: API token access key, or a login name.
+        password: API token secret, or a password.
+        verify: TLS verification. Disable only for a deployment using a
+            self-signed certificate, and prefer passing a CA bundle path.
+        timeout: A full ``httpx.Timeout``, or a read deadline in seconds.
+        retries: A :class:`RetryPolicy`, or a retry count.
+        rate_limit_rpm: Client-side pacing. ``"auto"`` paces requests against
+            Forward's hosted service, where a server-side ceiling exists, and
+            leaves self-hosted deployments alone.
+        network_id: Default network for calls that omit one.
+        snapshot_id: Default snapshot. ``None`` means each call uses the
+            network's latest processed snapshot.
+        user_agent: Identifies your application in the ``User-Agent`` header.
+        transport: An ``httpx`` transport, mainly for tests.
+        throttle: A custom pacer, for coordinating across processes.
+        hooks: Callbacks around each request.
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        *,
+        username: str | None = None,
+        password: str | None = None,
+        verify: bool | str = True,
+        timeout: httpx.Timeout | float | None = None,
+        retries: RetryPolicy | int | None = None,
+        rate_limit_rpm: int | Literal["auto"] | None = "auto",
+        network_id: str | None = None,
+        snapshot_id: str | None = None,
+        user_agent: str | None = None,
+        cache_ttl: float = 60.0,
+        proxy: str | None = None,
+        trust_env: bool = True,
+        transport: httpx.AsyncBaseTransport | None = None,
+        throttle: Throttle | None = None,
+        hooks: Hooks | None = None,
+    ) -> None:
+        self.config: ClientConfig = build_config(
+            base_url,
+            username=username,
+            password=password,
+            verify=verify,
+            timeout=timeout,
+            retries=retries,
+            rate_limit_rpm=rate_limit_rpm,
+            network_id=network_id,
+            snapshot_id=snapshot_id,
+            user_agent=user_agent,
+            cache_ttl=cache_ttl,
+            proxy=proxy,
+            trust_env=trust_env,
+        )
+        self._transport = AsyncTransport(
+            self.config, transport=transport, throttle=throttle, hooks=hooks
+        )
+        self.networks = AsyncNetworksService(self._transport)
+        self.snapshots = AsyncSnapshotsService(self._transport)
+        self.devices = AsyncDevicesService(self._transport)
+        self.device_tags = AsyncDeviceTagsService(self._transport)
+        self.nqe = AsyncNqeService(self._transport)
+
+        # The rest of the API, one attribute per group; see scripts/gen_services.py.
+        self._attach_generated_services(self._transport)
+
+    @classmethod
+    def from_env(cls, **overrides: Any) -> AsyncForwardClient:
+        """Build a client from ``FORWARD_*`` environment variables.
+
+        Reads ``FORWARD_URL``, ``FORWARD_USERNAME``, ``FORWARD_PASSWORD``,
+        ``FORWARD_NETWORK_ID``, ``FORWARD_SNAPSHOT_ID``, ``FORWARD_VERIFY_TLS``,
+        ``FORWARD_TIMEOUT``, ``FORWARD_RETRIES``, ``FORWARD_RATE_LIMIT_RPM`` and
+        ``FORWARD_USER_AGENT``. Keyword arguments win over the environment.
+        """
+        settings = config_from_env(**overrides)
+        base_url = settings.pop("base_url")
+        return cls(base_url, **settings)
+
+    async def version(self) -> Any:
+        """The Forward release this instance is running."""
+        return await self.networks.version()
+
+    @property
+    def counters(self) -> CounterSnapshot:
+        """A reading of this client's request counters."""
+        return self._transport.counters.snapshot()
+
+    @property
+    def counters_raw(self) -> Counters:
+        """The live counters, for readings that are not a flat record.
+
+        :meth:`Counters.status_classes` in particular, which is a mapping and
+        so does not belong in the snapshot's scalars.
+        """
+        return self._transport.counters
+
+    async def aclose(self) -> None:
+        await self._transport.aclose()
+
+    async def __aenter__(self) -> AsyncForwardClient:
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.aclose()
+
+    def __repr__(self) -> str:
+        return f"<AsyncForwardClient {self.config.base_url}>"

forward_sdk/_async/services/_base.py

@@ -0,0 +1,51 @@
+"""Shared plumbing for service objects."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from forward_sdk._ops import RequestSpec
+from forward_sdk.errors import ForwardConfigurationError
+from forward_sdk.nqe.query_ref import LATEST_PROCESSED
+
+if TYPE_CHECKING:  # pragma: no cover
+    from forward_sdk._async.transport import AsyncTransport
+
+
+class AsyncService:
+    """Base for the grouped call surfaces hanging off a client."""
+
+    def __init__(self, transport: AsyncTransport) -> None:
+        self._transport = transport
+
+    @property
+    def _config(self) -> Any:
+        return self._transport.config
+
+    def _network(self, network_id: str | None) -> str:
+        """Resolve a network id, falling back to the client's default."""
+        resolved = network_id or self._config.network_id
+        if not resolved:
+            raise ForwardConfigurationError(
+                "no network id: pass network_id, or set one on the client "
+                "(ForwardClient(..., network_id=...) or FORWARD_NETWORK_ID)"
+            )
+        return str(resolved)
+
+    def _snapshot(self, snapshot_id: str | None) -> str | None:
+        """Resolve a snapshot id.
+
+        ``None`` is meaningful: Forward interprets an omitted snapshot as the
+        network's latest processed one, so it is passed through rather than
+        resolved eagerly.
+        """
+        resolved = snapshot_id if snapshot_id is not None else self._config.snapshot_id
+        if resolved in (None, "", LATEST_PROCESSED):
+            return None
+        return str(resolved)
+
+    async def _send_json(self, spec: RequestSpec) -> Any:
+        response = await self._transport.send(spec)
+        if not response.content:
+            return None
+        return response.json()

forward_sdk/_async/services/_generated/__init__.py

@@ -0,0 +1,158 @@
+"""Service classes generated from the Forward API description.
+
+Generated by scripts/gen_services.py -- do not edit.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from forward_sdk._async.services._generated.aliases import AsyncAliasesService
+from forward_sdk._async.services._generated.checks import AsyncChecksService
+from forward_sdk._async.services._generated.classic_devices import AsyncClassicDevicesService
+from forward_sdk._async.services._generated.collection_schedules import (
+    AsyncCollectionSchedulesService,
+)
+from forward_sdk._async.services._generated.collector_tasks import AsyncCollectorTasksService
+from forward_sdk._async.services._generated.credentials import AsyncCredentialsService
+from forward_sdk._async.services._generated.data_connectors import AsyncDataConnectorsService
+from forward_sdk._async.services._generated.data_files import AsyncDataFilesService
+from forward_sdk._async.services._generated.encryptors import AsyncEncryptorsService
+from forward_sdk._async.services._generated.endpoint_profiles import AsyncEndpointProfilesService
+from forward_sdk._async.services._generated.internet_node import AsyncInternetNodeService
+from forward_sdk._async.services._generated.intranet_nodes import AsyncIntranetNodesService
+from forward_sdk._async.services._generated.jump_servers import AsyncJumpServersService
+from forward_sdk._async.services._generated.l2vpns import AsyncL2vpnsService
+from forward_sdk._async.services._generated.l3vpns import AsyncL3vpnsService
+from forward_sdk._async.services._generated.legacy_collection import AsyncLegacyCollectionService
+from forward_sdk._async.services._generated.network_endpoints import AsyncNetworkEndpointsService
+from forward_sdk._async.services._generated.network_locations import AsyncNetworkLocationsService
+from forward_sdk._async.services._generated.network_topology import AsyncNetworkTopologyService
+from forward_sdk._async.services._generated.path_search import AsyncPathSearchService
+from forward_sdk._async.services._generated.system_administration import (
+    AsyncSystemAdministrationService,
+)
+from forward_sdk._async.services._generated.user_accounts import AsyncUserAccountsService
+from forward_sdk._async.services._generated.vulnerability_analysis import (
+    AsyncVulnerabilityAnalysisService,
+)
+from forward_sdk._async.services._generated.wan_circuits import AsyncWANCircuitsService
+
+if TYPE_CHECKING:  # pragma: no cover
+    from forward_sdk._async.transport import AsyncTransport
+
+__all__ = [
+    "AsyncAliasesService",
+    "AsyncChecksService",
+    "AsyncClassicDevicesService",
+    "AsyncCollectionSchedulesService",
+    "AsyncCollectorTasksService",
+    "AsyncCredentialsService",
+    "AsyncDataConnectorsService",
+    "AsyncDataFilesService",
+    "AsyncEncryptorsService",
+    "AsyncEndpointProfilesService",
+    "AsyncGeneratedServices",
+    "AsyncInternetNodeService",
+    "AsyncIntranetNodesService",
+    "AsyncJumpServersService",
+    "AsyncL2vpnsService",
+    "AsyncL3vpnsService",
+    "AsyncLegacyCollectionService",
+    "AsyncNetworkEndpointsService",
+    "AsyncNetworkLocationsService",
+    "AsyncNetworkTopologyService",
+    "AsyncPathSearchService",
+    "AsyncSystemAdministrationService",
+    "AsyncUserAccountsService",
+    "AsyncVulnerabilityAnalysisService",
+    "AsyncWANCircuitsService",
+]
+
+
+class AsyncGeneratedServices:
+    """The API groups whose services are generated.
+
+    Declared as attributes rather than attached dynamically so that type
+    checkers and editors can see them.
+    """
+
+    aliases: AsyncAliasesService
+    checks: AsyncChecksService
+    classic_devices: AsyncClassicDevicesService
+    collection_schedules: AsyncCollectionSchedulesService
+    collector_tasks: AsyncCollectorTasksService
+    credentials: AsyncCredentialsService
+    data_connectors: AsyncDataConnectorsService
+    data_files: AsyncDataFilesService
+    encryptors: AsyncEncryptorsService
+    endpoint_profiles: AsyncEndpointProfilesService
+    internet_node: AsyncInternetNodeService
+    intranet_nodes: AsyncIntranetNodesService
+    jump_servers: AsyncJumpServersService
+    l2vpns: AsyncL2vpnsService
+    l3vpns: AsyncL3vpnsService
+    legacy_collection: AsyncLegacyCollectionService
+    network_endpoints: AsyncNetworkEndpointsService
+    network_locations: AsyncNetworkLocationsService
+    network_topology: AsyncNetworkTopologyService
+    path_search: AsyncPathSearchService
+    system_administration: AsyncSystemAdministrationService
+    user_accounts: AsyncUserAccountsService
+    vulnerability_analysis: AsyncVulnerabilityAnalysisService
+    wan_circuits: AsyncWANCircuitsService
+
+    def _attach_generated_services(self, transport: AsyncTransport) -> None:
+        self.aliases = AsyncAliasesService(transport)
+        self.checks = AsyncChecksService(transport)
+        self.classic_devices = AsyncClassicDevicesService(transport)
+        self.collection_schedules = AsyncCollectionSchedulesService(transport)
+        self.collector_tasks = AsyncCollectorTasksService(transport)
+        self.credentials = AsyncCredentialsService(transport)
+        self.data_connectors = AsyncDataConnectorsService(transport)
+        self.data_files = AsyncDataFilesService(transport)
+        self.encryptors = AsyncEncryptorsService(transport)
+        self.endpoint_profiles = AsyncEndpointProfilesService(transport)
+        self.internet_node = AsyncInternetNodeService(transport)
+        self.intranet_nodes = AsyncIntranetNodesService(transport)
+        self.jump_servers = AsyncJumpServersService(transport)
+        self.l2vpns = AsyncL2vpnsService(transport)
+        self.l3vpns = AsyncL3vpnsService(transport)
+        self.legacy_collection = AsyncLegacyCollectionService(transport)
+        self.network_endpoints = AsyncNetworkEndpointsService(transport)
+        self.network_locations = AsyncNetworkLocationsService(transport)
+        self.network_topology = AsyncNetworkTopologyService(transport)
+        self.path_search = AsyncPathSearchService(transport)
+        self.system_administration = AsyncSystemAdministrationService(transport)
+        self.user_accounts = AsyncUserAccountsService(transport)
+        self.vulnerability_analysis = AsyncVulnerabilityAnalysisService(transport)
+        self.wan_circuits = AsyncWANCircuitsService(transport)
+
+
+#: API group name to the client attribute carrying its service.
+SERVICE_TAGS: dict[str, str] = {
+    "Aliases": "aliases",
+    "Checks": "checks",
+    "Classic Devices": "classic_devices",
+    "Collection Schedules": "collection_schedules",
+    "Collector Tasks": "collector_tasks",
+    "Credentials": "credentials",
+    "Data Connectors": "data_connectors",
+    "Data Files": "data_files",
+    "Encryptors": "encryptors",
+    "Endpoint Profiles": "endpoint_profiles",
+    "Internet Node": "internet_node",
+    "Intranet Nodes": "intranet_nodes",
+    "Jump Servers": "jump_servers",
+    "L2VPNs": "l2vpns",
+    "L3VPNs": "l3vpns",
+    "Legacy Collection": "legacy_collection",
+    "Network Endpoints": "network_endpoints",
+    "Network Locations": "network_locations",
+    "Network Topology": "network_topology",
+    "Path Search": "path_search",
+    "System Administration": "system_administration",
+    "User Accounts": "user_accounts",
+    "Vulnerability Analysis": "vulnerability_analysis",
+    "WAN Circuits": "wan_circuits",
+}

forward_sdk/_async/services/_generated/aliases.py

@@ -0,0 +1,77 @@
+"""Aliases.
+
+Generated by scripts/gen_services.py -- do not edit.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Any
+
+from forward_sdk._async.services._base import AsyncService
+from forward_sdk._generated import models
+from forward_sdk._ops import rest as ops
+
+__all__ = ["AsyncAliasesService"]
+
+
+class AsyncAliasesService(AsyncService):
+    """Aliases."""
+
+    async def create_alias(
+        self,
+        *,
+        snapshot_id: str,
+        name: str,
+        body: Any,
+    ) -> models.Alias:
+        """Create an Alias."""
+        payload = await self._send_json(
+            ops.BUILDERS["createAlias"](snapshot_id=snapshot_id, name=name, body=body)
+        )
+        return models.Alias.model_validate(payload or {})
+
+    async def deactivate_alias(
+        self,
+        *,
+        snapshot_id: str,
+        name: str,
+    ) -> models.Alias:
+        """Delete an Alias."""
+        payload = await self._send_json(
+            ops.BUILDERS["deactivateAlias"](snapshot_id=snapshot_id, name=name)
+        )
+        return models.Alias.model_validate(payload or {})
+
+    async def deactivate_aliases(
+        self,
+        *,
+        snapshot_id: str,
+        name: Sequence[str] | None = None,
+    ) -> models.Aliases:
+        """Delete Aliases."""
+        payload = await self._send_json(
+            ops.BUILDERS["deactivateAliases"](snapshot_id=snapshot_id, name=name)
+        )
+        return models.Aliases.model_validate(payload or {})
+
+    async def get_all_aliases(
+        self,
+        *,
+        snapshot_id: str,
+    ) -> models.Aliases:
+        """Get all Aliases."""
+        payload = await self._send_json(ops.BUILDERS["getAllAliases"](snapshot_id=snapshot_id))
+        return models.Aliases.model_validate(payload or {})
+
+    async def get_single_alias(
+        self,
+        *,
+        snapshot_id: str,
+        name: str,
+    ) -> models.AliasAndValue:
+        """Get an Alias."""
+        payload = await self._send_json(
+            ops.BUILDERS["getSingleAlias"](snapshot_id=snapshot_id, name=name)
+        )
+        return models.AliasAndValue.model_validate(payload or {})

forward_sdk/_async/services/_generated/checks.py

@@ -0,0 +1,88 @@
+"""Checks.
+
+Generated by scripts/gen_services.py -- do not edit.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Any
+
+from forward_sdk._async.services._base import AsyncService
+from forward_sdk._generated import models
+from forward_sdk._ops import rest as ops
+
+__all__ = ["AsyncChecksService"]
+
+
+class AsyncChecksService(AsyncService):
+    """Checks."""
+
+    async def add_check(
+        self,
+        *,
+        snapshot_id: str,
+        body: Any,
+        persistent: bool | None = None,
+    ) -> models.NetworkCheckResult:
+        """Add a check."""
+        payload = await self._send_json(
+            ops.BUILDERS["addCheck"](snapshot_id=snapshot_id, body=body, persistent=persistent)
+        )
+        return models.NetworkCheckResult.model_validate(payload or {})
+
+    async def deactivate_check(
+        self,
+        *,
+        snapshot_id: str,
+        check_id: str,
+    ) -> Any:
+        """Deactivate a check."""
+        payload = await self._send_json(
+            ops.BUILDERS["deactivateCheck"](snapshot_id=snapshot_id, check_id=check_id)
+        )
+        return payload
+
+    async def deactivate_checks(
+        self,
+        *,
+        snapshot_id: str,
+    ) -> Any:
+        """Deactivate all checks."""
+        payload = await self._send_json(ops.BUILDERS["deactivateChecks"](snapshot_id=snapshot_id))
+        return payload
+
+    async def get_available_predefined_checks(
+        self,
+    ) -> list[models.AvailablePredefinedCheck]:
+        """Get available Predefined checks."""
+        payload = await self._send_json(ops.BUILDERS["getAvailablePredefinedChecks"]())
+        return [models.AvailablePredefinedCheck.model_validate(row) for row in payload or []]
+
+    async def get_check(
+        self,
+        *,
+        snapshot_id: str,
+        check_id: str,
+    ) -> models.NetworkCheckResultWithDiagnosis:
+        """Get a check (with status)."""
+        payload = await self._send_json(
+            ops.BUILDERS["getCheck"](snapshot_id=snapshot_id, check_id=check_id)
+        )
+        return models.NetworkCheckResultWithDiagnosis.model_validate(payload or {})
+
+    async def get_checks(
+        self,
+        *,
+        snapshot_id: str,
+        type: Sequence[str] | None = None,
+        priority: Sequence[str] | None = None,
+        status: Sequence[str] | None = None,
+    ) -> list[models.NetworkCheckResult]:
+        """Get checks (with status)."""
+        payload = await self._send_json(
+            ops.BUILDERS["getChecks"](
+                snapshot_id=snapshot_id, type=type, priority=priority, status=status
+            )
+        )
+        return [models.NetworkCheckResult.model_validate(row) for row in payload or []]