plotwork 0.1.0__py3-none-any.whl

plotwork/_request.py

@@ -0,0 +1,187 @@
+"""The one transport every operation calls.
+
+It sends a request to the Plotwork API with ``urllib.request`` and reads the answer. A 2xx answer is the result; a mistake in a
+diagram is part of that result (``valid: False``, ``errors`` with line, column and hint), never an exception. Anything else is a
+``PlotworkApiError`` with the API's stable ``error_code``. A call the API may answer again safely is retried on 429 and 503,
+after the ``Retry-After`` it gives; publishing is never retried.
+"""
+
+from __future__ import annotations
+
+import json
+import math
+import socket
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Callable, Mapping, Optional
+
+from ._version import __version__
+
+#: The longest the client waits before one retry, whatever ``Retry-After`` says, in seconds.
+MAX_RETRY_WAIT = 30.0
+
+#: Opens a ``urllib.request.Request`` and returns the response, called like ``urllib.request.urlopen(request, timeout=...)``.
+#: It may raise ``urllib.error.HTTPError`` for a status that is not 2xx, as ``urlopen`` does, or return that response.
+Opener = Callable[..., Any]
+
+
+class PlotworkApiError(Exception):
+    """The API's error envelope (``ErrorResponse``), or what the client knew when there was none."""
+
+    #: The HTTP status, or 0 when no answer came (offline, refused, timed out).
+    status: int
+    #: A stable key such as ``auth.invalid_key``, ``rate_limit.exceeded`` or ``request.timeout``.
+    error_code: str
+    message: str
+    details: Any
+    #: The API's trace id, to quote to support.
+    request_id: Optional[str]
+
+    def __init__(self, status: int, error_code: str, message: str, details: Any = None, request_id: Optional[str] = None) -> None:
+        super().__init__(message)
+        self.status = status
+        self.error_code = error_code
+        self.message = message
+        self.details = details
+        self.request_id = request_id
+
+    def __repr__(self) -> str:
+        return f"PlotworkApiError(status={self.status!r}, error_code={self.error_code!r}, message={self.message!r}, request_id={self.request_id!r})"
+
+
+def retry_delay(retry_after: Optional[str], attempt: int) -> float:
+    """How many seconds to wait before retry number ``attempt`` (from 1): the API's ``Retry-After``, else a doubling half second."""
+    seconds = math.nan
+    if retry_after is not None:
+        try:
+            seconds = float(retry_after)
+        except ValueError:
+            seconds = math.nan
+    wait = seconds if math.isfinite(seconds) and seconds >= 0 else 0.5 * 2 ** (attempt - 1)
+    return min(wait, MAX_RETRY_WAIT)
+
+
+def _query_value(value: Any) -> str:
+    if value is True:
+        return "true"
+    if value is False:
+        return "false"
+    return str(value)
+
+
+def _status_of(response: Any) -> int:
+    status = getattr(response, "status", None)
+    return int(status if status is not None else response.getcode())
+
+
+def _header(response: Any, name: str) -> Optional[str]:
+    headers = getattr(response, "headers", None)
+    if headers is None:
+        return None
+    value = headers.get(name)
+    return None if value is None else str(value)
+
+
+def _is_timeout(error: BaseException) -> bool:
+    reason = getattr(error, "reason", None)
+    return isinstance(error, (TimeoutError, socket.timeout)) or isinstance(reason, (TimeoutError, socket.timeout))
+
+
+def _no_answer(error: BaseException) -> PlotworkApiError:
+    if _is_timeout(error):
+        return PlotworkApiError(0, "request.timeout", "The Plotwork API did not answer in time")
+    return PlotworkApiError(0, "request.failed", "The Plotwork API could not be reached")
+
+
+def _error_of(status: int, raw: bytes, request_id: Optional[str]) -> PlotworkApiError:
+    try:
+        body = json.loads(raw.decode("utf-8"))
+    except ValueError:
+        body = None  # Not JSON (a proxy's page): the status says enough.
+    if isinstance(body, dict) and isinstance(body.get("errorCode"), str):
+        message = body.get("message")
+        envelope_id = body.get("requestId")
+        return PlotworkApiError(
+            status,
+            body["errorCode"],
+            message if isinstance(message, str) else f"HTTP {status}",
+            body.get("details"),
+            envelope_id if isinstance(envelope_id, str) else request_id,
+        )
+    return PlotworkApiError(status, f"http.{status}", f"The Plotwork API answered HTTP {status}", None, request_id)
+
+
+def _default_opener() -> Opener:
+    director = urllib.request.build_opener()
+    return director.open
+
+
+class Transport:
+    """How the client sends requests: the address, the headers, the timeout, the retries, and the opener."""
+
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        headers: Mapping[str, str],
+        timeout: float,
+        max_retries: int,
+        opener: Optional[Opener] = None,
+        sleep: Optional[Callable[[float], Any]] = None,
+    ) -> None:
+        self.base_url = base_url
+        self.headers = dict(headers)
+        self.timeout = timeout
+        self.max_retries = max(0, max_retries)
+        self.opener: Opener = opener if opener is not None else _default_opener()
+        self.sleep: Callable[[float], Any] = sleep if sleep is not None else time.sleep
+
+    def url_of(self, path: str, query: Optional[Mapping[str, Any]] = None) -> str:
+        """The address of ``path`` on the base address, with every query value that is not ``None``."""
+        base = self.base_url if self.base_url.endswith("/") else f"{self.base_url}/"
+        url = urllib.parse.urljoin(base, path)
+        pairs = [(name, _query_value(value)) for name, value in (query or {}).items() if value is not None]
+        return f"{url}?{urllib.parse.urlencode(pairs)}" if pairs else url
+
+    def request(self, method: str, path: str, *, idempotent: bool, body: Any = None, query: Optional[Mapping[str, Any]] = None) -> Any:
+        """Sends one request and returns the decoded JSON answer, or raises ``PlotworkApiError``."""
+        retries = self.max_retries if idempotent else 0
+        headers = {"Accept": "application/json", "User-Agent": f"plotwork-python/{__version__}"}
+        data = None
+        if body is not None:
+            headers["Content-Type"] = "application/json"
+            data = json.dumps(body, ensure_ascii=False, separators=(",", ":")).encode("utf-8")
+        headers.update(self.headers)
+        url = self.url_of(path, query)
+        attempt = 0
+        while True:
+            prepared = urllib.request.Request(url, data=data, headers=headers, method=method)
+            try:
+                response = self.opener(prepared, timeout=self.timeout)
+            except urllib.error.HTTPError as answer:
+                response = answer
+            except (urllib.error.URLError, OSError) as error:
+                raise _no_answer(error) from None
+            try:
+                status = _status_of(response)
+                if 200 <= status < 300:
+                    try:
+                        raw = response.read()
+                    except OSError as error:
+                        raise _no_answer(error) from None
+                    return None if status == 204 or raw == b"" else json.loads(raw.decode("utf-8"))
+                if status in (429, 503) and attempt < retries:
+                    attempt += 1
+                    self.sleep(retry_delay(_header(response, "retry-after"), attempt))
+                    continue
+                try:
+                    raw = response.read()
+                except OSError:
+                    raw = b""
+                raise _error_of(status, raw, _header(response, "x-request-id"))
+            finally:
+                close = getattr(response, "close", None)
+                if close is not None:
+                    close()

plotwork/_version.py

@@ -0,0 +1,3 @@
+"""The version of the ``plotwork`` package; ``pyproject.toml`` names the same one, and a test holds them equal."""
+
+__version__ = "0.1.0"

plotwork-0.1.0.dist-info/METADATA

@@ -0,0 +1,141 @@
+Metadata-Version: 2.5
+Name: plotwork
+Version: 0.1.0
+Summary: The Plotwork API from Python: validate, draw, render, import and publish diagrams, on the standard library alone.
+Project-URL: Homepage, https://plotwork.dev
+Project-URL: Documentation, https://docs.plotwork.dev/sdks
+Project-URL: Source, https://github.com/plotwork-official/plotwork-sdk
+Project-URL: Issues, https://github.com/plotwork-official/plotwork-sdk/issues
+Author: Plotwork
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api-client,architecture,diagrams,diagrams-as-code,plotwork,svg
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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 :: Documentation
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <a href="https://plotwork.dev">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://plotwork.dev/brand/logo/plotwork-lockup-on-dark.svg">
+      <img alt="Plotwork" src="https://plotwork.dev/brand/logo/plotwork-lockup-on-light.svg" width="240">
+    </picture>
+  </a>
+</p>
+
+# plotwork
+
+<p>
+  <a href="https://pypi.org/project/plotwork/"><img alt="PyPI" src="https://img.shields.io/pypi/v/plotwork?logo=pypi&logoColor=white&color=0f766e"></a>
+  <img alt="Python" src="https://img.shields.io/pypi/pyversions/plotwork?logo=python&logoColor=white&color=0f766e">
+  <a href="https://pypi.org/project/plotwork/#provenance"><img alt="Provenance" src="https://img.shields.io/badge/provenance-attested-0f766e?logo=sigstore&logoColor=white"></a>
+  <img alt="Runtime dependencies" src="https://img.shields.io/badge/runtime%20dependencies-0-0f766e?logo=dependabot&logoColor=white">
+  <img alt="Typed" src="https://img.shields.io/badge/types-generated%20from%20OpenAPI-3776ab?logo=python&logoColor=white">
+</p>
+
+The hosted Plotwork API from Python. Every `/v1` operation (validate, draw, render, import a file, publish, patterns, icons) is a typed method generated from the API's OpenAPI document, sent with `urllib` from the standard library alone. It runs on Python 3.10 and later.
+
+## TL;DR
+
+| Question | Answer |
+|---|---|
+| What does it install? | Nothing else. |
+| Where do the types come from? | The API's OpenAPI document, kept in the SDK repository as [`spec/openapi.json`](https://github.com/plotwork-official/plotwork-sdk/blob/main/spec/openapi.json). Every request and answer is a `TypedDict`. |
+| How do I sign in? | An API key from the Plotwork portal (`api_key`), or an OAuth access token (`access_token`). |
+| Does a mistake in a diagram raise? | No. It is part of the answer, with a line, a column and a hint. Only a failed request raises, as `PlotworkApiError` with a stable `error_code`. |
+| Does it retry? | A safe call is retried twice on 429 and 503, after the API's `Retry-After`. Publishing is never retried. |
+| Is there a TypeScript client? | Yes, [`@plotwork.official/sdk`](https://www.npmjs.com/package/@plotwork.official/sdk), with the same calls in camelCase. |
+
+## Install
+
+```bash
+pip install plotwork
+```
+
+## Use
+
+```python
+import os
+
+from plotwork import Plotwork
+
+plotwork = Plotwork(api_key=os.environ["PLOTWORK_API_KEY"])
+
+source = 'flow "Checkout"\nnode web service "Web tier"\nnode api service "Orders API"\nweb -> api : "places order"\n'
+
+checked = plotwork.diagrams.validate(source=source)
+if not checked["valid"]:
+    for error in checked["errors"]:
+        print(error["line"], error["column"], error["message"], error.get("hint"))
+
+published = plotwork.diagrams.publish(source=source, embedSource=True)
+# A diagram an organisation's policy keeps private has no public link.
+if "url" in published:
+    print(published["url"])
+```
+
+A method takes the request's fields as keyword arguments, named as the API names them (`embedSource`, `documentPath`), and returns the answer as a plain `dict` typed by a `TypedDict`. A body you already have as a `dict` is passed with `**body`. Keep the key in an environment variable or your CI's secret store, never in a file you commit.
+
+| Group | Calls |
+|---|---|
+| `diagrams` | `validate`, `draw`, `render`, `outline`, `read`, `edit`, `compare`, `suggest`, `convert_mermaid`, `publish` |
+| `import_source` | A diagram from Terraform, OpenAPI, SQL, Kubernetes, Compose and the other formats the API reads |
+| `markdown` | `sync`, `plan` |
+| `patterns` | `find`, `get`, `draw`, `check` |
+| `icons` | `search`, `map` |
+| `vocabulary` | The language's statements and limits, for a kind or a topic |
+
+## Errors
+
+```python
+from plotwork import PlotworkApiError
+
+try:
+    plotwork.diagrams.render(source=source)
+except PlotworkApiError as error:
+    print(error.status, error.error_code, error.request_id)
+```
+
+| `error_code` | Means |
+|---|---|
+| `auth.missing`, `auth.invalid_key` | No key, or one the API does not accept |
+| `rate_limit.exceeded` | Too many calls; already retried for a safe call |
+| `http.<status>` | An answer that was not the API's error envelope, such as a proxy's page |
+| `request.timeout`, `request.failed` | No answer came; `status` is 0 |
+
+## Options
+
+| Option | Default |
+|---|---|
+| `api_key` | none |
+| `access_token` | none |
+| `base_url` | `https://api.plotwork.dev` (`https://api-preview.plotwork.dev` for preview, or a self-hosted engine) |
+| `timeout` | `60` seconds |
+| `max_retries` | `2` |
+| `opener` | `urllib.request.build_opener().open`; pass your own for a proxy or a test |
+| `sleep` | `time.sleep`, the wait before a retry |
+
+`plotwork.with_options(timeout=120)` gives a copy with another timeout or number of retries, for a slow call such as a large import.
+
+## See also
+
+| Page | Why |
+|---|---|
+| [SDKs guide](https://docs.plotwork.dev/sdks) | Every Plotwork SDK, and which to choose |
+| [API reference](https://docs.plotwork.dev) | What each operation does |
+| [TypeScript client](https://www.npmjs.com/package/@plotwork.official/sdk) | The same API from TypeScript |
+| [Viewer](https://www.npmjs.com/package/@plotwork.official/viewer) | Show what you publish, interactively, in a web page |
+| [Source](https://github.com/plotwork-official/plotwork-sdk/tree/main/python) | This package, its tests and its generator |

plotwork-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+plotwork/__init__.py,sha256=eTQnRuuT5YAYs9rdw0cc8zE2RKtpskUoE4jS2mGs38M,3464
+plotwork/_generated.py,sha256=B0ZaWhjwyexxDZhzg0OlSRsKRp5pC4iLHHfGqR8nvd8,114022
+plotwork/_request.py,sha256=itD8pvNNioW-DYrNcSCuWapDEQGE-aU1YsLtP32dJp0,7747
+plotwork/_version.py,sha256=XR92RURavhZFjFy8y6Atyjs7_paojt-E7BKhSavuEbU,138
+plotwork/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+plotwork-0.1.0.dist-info/METADATA,sha256=8kAYBZlyme17saQqfHgF90Hq51rM96UUVtuKWTP1U7k,6661
+plotwork-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+plotwork-0.1.0.dist-info/licenses/LICENSE,sha256=qwged3eiPcCNEOysunrXSLtz_IQpKD4xzLQlqmNEfO0,1065
+plotwork-0.1.0.dist-info/RECORD,,

plotwork-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

plotwork-0.1.0.dist-info/licenses/LICENSE

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