python: thin Python client (pip install capcut) over the CLI and its JSONL queue

[renezander030]

What

python/ — a pure-Python package, capcut on PyPI, that wraps the installed CLI.

• capcut.run(cmd, *args, **flags) spawns capcut once, without a shell, and returns the JSON it prints. Keyword arguments become flags (font_size=16 → --font-size 16, karaoke=True → --karaoke, lists repeat, None/False drop). Positionals pass through as single argv tokens, so Chinese text, spaces and quotes never need escaping. A non-zero exit raises CommandError with status and the CLI's own {"error": ...} (read from stderr when stdout is empty). run_raw never raises.
• capcut.serve(jobs, workers=…) feeds the stateless JSONL queue and returns one parsed result per job; a failed job is ok: false, not an exception.
• describe(), doctor() (returned even on exit 1), version(), human=True for -H text.
• The binary is found on PATH or through CAPCUT_CLI (a command line, e.g. node …/dist/index.js); a missing binary raises CliNotFound with the npm install line in Chinese and English.
• Output is captured to temporary files rather than pipes: describe (93 KB) was cut at the 64 KiB pipe buffer on exit, the same effect the repo's spawn-cli test helper works around.

README in Chinese first, English second (it is the PyPI page). Root READMEs point at it from the install block. Not in the npm tarball (files whitelist unchanged). No runtime dependencies on either side.

Checks

• python -m unittest discover -s tests: 11 tests against a stand-in binary (flag conversion, unicode positionals, error propagation, -H, version, doctor on exit 1, serve round trip, missing-binary message).
• Wheel and sdist build with python -m build; the wheel installed into a clean venv and run against the built CLI: quickstart 9:16, add-text with Chinese and quotes, lint, info on a missing path (CommandError with the CLI's message), serve with two jobs, describe (86 commands), doctor, -H.
• Not published yet: python -m build && twine upload dist/* from python/ when this merges.

Docs

python/README.md, install pointers in README.md and README.zh-CN.md, CHANGELOG (Unreleased), .gitignore for the build artifacts.