Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.
Rust agentai-agentapplecomputer-usecomputer-use-agentcontainerizationcuadesktop-automationhacktoberfestlumemacosmanusoperatorswiftvirtualizationvirtualization-frameworkwindowswindows-sandbox
#!/usr/bin/env npx tsx
/**
* Python reference generator (griffe, static analysis: nothing is imported).
*
* Two hand-written Python layers are documented here; the UniFFI binding
* (`cua._native`) is documented from UniFFI metadata instead.
*
* - `cua` (libs/cua/python/src/cua, `_native` excluded) and the package
* facts -> cua-sdk/reference/python/index.mdx
* - `cua_sandbox` (libs/python/cua-sandbox) public API ->
* cua-sdk/reference/python/*.mdx (+ an explicit meta.json)
*
* Curated prose comes from headers/cua-sdk/python/<page>.md; tested examples
* from examples/cua-sdk/python/<Owner>.<member>.py, placed under the entry
* they show.
*
* Usage:
* pnpm --dir docs docs:generate:python # write the pages
* pnpm --dir docs docs:check:python # drift check (CI)
* tsx scripts/docs-generators/python-sdk.ts [--check] [--only cua|cua-sandbox]
*
* griffe is pinned in requirements.txt and run through `uv run --no-project`.
* Set PYTHON_DOCS_EXTRACTOR="python3" to use an interpreter that already has
* the pinned griffe instead.
*/
import { execFileSync } from 'child_process';
import * as fs from 'fs';
import * as path from 'path';
import {
DOCS_CONTENT,
EXAMPLES_DIR,
REPO_ROOT,
codeCell,
codeFence,
escapeMdxText,
escapeTableCell,
finish,
isCheckMode,
loadExamples,
metaJson,
readHeader,
renderExamples,
renderPage,
slug,
syncFiles,
type Example,
} from './lib/mdx';
// ============================================================================
// Extractor output
// ============================================================================
export interface PyParam {
name: string;
type: string;
/** `required`, the literal default, or '' when the signature lacks the parameter. */
default?: string;
description: string;
}
export interface PyDoc {
kind: 'class' | 'function' | 'attribute' | 'module' | 'external';
name: string;
path?: string;
defined_in?: string;
labels?: string[];
signature?: string;
type?: string;
value?: string;
bases?: string[];
members?: PyDoc[];
description?: string;
params?: PyParam[];
returns?: string;
raises?: Array<{ type: string; description: string }>;
target?: string;
}
export interface PyModuleDoc extends PyDoc {
all: string[];
lazy: Array<{ name: string; module: string; attribute: string; extra: string }>;
aliases: Array<{ name: string; target: string }>;
imports: Record<string, string>;
}
interface Extracted {
objects: PyDoc[];
modules: PyModuleDoc[];
}
// ============================================================================
// Page specifications
// ============================================================================
interface Section {
title: string;
intro?: string;
objects: string[];
/** Hide constructors (objects users get from a sandbox, not build). */
hideInit?: boolean;
/**
* The module users reach these objects through (`pools` for
* `pools.list_pools`): their headings and anchors carry it, so a name
* another section of the page also documents stays distinct.
*/
prefix?: string;
}
interface PageSpec {
file: string;
title: string;
description: string;
intro: string;
sections: Section[];
}
const SB = 'cua_sandbox';
const SANDBOX_API_DIR = path.join(DOCS_CONTENT, 'cua-sdk', 'reference', 'python');
const CUA_PYTHON_PAGE = path.join(SANDBOX_API_DIR, 'index.mdx');
const SANDBOX_ROUTE = '/cua-sdk/reference/python';
const GENERATOR = 'pnpm --dir docs docs:generate:python';
const PY_EXAMPLES = path.join(EXAMPLES_DIR, 'cua-sdk', 'python');
export const SANDBOX_PAGES: PageSpec[] = [
{
file: 'sandbox',
title: 'Sandbox, images and services',
description:
'Sandbox, the sandbox() helper and its creation options, the Image builder, and the services, tunnels and MCP endpoints of a sandbox.',
intro:
'The `Sandbox` class is the entry point of `cua-sandbox`: create, connect to, or reattach a sandbox, then use its interfaces.',
sections: [
{
title: 'Sandboxes',
objects: [`${SB}.sandbox.Sandbox`, `${SB}.sandbox.sandbox`, `${SB}.sandbox.SandboxInfo`],
},
{
title: 'Creation options',
objects: [
`${SB}.options.Probe`,
`${SB}.options.http`,
`${SB}.options.tcp`,
`${SB}.options.PublicUrl`,
],
},
{ title: 'Sandbox references', objects: [`${SB}._refs.AmbiguousSandbox`] },
],
},
{
file: 'image',
title: 'Images and registries',
description: 'The Image builder, sidecar containers and registry credentials of cua-sandbox.',
intro:
'`Image` is an immutable, chainable description of what a sandbox boots. Builder methods return a new `Image`.',
sections: [
{ title: 'Image builder', objects: [`${SB}.image.Image`, `${SB}.image.ImageInfo`] },
{
title: 'Containers and registries',
objects: [
`${SB}.containers.Container`,
`${SB}.containers.RegistrySecret`,
],
},
],
},
{
file: 'pool',
title: 'Pools on this machine',
description: 'Pools of ready sandboxes the cua daemon keeps on this machine.',
intro:
'`create_pool` keeps sandboxes of one shape ready on this machine (the cua daemon holds them); `Sandbox.create(pool=...)` takes one in about 0.1 s.',
sections: [
{
title: 'Pools',
objects: [
`${SB}.sandbox_pool.create_pool`,
`${SB}.sandbox_pool.SandboxPool`,
`${SB}.sandbox_pool.get_pool`,
`${SB}.sandbox_pool.list_pools`,
`${SB}.sandbox_pool.delete_pool`,
],
},
],
},
{
file: 'interfaces',
title: 'Interfaces',
description:
'Shell, mouse, keyboard, screen, clipboard, window, terminal, files, apps, mobile and driver interfaces.',
intro:
'Every sandbox exposes these interfaces as attributes (`sb.shell`, `sb.mouse`, ...). Input goes through cua-driver inside the guest.',
sections: [
{
title: 'Shell commands',
hideInit: true,
objects: [`${SB}.interfaces.shell.Shell`, `${SB}.interfaces.shell.CommandResult`],
},
{
title: 'Input and display',
hideInit: true,
objects: [
`${SB}.interfaces.mouse.Mouse`,
`${SB}.interfaces.keyboard.Keyboard`,
`${SB}.interfaces.screen.Screen`,
`${SB}.interfaces.clipboard.Clipboard`,
`${SB}.interfaces.window.Window`,
],
},
{
title: 'Terminal, files and apps',
hideInit: true,
objects: [
`${SB}.interfaces.terminal.Terminal`,
`${SB}.interfaces.files.Files`,
`${SB}.interfaces.files.FileEntry`,
`${SB}.interfaces.apps.Apps`,
],
},
{ title: 'Mobile gestures', hideInit: true, objects: [`${SB}.interfaces.mobile.Mobile`] },
{
title: 'Cua Driver',
hideInit: true,
objects: [
`${SB}.interfaces.driver.Driver`,
`${SB}.interfaces.driver.DriverConnectionError`,
],
},
],
},
{
file: 'services',
title: 'Services, tunnels and MCP',
description:
'Named services, signed and public URLs, tunnels and MCP endpoints of a cua-sandbox sandbox.',
intro: 'Reach ports inside a sandbox: named services, tunnels, shareable URLs and MCP servers.',
sections: [
{
title: 'Named services',
hideInit: true,
objects: [
`${SB}.interfaces.services.ServiceHandle`,
`${SB}.interfaces.services.Services`,
],
},
{
title: 'Tunnels',
hideInit: true,
objects: [`${SB}.interfaces.tunnel.Tunnel`, `${SB}.interfaces.tunnel.TunnelInfo`],
},
{
title: 'MCP',
objects: [
`${SB}.interfaces.mcp.mcp_config`,
`${SB}.interfaces.mcp.connect`,
`${SB}.interfaces.mcp.open_mcp`,
],
},
],
},
{
file: 'runtimes',
title: 'Runtimes and configuration',
description:
'Local runtimes (Docker, QEMU, Lume, Hyper-V, Tart, Android emulator), support checks, configuration, sign-in and errors.',
intro:
'Local sandboxes run on a runtime the SDK picks for the image. Pass one explicitly to `Sandbox.create(..., runtime=...)` to override it.',
sections: [
{
title: 'Support checks',
objects: [
`${SB}.runtime.compat.RuntimeSupport`,
`${SB}.runtime.compat.check_local_support`,
`${SB}.runtime.compat.skip_if_unsupported`,
],
},
{
title: 'Runtimes',
objects: [
`${SB}.runtime.base.Runtime`,
`${SB}.runtime.base.RuntimeInfo`,
`${SB}.runtime.docker.DockerRuntime`,
`${SB}.runtime.qemu.QEMURuntime`,
`${SB}.runtime.qemu.QEMUDockerRuntime`,
`${SB}.runtime.qemu.QEMUBaremetalRuntime`,
`${SB}.runtime.qemu.QEMUWSL2Runtime`,
`${SB}.runtime.lume.LumeRuntime`,
`${SB}.runtime.hyperv.HyperVRuntime`,
`${SB}.runtime.tart.TartRuntime`,
`${SB}.runtime.android_emulator.AndroidEmulatorRuntime`,
],
},
],
},
{
file: 'configuration',
title: 'Configuration and errors',
description: 'configure, login, whoami, transports and the errors cua-sandbox raises.',
intro:
'Process-wide settings, sign-in helpers, transports and the typed errors of `cua-sandbox`.',
sections: [
{
title: 'Configuration and sign-in',
objects: [
`${SB}._config.configure`,
`${SB}._auth.login`,
`${SB}._auth.whoami`,
],
},
{
title: 'Errors',
objects: [
`${SB}._sdk.SpacesdNotAvailable`,
`${SB}._sdk.InvalidArgument`,
`${SB}._sdk.InvalidPlacement`,
`${SB}._sdk.Unsupported`,
],
},
{
title: 'Transports',
hideInit: true,
objects: [`${SB}.transport.env.EnvTransport`],
},
],
},
];
const CUA_OBJECTS = ['cua.embedded', 'cua.connect', 'cua.images.Image'];
const CUA_MODULES = ['cua', 'cua.runtime', 'cua.tools', 'cua.callbacks'];
// ============================================================================
// Extraction
// ============================================================================
function extractorCommand(): [string, string[]] {
const script = path.join('scripts', 'docs-generators', 'extract_python_docs.py');
const explicit = process.env.PYTHON_DOCS_EXTRACTOR;
if (explicit) return [explicit, [script]];
return [
'uv',
[
'run',
'--quiet',
'--no-project',
'--python',
'3.12',
'--with-requirements',
path.join('scripts', 'docs-generators', 'requirements.txt'),
'python',
script,
],
];
}
export function extract(request: object): Extracted {
const [cmd, args] = extractorCommand();
const out = execFileSync(cmd, args, {
cwd: REPO_ROOT,
input: JSON.stringify(request),
encoding: 'utf-8',
maxBuffer: 64 * 1024 * 1024,
});
return JSON.parse(out) as Extracted;
}
// ============================================================================
// Rendering
// ============================================================================
/**
* Docstring code MDX would not render: a four-space-indented block after a
* blank line (outside lists), or a run of doctest `>>>` lines, becomes a
* fenced `python` block.
*/
export function fenceIndentedCode(markdown: string): string {
const lines = markdown.split('\n');
const out: string[] = [];
let fence: string | null = null;
let lastText = '';
for (let i = 0; i < lines.length; i += 1) {
const line = lines[i];
const m = line.match(/^\s*(`{3,}|~{3,})/);
if (m) {
if (fence === null) fence = m[1];
else if (m[1].startsWith(fence)) fence = null;
out.push(line);
continue;
}
if (fence !== null) {
out.push(line);
continue;
}
const prevBlank = i === 0 || lines[i - 1].trim() === '';
const inList = /^\s*([-*+]|\d+[.)])\s/.test(lastText);
const indented = /^ {4,}\S/.test(line) && prevBlank && !inList;
const doctest = /^\s*>>> /.test(line);
if (indented || doctest) {
const block: string[] = [];
const indent = indented ? 4 : line.match(/^\s*/)![0].length;
while (i < lines.length) {
const l = lines[i];
const keep = indented
? l.trim() === '' || l.startsWith(' '.repeat(4))
: l.trim() !== '' && l.match(/^\s*/)![0].length >= indent;
if (!keep) break;
block.push(l.slice(Math.min(indent, l.match(/^\s*/)![0].length)));
i += 1;
}
i -= 1;
while (block.length && block[block.length - 1].trim() === '') block.pop();
out.push('```python', ...block.map((b) => b.replace(/^>>> |^\.\.\. /, '')), '```');
if (lines[i + 1]?.trim()) out.push('');
continue;
}
if (line.trim()) lastText = line;
out.push(line);
}
return out.join('\n');
}
/** Escapes Markdown prose for MDX, leaving fenced code blocks untouched. */
export function mdxProse(markdown: string): string {
markdown = fenceIndentedCode(markdown);
const out: string[] = [];
let fence: string | null = null;
for (const line of markdown.split('\n')) {
const m = line.match(/^\s*(`{3,}|~{3,})/);
if (m) {
if (fence === null) fence = m[1];
else if (m[1].startsWith(fence)) fence = null;
out.push(line);
continue;
}
out.push(fence === null ? escapeMdxText(line) : line);
}
if (fence !== null) out.push(fence);
return out.join('\n');
}
function publicName(doc: PyDoc): string {
return doc.name;
}
/** An object's heading (and anchor) name: `prefix.name`, except the module itself. */
export function headingName(name: string, kind?: string, prefix?: string): string {
return prefix && kind !== 'module' && name !== prefix ? `${prefix}.${name}` : name;
}
function displaySignature(doc: PyDoc, owner?: string): string {
let sig = doc.signature ?? '';
if (doc.name === '__init__' && owner) {
sig = sig.replace(/^def /, '').replace(/ -> None$/, '');
}
return sig;
}
/** The Default cell: `required`, or the literal default as code. */
export function defaultCell(value: string | undefined): string {
if (!value) return '';
return value === 'required' ? 'required' : codeCell(value);
}
export function paramTable(params: PyParam[]): string[] {
if (!params.length) return [];
const lines = ['| Parameter | Type | Default | Description |', '| --- | --- | --- | --- |'];
for (const p of params) {
lines.push(
`| ${codeCell(p.name)} | ${p.type ? codeCell(p.type) : ''} | ${defaultCell(p.default)} | ${escapeTableCell(p.description)} |`
);
}
return [...lines, ''];
}
function docTail(doc: PyDoc): string[] {
const lines: string[] = [];
if (doc.description) lines.push(mdxProse(doc.description), '');
lines.push(...paramTable(doc.params ?? []));
if (doc.returns) lines.push(`**Returns:** ${escapeMdxText(doc.returns)}`, '');
if (doc.raises?.length) {
lines.push('**Raises:**', '');
for (const r of doc.raises) {
lines.push(
`- ${r.type ? codeCell(r.type) : ''}${r.description ? ': ' + escapeMdxText(r.description) : ''}`
);
}
lines.push('');
}
return lines;
}
function attributeTable(attrs: PyDoc[]): string[] {
if (!attrs.length) return [];
const lines = ['| Attribute | Type | Description |', '| --- | --- | --- |'];
for (const a of attrs) {
const desc = (a.description ?? '').split('\n\n')[0];
lines.push(
`| ${codeCell(a.name)} | ${a.type ? codeCell(a.type) : ''} | ${escapeTableCell(desc)} |`
);
}
return [...lines, ''];
}
export interface ExampleSet {
examples: Map<string, Example[]>;
used: Set<string>;
}
/** Tested examples for `target` (an object, `Owner.member` or a function), if any. */
function examplesFor(target: string, set?: ExampleSet): string[] {
const list = set?.examples.get(target);
if (!list) return [];
set!.used.add(target);
return ['**Example**', '', renderExamples(list), ''];
}
export function renderObject(
doc: PyDoc,
opts: { hideInit?: boolean; examples?: ExampleSet; prefix?: string } = {}
): string[] {
const name = publicName(doc);
const lines: string[] = [`### ${headingName(name, doc.kind, opts.prefix)}`, ''];
if (doc.kind === 'external') {
lines.push(`Re-exported from ${codeCell(doc.target ?? '')}.`, '');
return lines;
}
if (doc.kind === 'class') {
const bases = (doc.bases ?? []).filter((b) => b !== 'object');
const init = doc.members?.find((m) => m.name === '__init__');
const head = [`class ${name}${bases.length ? `(${bases.join(', ')})` : ''}`];
if (init && !opts.hideInit) head.push('', displaySignature(init, name));
lines.push(codeFence('python', head.join('\n')), '');
lines.push(...docTail(doc));
if (init && !opts.hideInit && (init.description || init.params?.length))
lines.push(...docTail(init));
const members = (doc.members ?? []).filter((m) => m.name !== '__init__');
lines.push(...attributeTable(members.filter((m) => m.kind === 'attribute')));
lines.push(...examplesFor(name, opts.examples));
for (const m of members.filter((m) => m.kind === 'function')) {
lines.push(`#### ${name}.${m.name}`, '');
const decorators = (m.labels ?? []).filter(
(l) => l === 'staticmethod' || l === 'classmethod'
);
const sig = [...decorators.map((d) => `@${d}`), displaySignature(m)].join('\n');
lines.push(codeFence('python', sig), '');
lines.push(...docTail(m));
lines.push(...examplesFor(`${name}.${m.name}`, opts.examples));
}
return lines;
}
if (doc.kind === 'function') {
lines.push(codeFence('python', displaySignature(doc)), '');
lines.push(...docTail(doc));
lines.push(...examplesFor(name, opts.examples));
return lines;
}
// attribute or module
if (doc.type || doc.value) {
lines.push(
codeFence(
'python',
`${name}${doc.type ? `: ${doc.type}` : ''}${doc.value ? ` = ${doc.value}` : ''}`
),
''
);
}
lines.push(...docTail(doc));
return lines;
}
/** `name` -> `/cua-sdk/reference/python/<page>#<anchor>` for every documented object. */
/**
* Pages rendered as a section of another page (file -> the page it joins),
* so the Python reference stays a few pages within the page budget.
* `Pool` and the managed pools belonged to Cua Cloud, which has ended; every
* call raises, so they have no entry (the module goes in cua-sandbox 0.10.0).
*/
export const PY_MERGED: Record<string, string> = {
image: 'sandbox',
pool: 'sandbox',
services: 'sandbox',
configuration: 'runtimes',
};
/** Modules of the ended Cua Cloud pools, left out of the reference. */
export const ENDED_MODULES = [`${SB}.pool`, `${SB}.pools`, `${SB}.spec`];
/** Whether `cua_sandbox` imports `name` from an ended module. */
export function isEnded(module: PyModuleDoc, name: string): boolean {
const from = (module.imports[name] ?? '').replace(/^\.+/, '').replace(new RegExp(`^${SB}\\.`), '');
return ENDED_MODULES.some((m) => {
const short = m.slice(SB.length + 1);
return name === short || from === short || from.startsWith(`${short}.`);
});
}
/** The file a page is written to. */
export function pageFileOf(file: string): string {
return PY_MERGED[file] ?? file;
}
export function sandboxAnchors(pages: PageSpec[] = SANDBOX_PAGES): Map<string, string> {
const anchors = new Map<string, string>();
for (const page of pages) {
for (const section of page.sections) {
for (const obj of section.objects) {
const name = headingName(obj.split('.').at(-1)!, undefined, section.prefix);
anchors.set(name, `${SANDBOX_ROUTE}/${pageFileOf(page.file)}#${slug(name)}`);
}
}
}
return anchors;
}
function sandboxSectionBody(page: PageSpec, docs: Map<string, PyDoc>, version: string, examples?: ExampleSet): string[] {
const body: string[] = [escapeMdxText(page.intro), ''];
const header = readHeader(`cua-sdk/python/${page.file}.md`, { version });
if (header) body.push(header, '');
for (const section of page.sections) {
body.push(`## ${section.title}`, '');
if (section.intro) body.push(escapeMdxText(section.intro), '');
for (const obj of section.objects) {
const doc = docs.get(obj);
if (!doc) throw new Error(`griffe returned no documentation for ${obj}`);
body.push(...renderObject(doc, { hideInit: section.hideInit, examples, prefix: section.prefix }));
}
}
return body;
}
/** A page and the pages `PY_MERGED` into it, each under a `##` heading of its title. */
export function renderSandboxPage(
page: PageSpec,
docs: Map<string, PyDoc>,
version: string,
examples?: ExampleSet,
merged: PageSpec[] = []
): string {
const body = sandboxSectionBody(page, docs, version, examples);
for (const part of merged) body.push(`## ${part.title}`, '', ...sandboxSectionBody(part, docs, version, examples));
return renderPage({
title: page.title,
description: page.description,
generator: GENERATOR,
source: `griffe over libs/python/cua-sandbox/cua_sandbox (${[page, ...merged].map((p) => `${SB}.${p.file}`).join(', ')})`,
version: `cua-sandbox ${version}`,
components: body.some((l) => l.startsWith('<Tabs')) ? ['Tabs'] : [],
body: body.join('\n'),
});
}
export function renderReexports(module: PyModuleDoc, documented: Set<string>): string {
const rows = module.all
.filter((name) => !documented.has(name) && !isEnded(module, name))
.map((name) => [name, module.imports[name] ?? module.path ?? '']);
if (!rows.length) return '';
const byModule = new Map<string, string[]>();
for (const [name, mod] of rows) byModule.set(mod, [...(byModule.get(mod) ?? []), name]);
const lines = [
'## Re-exported names',
'',
'`cua_sandbox` also re-exports these names from other packages; see their own documentation.',
'',
'| Module | Names |',
'| --- | --- |',
];
for (const [mod, names] of [...byModule].sort(([a], [b]) => a.localeCompare(b))) {
lines.push(`| ${codeCell(mod)} | ${names.sort().map(codeCell).join(', ')} |`);
}
return lines.join('\n');
}
export function renderCuaPython(
docs: Map<string, PyDoc>,
modules: Map<string, PyModuleDoc>,
anchors: Map<string, string>,
version: string,
sandboxVersion: string,
examples?: ExampleSet
): string {
const root = modules.get('cua')!;
const body: string[] = [];
body.push(
'The high-level Python API: `cua_sandbox` (`Sandbox`, `Image`, the computer interfaces) and the helpers the `cua` package adds. It is a thin layer over the [Cua SDK objects](/cua-sdk/reference): the local runtimes and cua-spacesd all go through `cua`, whose generated binding (`cua._native`) those pages document.',
''
);
const header = readHeader('cua-sdk/python/index.md', { version, sandboxVersion });
if (header) body.push(header, '');
body.push('## Pages', '', '| Page | Covers |', '| --- | --- |');
for (const page of SANDBOX_PAGES.filter((p) => !PY_MERGED[p.file])) {
body.push(`| [${escapeTableCell(page.title)}](${SANDBOX_ROUTE}/${page.file}) | ${escapeTableCell(page.description)} |`);
}
body.push('');
body.push('## The cua package', '');
body.push(
'The hand-written layer of `cua`: two module-level constructors, a canonical-image helper and lazy re-exports of the extras.',
''
);
for (const name of ['cua.embedded', 'cua.connect']) body.push(...renderObject(docs.get(name)!, { examples }));
const image = renderObject(docs.get('cua.images.Image')!, { examples });
image.splice(
2,
0,
'Without `cua[sandbox]`, `cua.Image` is this helper. With it installed, `cua.Image` is the richer [cua_sandbox Image](' +
`${SANDBOX_ROUTE}/sandbox#image).`,
''
);
body.push(...image);
body.push('### Names from the extras', '');
body.push(
'`cua` resolves these names lazily from the optional extras. Install the extra to use them.',
''
);
body.push('| Name | Resolves to | Extra |', '| --- | --- | --- |');
const lazy = [
{ name: 'Image', module: 'cua_sandbox', attribute: 'Image', extra: 'sandbox' },
...root.lazy,
].sort((a, b) => a.name.localeCompare(b.name));
for (const row of lazy) {
const target = codeCell(`${row.module}.${row.attribute}`);
const link = row.extra === 'sandbox' ? anchors.get(row.attribute) : undefined;
body.push(
`| ${codeCell(`cua.${row.name}`)} | ${link ? `[${target}](${link})` : target} | ${codeCell(`cua[${row.extra}]`)} |`
);
}
body.push('');
for (const name of ['cua.runtime', 'cua.tools', 'cua.callbacks']) {
const mod = modules.get(name)!;
body.push(`### ${name}`, '');
body.push(mdxProse(firstParagraph(mod.description ?? '')), '');
const names = mod.all.map((n) => {
const link = name === 'cua.runtime' ? anchors.get(n) : undefined;
return link ? `[${codeCell(n)}](${link})` : codeCell(n);
});
body.push(`Exports: ${names.join(', ')}.`, '');
}
if (root.aliases.length) {
body.push('### Deprecated aliases', '');
body.push('Kept for one release after a rename. Use the new names.', '');
body.push('| Deprecated | Use |', '| --- | --- |');
for (const a of root.aliases)
body.push(`| ${codeCell(`cua.${a.name}`)} | ${codeCell(`cua.${a.target}`)} |`);
body.push('');
}
return renderPage({
title: 'Python high-level API',
description:
'cua_sandbox and the cua package helpers: packages, configuration, and the page for each class.',
generator: GENERATOR,
source: 'griffe over libs/cua/python/src/cua (cua._native excluded) and libs/python/cua-sandbox',
version: `cua ${version}, cua-sandbox ${sandboxVersion}`,
components: body.some((l) => l.startsWith('<Tabs')) ? ['Tabs'] : [],
body: body.join('\n'),
});
}
function firstParagraph(markdown: string): string {
return markdown.split('\n\n')[0] ?? '';
}
function readVersion(file: string): string {
const text = fs.readFileSync(path.join(REPO_ROOT, file), 'utf-8');
const m = text.match(/^__version__\s*=\s*"([^"]+)"/m);
if (!m) throw new Error(`no __version__ in ${file}`);
return m[1];
}
// ============================================================================
// Main
// ============================================================================
export function buildFiles(
extracted: Extracted,
examples: Map<string, Example[]> = loadExamples(PY_EXAMPLES)
): Map<string, string> {
const docs = new Map(extracted.objects.map((d) => [d.path!, d]));
const modules = new Map(extracted.modules.map((m) => [m.path!, m]));
const files = new Map<string, string>();
const anchors = sandboxAnchors();
const set: ExampleSet = { examples, used: new Set() };
const sandboxVersion = readVersion('libs/python/cua-sandbox/cua_sandbox/__init__.py');
const homes = SANDBOX_PAGES.filter((p) => !PY_MERGED[p.file]);
for (const page of homes) {
const merged = SANDBOX_PAGES.filter((p) => PY_MERGED[p.file] === page.file);
let content = renderSandboxPage(page, docs, sandboxVersion, set, merged);
if (page.file === 'sandbox') {
const reexports = renderReexports(modules.get(SB)!, new Set(anchors.keys()));
if (reexports) content = content.replace(/\n$/, `\n\n${reexports}\n`);
}
files.set(path.join(SANDBOX_API_DIR, `${page.file}.mdx`), content);
}
files.set(
path.join(SANDBOX_API_DIR, 'meta.json'),
metaJson('Python high-level API', homes.map((p) => p.file))
);
files.set(
CUA_PYTHON_PAGE,
renderCuaPython(docs, modules, anchors, readVersion('libs/cua/python/src/cua/__init__.py'), sandboxVersion, set)
);
const unused = [...examples.keys()].filter((k) => !set.used.has(k));
if (unused.length) {
throw new Error(`Python examples with no matching entry: ${unused.join(', ')} (scripts/docs-generators/examples/cua-sdk/python)`);
}
return files;
}
/** Every public `cua_sandbox` name is documented. */
export function assertCoverage(extracted: Extracted): void {
const root = extracted.modules.find((m) => m.path === SB);
if (!root) throw new Error('cua_sandbox module was not extracted');
const documented = new Set(sandboxAnchors().keys());
const ended = (n: string) => isEnded(root, n);
const missing = root.all.filter(
(n) => !documented.has(n) && !ended(n)
);
if (missing.length) {
throw new Error(
`cua_sandbox.__all__ names without a reference entry: ${missing.join(', ')}. Add them to SANDBOX_PAGES in python-sdk.ts.`
);
}
}
function main(): void {
const checkOnly = isCheckMode();
const objects = [
...SANDBOX_PAGES.flatMap((p) => p.sections.flatMap((s) => s.objects)),
...CUA_OBJECTS,
];
const extracted = extract({
search_paths: ['libs/python/cua-sandbox', 'libs/cua/python/src'],
objects,
modules: [SB, ...CUA_MODULES],
});
assertCoverage(extracted);
const drift = syncFiles(buildFiles(extracted), checkOnly, [SANDBOX_API_DIR], GENERATOR);
finish('Python', drift, checkOnly, GENERATOR);
}
if (require.main === module) main();