Merge pull request #252 from atomic-ehr/py/reference-family-comment

PY: name the widened reference family, and drop the TypeScript references from comments

Author: ryukzak

examples/python-r4-us-core/fhir_types/hl7_fhir_r4_core/observation.py

@@ -67,7 +67,7 @@ class Observation(DomainResource):
     effectivePeriod: Period | None = Field(None, alias="effectivePeriod", serialization_alias="effectivePeriod")
     effectiveTiming: Timing | None = Field(None, alias="effectiveTiming", serialization_alias="effectiveTiming")
     encounter: Reference[Literal["Encounter"]] | None = Field(None, alias="encounter", serialization_alias="encounter")
-    focus: PyList[Reference] | None = Field(None, alias="focus", serialization_alias="focus")
+    focus: PyList[Reference] | None = Field(None, alias="focus", serialization_alias="focus")  # Resource
     hasMember: PyList[Reference[Literal["MolecularSequence", "Observation", "QuestionnaireResponse"]]] | None = Field(None, alias="hasMember", serialization_alias="hasMember")
     identifier: PyList[Identifier] | None = Field(None, alias="identifier", serialization_alias="identifier")
     interpretation: PyList[CodeableConcept[Literal["_GeneticObservationInterpretation", "CAR", "Carrier", "_ObservationInterpretationChange", "B", "D", "U", "W", "_ObservationInterpretationExceptions", "<", ">", "AC", "IE", "QCF", "TOX", "_ObservationInterpretationNormality", "A", "AA", "HH", "LL", "H", "H>", "HU", "L", "L<", "LU", "N", "_ObservationInterpretationSusceptibility", "I", "MS", "NCL", "NS", "R", "SYN-R", "S", "SDD", "SYN-S", "VS", "EX", "HX", "LX", "HM", "ObservationInterpretationDetection", "IND", "E", "NEG", "ND", "POS", "DET", "ObservationInterpretationExpectation", "EXP", "UNE", "OBX", "ReactivityObservationInterpretation", "NR", "RR", "WR"] | str]] | None = Field(None, alias="interpretation", serialization_alias="interpretation")

examples/python-r4-us-core/fhir_types/hl7_fhir_r4_core/provenance.py

@@ -26,7 +26,7 @@ class ProvenanceEntity(BackboneElement):
     model_config = ConfigDict(validate_by_name=True, serialize_by_alias=True, extra="forbid")
     agent: PyList[ProvenanceAgent] | None = Field(None, alias="agent", serialization_alias="agent")
     role: Literal["derivation", "revision", "quotation", "source", "removal"] = Field(alias="role", serialization_alias="role")
-    what: Reference = Field(alias="what", serialization_alias="what")
+    what: Reference = Field(alias="what", serialization_alias="what")  # Resource
 
 
 class Provenance(DomainResource):
@@ -50,7 +50,7 @@ class Provenance(DomainResource):
     recorded: str = Field(alias="recorded", serialization_alias="recorded")
     recordedExtension: Element | None = Field(None, alias="_recorded", serialization_alias="_recorded")
     signature: PyList[Signature] | None = Field(None, alias="signature", serialization_alias="signature")
-    target: PyList[Reference] = Field(alias="target", serialization_alias="target")
+    target: PyList[Reference] = Field(alias="target", serialization_alias="target")  # Resource
 
     def model_post_init(self, __context: Any) -> None:
         self.__pydantic_fields_set__.add("resourceType")

src/api/writer-generator/python/naming-utils.ts

@@ -146,10 +146,10 @@ export const pyTypeFromIdentifier = (id: TypeIdentifier): string => {
     return deriveResourceName(id);
 };
 
-/** `Literal[...]` type argument for a `Reference` field's targets, mirroring
- *  the TypeScript writer's `Reference<"Patient" | ...>`. Returns undefined
- *  when there are no targets or a target is a family type (e.g. `Resource`),
- *  where the bare `Reference` (defaulting to `str`) is the right annotation. */
+/** `Literal[...]` type argument naming a `Reference` field's permitted targets.
+ *  Returns undefined when there are no targets, or when one is a family type
+ *  (e.g. `Resource`) — a family admits any resource, so the bare `Reference`
+ *  (defaulting to `str`) is the honest annotation. */
 export const pyReferenceTypeParam = (
     field: RegularField | ChoiceFieldInstance,
     tsIndex: TypeSchemaIndex,
@@ -160,3 +160,18 @@ export const pyReferenceTypeParam = (
     const names = [...new Set(resolved.map((ref) => ref.name))];
     return `Literal[${names.map((n) => JSON.stringify(n)).join(", ")}]`;
 };
+
+/** The family a reference's targets were widened to, when they were.
+ *
+ *  A family target such as `Resource` leaves the annotation a bare `Reference`,
+ *  which on its own does not say whether the element is unconstrained by design
+ *  or whether something was lost. The name goes at end of line, since Python
+ *  cannot carry a comment inside an annotation. */
+export const pyReferenceFamilyName = (
+    field: RegularField | ChoiceFieldInstance,
+    tsIndex: TypeSchemaIndex,
+): string | undefined => {
+    if (!field.reference || field.reference.resource.length === 0) return undefined;
+    const resolved = field.reference.resource.map((ref) => tsIndex.findLastSpecializationByIdentifier(ref));
+    return resolved.find(tsIndex.isFamilyType)?.name;
+};

src/api/writer-generator/python/profile-slices.ts

@@ -21,7 +21,7 @@ export type SliceDef = {
     match: Record<string, unknown>;
     required: string[];
     array: boolean;
-    /** 0 = unbounded ("*"), mirrors TS SliceDef.max */
+    /** 0 = unbounded ("*"). */
     max: number;
     constrainedChoice: ConstrainedChoiceInfo | undefined;
     elementTypeName: string | undefined;
@@ -274,7 +274,7 @@ export const generateSliceSetters = (
             }
         } else {
             // Make input optional when there are no required fields (input can be empty / omitted),
-            // mirroring TS `inputOptional = sliceDef.required.length === 0`.
+            // A slice that requires nothing of its element accepts no input.
             const inputOptional = sliceDef.required.length === 0;
             const sig = inputOptional
                 ? `def set_${baseName}(self, value: dict[str, Any] | None = None) -> "${className}":`

src/api/writer-generator/python/profile-validation.ts

@@ -148,8 +148,6 @@ const collectRegularFieldValidation = (
  * satisfied by any one of its permitted typed variants — the choice base name
  * itself is not a FHIR element and can never be present on a conformant
  * resource, so it must never be emitted as a plain required field.
- *
- * Mirrors `collectSliceRequirements` in the TypeScript writer.
  */
 const collectSliceRequirements = (
     slice: FieldSlice,

src/api/writer-generator/python/writer.ts

@@ -23,7 +23,7 @@ import {
     type TypeIdentifier,
 } from "@typeschema/types.ts";
 import { resolveGeneratorAsset } from "../assets";
-import { pyReferenceTypeParam } from "./naming-utils";
+import { pyReferenceFamilyName, pyReferenceTypeParam } from "./naming-utils";
 import { collectProfileClassNames, generateNewProfiles } from "./profile";
 
 export const resolvePyAssets = (fn: string) => resolveGeneratorAsset(import.meta.url, "python", fn);
@@ -94,6 +94,8 @@ interface FieldInfo {
     name: string;
     type: string;
     defaultValue: string;
+    /** Trailing `# <Family>` when a family target widened the annotation away. */
+    comment?: string;
 }
 
 type TypeSchemaPackageGroups = {
@@ -302,8 +304,8 @@ export class Python extends Writer<PythonGeneratorOptions> {
     }
 
     /** Re-export a package's profile classes from its `__init__.py`, so they are
-     *  reachable as `<package>.<ProfileClass>` the way the TypeScript barrel makes
-     *  them. Explicit, so strict mypy (`no_implicit_reexport`) sees the names. */
+     *  reachable as `<package>.<ProfileClass>` and not only by module path.
+     *  Explicit, so strict mypy (`no_implicit_reexport`) sees the names. */
     private importPackageProfiles(profileNames: string[]): void {
         if (profileNames.length === 0) return;
         this.pyImportFrom(".profiles", ...profileNames);
@@ -533,7 +535,7 @@ export class Python extends Writer<PythonGeneratorOptions> {
             if ("choices" in field && field.choices) continue;
 
             const fieldInfo = this.buildFieldInfo(fieldName, field, schema);
-            this.line(`${fieldInfo.name}: ${fieldInfo.type}${fieldInfo.defaultValue}`);
+            this.line(`${fieldInfo.name}: ${fieldInfo.type}${fieldInfo.defaultValue}${fieldInfo.comment ?? ""}`);
 
             if (withExtensions && "type" in field && isPrimitiveIdentifier(field.type)) {
                 this.addPrimitiveExtensionField(fieldName, field.array ?? false);
@@ -567,11 +569,13 @@ export class Python extends Writer<PythonGeneratorOptions> {
         const pyFieldName = fixReservedWords(this.nameFormatFunction(fieldName));
         const fieldType = this.determineFieldType(field, fieldName, schema);
         const defaultValue = this.getFieldDefaultValue(field, fieldName);
+        const family = this.tsIndex && "reference" in field ? pyReferenceFamilyName(field, this.tsIndex) : undefined;
 
         return {
             name: pyFieldName,
             type: fieldType,
             defaultValue: defaultValue,
+            comment: family ? `  # ${family}` : undefined,
         };
     }
 

test/api/write-generator/python.test.ts

@@ -69,6 +69,22 @@ describe("Python Writer Generator", async () => {
         });
     });
 
+    describe("observation.py", () => {
+        const observationPy = files["generated/hl7_fhir_r4_core/observation.py"];
+        // A family target widens the annotation to a bare Reference; the name it
+        // was widened from is kept at end of line, since Python cannot comment
+        // inside an annotation.
+        it("names the family a reference was widened from", () => {
+            expect(observationPy).toContain(
+                'focus: PyList[Reference] | None = Field(None, alias="focus", serialization_alias="focus")  # Resource',
+            );
+        });
+        it("leaves a narrow reference without the comment", () => {
+            expect(observationPy).toContain("subject: Reference[Literal[");
+            expect(observationPy).not.toMatch(/subject: Reference\[Literal\[[^\n]*# \w/);
+        });
+    });
+
     describe("patient.py", () => {
         const patientPy = files["generated/hl7_fhir_r4_core/patient.py"];
         it("generates CodeableConcept fields with enum bindings", () => {