Python SDK for the Typeship API

typeship on PyPI is the Python SDK for the Typeship API. Use it to generate packages, manage Projects, and inspect results from your application.

The package has zero runtime dependencies, TypedDict payloads, typed exceptions, pagination, retries, and an async client.

Install

pip install typeship

Python 3.11 or newer. Nothing else is installed.

Create a client

import os

from typeship import TypeshipClient

client = TypeshipClient(bearer_token=os.environ["TYPESHIP_TOKEN"])

Create a key in the Console under API keys. Pass it directly or set TYPESHIP_TOKEN.

TypeshipClient accepts base_url, timeout, max_retries, default_headers, transport, hooks, debugging, and validation options. See Python.

Generate a package

packages.generate returns one generated package without creating a Project. The free plan generates 25 operations; paid plans generate the whole spec:

from pathlib import Path

result = client.packages.generate(
    spec={"url": "https://api.parcel.example/openapi.json"},
    target={"type": "python_sdk"},
)

for file in result["files"]:
    target = Path("out") / file["path"]
    target.parent.mkdir(parents=True, exist_ok=True)
    target.write_text(file["content"])
print(result["coverage"]["generated"], "operations")

Work with projects

project = client.projects.create(
    name="Parcel API",
    spec={"source": {"type": "url", "url": {"url": "https://api.parcel.example/openapi.json"}}},
    targets=[
        {
            "name": "Parcel Python SDK",
            "type": "python_sdk",
            "deliveries": [{
                "type": "repository",
                "repository": {"provider": "github", "identifier": "parcel/python", "package_name": "parcel"},
            }],
        },
        {"name": "Parcel CLI", "type": "cli"},
        {"name": "Parcel MCP", "type": "mcp", "deliveries": [{"type": "hosted_mcp"}]},
    ],
    auto_generate=True,
)

# Start every selected Target, then wait for its generated files.
for generation in client.projects.generate(project["id"])["data"]:
    completed = client.generations.wait(generation["id"])
    print(completed["target_id"], completed["status"], completed["errors"])

# Walk history: the iterator fetches every page.
for generation in client.generations.list(project_id=project["id"]):
    print(generation["created_at"], generation["trigger"], generation["status"])

Async

AsyncTypeshipClient has the same methods, awaitable:

import asyncio

from typeship import AsyncTypeshipClient


async def main() -> None:
    async with AsyncTypeshipClient(bearer_token=os.environ["TYPESHIP_TOKEN"]) as client:
        me = await client.organization.get()
        async for project in client.projects.list():
            print(project["name"])


asyncio.run(main())

Every method

Resource	Methods
`projects`	`create`, `list`, `get`, `update`, `delete`, `generate`
`specs`	`get`, `update`, `refresh`
`spec_revisions`	`list`, `get`, `list_files`
`targets`	`create`, `list`, `get`, `update`, `delete`, `adopt`
`deliveries`	`create`, `list`, `get`, `update`, `delete`
`generations`	`get`, `list`, `list_files`, `wait`
`drafts`	`list`, `get`, `update`, `list_files`, `resolve`, `recover`
`releases`	`list`, `get`, `retry`
`files`	`get`
`packages`	`generate`, `download`
`organization`	`get`
`api_keys`	`list`, `get`, `revoke`

Paginated methods have a _page twin, such as projects.list_page(), that returns one envelope. Bodies and responses use the API's snake_case names.

api.md is the readable package reference. api.json provides the operations, schemas, examples, authentication, and agent safety metadata as structured data. The API reference has every schema.

Errors

Every call raises. Each status family (400, 401, 403, 404, 409, 422, 429, and 5xx) has one class, raised whether or not the operation documents the status, and all of them are ApiError:

from typeship import NotFoundError, PaymentRequiredError

try:
    client.projects.generate("prj_...")
except PaymentRequiredError as exc:
    # free plan allowance used up; exc.body["errors"][0]["message"] says so
    ...
except NotFoundError:
    # no such project in this Organization
    ...

See Errors for the envelope and codes.

Python