fix(codegen/python): disambiguate namespace/root leaf-name collisions (#161)

[hardbyte]

Fixes #161.

Problem

In the multi-file (package) Python client, a root type and a same-leaf type under a sub-namespace (e.g. a root IfConflictOnUpdate and a nomatches::IfConflictOnUpdate) collide on a bare public name. Each namespace module emitted both:

from .._types import IfConflictOnUpdate          # the root type
...
class NomatchesIfConflictOnUpdate(BaseModel, Generic[C]): ...
class NomatchesUpdateRequest(BaseModel):
    conflict: IfConflictOnUpdate[SomeMatch]       # bare → resolves to the rebind below
IfConflictOnUpdate = NomatchesIfConflictOnUpdate  # rebind shadows the import

So _types.IfConflictOnUpdate is not nomatches.IfConflictOnUpdate — two distinct classes sharing a name — and a field annotated against one rejects an instance of the other at runtime with a confusingly self-identical pydantic ValidationError. Reproduces identically on 0.17.4 and current main (the recent namespace-import work did not touch the duplicate-definition logic).

Fix

Collision-aware naming in reflectapi/src/codegen/python.rs. A leaf "collides" when a sub-namespace defines a type whose short (prefix-stripped) name equals a root type imported into every module. For collisions only, the generator now:

• keeps the short name (IfConflictOnUpdate) bound to the imported root type — suppresses the colliding bare alias;
• exposes the namespace-local type under its disambiguated flat name (NomatchesIfConflictOnUpdate), and rewrites references to it — in its own field annotations and in cross-namespace references from other modules — to that name.

Result: one Python class per logical type, so model.<X> resolves consistently. The collision key is the io-qualified type name, so genuinely-distinct input::/output:: projections are never collapsed. It is a strict no-op for schemas without such collisions — the committed demo client is byte-identical.

Tests

• New regression test test_python_namespace_leaf_collision_no_shadowing (multi-file package path): asserts no colliding bare rebind, the namespace field uses the disambiguated name, and a root cross-namespace ref is qualified with the disambiguated name. Fails before the fix, passes after.
• Verified at runtime against reflectapi-runtime + pydantic 2.13: _types.IfConflictOnUpdate is nomatches.IfConflictOnUpdate is now True, the namespace-local type stays distinct, and a request/response round-trip validates without the ValidationError.
• cargo fmt --all, clippy -D warnings, build --workspace, demo + CLI suites pass (Python snapshots require ruff installed locally).

Docs

• CHANGELOG entry under Unreleased.
• Python client naming note in docs/src/clients/README.md.

[github-actions]

📖 Documentation Preview: https://reflectapi-docs-preview-pr-162.partly.workers.dev

Updated automatically from commit b261956

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 98d0de222a

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".