fix(python): keep unions of named object types distinct instead of merging them

[schani]

What was broken

TypeScript unions of named interfaces (and the equivalent JSON Schema oneOf/anyOf of $refs) targeting Python were collapsed into a single synthetic class with all fields made optional, instead of a real Union[...].

Repro from the issue:

interface Foo {
    foo: string;
}

interface Bar {
    bar: string;
}

interface Container {
    op: Foo | Bar;
}

quicktype --src-lang typescript --lang python produced:

@dataclass
class Op:
    foo: Optional[str] = None
    bar: Optional[str] = None

@dataclass
class Container:
    op: Op

instead of the expected:

@dataclass
class Container:
    op: Union[Foo, Bar]

Root cause

This isn't Python-specific or TypeScript-input-specific: quicktype-core's UnionType model only ever allowed one member per kind. Any union with two class-kind members was therefore treated as "non-canonical" and unconditionally merged by the flattenUnions graph rewrite (via UnifyUnionBuilder.makeObject in UnifyClasses.ts), for every target language, before any language-specific renderer saw the type graph. The same merging happens today for JSON Schema oneOf input and for every other target language (C#, Rust, Swift, Kotlin, etc.) — Python is just where it's most visible because Python has a native union type.

A fully general fix (arbitrary language, arbitrary overlap, arbitrary union arity) would require relaxing that core invariant everywhere and auditing every renderer that assumes at most one object member per union — too large and risky for this issue. This PR takes a minimal, opt-in approach instead.

The fix

• Added TargetLanguage.supportsUnionsWithMultipleObjectTypes (default false), following the existing precedent of capability flags like supportsFullObjectType. Enabled it for Python only.
• Threaded the flag through Run.ts into flattenUnions/UnifyClasses.ts.
• Added a new explicit-union-member type attribute (packages/quicktype-core/src/attributes/ExplicitUnionMember.ts), set by JSONSchemaInput.ts on direct $ref alternatives of a oneOf/anyOf (TypeScript input lowers Foo | Bar to schema anyOf, so this covers both entry points).
• UnifyUnionBuilder.makeObject now keeps object-kind union members distinct (instead of merging them) when the capability is on and the members are named, non-empty, closed (no additionalProperties), and pairwise disjoint in property names — i.e. exactly the unambiguous case from the issue. Anything outside that (anonymous shapes, overlapping properties, maps/additional properties, non-opted-in languages) keeps the previous merge behavior.
• Python's renderer already handles unions of classes correctly (from_union, etc.) once the graph preserves them distinctly, so no renderer changes were needed.

Test coverage

• test/inputs/schema/named-class-union.schema + .1.json/.2.json positive samples and a .1.fail.union.json negative sample — exercised end-to-end via the schema-python fixture suite.
• test/unit/named-class-union.test.ts — asserts the merged synthetic class is no longer generated for Python (for both oneOf and the anyOf shape TypeScript input produces), and that non-opted-in languages (TypeScript) are unaffected.

Verification

• npm run build passes.
• npm run test:unit — 179/179 passing.
• QUICKTEST=true FIXTURE=schema-python script/test — full suite passing, including the pre-existing renaming-bug.schema fixture (a regression an earlier attempt at this fix hit there; not an issue here).
• QUICKTEST=true FIXTURE=schema-typescript script/test — full suite passing, confirming TypeScript output is unaffected.
• Re-ran the exact issue repro: Container.op now renders as Foo | Bar (or Union[Foo, Bar] on --python-version 3.7), with correct from_union([Foo.from_dict, Bar.from_dict], ...) round-trip code.
• C# and other toolchains weren't available in the sandbox to spot-check locally; CI will validate those. The change is opt-in and defaults to false for every language other than Python, so no other language's output should change.

Fixes #1646

🤖 Generated with Claude Code

[github-actions]

Generated-output differences

29 files differ — 1 modified, 28 new, 0 deleted
2359 changed lines — +2235 / −124

Open the generated-output report →

[github-actions]

Generated-output differences

30 files differ — 1 modified, 29 new, 0 deleted
2429 changed lines — +2305 / −124

Open the generated-output report →