from __future__ import annotations
import argparse
import ast
import difflib
import hashlib
import json
import re
import subprocess
import tempfile
from pathlib import Path
from typing import Any, Iterable
REPOSITORY = "https://github.com/openai/codex.git"
TRACKED_GROUPS = {
"package_and_docs": ("README.md", "pyproject.toml", "docs/*.md"),
"source": ("src/openai_codex/**/*.py",),
"tests": ("tests/*.py",),
}
def command(*args: str, cwd: Path | None = None) -> str:
return subprocess.run(
args,
cwd=cwd,
check=True,
text=True,
stdout=subprocess.PIPE,
).stdout.strip()
def checkout(ref: str, destination: Path) -> tuple[Path, str]:
command(
"git",
"clone",
"--quiet",
"--filter=blob:none",
"--no-checkout",
REPOSITORY,
str(destination),
)
command("git", "sparse-checkout", "init", "--cone", cwd=destination)
command("git", "sparse-checkout", "set", "sdk/python", cwd=destination)
command("git", "fetch", "--quiet", "--depth=1", "origin", ref, cwd=destination)
command("git", "checkout", "--quiet", "FETCH_HEAD", cwd=destination)
return destination / "sdk/python", command("git", "rev-parse", "HEAD", cwd=destination)
def source_revision(source: Path) -> tuple[Path, str]:
if (source / "sdk/python/pyproject.toml").is_file():
sdk = source / "sdk/python"
repository = source
elif (source / "pyproject.toml").is_file() and (source / "src/openai_codex").is_dir():
sdk = source
repository = source
while repository != repository.parent and not (repository / ".git").exists():
repository = repository.parent
else:
raise SystemExit(f"{source} is neither an openai/codex checkout nor sdk/python")
try:
revision = command("git", "rev-parse", "HEAD", cwd=repository)
except subprocess.CalledProcessError:
revision = "unknown"
return sdk, revision
def parse_module(path: Path) -> ast.Module:
return ast.parse(path.read_text(encoding="utf-8"), filename=str(path))
def literal_string_list(module: ast.Module, name: str) -> list[str]:
for node in module.body:
if isinstance(node, (ast.Assign, ast.AnnAssign)):
targets = node.targets if isinstance(node, ast.Assign) else [node.target]
if any(isinstance(target, ast.Name) and target.id == name for target in targets):
value = ast.literal_eval(node.value)
return list(value)
raise ValueError(f"{name} not found")
def annotation(node: ast.expr | None) -> str | None:
return ast.unparse(node) if node is not None else None
def default_value(node: ast.expr | None) -> str | None:
return ast.unparse(node) if node is not None else None
def function_contract(node: ast.FunctionDef | ast.AsyncFunctionDef) -> str:
prefix = "async " if isinstance(node, ast.AsyncFunctionDef) else ""
returns = f" -> {annotation(node.returns)}" if node.returns is not None else ""
return f"{prefix}def {node.name}({ast.unparse(node.args)}){returns}"
def public_classes(source_dir: Path, exports: set[str]) -> dict[str, Any]:
classes: dict[str, Any] = {}
for path in sorted(source_dir.glob("*.py")):
for node in parse_module(path).body:
if not isinstance(node, ast.ClassDef) or node.name not in exports:
continue
methods = {
child.name: function_contract(child)
for child in node.body
if isinstance(child, (ast.FunctionDef, ast.AsyncFunctionDef))
and not child.name.startswith("_")
}
fields = {}
for child in node.body:
if isinstance(child, ast.AnnAssign) and isinstance(child.target, ast.Name):
default = (
f" = {default_value(child.value)}" if child.value is not None else ""
)
fields[child.target.id] = f"{annotation(child.annotation)}{default}"
classes[node.name] = {
"defined_in": path.name,
"fields": fields,
"methods": methods,
}
return classes
def request_methods(source_dir: Path) -> list[str]:
methods = set()
for path in sorted(source_dir.glob("*.py")):
for node in ast.walk(parse_module(path)):
if not isinstance(node, ast.Call) or not node.args:
continue
if not isinstance(node.func, ast.Attribute) or node.func.attr not in {"request", "notify"}:
continue
first = node.args[0]
if isinstance(first, ast.Constant) and isinstance(first.value, str):
methods.add(first.value)
return sorted(methods)
def notification_registry(path: Path) -> dict[str, str]:
module = parse_module(path)
for node in module.body:
if not isinstance(node, ast.AnnAssign):
continue
if not isinstance(node.target, ast.Name) or node.target.id != "NOTIFICATION_MODELS":
continue
if not isinstance(node.value, ast.Dict):
break
return {
ast.literal_eval(key): value.id
for key, value in zip(node.value.keys, node.value.values)
if isinstance(value, ast.Name)
}
raise ValueError("NOTIFICATION_MODELS not found")
def tracked_files(sdk: Path, patterns: Iterable[str]) -> Iterable[Path]:
paths = set()
for pattern in patterns:
paths.update(path for path in sdk.glob(pattern) if path.is_file())
return sorted(paths)
def sha256(path: Path) -> str:
return hashlib.sha256(path.read_bytes()).hexdigest()
def grouped_sha256(sdk: Path, patterns: Iterable[str]) -> str:
digest = hashlib.sha256()
for path in tracked_files(sdk, patterns):
digest.update(str(path.relative_to(sdk)).encode())
digest.update(b"\0")
digest.update(path.read_bytes())
digest.update(b"\0")
return digest.hexdigest()
def generated_model_summary(path: Path) -> dict[str, Any]:
classes = [node.name for node in parse_module(path).body if isinstance(node, ast.ClassDef)]
return {
"class_count": len(classes),
"sha256": sha256(path),
}
def build_contract(sdk: Path, revision: str) -> dict[str, Any]:
package = sdk / "src/openai_codex"
root_exports = literal_string_list(parse_module(package / "__init__.py"), "__all__")
type_exports = literal_string_list(parse_module(package / "types.py"), "__all__")
exports = set(root_exports) | set(type_exports)
pyproject = (sdk / "pyproject.toml").read_text(encoding="utf-8")
runtime = re.search(r'"openai-codex-cli-bin==([^"]+)"', pyproject)
return {
"schema_version": 1,
"upstream": {
"repository": REPOSITORY,
"revision": revision,
"sdk_path": "sdk/python",
"runtime_version": runtime.group(1) if runtime else None,
},
"public_root_exports": root_exports,
"public_type_exports": type_exports,
"public_classes": public_classes(package, exports),
"rpc_methods": request_methods(package),
"notification_models": notification_registry(
package / "generated/notification_registry.py"
),
"generated_protocol": generated_model_summary(package / "generated/v2_all.py"),
"file_group_sha256": {
group: grouped_sha256(sdk, patterns)
for group, patterns in TRACKED_GROUPS.items()
},
}
def encoded(contract: dict[str, Any]) -> str:
return json.dumps(contract, indent=2, sort_keys=True) + "\n"
def main() -> int:
parser = argparse.ArgumentParser(
description="Capture or verify the public contract of openai/codex sdk/python."
)
parser.add_argument("--ref", default="main", help="upstream Git ref to inspect")
parser.add_argument("--source", type=Path, help="existing checkout or sdk/python directory")
parser.add_argument(
"--snapshot",
type=Path,
default=Path("upstream/python-sdk-contract.json"),
)
mode = parser.add_mutually_exclusive_group(required=True)
mode.add_argument("--check", action="store_true")
mode.add_argument("--write", action="store_true")
args = parser.parse_args()
with tempfile.TemporaryDirectory(prefix="codex-sdk-upstream-") as temp:
if args.source is not None:
sdk, revision = source_revision(args.source.resolve())
else:
sdk, revision = checkout(args.ref, Path(temp) / "codex")
actual = encoded(build_contract(sdk, revision))
if args.write:
args.snapshot.parent.mkdir(parents=True, exist_ok=True)
args.snapshot.write_text(actual, encoding="utf-8")
print(f"wrote {args.snapshot} for {revision}")
return 0
if not args.snapshot.exists():
print(f"missing snapshot: {args.snapshot}")
return 1
expected = args.snapshot.read_text(encoding="utf-8")
if expected == actual:
print(f"upstream Python SDK contract matches {revision}")
return 0
print(
"".join(
difflib.unified_diff(
expected.splitlines(keepends=True),
actual.splitlines(keepends=True),
fromfile=str(args.snapshot),
tofile=f"openai/codex@{revision}:sdk/python",
)
)
)
return 1
if __name__ == "__main__":
raise SystemExit(main())