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 credential is supplied.

MesaAuth | None

A credential group holding either a private key or an existing access token, never both. A client built from an access token forwards that token unchanged and cannot mint another one.

str

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

str | None

Optional VCS gateway override. Only use when self-hosting Mesa.

str | None

Optional organization check. Private-key and access-token clients derive the organization from the credential and only accept a matching value.

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

Private-key and access-token clients read the organization from the credential. A constructor or per-call org value is optional, but it must match that organization.

await mesa.repos.list()
await mesa.repos.list(org="acme")

Resource namespaces

Namespace	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.api_keys`	Create, list, and revoke Mesa API keys (deprecated).
`mesa.tokens`	Sign short-lived, scoped access tokens locally from a private key.
`mesa.webhook_targets`	Manage outbound webhook targets.
`mesa.fs`	Mount repos as a virtual filesystem and run Bash commands. Call `mesa.fs(layout=...)` to build a layout definition; `mesa.fs.mount(repos=...)` mounts the canonical `/<org>/<repo>` paths.
`mesa.org`	Fetch organization metadata.

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, FileDelete, FileUpsert

files = [
    FileUpsert(path="README.md", content=base64.b64encode(b"hello").decode()),
    FileDelete(path="old.txt"),
]
author = Author(name="Alice", email="alice@example.com")

Type	Purpose
`Author`	Commit author or committer identity.
`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.
`RepoConfig`	Pin a mounted repo to a bookmark or change.
`LayoutDefinition`	Layout bundled with its `layout()`, `mount()`, and `token()` operations, returned by `mesa.fs(layout=...)`.
`Layout`	Prepared layout the definition exposes. `str(...)` serializes it for `mesa mount --layout`.
`DiskCacheConfig`	Configure on-disk MesaFS cache placement and size.
`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 credential.
`AuthorizationError`	`403`	The credential 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. Filesystem and Bash operations raise built-in Python exceptions such as FileNotFoundError, FileExistsError, IsADirectoryError, NotADirectoryError, PermissionError, NotImplementedError, and OSError.

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

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

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

    change = await mesa.changes.create(
        repo=repo.name,
        base_change_id=repo.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=repo.name,
        bookmark=repo.default_bookmark,
        change_id=change.id,
    )

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

asyncio.run(main())

​Installation

​Create a client

​Client options

​Client lifecycle

​Organization resolution

​Resource namespaces

​Response objects

​Common types

​Error model

​Raw generated client

​Complete example

Installation

Create a client

Client options

Client lifecycle

Organization resolution

Resource namespaces

Response objects

Common types

Error model

Raw generated client

Complete example