nanoping-api 11.1.0.dev0__tar.gz

nanoping_api-11.1.0.dev0/.github/workflows/publish.yml

@@ -0,0 +1,29 @@
+name: Publish
+on:
+  push:
+    tags:
+      - "v*"
+permissions:
+  contents: read
+jobs:
+  publish:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Check that the tag matches the package version
+        run: test "v$(python -c 'import tomllib; print(tomllib.load(open("pyproject.toml", "rb"))["project"]["version"])')" = "$GITHUB_REF_NAME"
+      - name: Build
+        run: |
+          python -m pip install build
+          python -m build
+      - name: Publish
+        uses: pypa/gh-action-pypi-publish@release/v1

nanoping_api-11.1.0.dev0/.gitignore

@@ -0,0 +1,3 @@
+__pycache__
+dist
+.venv

nanoping_api-11.1.0.dev0/PKG-INFO

@@ -0,0 +1,63 @@
+Metadata-Version: 2.5
+Name: nanoping-api
+Version: 11.1.0.dev0
+Summary: Typed client for the NanoPing REST API
+Project-URL: Homepage, https://nanoping.com
+Project-URL: Documentation, https://docs.nanoping.com/api/reference
+Project-URL: Source, https://github.com/nanoping-labs/nanoping-api-python
+License-Expression: LicenseRef-Proprietary
+Classifier: Framework :: AsyncIO
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: websockets>=14
+Description-Content-Type: text/markdown
+
+# NanoPing API for Python
+
+A typed client for the REST API of a [NanoPing](https://nanoping.com) node. It
+covers every method of the API, with helpers for flows that take more than one
+call, such as joining a hub. It has a blocking and an asyncio client, and needs
+Python 3.11 or later.
+
+This repository is generated from the NanoPing sources on every release, and
+its version matches the NanoPing release it was made from. Changes made here
+are overwritten by the next release.
+
+## Install
+
+```bash
+pip install nanoping-api
+```
+
+## Use
+
+```python
+from nanoping_api import NanopingClient
+
+client = NanopingClient("http://127.0.0.1:10565")
+
+local = client.hub_client.get_local_node_id()
+for update in client.hub_client.stream_connection_state():
+    print(update.state)
+```
+
+`AsyncNanopingClient` has the same methods for asyncio, and its streams are
+read with `async for`. Requests and responses are dataclasses, and the fields of
+a request are passed as keyword arguments. A failed call raises an `ApiError`,
+whose `code` says why, such as `Code.NOT_FOUND`.
+
+## Examples
+
+`examples` holds the program the
+[HTTP REST guide](https://docs.nanoping.com/api/http-rest) is made from. It
+joins a node to a hub and manages pipelines on both. Start the two nodes as the
+comment in `examples/main.py` describes, then run
+
+```bash
+pip install nanoping-api
+python examples/main.py --client http://127.0.0.1:10565 --server http://127.0.0.1:10566
+```
+
+The API is documented at https://docs.nanoping.com/api/reference.

nanoping_api-11.1.0.dev0/README.md

@@ -0,0 +1,47 @@
+# NanoPing API for Python
+
+A typed client for the REST API of a [NanoPing](https://nanoping.com) node. It
+covers every method of the API, with helpers for flows that take more than one
+call, such as joining a hub. It has a blocking and an asyncio client, and needs
+Python 3.11 or later.
+
+This repository is generated from the NanoPing sources on every release, and
+its version matches the NanoPing release it was made from. Changes made here
+are overwritten by the next release.
+
+## Install
+
+```bash
+pip install nanoping-api
+```
+
+## Use
+
+```python
+from nanoping_api import NanopingClient
+
+client = NanopingClient("http://127.0.0.1:10565")
+
+local = client.hub_client.get_local_node_id()
+for update in client.hub_client.stream_connection_state():
+    print(update.state)
+```
+
+`AsyncNanopingClient` has the same methods for asyncio, and its streams are
+read with `async for`. Requests and responses are dataclasses, and the fields of
+a request are passed as keyword arguments. A failed call raises an `ApiError`,
+whose `code` says why, such as `Code.NOT_FOUND`.
+
+## Examples
+
+`examples` holds the program the
+[HTTP REST guide](https://docs.nanoping.com/api/http-rest) is made from. It
+joins a node to a hub and manages pipelines on both. Start the two nodes as the
+comment in `examples/main.py` describes, then run
+
+```bash
+pip install nanoping-api
+python examples/main.py --client http://127.0.0.1:10565 --server http://127.0.0.1:10566
+```
+
+The API is documented at https://docs.nanoping.com/api/reference.

nanoping_api-11.1.0.dev0/examples/guide.py

@@ -0,0 +1,194 @@
+"""The code of the HTTP REST guide in the NanoPing docs. Each step of the guide is
+one function, and run runs them in order."""
+
+import asyncio
+from collections.abc import Callable
+from dataclasses import dataclass
+
+from nanoping_api import (
+    ApiError,
+    AsyncNanopingClient,
+    AsyncServerStream,
+    Code,
+    HubNode,
+    Level,
+    NodeMetadata,
+    NodeMetadataItem,
+    NodeService,
+    RestartPolicy,
+    RestartPolicyOnFailure,
+    StreamPipelinesEvent,
+)
+from pipeline_config import PIPELINE_CONFIG
+
+Output = Callable[[str], None]
+
+
+@dataclass
+class Addresses:
+    """Addresses of the two nodes the guide uses: a client node that joins the hub,
+    and the node hosting the hub server."""
+
+    client: str
+    """REST API of the client node, e.g. "http://127.0.0.1:10565"."""
+    server: str
+    """REST API of the hub server node, e.g. "http://127.0.0.1:10566"."""
+    server_http: str
+    """HTTP address of the hub server node, e.g. "http://127.0.0.1:8769"."""
+
+
+async def set_node_information(client: AsyncNanopingClient, out: Output) -> None:
+    """Names the client node and gives it metadata that other nodes on the hub can
+    filter on."""
+    local = await client.hub_client.get_local_node_id()
+
+    response = await client.hub_client.set_node(
+        node_id=local.node_id,
+        name="My NanoPing Client",
+        metadata=NodeMetadata(
+            items={
+                "type": NodeMetadataItem(string_value="my-type"),
+                "location": NodeMetadataItem(string_value="Denmark, Aalborg"),
+            }
+        ),
+    )
+
+    out(f'Named node {response.node.id} "{response.node.name}"')
+
+
+async def watch_connection_state(client: AsyncNanopingClient, out: Output) -> None:
+    """Prints the connection state of the client node every time it changes, until
+    the task is cancelled."""
+    async for update in client.hub_client.stream_connection_state():
+        out(f"Connection state: {update.state}")
+
+
+async def accept_join_requests(server: AsyncNanopingClient) -> None:
+    """Accepts every node that asks to join the hub server, until the task is
+    cancelled."""
+    await server.answer_join_requests(lambda request: True)
+
+
+async def join_the_hub(client: AsyncNanopingClient, server_http_address: str, out: Output) -> None:
+    """Joins the client node to the hub server. The call waits until the hub server
+    accepted or rejected the request. A node that already is part of the hub stays
+    so."""
+    try:
+        await client.join_hub(server_http_address)
+        out("Joined the hub")
+    except ApiError as error:
+        if error.code == Code.ALREADY_EXISTS:
+            out("Already part of the hub")
+            return
+        if error.code == Code.UNAUTHENTICATED:
+            raise RuntimeError("The hub server rejected the node") from error
+        raise
+
+
+async def print_nodes(client: AsyncNanopingClient, out: Output) -> None:
+    """Prints the nodes on the hub: all of them, the ones with metadata "type" set
+    to "my-type", and the ones running pipelines."""
+    everything = await client.hub_server.get_nodes()
+    out("All nodes:")
+    for node in everything.nodes:
+        out(f"  {node.name}")
+
+    my_type = await client.hub_server.get_nodes(
+        metadata_filters={"type": NodeMetadataItem(string_value="my-type")},
+    )
+    out("Nodes with type my-type:")
+    for node in my_type.nodes:
+        out(f"  {node.name}")
+
+    out("Nodes running pipelines:")
+    for node in await pipeline_nodes(client):
+        out(f"  {node.name}")
+
+
+async def pipeline_nodes(client: AsyncNanopingClient) -> list[HubNode]:
+    """Returns the nodes on the hub that run pipelines."""
+    response = await client.hub_server.get_nodes(service_filters=[NodeService.PIPELINES])
+    return response.nodes
+
+
+async def watch_pipelines(
+    client: AsyncNanopingClient, node: HubNode
+) -> AsyncServerStream[StreamPipelinesEvent]:
+    """Opens a stream of the changes to the pipelines on the node. It returns once
+    the stream is ready, so no change made after it returns is missed."""
+    return await client.pipelines.stream_pipelines(node_id=node.id)
+
+
+async def print_pipeline_events(
+    events: AsyncServerStream[StreamPipelinesEvent], node: HubNode, out: Output
+) -> None:
+    """Prints an event every time a pipeline on the node is created, updated or
+    deleted, until the task is cancelled."""
+    async for event in events:
+        if event.create:
+            out(f'  Event on {node.name}: created "{event.create.pipeline.name}"')
+        elif event.update:
+            out(f'  Event on {node.name}: updated "{event.update.pipeline.name}"')
+        elif event.delete:
+            out(f'  Event on {node.name}: deleted "{event.delete.pipeline.name}"')
+
+
+async def manage_pipeline(client: AsyncNanopingClient, node_id: str, out: Output) -> None:
+    """Creates a pipeline on the node, renames it, reads it back and deletes it
+    again."""
+    created = await client.pipelines.create_pipeline(
+        node_id=node_id,
+        name="My First Pipeline",
+        json_config=PIPELINE_CONFIG,
+        restart_policy=RestartPolicy(on_failure=RestartPolicyOnFailure(max_restarts=3)),
+        default_logging_level=Level.DEBUG,
+    )
+    pipeline = created.pipeline
+    out(f'  Created "{pipeline.name}"')
+
+    # An update replaces every setting, so send the current ones along with the
+    # new name.
+    updated = await client.pipelines.update_pipeline(
+        node_id=node_id,
+        id=pipeline.id,
+        name="My Renamed Pipeline",
+        json_config=pipeline.json_config,
+        restart_policy=pipeline.restart_policy,
+        startup_policy=pipeline.startup_policy,
+        default_logging_level=pipeline.default_logging_level,
+        instructions_timeout=pipeline.instructions_timeout,
+    )
+    out(f'  Renamed to "{updated.pipeline.name}"')
+
+    fetched = await client.pipelines.get_pipeline_by_id(node_id=node_id, id=pipeline.id)
+    out(f'  Read back "{fetched.pipeline.name}"')
+
+    await client.pipelines.delete_pipeline(node_id=node_id, id=pipeline.id)
+    out(f'  Deleted "{fetched.pipeline.name}"')
+
+
+async def run(addresses: Addresses, out: Output) -> None:
+    """Connects to both nodes and runs every step of the guide."""
+    async with (
+        AsyncNanopingClient(addresses.client) as client,
+        AsyncNanopingClient(addresses.server) as server,
+    ):
+        background: list[asyncio.Task[None]] = []
+        try:
+            background.append(asyncio.create_task(watch_connection_state(client, out)))
+            await set_node_information(client, out)
+
+            background.append(asyncio.create_task(accept_join_requests(server)))
+            await join_the_hub(client, addresses.server_http, out)
+
+            await print_nodes(client, out)
+
+            for node in await pipeline_nodes(client):
+                out(f"Managing a pipeline on {node.name}")
+                events = await watch_pipelines(client, node)
+                background.append(asyncio.create_task(print_pipeline_events(events, node, out)))
+                await manage_pipeline(client, node.id, out)
+        finally:
+            for task in background:
+                task.cancel()
+            await asyncio.gather(*background, return_exceptions=True)

nanoping_api-11.1.0.dev0/examples/main.py

@@ -0,0 +1,37 @@
+# Runs the HTTP REST guide of the NanoPing docs against two nodes.
+#
+# Start the client node with
+#
+#   np up --rest-api 127.0.0.1:10565
+#
+# and the hub server node with `np -c config.yaml up`, where config.yaml is
+#
+#   node:
+#     name: My Server
+#   http:
+#     address: 127.0.0.1:8769
+#   hubServer:
+#     authenticationByRequest:
+#       timeout: 5m
+#   restApi:
+#     address: 127.0.0.1:10566
+#   pipelines: {}
+#
+# Then run `python main.py`.
+import argparse
+import asyncio
+import sys
+
+from guide import Addresses, run
+
+parser = argparse.ArgumentParser()
+parser.add_argument("--client", default="http://127.0.0.1:10565")
+parser.add_argument("--server", default="http://127.0.0.1:10566")
+parser.add_argument("--server-http", default="http://127.0.0.1:8769")
+arguments = parser.parse_args()
+
+try:
+    asyncio.run(run(Addresses(arguments.client, arguments.server, arguments.server_http), print))
+except Exception as error:
+    print(error, file=sys.stderr)
+    sys.exit(1)

nanoping_api-11.1.0.dev0/examples/pipeline_config.py

@@ -0,0 +1,23 @@
+"""A pipeline that sends traffic from a traffic source to a traffic sink on the
+same node."""
+
+PIPELINE_CONFIG = """{
+  "version": 13,
+  "plumr_config": {
+    "pipeline": {
+      "traffic_sink-1": {
+        "traffic_sink": {
+          "input": "[traffic_sink-1|in:0]-[uniform_traffic_source-1|out:0]",
+          "mtu": 1500
+        }
+      },
+      "uniform_traffic_source-1": {
+        "uniform_traffic_source": {
+          "output": "[traffic_sink-1|in:0]-[uniform_traffic_source-1|out:0]",
+          "total_packets": 5000,
+          "interval": 25
+        }
+      }
+    }
+  }
+}"""

nanoping_api-11.1.0.dev0/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "nanoping-api"
+version = "11.1.0.dev0"
+description = "Typed client for the NanoPing REST API"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "LicenseRef-Proprietary"
+dependencies = [
+    "httpx>=0.27",
+    "websockets>=14",
+]
+classifiers = [
+    "Framework :: AsyncIO",
+    "Programming Language :: Python :: 3",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://nanoping.com"
+Documentation = "https://docs.nanoping.com/api/reference"
+Source = "https://github.com/nanoping-labs/nanoping-api-python"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/nanoping_api"]
+
+[tool.mypy]
+strict = true

nanoping_api-11.1.0.dev0/src/nanoping_api/__init__.py

@@ -0,0 +1,18 @@
+"""A typed client for the REST API of a NanoPing node."""
+
+from ._client import AsyncNanopingClient, NanopingClient
+from ._generated import *
+from ._generated import __all__ as _generated_all
+from ._runtime import ApiError, AsyncBidiStream, AsyncServerStream, BidiStream, Code, ServerStream
+
+__all__ = [
+    "ApiError",
+    "AsyncBidiStream",
+    "AsyncNanopingClient",
+    "AsyncServerStream",
+    "BidiStream",
+    "Code",
+    "NanopingClient",
+    "ServerStream",
+    *_generated_all,
+]

nanoping_api-11.1.0.dev0/src/nanoping_api/_client.py

@@ -0,0 +1,154 @@
+from __future__ import annotations
+
+import inspect
+from collections.abc import AsyncIterator, Awaitable, Callable, Iterator, Mapping
+from typing import Self
+
+import httpx
+
+from ._generated import (
+    AuthenticationByRequestAnswer,
+    AuthenticationByRequestRequest,
+    Message,
+    Options,
+    _AsyncServices,
+    _Services,
+)
+from ._runtime import AsyncTransport, Transport
+
+_EVERY_LINE = Options(lines=2**63 - 1)
+
+
+class NanopingClient(_Services):
+    """A blocking client for the REST API of a node.
+
+    `base_url` is the address of the REST API, such as "http://127.0.0.1:10565",
+    and `headers` are sent with every request. `timeout` limits each call, in
+    seconds, but not the wait for the next message of a stream. By default a call
+    waits as long as it takes. Pass `http_client` to send the calls with an
+    httpx.Client of your own.
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        *,
+        headers: Mapping[str, str] | None = None,
+        timeout: float | None = None,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        self._transport = Transport(base_url, headers, timeout, http_client)
+        super().__init__(self._transport)
+
+    def close(self) -> None:
+        """Closes the connections of the client, unless they belong to `http_client`."""
+        self._transport.close()
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()
+
+    def join_hub(self, hub_server_address: str) -> None:
+        """Joins the hub server at `hub_server_address` with the node hosting the API.
+
+        Returns once the hub server approved the node. Raises an ApiError with
+        Code.UNAUTHENTICATED when the request was rejected, Code.DEADLINE_EXCEEDED
+        when nobody answered in time and Code.ALREADY_EXISTS when the node already
+        is part of a hub.
+        """
+        self.hub_client.authenticate_by_request(hub_server_address=hub_server_address)
+
+    def answer_join_requests(self, decide: Callable[[AuthenticationByRequestRequest], bool]) -> None:
+        """Answers the nodes that ask to join the hub server hosted by the node hosting
+        the API.
+
+        `decide` is called for every request and returns whether the node may join.
+        Runs until the stream ends or fails.
+        """
+        with self.hub_server.authentication_by_requests() as stream:
+            for request in stream:
+                stream.send(AuthenticationByRequestAnswer(request_id=request.request_id, accept=decide(request)))
+
+    def run_pipeline(self, node_id: str, pipeline_id: str) -> Iterator[Message]:
+        """Starts a pipeline and follows the log of the new run from its first line.
+
+        The pipeline starts when the loop does. Yields each log message until the
+        log stream ends or the loop stops, which closes the stream.
+        """
+        run = self.pipelines.start_pipeline(node_id=node_id, id=pipeline_id)
+        with self.pipelines.open_log_stream(node_id=node_id, run_id=run.run_id, options=_EVERY_LINE) as stream:
+            for batch in stream:
+                yield from batch.messages
+
+
+class AsyncNanopingClient(_AsyncServices):
+    """An asyncio client for the REST API of a node.
+
+    `base_url` is the address of the REST API, such as "http://127.0.0.1:10565",
+    and `headers` are sent with every request. `timeout` limits each call, in
+    seconds, but not the wait for the next message of a stream. By default a call
+    waits as long as it takes. Pass `http_client` to send the calls with an
+    httpx.AsyncClient of your own.
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        *,
+        headers: Mapping[str, str] | None = None,
+        timeout: float | None = None,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self._transport = AsyncTransport(base_url, headers, timeout, http_client)
+        super().__init__(self._transport)
+
+    async def aclose(self) -> None:
+        """Closes the connections of the client, unless they belong to `http_client`."""
+        await self._transport.aclose()
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(self, *_: object) -> None:
+        await self.aclose()
+
+    async def join_hub(self, hub_server_address: str) -> None:
+        """Joins the hub server at `hub_server_address` with the node hosting the API.
+
+        Returns once the hub server approved the node. Raises an ApiError with
+        Code.UNAUTHENTICATED when the request was rejected, Code.DEADLINE_EXCEEDED
+        when nobody answered in time and Code.ALREADY_EXISTS when the node already
+        is part of a hub.
+        """
+        await self.hub_client.authenticate_by_request(hub_server_address=hub_server_address)
+
+    async def answer_join_requests(
+        self, decide: Callable[[AuthenticationByRequestRequest], bool | Awaitable[bool]]
+    ) -> None:
+        """Answers the nodes that ask to join the hub server hosted by the node hosting
+        the API.
+
+        `decide` is called for every request and returns, or resolves to, whether
+        the node may join. Runs until the stream ends or fails, or the task is
+        cancelled.
+        """
+        async with self.hub_server.authentication_by_requests() as stream:
+            async for request in stream:
+                accept = decide(request)
+                if inspect.isawaitable(accept):
+                    accept = await accept
+                await stream.send(AuthenticationByRequestAnswer(request_id=request.request_id, accept=accept))
+
+    async def run_pipeline(self, node_id: str, pipeline_id: str) -> AsyncIterator[Message]:
+        """Starts a pipeline and follows the log of the new run from its first line.
+
+        The pipeline starts when the loop does. Yields each log message until the
+        log stream ends or the loop stops, which closes the stream.
+        """
+        run = await self.pipelines.start_pipeline(node_id=node_id, id=pipeline_id)
+        async with self.pipelines.open_log_stream(node_id=node_id, run_id=run.run_id, options=_EVERY_LINE) as stream:
+            async for batch in stream:
+                for message in batch.messages:
+                    yield message