Experimental Status

Experimental work: this PR is part of an exploratory contract/generated docs and SDK effort, and is intentionally kept as a Draft while the approach is validated.

Why

This adds the first generated island for the API2-owned TUS protocol client generator in tus-py-client. The goal is to prove the same raw TUS protocol + client feature contract can drive Python behavior without duplicating endpoint/header/status knowledge in the generator.

What

• Add generated tusclient/protocol_generated.py with the default Tus-Resumable wire version.
• Add generated tests/generated_protocol_contract.py with TUS wire operations, response shapes, and client feature metadata.
• Use the generated default protocol version in BaseUploader.DEFAULT_HEADERS without changing behavior.
• Add a real create+patch lifecycle test that drives TusClient.uploader(...).upload() from generated contract facts.
• Fetch LFS fixtures in CI so existing fingerprint tests exercise the real sample PNG instead of its LFS pointer.
• Add a checked-in API2 devdock custom-request-headers example that reads contract-owned upload headers, sends them through the public headers option, and reports the POST/PATCH headers observed through request lifecycle hooks.
• Add generated request-header helpers that prepare default operation headers, custom headers, and generated request IDs from the shared TUS request-planning contract.
• Add TusClient(add_request_id=...), enable_request_id_header(), and disable_request_id_header() so the SDK can opt into generated request IDs through public API.
• Add a checked-in API2 devdock request-ID headers example that reports generated X-Request-ID values observed on POST and PATCH through request lifecycle hooks.
• Add a checked-in API2 devdock upload-body-headers example that reads method-specific body header expectations from scenario JSON and reports final POST/PATCH headers observed through request lifecycle hooks.

Verification

• python -m pytest -q in a temporary venv: 48 passed, 1 LibreSSL warning from urllib3.
• CI failure triage confirmed the generated contract test passed; the first matrix failure was existing LFS fixture checkout drift, now fixed with actions/checkout lfs: true.
• From API2: api2/bin/cli.ts contracts sdks --target tus --platform python --sdk-root ../tus-py-client --rewrite-sdk --compare-existing --no-motd
• API2 wrapper: core/bin/devdock.ts exec tstrun system/sdk_examples/python-tus-transloadit-assembly-upload.test.ts -vv --max-time-per-test 420 after API2 custom request headers proof
• python3 -m pytest -q tests/test_examples.py after API2 custom request headers proof
• python3 -m py_compile examples/api2devdock.py examples/api2-devdock-tus-custom-request-headers/main.py after API2 custom request headers proof
• python3 -m pytest -q after API2 request ID headers proof
• From API2: api2/bin/cli.ts contracts sdks --target tus --platform python --sdk-root ../tus-py-client --compare-existing --no-motd after API2 request ID headers proof
• API2 wrapper: core/bin/devdock.ts exec tstrun system/sdk_examples/python-tus-transloadit-assembly-upload.test.ts -vv --max-time-per-test 420 after API2 request ID headers proof
• python3 -m pytest -q after API2 upload body headers proof
• From API2: api2/bin/cli.ts contracts sdks --no-motd --target tus --platform python --sdk-root ../tus-py-client --compare-existing after upload body headers proof
• From API2: api2/bin/cli.ts contracts sdks qa --no-motd --target tus --platform python --dry-run after upload body headers proof
• API2 wrapper: core/bin/devdock.ts exec tstrun system/sdk_examples/python-tus-transloadit-assembly-upload.test.ts -vv --max-time-per-test 420 after upload body headers proof

Companion PRs (tus org only)

• tus-js-client: Mark protocol versions as generated tus-js-client#872
• tus-go-client: Add generated TUS protocol canary tus-go-client#6
• tus-java-client: Add generated TUS protocol contract canary tus-java-client#149
• tus-android-client: Add generated TUS protocol contract canary tus-android-client#167