pypaligo 0.1.0

A Python API wrapper for the Paligo REST API v2

pypaligo

A Python wrapper for the Paligo REST API v2.

pypaligo gives you a small, typed, synchronous client over the Paligo API. Every documented v2 endpoint is covered, grouped into resource namespaces (client.documents, client.variables, client.imports, …). Non-2xx responses raise typed exceptions, and rate-limit (429) responses are retried automatically using the server's Retry-After header.

Installation

pip install pypaligo

Requires Python 3.10+.

Authentication

The Paligo API uses HTTP Basic auth with your Paligo username and API key (the user must be an admin). Each Paligo customer has their own subdomain, so you must supply your instance name (or a full base URL).

from pypaligo import PaligoClient

# instance name -> https://mycompany.paligoapp.com/api/v2/
client = PaligoClient("mycompany", username="[e-mail]", api_key="APIKEY")

Credentials also fall back to the PALIGO_USERNAME and PALIGO_API_KEY environment variables:

import os
os.environ["PALIGO_USERNAME"] = "[e-mail]"
os.environ["PALIGO_API_KEY"] = "APIKEY"

client = PaligoClient("mycompany")

The client is a context manager and closes its HTTP session on exit:

with PaligoClient("mycompany") as client:
    doc = client.documents.get(1234)

Usage

Methods return plain dicts and lists parsed straight from the API JSON.

from pypaligo import PaligoClient
from pypaligo.resources.documents import STATUS_RELEASED

with PaligoClient("mycompany") as client:
    # Documents
    doc = client.documents.get(1234)
    client.documents.update(1234, name="New title")
    client.documents.set_release_status(1234, STATUS_RELEASED)
    client.documents.add_taxonomies(1234, [55, 66])   # merges with existing

    # List one page, or iterate every page
    first_page = client.documents.list(parent=10, per_page=50)
    for d in client.documents.iter(parent=10):
        print(d["id"], d["name"])

    # Search
    doc_id = client.search.find_by_uuid("UUID-b4d615c4-...")
    results = client.search.query(
        "documents",
        where=[client.search.where_equals("name", "Release notes")],
    )

    # Variables
    for variable in client.variables.iter(variable_set_id=7):
        print(variable["title"])
    client.variable_values.update(999, value="new text value")

    # Imports (multipart upload)
    imp = client.imports.create("content.zip", parent=10, type="xhtml")

    # Productions & outputs
    prod = client.productions.create("publishsetting.1234-5678")
    client.outputs.download("output-name.zip", "out.zip")

Resource namespaces

Namespace	Endpoints
client.documents	list / iter / get / create / update / delete, plus set_release_status, add_taxonomies
client.folders	list / iter / get / create
client.forks	list / iter / get / create / delete
client.images	list / iter / get / create / update (multipart)
client.search	query, find_by_uuid, where_* clause builders
client.imports	list / get / create (multipart)
client.outputs	get (bytes) / download (to file)
client.productions	list / get / create
client.publish_settings	list / iter / get
client.translation_exports	list / get / create
client.translation_imports	list / get / create (multipart)
client.taxonomies	list / iter / get / create / update / delete
client.variable_sets	list / iter / get / create / update / delete
client.variants	list / iter / get / create / update / delete
client.variables	list / iter / get / create / update / delete
client.variable_values	list / iter / get / create / update
client.groups	list / iter / get
client.assignments	list / iter / get / create / update / delete
client.users	list / iter / get

Error handling

All errors derive from PaligoError. Non-2xx responses raise PaligoAPIError (carrying .status_code, .body, and the underlying .response), with more specific subclasses for common cases:

from pypaligo import (
    PaligoAPIError,
    PaligoAuthError,       # 401 / 403
    PaligoNotFoundError,   # 404
    PaligoRateLimitError,  # 429 after retries are exhausted (has .retry_after)
    PaligoConnectionError, # network-level failure, no HTTP response
)

try:
    client.documents.get(999999)
except PaligoNotFoundError:
    print("no such document")
except PaligoAPIError as exc:
    print(exc.status_code, exc.body)

Rate limiting

The client retries 429 responses automatically (default: 3 retries), honouring the server's Retry-After header and falling back to a 60-second backoff when the header is absent. Configure the retry count per client:

client = PaligoClient("mycompany", max_retries=5)

Once retries are exhausted, a PaligoRateLimitError is raised.

Development

pip install -e ".[dev]"
ruff check .
pytest

License

MIT — see LICENSE.