feat(python): add Python contract generator

[elzalem]

Summary

This PR extracts the Python generator work from #126.

Included here:

• add protoc-gen-py-client
• add Python golden coverage

Why

The Python generator uses the shared internal/contractmodel introduced in #131, so this PR is intentionally stacked on top of that base instead of duplicating the shared traversal layer.

What Changed

• add cmd/protoc-gen-py-client
• add internal/pyclientgen

Tests

• env GOTOOLCHAIN=auto go test ./internal/pyclientgen
• env GOTOOLCHAIN=auto go test ./cmd/protoc-gen-py-client

[SebastienMelki]

Code Review — PR #132

@elzalem thanks for the Python generator! Since this builds on contractmodel from #131, many of the foundational issues carry over. Here's the Python-specific feedback.

---

internal/pyclientgen/generator.go

1. Unused package flag

The package flag is registered via flags.String("package", "", "Override Python package output path") but never read or used anywhere in the generator. Either implement it or remove it — dead flags confuse users.

2. All fields are T | None = None — no required/optional distinction

Every field is generated as optional (| None = None), making required fields indistinguishable from optional ones. Proto3 optional keyword and required semantics should produce different Python types. At minimum, non-optional fields should not default to None.

3. services dict is stringly-typed

The service metadata is generated as a deeply nested dict[str, dict[str, dict[str, str]]]. This is not Pythonic and provides no type safety. Consider generating typed dataclasses or at least TypedDict definitions for the service registry. It also lacks HTTP method/path information — for a plugin called protoc-gen-py-client, users would expect actual HTTP client functionality.

4. No to_dict() / from_dict() serialization

The generated dataclasses are pure data holders with no serialization methods. For a client generator, users need to convert to/from JSON dicts for HTTP requests. Without this, the generated code is incomplete as a "client" — it's just a set of data classes.

5. Enum values use raw proto names

Enum values like STATE_UNSPECIFIED are used directly. While this is technically valid Python, it doesn't match Python naming conventions (which would be STATE_UNSPECIFIED for constants, which happens to match — but the class name ItemItem_State is odd). The naming comes from contractmodel's __ separator issue.

6. No sebuf annotation support

Same as #131 — none of the project's custom annotations are handled. int64_encoding, enum_encoding, timestamp_format, nullable, etc. are all ignored.

---

internal/pyclientgen/golden_test.go

7. Same minimal test proto as C#

The test proto is identical to the one in #131 — single file, basic types only. Same gaps apply: no optional, no oneof, no complex maps, no well-known types beyond Struct, no sebuf annotations, no multi-file imports.

8. diffStrings() duplicated again

Same helper copy-pasted from csharpgen tests.

---

Missing Requirements

Same as #131 — this PR needs the following before it's ready:

1. Documentation: Top-level docs (README/CLAUDE.md updates) explaining the Python generator, plus generator-specific docs covering all supported features, options, and limitations.

2. Examples: A working example in the examples/ directory demonstrating the Python generator across all supported use cases — including different field types, nested messages, enums, maps, well-known types, and how to use the generated code in a real Python project.

3. Extensive testing: We need:

   • Unit tests for Python-specific functions (pythonType, pythonScalar, pythonBaseType, initFiles)
   • Multiple golden test protos covering edge cases (optional fields, oneof, complex maps, deeply nested messages, multiple services, well-known types)
   • The shared contractmodel also needs its own unit test suite (see #131 review)

4. Plugin completeness: For something named protoc-gen-py-client, users expect an actual HTTP client — not just dataclasses. Either implement client functionality or rename to protoc-gen-py-contracts to set expectations correctly.

[SebastienMelki]

@shavaizknz this pull request adds python support on the client side

[SebastienMelki]

Hey @elzalem — really appreciate the work here, thank you for putting this together.

We need the Python client shipped today for an internal deadline and we don't want to block it behind the contractmodel / C# work, which has its own design questions we want to discuss separately. I'm going to close this PR and reopen a fresh one based directly on main, following the same pattern as our existing tsclientgen and clientgen generators (calling internal/annotations/ directly rather than going through an intermediate model layer).

I'll cherry-pick your test protos and serialization helpers (bytes encoding, snake_case conversion, path/query param logic, oneof discriminator sketch) into the new PR with credit to you. Let's keep the C# generator and contractmodel discussion alive on #131 — I'll come back to that thread once Python is out.

Thanks again for the contribution, and sorry about the churn here.