plotwork

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

Install

pip install plotwork

Use

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.

Errors

from plotwork import PlotworkApiError

try:
    plotwork.diagrams.render(source=source)
except PlotworkApiError as error:
    print(error.status, error.error_code, error.request_id)

Options

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