Overview - Mesa Docs

The Mesa Python SDK is the ergonomic async client for Mesa. It wraps the generated mesa-rest client, resolves the default organization for you, and exposes a native virtual filesystem for repo I/O and shell execution. Python 3.10 or newer is required.

Installation

pip install mesa-sdk

Create a client

import asyncio
import os
from mesa_sdk import Mesa

mesa = Mesa(private_key=os.environ["MESA_PRIVATE_KEY"])

async def main():
    repos = await mesa.repos.list()
    print(f"found {len(repos.repos)} repos")

asyncio.run(main())

Set MESA_PRIVATE_KEY in a trusted environment to omit private_key from the constructor.

Client options

from mesa_sdk import Mesa

mesa = Mesa(
    private_key="mesa_private_key_acme_...",
    api_url="https://api.mesa.dev/v1",
    user_agent="my-app/1.0.0",
)

str | None

Ed25519 private key. The SDK reads MESA_PRIVATE_KEY when no explicit private key is supplied.

str

REST API base URL. Defaults to https://api.mesa.dev/v1. http and https are accepted. Trailing slashes are stripped.

str | None

Appended to the SDK user agent. The default user agent starts with mesa-sdk-python.

Client lifecycle

Create one Mesa client for your process or application and reuse it across request handlers. If your framework has a lifespan hook and you want explicit cleanup, wrap the client in async with Mesa(...) at application lifespan, not inside each handler.

from mesa_sdk import Mesa

mesa = Mesa()

async def handler():
    repos = await mesa.repos.list()
    return repos

Organization resolution

The client reads its organization from the private key. Resource methods always use that organization and do not accept an org value.

print(mesa.org.slug)
await mesa.repos.list()

Use await mesa.org.get() when you need organization metadata from the API.

Resource APIs

API	Purpose
`mesa.repos`	Create, read, update, delete, sync upstreams, and read upstream sync history on repositories.
`mesa.content`	Read files, symlinks, and directory listings without mounting.
`mesa.changes`	Create, patch, and inspect Mesa changes.
`mesa.diffs`	Inspect diffs and conflicts between changes.
`mesa.bookmarks`	Manage branch-like bookmark refs.
`mesa.webhook_targets`	Manage outbound webhook targets.
`mesa.fs`	Define a layout and mount it as a virtual filesystem, or mint its scoped token. Call `mesa.fs(layout=..., authors=..., ttl=...)` then `.mount()` / `.token()`.
`mesa.org`	Read the private key’s organization slug with `mesa.org.slug`, or fetch organization metadata with `await mesa.org.get()`.

Response objects

The high-level SDK returns model instances generated by mesa-rest. Use attribute access, not dictionary access.

repos = await mesa.repos.list()
for repo in repos.repos:
    print(repo.name, repo.head_change_id)

Common types

Import common dataclasses and native result types from mesa_sdk.

import base64
from mesa_sdk import Author, Committer, FileDelete, FileUpsert, Layout

files = [
    FileUpsert(path="README.md", content=base64.b64encode(b"hello").decode()),
    FileDelete(path="old.txt"),
]
authors: list[Author] = [{"name": "Build Bot"}]
committer = Committer(name="Build Bot", email="build@example.com")

Type	Purpose
`Author`	Commit attribution for commit-producing operations.
`Committer`	Committer identity for change creation and updates.
`FileUpsert`	Create or replace one file in a change. `content` must be base64-encoded.
`FileDelete`	Delete one file in a change.
`WholeFileResolution`	Resolve a conflicted path by replacing full content or taking one side.
`HunkResolution` / `HunkFix`	Resolve individual conflict hunks.
`FilesystemDefinition`	Layout, authors, and token lifetime bundled with the `layout()`, `mount()`, and `token()` operations they configure, returned by `mesa.fs(layout=..., authors=...)`.
`AccessToken`	Short-lived access token returned by `definition.token()`, scoped to the layout that minted it, with `token` and timezone-aware `expires_at` fields.
`Layout`	Raw path map validated by `mesa.fs(...)` and returned by `definition.layout()`. Serialize it for the CLI with `json.dumps(...)`.
`repo`	Helper that builds one layout repository declaration (`mode` required).
`DiskCacheConfig`	Configure on-disk MesaFS cache placement and size (passed to `definition.mount(...)`).
`FsStat`	File metadata returned by `stat` and `lstat`.
`ChangeInfo`	Change metadata returned by mounted filesystem change operations.
`ExecResult`	Output from `fs.bash().exec(...)`.

Upstream configuration types live in mesa_sdk.types:

from mesa_sdk.types import TokenAuth, UpstreamConfig, UsernamePasswordAuth

public = UpstreamConfig(url="https://github.com/acme/app.git")
token = UpstreamConfig(
    url="https://github.com/acme/app.git",
    auth=TokenAuth(token="github_pat_...", token_username="bot"),
)
password = UpstreamConfig(
    url="https://git.example.com/acme/app.git",
    auth=UsernamePasswordAuth(username="bot", password="secret"),
)

On mesa.repos.update(...), UpstreamConfig.auth is tri-state: omit to preserve existing credentials, pass None to clear credentials, or pass TokenAuth / UsernamePasswordAuth to set credentials.

Error model

REST API operations raise MesaError subclasses.

Exception	Status	Meaning
`ValidationError`	`400`, `406`	Invalid request parameters or unacceptable response variant.
`AuthenticationError`	`401`	Missing or invalid access token.
`AuthorizationError`	`403`	The access token does not have the required scope or repository access.
`NotFoundError`	`404`	Requested resource does not exist.
`ConflictError`	`409`	Resource conflict, optimistic concurrency failure, or merge conflict.
`RateLimitError`	`429`	Rate limit exceeded.
`ServerError`	`5xx`	Server-side failure.

SDK setup errors include MissingCredentialError, InvalidApiUrlError, OrgResolutionError, and InvalidOptionsError. Classified native filesystem failures raise one of three public exceptions. All inherit from MesaFileSystemError, so except MesaFileSystemError catches every category.

Exception	`error_class`	Meaning
`MesaTransientError`	`"transient"`	Another client or a transient network condition interfered. Rerunning the same call may succeed.
`MesaBadInputError`	`"bad-input"`	The caller must fix their input or environment first, such as checking out a bookmark or re-authenticating.
`MesaFatalError`	`"fatal"`	A Mesa bug or a failure the caller cannot fix. Report it.

Each exception preserves the message, the original exception in __cause__, and its errno when available (None otherwise). Its error_class attribute holds the classification. Copying and pickling preserve the exception’s category, cause, and errno. These exceptions no longer inherit from built-in types such as ValueError, FileNotFoundError, or OSError. Update handlers for native filesystem failures to catch a category above or MesaFileSystemError. Inspect __cause__ when you need the original built-in error. Bash failures and Python-side argument validation continue to use their existing exceptions. The TypeScript SDK exposes the same three exception classes. These categories also drive the mesa CLI’s exit codes.

from mesa_sdk import MesaTransientError

try:
    await fs.changes.checkpoint(repo)
except MesaTransientError:
    # Retry once; a second failure propagates to the caller.
    await fs.changes.checkpoint(repo)

Raw generated client

mesa.raw exposes the authenticated generated mesa-rest client. Use it when the high-level SDK does not expose a generated REST operation or option yet.

from mesa_rest.api.repo import list_repos

response = await list_repos.asyncio_detailed("acme", client=mesa.raw)
if response.status_code == 200:
    print(response.parsed.repos)

Raw generated calls return a Response[T] wrapper with status_code, parsed, and headers. High-level SDK methods unwrap successful responses and raise typed errors for non-2xx responses.

Complete example

import asyncio
import base64
import os
from mesa_sdk import FileUpsert, Mesa, repo

mesa = Mesa(private_key=os.environ["MESA_PRIVATE_KEY"])

async def main():
    created = await mesa.repos.create(name="demo")

    change = await mesa.changes.create(
        repo=created.name,
        base_change_id=created.head_change_id,
        message="Add README",
        authors=[{"name": "Docs Bot", "email": "docs@example.com"}],
        files=[
            FileUpsert(
                path="README.md",
                content=base64.b64encode(b"# Demo\n").decode(),
            )
        ],
    )

    await mesa.bookmarks.move(
        repo=created.name,
        bookmark=created.default_bookmark,
        change_id=change.id,
    )

    async with mesa.fs(
        layout={"/workspace": repo(created.name, mode="rw")},
        authors=[{"name": "Docs Bot", "email": "docs@example.com"}],
    ).mount() as fs:
        data = await fs.read("/workspace/README.md")
        print(data.decode())

asyncio.run(main())

​Installation

​Create a client

​Client options

​Client lifecycle

​Organization resolution

​Resource APIs

​Response objects

​Common types

​Error model

​Raw generated client

​Complete example

Installation

Create a client

Client options

Client lifecycle

Organization resolution

Resource APIs

Response objects

Common types

Error model

Raw generated client

Complete example