​

The cmd API, and the RPC contract over it

​

1. What the cmd API surface actually is

​

1.1 packages/engine/modules/pymol/api.py — the public Python API

​

1.2 packages/engine/modules/pymol/keywords.py — the command-language keyword table

​

1.3 Runtime-discoverable tables (important for codegen — see §9)

​

2. How command strings are parsed and executed (parser.py / parsing.py)

​

2.1 Path A — string command line (cmd.do → C → parser.parse)

1. cmd.do(commands, log=1, echo=1, flush=0) splits on newlines, sets defer_updates when given >1 command, and calls _cmd.do() under lockcm (packages/engine/modules/pymol/commanding.py:441-475).
2. C queues/executes and calls back into Python: G->P_inst->parse is a closure built by parser.new_parse_closure(cmd) (packages/engine/layer1/P.cpp:2038-2040, packages/engine/modules/pymol/parser.py:595-601), invoked as parse(buffer, 0) (packages/engine/layer1/P.cpp:2352, :2390).
3. Parser._parse() (packages/engine/modules/pymol/parser.py:182-481) does, in order:
   • embed/python-block sentinel handling (:190-215, :220-222)
   • \ line continuation (:226-235)
   • ; splitting via parsing.split (:239)
   • /-prefix ⇒ literal Python (:248-252)
   • assignment-operator sniffing (=, +=, … from py_delims, packages/engine/modules/pymol/parser.py:43-46) ⇒ Python (:253-254)
   • keyword lookup through cmd.kwhash abbreviation resolution, with ambiguity error (:257-268)
   • for mode >= NO_CHECK: parsing.parse_arg then parsing.prepare_call, then self.result = layer.kw[0](*args, **kwargs) (packages/engine/modules/pymol/parser.py:287-292)
   • @file script inclusion with recursion + stop_on_exceptions (:402-445)
   • fallback: unknown token is executed as literal Python (:446-452)
4. Return code semantics: 1 = ok, 0 = exception, None = abort (packages/engine/modules/pymol/parser.py:481). Exceptions are caught and printed, not propagated (:465-478). parser.result holds the last return value (:137, :292, :337).

• unwraps decorators, reads fn.__code__.co_varnames / co_argcount / co_kwonlyargcount / co_posonlyargcount / __defaults__ (:346-360)
• disables checking for *args/**kw functions via co_flags & 0xC (:352-353)
• cmd ? ⇒ prints the usage line via dump_arg and raises QuietException (:365-366, dump_arg at :311-327) — this is the color ? → Usage: color color [, selection ...] feature documented in packages/engine/modules/pymol/cmd.py:251-255
• LEGACY mode rewrites key=value into two positional args (:384-392)
• injects _self= when the target accepts it (:379, :414-415)
• injects quiet=0 when fb_mask.results is enabled and the caller didn’t pass it (:418-420)
• raises QuietException for missing required args (:409-411) and too many positionals (:400-403)

​

2.2 Path B — direct Python call (cmd.color("red", "sele"))

​

2.3 The one typed entry point that already exists: cmd.new_command

• resolves PEP-563 string annotations via get_type_hints (:734-740)
• wraps the function so that when the caller is parser.py (detected by comparing sys._getframe(1).f_code.co_filename against pymol.parser.__file__, :748-750) each argument string is coerced through _into_types (packages/engine/modules/pymol/commanding.py:619-712)
• _into_types supports Any, bool (yes/1/true/on/y vs no/0/false/off/n, :629-646), Union/| (:650-661), tuple[...] via shlex.split (:663-685), list[...] (:687-693), StrEnum (:695-702), Enum by member name (:705-713), and any class accepting a single str (:716-723)
• registers into cmd.keyword, cmd.kwhash, cmd.help_sc with parsing.STRICT (:775-777)

​

3. Tab completion (parser.complete + completing.py)

• no space/@ in the string ⇒ complete a command name against cmd.kwhash with mode 1 and ' ' postfix (:532-536)
• otherwise resolve the command, count commas outside [...] to determine the argument index (remove_lists_re, packages/engine/modules/pymol/parser.py:48, :538-540), then look up cmd.auto_arg[count][command] (:543-557)
• fallback: filesystem glob completion plus $ENVVAR completion (:560-589)

​

4. Feedback / stdout capture (pcatch, feedingback.py, Ortho queue)

​

4.1 pcatch — stdout/stderr hijack

​

4.2 The Ortho feedback queue

​

4.3 Feedback levels

​

4.4 Progress / busy

​

5. Existing bridge #1: packages/engine/modules/pymol/pymolhttpd.py (529 lines)

​

5.1 What it provides

• HTTPServer + BaseHTTPRequestHandler, single-threaded, one request per handle_request() in a daemon thread (packages/engine/modules/pymol/pymolhttpd.py:475-499).
• Hard localhost check: rejects any client whose address doesn’t start with 127.0. with HTTP 403 (packages/engine/modules/pymol/pymolhttpd.py:61-68).
• Three URL verbs, dispatched by splitting self.urlpath on / (packages/engine/modules/pymol/pymolhttpd.py:98-124):
  • /apply/<method> → pymol_apply (:117, impl :209-335)
  • /getattr/<attr> → pymol_getattr, returns repr() of a value that was pre-registered under the key /getattr/<attr> in the session dict (:118-119, impl :126-142)
  • /echo/<...> → debug echo (:120-122, impl :410-437 — note echo_args takes no args but is called with one at :122, i.e. this endpoint is broken)
  • anything else → static file serving from pymol_root (:123-124, impl :337-362)
• Static serving blocks .. (:342-344), auto-appends index.html for dirs (:351-352), and guesses MIME from extension for .html/.js/.jpg/.png/.gif/.sdf/.mol/.pwg (:364-385).

​

5.2 Wire format of /apply

• _quit → shuts the server down and emits an HTML page with window.close() / document.location.replace(href) (:306-327)
• pymol.cmd.delete_ and pymol.cmd.super_ — trailing-underscore aliases because delete and super are JS/Python reserved-ish words
• pymol.cmd.label is remapped to cmd.label2 — the no-eval variant, explicitly for safety

• wrap_natives=1 ⇒ {"status": "OK"|"ERROR", "result": ...}, else the bare result (:144-149)
• content negotiation on Accept against ['text/json','application/json'] (packages/engine/modules/pymol/pymolhttpd.py:33, :163-172); anything else gets an HTML <pre> debug page
• errors: send_json_error(code, message) (:174-187) and send_exception_json which appends the full Python traceback split into lines (:189-207)
• batching: when _json is a list of lists, only the last result is returned — send_multi_result_list is initialised False and then re-set to False, so the multi-result branch at :329-330 is dead code (:216, :269, :331-332)
• no-cache headers + optional custom headers on every response (:387-408)

​

5.3 How it is launched

​

5.4 Why it was not built on

​

6. Existing bridge #2: packages/engine/modules/pymol/rpc.py (474 lines, XML-RPC)

• host from $PYMOL_RPCHOST else localhost (:422-424)
• tries 5 consecutive ports (:428-435)
• SimpleXMLRPCServer(..., logRequests=0, allow_none=True) (:430-431)
• serv.register_instance(cmd) (packages/engine/modules/pymol/rpc.py:441) — this exposes the ENTIRE cmd module over XML-RPC by attribute lookup. Every one of the 404 api symbols is callable.
• plus 17 hand-written legacy rpcXxx wrappers registered under camelCase names (:444-465): ping, resetCGO, renderCGO, sphere, spheres, cylinder, deleteObject, deleteAll, loadPDB, loadMolBlock, loadSurface, loadSurfaceData, loadFile, getNames, countAtoms, idAtom, help, getAtomCoords
• label and rotate are registered last and therefore SHADOW the real cmd.label and cmd.rotate — the source itself flags this: “legacy stuff, should be removed because overwrites API names!” (packages/engine/modules/pymol/rpc.py:463-465). rpcLabel actually creates a pseudoatom (:38-54) and rpcRotate takes an xyz vector (:354-367).
• register_introspection_functions() gives system.listMethods / system.methodSignature / system.methodHelp (packages/engine/modules/pymol/rpc.py:467)
• rpcHelp(what) reflects on __defaults__/__code__.co_varnames to build a usage string (packages/engine/modules/pymol/rpc.py:382-408) — another codegen precedent
• module-global cgoDict accumulates CGO buffers per id (:426-427, used :56-147)
• launched with the -R CLI flag → options.rpcServer = 1 (packages/engine/modules/pymol/invocation.py:184, :453) which defers '_do__ /import pymol.rpc;pymol.rpc.launch_XMLRPC()' (packages/engine/modules/pymol/invocation.py:521-522)

​

6.1 Why it was not built on

​

7. What the C++ layer can emit

​

7.1 Exists

​

7.2 DOES NOT EXIST

1. Object list changed (object created/deleted/renamed/reordered/grouped). Only pollable via cmd.get_names() (packages/engine/modules/pymol/querying.py:1155-1199, 10 modes) / cmd.get_names_of_type (:1459) / cmd.get_object_list (:131).
2. Object enabled/disabled — ReportEnabledChange exists but is _PYMOL_LIB-only and unbound (see above). Pollable via cmd.get_names(..., enabled_only=1) or cmd.get_vis() (packages/engine/modules/pymol/viewing.py:899-901).
3. View changed (camera moved by mouse drag, zoom, orient, scene recall). Only cmd.get_view() polling (packages/engine/modules/pymol/viewing.py:634-733; returns an 18-float tuple, layout documented at :663-677).
4. Frame / state changed (movie playing, frame, mset). Only cmd.get_frame() (packages/engine/modules/pymol/moving.py:984), cmd.get_state() (:958), cmd.get_movie_playing() (:64).
5. Selection changed (named selection created/modified, atom picked in viewport). There is a click string (packages/engine/layer4/Cmd.cpp:1420-1430) but grepping packages/engine/modules/ for get_click_string returns zero Python callers — it is dead from Python’s side.
6. Representation/color changed on an object.
7. Scene list changed — cmd.get_scene_list() poll only (packages/engine/modules/pymol/viewing.py:919).
8. Wizard prompt/panel changed — cmd.get_wizard() / get_wizard_stack() poll only (packages/engine/modules/pymol/wizarding.py:156-174); dirty_wizard (:146) sets a C flag, no Python signal.
9. Undo/redo stack changed — cmd.undo/redo/push_undo exist (packages/engine/modules/pymol/api.py:223, :227, :256) with no depth query and no event.
10. Busy message text — OrthoBusyMessage is C-internal (packages/engine/layer1/Ortho.cpp:530-539).
11. Severity/category on feedback lines — colorprinting.error/warning/suggest/parrot are all print (packages/engine/modules/pymol/colorprinting.py:27-31); the stream is untyped text.
12. Return value from a parsed command line — cmd.do() returns None (packages/engine/modules/pymol/commanding.py:441-475); parser.result is stored (packages/engine/modules/pymol/parser.py:292) but is not returned through _cmd.do.

​

8. The bridge

​

8.1 Process & transport

• HTTP/1.1 on 127.0.0.1:<port> (bind explicitly to loopback, unlike rpc.py:430) for:
  • GET /healthz → {version, renderer, pid} from cmd.get_version() (packages/engine/modules/pymol/api.py:147) and cmd.get_renderer() (packages/engine/modules/pymol/api.py:142)
  • GET /schema → the generated API descriptor (§9)
  • GET /blob/{id} and POST /blob for large payloads (PNG from cmd.png packages/engine/modules/pymol/exporting.py:499, session bytes from cmd.get_session packages/engine/modules/pymol/exporting.py:371, cmd.get_bytes :679, geometry buffers)
  • POST /upload for drag-and-drop file ingestion (mirrors packages/engine/modules/pmg_qt/pymol_gl_widget.py:262-270)
• WebSocket on 127.0.0.1:<port>/ws — the primary channel. Binary frames carry MessagePack (msgpack is already a dev dependency, pyproject.toml:33); text frames carry JSON for debuggability. One socket per client; server rejects a second concurrent socket.
• Auth: a 256-bit token minted at startup, written to a 0600 file under the user’s runtime dir and passed as ?token=. Reject on mismatch and enforce Origin allow-listing and keep the 127.0. peer check from packages/engine/modules/pymol/pymolhttpd.py:63-67. Without this, any web page can reach cmd.system (packages/engine/modules/pymol/api.py:279) / cmd.run (:436).

​

8.2 Message envelope

// client -> server
{ "id": 42, "t": "call",     "m": "get_view", "a": [], "k": {} }
{ "id": 43, "t": "call",     "m": "load", "a": ["/x/1abc.cif"], "k": {"object":"m1"} }
{ "id": 44, "t": "batch",    "calls": [ {"m":"hide","a":["everything"]},
                                        {"m":"show","a":["cartoon","polymer"]} ] }
{ "id": 45, "t": "do",       "line": "color red, chain A" }        // parser path, §2.1
{ "id": 46, "t": "complete", "line": "col" }                        // §3
{ "id": 47, "t": "cancel",   "target": 43 }                         // -> cmd.interrupt / abort
{ "id": 48, "t": "sub",      "topics": ["objects","view","frame","feedback","progress"] }

// server -> client
{ "id": 42, "t": "ok",   "v": [ /* 18 floats */ ] }
{ "id": 43, "t": "err",  "e": { "kind": "CmdException", "label": "Error",
                                "message": "...", "traceback": ["..."] } }
{           "t": "ev",   "topic": "feedback", "seq": 991, "v": { "lines": ["..."] } }
{           "t": "ev",   "topic": "objects",  "seq": 992, "v": { /* §8.5 */ } }
{ "id": 43, "t": "prog", "v": 0.42 }

• id is a client-monotonic u32; every call/batch/do/complete gets exactly one terminal ok or err. Events carry no id.
• m is a flat cmd attribute name — "get_view", not "pymol.cmd.get_view". Drop pymolhttpd’s 10-char-prefix trick (packages/engine/modules/pymol/pymolhttpd.py:280-281) but keep its reserved-word aliasing convention (delete_, super_, packages/engine/modules/pymol/pymolhttpd.py:468-469) as a client-side concern only — the wire uses real names.
• Dotted names util.cbag, movie.produce etc. resolve by splitting on . and walking, matching the keyword table (packages/engine/modules/pymol/keywords.py:307-332).
• Allow-list, not attribute traversal. The dispatcher resolves m against a frozen dict built from api.py’s exports ∪ cmd.keyword, minus a deny-list. Deny by default: system (packages/engine/modules/pymol/api.py:279), run/spawn (:436-437), quit/_quit (packages/engine/modules/pymol/keywords.py:281-282), cd (:39), everything starting with _. Gate them behind an explicit --allow-unsafe bridge flag. Note pymolhttpd already made this call for label → label2 to avoid eval (packages/engine/modules/pymol/pymolhttpd.py:473); do the same, and additionally sandbox alter/iterate/alter_state/iterate_state (the LITERAL1/LITERAL2 commands, packages/engine/modules/pymol/keywords.py:19,21,144,145,147) behind the same flag since their last argument is eval’d Python.

​

8.3 Typed arguments

• ints/floats/bools/strings/lists/dicts map 1:1
• 18-float view vectors are plain arrays → cmd.set_view(list) (packages/engine/modules/pymol/viewing.py:734)
• bytes ride as MessagePack bin, or via /blob for anything > 256 KiB
• None ⇒ Python None (needed for e.g. set_bond(..., selection2=None), packages/engine/modules/pymol/setting.py:116)
• Never send _self; the dispatcher injects the instance’s Cmd proxy itself, mirroring parsing.prepare_call’s behaviour (packages/engine/modules/pymol/parsing.py:379, :414-415).
• Set quiet=1 by default; the parser’s implicit quiet=0 injection (packages/engine/modules/pymol/parsing.py:418-420) applies only to the do path and should be preserved there so the console behaves like PyMOL’s.
• Wrap every dispatch in try/except; map pymol.CmdException (packages/engine/modules/pymol/__init__.py:468-480, carries .message and .label) and parsing.QuietException (packages/engine/modules/pymol/parsing.py:71-72) to t:"err" with kind/label/message, and everything else to kind:"PythonError" plus a traceback.format_exception array — the same shape send_exception_json already produces (packages/engine/modules/pymol/pymolhttpd.py:189-207).

​

8.4 Completion contract

1. Reimplement in the bridge. Duplicate the 60-line dispatch of Parser._complete (packages/engine/modules/pymol/parser.py:528-596) but return { "prefix": str, "candidates": [str], "kind": "command"|"selection"|"color"|"setting"|"file"|…, "commonPrefix": str }. All inputs are public: cmd.kwhash (packages/engine/modules/pymol/cmd.py:332), cmd.auto_arg (packages/engine/modules/pymol/cmd.py:380), and Shortcut.interpret(keyword, mode) (packages/engine/modules/pymol/shortcut.py, used at packages/engine/modules/pymol/parser.py:58). kind comes for free — it is the type_name element of each auto_arg triple (packages/engine/modules/pymol/completing.py:52-66).
2. Wrap cmd._parser.complete(st) (packages/engine/modules/pymol/parser.py:524-526) and read the printed candidate list out of the feedback queue. This is what shipped: the console calls cmd._parser.complete (granted in packages/bridge/tenmol_bridge/policy/grants/wp-11-console.py) and pairs the completed string with the feedback lines (apps/web/src/features/console/CommandLine.tsx).

​

8.5 Change events

• drains cmd._get_feedback() (packages/engine/modules/pymol/internal.py:593-606) → topic:"feedback". Must tolerate the None return when the lock is contended (:605). Cap and coalesce; the Qt console uses a 500 ms period and resets to 0 ms right after a typed command (packages/engine/modules/pmg_qt/pymol_qt_gui.py:958, :964) — mirror that: bump to 0 ms after any do/call, back off to 250 ms when idle.
• calls cmd.get_progress() (packages/engine/modules/pymol/monitoring.py:5-7) → topic:"progress" when the value changes or crosses the <0 idle threshold.
• calls cmd.get_setting_updates() (packages/engine/modules/pymol/setting.py:440-447) → topic:"settings", emitting {name, value} per changed index via setting.name_dict (packages/engine/modules/pymol/setting.py:41) + cmd.get_setting_tuple (:413). This one is a real push-quality signal — it is exactly what the Qt GUI uses to keep its setting widgets in sync (packages/engine/modules/pmg_qt/pymol_qt_gui.py:952-957).
• calls _cmd._getRedisplay(COb, reset) (packages/engine/layer4/Cmd.cpp:6378, packages/engine/modules/pymol2/__init__.py:36-37) as a coarse dirty bit. When set, re-poll the cheap aggregates and diff.

1. Landed. Four monotonic counters on struct CExecutive — m_web_panel_version, m_web_enable_version, m_web_name_version, m_web_rep_version (packages/engine/layer3/ExecutiveDef.h:89-98), bumped at ExecutiveInvalidatePanelList (Executive.cpp:1521), ReportEnabledChange (:315), the rename path (:3686), ExecutiveUpdateCoordDepends (:1931) and the transform paths (:7695, :7717). Read through _cmd.web_get_versions (packages/engine/layer4/Cmd.cpp:6472, implementation packages/engine/layer4/CmdWebGeometry.cpp). This alone turns Tier 1 from “diff N object names” into “compare four integers”, which is what made an idle session cost ~1 us per poll. Consumed by packages/bridge/tenmol_bridge/state/repversions.py.
2. Partly landed. ReportEnabledChange (Executive.cpp:313) now bumps m_web_enable_version for every enable and disable; the #ifdef _PYMOL_LIB callback above it is untouched. No _cmd.get_events() queue was added — the counter made one unnecessary.
3. Not landed. There is still no view counter in SceneSetView/SceneRotate/SceneTranslate; the camera is detected by comparing the 18-float get_view() with an epsilon (Tier 1).
4. Landed differently. Rather than emit an event from PyMOL_SetClickReady (packages/engine/layer5/PyMOL.cpp:2594-2600), the client resolves a pick it already made against the engine through _cmd.web_resolve_pick (Cmd.cpp:6473). _cmd.get_click_string (Cmd.cpp:6451) still has zero Python callers upstream.
5. Not landed. colorprinting.error/warning/suggest/parrot (packages/engine/modules/pymol/colorprinting.py:27-31) are still bare print, so the stream is untyped text; the bridge classifies lines itself in packages/bridge/tenmol_bridge/feedback.py.
6. Not needed. The G->Option->pmgui gate on OrthoFeedbackIn (packages/engine/layer1/Ortho.cpp:494) stands; the bridge boots with pmgui enabled so the queue fills (§8.1).
7. Not landed. parser.result (packages/engine/modules/pymol/parser.py:292) is still not returned through _cmd.do, so a do frame still resolves to null and the result surfaces as feedback text.

​

8.6 Key bindings

​

9. Generating the TypeScript client from Python

​

9.1 Reality of the source material

• Type annotations: 6 in the entire API (packages/engine/modules/pymol/viewing.py:228, packages/engine/modules/pymol/commanding.py:548, packages/engine/modules/pymol/editing.py:2141, :2167, plus cgobuilder.py). So get_type_hints alone yields almost nothing.
• Defaults: universally present and informative. Every API function is def f(a='(all)', state=-1, quiet=1, *, _self=cmd). inspect.signature gives name, kind (POSITIONAL_ONLY / POSITIONAL_OR_KEYWORD / KEYWORD_ONLY / VAR_*), and default value. parsing.prepare_call already relies on exactly this data (packages/engine/modules/pymol/parsing.py:346-360) — so does rpcHelp (packages/engine/modules/pymol/rpc.py:392-405).
• Docstrings: highly regular. Uppercase section headers DESCRIPTION, USAGE, ARGUMENTS, NOTES, PYMOL API, EXAMPLES, SEE ALSO. write_html_ref already parses them by detecting line.isupper() and SEE ALSO (packages/engine/modules/pymol/cmd.py:290-303). ARGUMENTS blocks are name = type: description {default: x} — e.g. packages/engine/modules/pymol/commanding.py:107-110, packages/engine/modules/pymol/feedingback.py:52-58, packages/engine/modules/pymol/viewing.py:650-656.
• Completion tables give semantic domains: cmd.auto_arg[i][command] says argument i of command is a 'selection' / 'color' / 'setting' / 'representation' / 'object' / 'scene' / 'palette' / … (packages/engine/modules/pymol/completing.py:52-66, :85-315).
• Runtime enums: _cmd.get_setting_indices() (packages/engine/modules/pymol/setting.py:38) for all setting names; cmd.get_color_indices() (packages/engine/modules/pymol/internal.py:579) for all colors; the Shortcut objects viewing.cartoon_sc, viewing.clip_action_sc, viewing.scene_action_sc, controlling.button_sc/but_mod_sc/but_act_sc, editing.flag_sc/flag_action_sc/order_sc, creating.map_type_sc/group_action_sc, exporting.cache_action_sc, moving.mview_action_sc, commanding.reinit_sc — all referenced from packages/engine/modules/pymol/completing.py:97-307 and each exposes .keywords (packages/engine/modules/pymol/shortcut.py:41-49).
• keywords.get_command_keywords() gives the mode per command, which tells the generator which commands are LITERAL*/PYTHON/SECURE and must be typed specially or excluded (packages/engine/modules/pymol/keywords.py:14-333).

​

9.2 Pipeline

tools/gen-api/
  extract.py     # runs INSIDE a live PyMOL, dumps api-schema.json
  api-schema.json
  emit.mjs       # reads api-schema.json, writes packages/protocol/src/generated/api.ts

packages/bridge/.venv/bin/python tools/gen-api/extract.py > tools/gen-api/api-schema.json
node tools/gen-api/emit.mjs tools/gen-api/api-schema.json packages/protocol/src/generated/api.ts

import inspect, json, pymol
from pymol import cmd, keywords, setting

kw = keywords.get_command_keywords()          # packages/engine/modules/pymol/keywords.py:5
out = {"functions": {}, "keywords": {}, "enums": {}, "autoArg": []}

for name in dir(cmd):                          # api.py exports, via cmd.py:319
    fn = getattr(cmd, name)
    if not callable(fn) or name.startswith('_'):
        continue
    try:
        sig = inspect.signature(inspect.unwrap(fn))
    except (TypeError, ValueError):
        continue
    out["functions"][name] = {
        "module": getattr(fn, "__module__", None),
        "doc": inspect.getdoc(fn),
        "params": [
            {"name": p.name,
             "kind": p.kind.name,
             "hasDefault": p.default is not p.empty,
             "default": repr(p.default) if p.default is not p.empty else None,
             "annotation": None if p.annotation is p.empty else str(p.annotation)}
            for p in sig.parameters.values() if p.name != "_self"
        ],
    }

for k, row in kw.items():
    out["keywords"][k] = {"target": getattr(row[0], "__name__", None), "mode": row[4]}

out["enums"]["setting"] = sorted(setting.index_dict)          # setting.py:38
out["enums"]["color"]   = [c[0] for c in cmd.get_color_indices()]   # internal.py:579
out["autoArg"] = [
    {c: t[1] for c, t in table.items()}                       # completing.py:52-66
    for table in cmd.auto_arg                                  # cmd.py:380
]
json.dump(out, open("api-schema.json", "w"), indent=1)

1. explicit annotation, if present (the 6 cases)
2. auto_arg domain → branded alias: 'selection'→Selection, 'color'→ColorName, 'object'→ObjectName, 'setting'→SettingName, 'representation'→RepName, 'scene'→SceneName, 'palette'→PaletteName
3. default-value type: 1/0 on a param named quiet/updates/animate/hand/ray → boolean \| 0 \| 1; other ints → number; strings → string; tuples → fixed-length tuple
4. ARGUMENTS docstring line name = int: … / = str: / = float: / = list: — parsed with the same uppercase-section walk write_html_ref (packages/engine/modules/pymol/cmd.py:211) uses (:290-303)
5. name heuristics: state/frame/width/height/dpi→number, filename/prefix→string, *_sele/selection*→Selection
6. fallback ApiValue = string \| number \| boolean \| null \| ApiValue[] \| {[k:string]:ApiValue}

export interface ColorOptions { selection?: Selection; quiet?: 0|1; flags?: number }
/** Change the color of an object or selection.  (pymol.viewing.color) */
export function color(client: PymolClient, color: ColorName, opts?: ColorOptions): Promise<unknown>;

​

9.3 Runtime client shape

class PymolClient {
  call<T = unknown>(m: string, a?: unknown[], k?: Record<string, unknown>): Promise<T>;
  batch(calls: Call[]): Promise<unknown>;
  do(line: string): Promise<null>;                 // console only, always resolves null
  complete(line: string): Promise<CompleteResult>;
  usage(name: string): Promise<string>;
  help(name: string): Promise<string>;
  on<K extends Topic>(topic: K, cb: (v: TopicPayload[K]) => void): () => void;
  blob(id: string): Promise<Blob>;
}

​

10. Constraints this area lives under

1. G->Option->pmgui gates the feedback queue (packages/engine/layer1/Ortho.cpp:492-499), so a bridge that boots without pmgui gets zero console output. The bridge enables it (§8.1).
2. No change notifications exist at all (grep -r Notify layer0..layer5 gives 0 hits), so the whole event story is polling. §8.5 Tier 2 item 1 is what keeps that affordable: four integers instead of an O(objects) diff per tick.
3. cmd.do swallows return values and exceptions (packages/engine/modules/pymol/parser.py:465-481, packages/engine/modules/pymol/commanding.py:441-475), so anything built on the do path is blind to failure. That is why do is the console path only and UI actions take the typed call path.
4. Both bundled bridges are unauthenticated. rpc.py:441 register_instance(cmd) plus rpc.py:422-430 (no localhost binding) is remote code execution by design. pymolhttpd’s 127.0. check (:63-67) does not stop a hostile web page in the user’s own browser. The replacement ships a token, an Origin allow-list and a loopback peer check together.
5. LITERAL1/LITERAL2 commands eval user strings (alter, iterate, alter_state, iterate_state, label, alias, set_key — packages/engine/modules/pymol/keywords.py:16,19,21,144,145,147,257). pymolhttpd dodged label by substituting label2 (:473). Parity with the desktop app means an arbitrary-Python surface reachable from the browser; the transport is what bounds it, which is why §8.1 spends its security budget there rather than on a symbol deny-list.
6. prepare_call does no type coercion (packages/engine/modules/pymol/parsing.py:329-421); functions coerce internally and inconsistently. Sending a JSON number where PyMOL expected a string usually works but is untested across all 404 functions.
7. Six type annotations in the entire API, so generated types are largely heuristic. The override table and the CI drift check in §9 are what keep the long tail honest.
8. new_command has zero callers (packages/engine/modules/pymol/commanding.py:722). It is the intended modern path but is unexercised upstream.
9. Threading. cmd is protected by lock_api/lockcm (packages/engine/modules/pymol/cmd.py:135-142, packages/engine/modules/pymol/locking.py) and cmd._get_feedback can return None under contention (packages/engine/modules/pymol/internal.py:605). _call_in_gui_thread is a plain passthrough in the module singleton (packages/engine/modules/pymol/cmd.py:164-165) — Qt overrides it (packages/engine/modules/pmg_qt/pymol_qt_gui.py:1243-1251). The bridge marshals everything that touches the engine onto one thread (packages/bridge/tenmol_bridge/pump.py).
10. Deprecated stdlib usage in pymolhttpd (Event.isSet :490/:502, Thread.setDaemon :497) breaks on newer Pythons regardless of anything this port does.
11. The .pwg launch path (packages/engine/modules/pymol/importing.py:516-610) is the only way pymolhttpd starts, so any workflow that depends on .pwg depends on pymolhttpd.
12. rpc.py shadows cmd.label and cmd.rotate (packages/engine/modules/pymol/rpc.py:463-465), so a client written against XML-RPC has the wrong semantics for those two.