mesa-sdk 0.22.0

Official Mesa Python SDK

mesa-sdk

Official Mesa Python SDK.

This is the primary Python SDK for Mesa. It wraps the generated mesa-rest client with ergonomic async resource namespaces, automatic org inference, and git operations powered by dulwich.

Python 3.10+ is required.

Install

pip install mesa-sdk

Quick Start

import asyncio
from mesa_sdk import Mesa

async def main():
    async with Mesa(api_key="mk_...") as mesa:
        repos = await mesa.repos.list()
        print(repos)

asyncio.run(main())

Usage

Org Resolution

The SDK resolves your default organization automatically via /whoami on first use. You can bypass this by passing org to the constructor or overriding per-call:

# Default: org inferred from /whoami (lazy, cached)
mesa = Mesa(api_key="mk_...")
repos = await mesa.repos.list()

# Constructor org bypasses /whoami entirely
mesa = Mesa(api_key="mk_...", org="acme")
repos = await mesa.repos.list()

# Per-call override
repos = await mesa.repos.list(org="other-org")

Repositories

# List
repos = await mesa.repos.list()

# Create
repo = await mesa.repos.create(name="my-repo")

# Get
repo = await mesa.repos.get(repo="my-repo")

# Update
repo = await mesa.repos.update(repo="my-repo", name="renamed")

# Delete
await mesa.repos.delete(repo="my-repo")

Bookmarks

bookmarks = await mesa.bookmarks.list(repo="my-repo")
await mesa.bookmarks.create(repo="my-repo", name="feature-x", change_id="abc123")
await mesa.bookmarks.move(repo="my-repo", bookmark="feature-x", change_id="def456")
await mesa.bookmarks.merge(repo="my-repo", source="feature-x", target="main")
await mesa.bookmarks.delete(repo="my-repo", bookmark="feature-x")

Changes

from mesa_sdk import Author, FileUpsert

changes = await mesa.changes.list(repo="my-repo")
change = await mesa.changes.create(
    repo="my-repo",
    base_change_id="abc123",
    message="Add feature",
    author=Author(name="Alice", email="[e-mail]"),
    files=[FileUpsert(path="hello.txt", content="Hello, world!")],
)
change = await mesa.changes.get(repo="my-repo", change_id="def456")

Content & Diffs

content = await mesa.content.get(repo="my-repo", change_id="abc123")
diff = await mesa.diffs.get(
    repo="my-repo",
    base_change_id="abc123",
    head_change_id="def456",
)

API Keys

keys = await mesa.api_keys.list()
key = await mesa.api_keys.create(name="ci-key", scopes=["read", "write"])
await mesa.api_keys.revoke(key_id=key.id)

Webhooks

webhooks = await mesa.webhooks.list()
webhook = await mesa.webhooks.create(url="https://example.com/hook", events=["change.created"])
await mesa.webhooks.delete(webhook_id=webhook.id)

Git Operations

The SDK includes a git client powered by dulwich (pure Python git):

await mesa.git.clone("https://mesa.dev/acme/my-repo.git", "/tmp/my-repo", branch="main")
await mesa.git.add("/tmp/my-repo", ["."])
result = await mesa.git.commit(
    "/tmp/my-repo",
    message="Initial commit",
    author="Alice",
    email="[e-mail]",
)
print(result.sha)

status = await mesa.git.status("/tmp/my-repo")
print(status.current_branch, status.file_status)

branches = await mesa.git.branches("/tmp/my-repo")
await mesa.git.create_branch("/tmp/my-repo", "feature-x")
await mesa.git.checkout_branch("/tmp/my-repo", "feature-x")
await mesa.git.delete_branch("/tmp/my-repo", "feature-x")

await mesa.git.push("/tmp/my-repo", username="token", password="mk_...")
await mesa.git.pull("/tmp/my-repo")

Raw Client Access

For operations not covered by the resource namespaces, you can use the underlying mesa-rest AuthenticatedClient directly:

from mesa_rest.api.repo import list_repos

response = await list_repos.asyncio_detailed("acme", client=mesa.raw)

Configuration

Mesa accepts the following keyword arguments:

Parameter	Type	Default	Description
api_key	str | None	MESA_API_KEY env var	API key for authentication
api_url	str	https://api.mesa.dev/v1	Base URL for the Mesa API
org	str | None	Resolved from /whoami	Default organization slug
user_agent	str | None	None	Custom user agent suffix

Error Handling

The SDK raises typed exceptions for API errors:

from mesa_sdk import Mesa, NotFoundError, AuthenticationError

async with Mesa() as mesa:
    try:
        repo = await mesa.repos.get(repo="nonexistent")
    except NotFoundError:
        print("Repo not found")
    except AuthenticationError:
        print("Invalid API key")

Exception	HTTP Status	Description
ValidationError	400, 406	Invalid request parameters
AuthenticationError	401	Invalid or missing API key
AuthorizationError	403	Insufficient permissions
NotFoundError	404	Resource not found
ConflictError	409	Resource conflict
RateLimitError	429	Rate limit exceeded
ServerError	5xx	Server-side error

All API exceptions inherit from ApiError, which inherits from MesaError.

Package Relationship

• mesa-sdk is the ergonomic, main SDK.
• mesa-rest is the generated REST client used under the hood.

Use mesa.raw when you need direct access to the generated AuthenticatedClient.