feat(python): formally allow dicts to be passed in lieu of structs

Formalize the contract that it is allowed to pass a dict in places where
a struct instance is expected (this provides less type checking guarantees,
and the developer is responsible for passing the right keys in).

This should address a false-positive issue with the runtime type-checking
introduced in 1.63.0 (#3660).

Author: RomainMuller

packages/jsii-pacmak/lib/targets/python.ts

@@ -2530,6 +2530,7 @@ class PythonGenerator extends Generator {
       emittedTypes: new Set(),
       resolver,
       submodule: assm.name,
+      typeResolver: (fqn) => resolver.dereference(fqn),
     });
   }
 

packages/jsii-pacmak/lib/targets/python/type-name.ts

@@ -10,6 +10,7 @@ import {
   PrimitiveTypeReference,
   isUnionTypeReference,
   Type,
+  isInterfaceType,
 } from '@jsii/spec';
 import { toSnakeCase } from 'codemaker';
 import { createHash } from 'crypto';
@@ -37,6 +38,9 @@ export interface NamingContext {
   /** The assembly in which the PythonType is expressed. */
   readonly assembly: Assembly;
 
+  /** A resolver to obtain complete information about a type. */
+  readonly typeResolver: (fqn: string) => Type;
+
   /** The submodule of the assembly in which the PythonType is expressed (could be the module root) */
   readonly submodule: string;
 
@@ -293,14 +297,27 @@ class UserType implements TypeName {
     submodule,
     surroundingTypeFqns,
     typeAnnotation = true,
+    parameterType,
+    typeResolver,
   }: NamingContext) {
     const { assemblyName, packageName, pythonFqn } = toPythonFqn(
       this.#fqn,
       assembly,
     );
+
+    // If this is a type annotation for a parameter, allow dicts to be passed where structs are expected.
+    const type = typeResolver(this.#fqn);
+    const isStruct = isInterfaceType(type) && !!type.datatype;
+    const wrapType =
+      typeAnnotation && parameterType && isStruct
+        ? (pyType: string) =>
+            `typing.Union[${pyType}, typing.Dict[str, typing.Any]]`
+        : (pyType: string) => pyType;
+
     if (assemblyName !== assembly.name) {
       return {
-        pythonType: pythonFqn,
+        // If it's a struct, then we allow passing as a dict, too...
+        pythonType: wrapType(pythonFqn),
         requiredImport: {
           sourcePackage: packageName,
           item: '',
@@ -330,8 +347,8 @@ class UserType implements TypeName {
       ) {
         // Possibly a forward reference, outputting the stringifierd python FQN
         return {
-          pythonType: JSON.stringify(
-            pythonFqn.substring(submodulePythonName.length + 1),
+          pythonType: wrapType(
+            JSON.stringify(pythonFqn.substring(submodulePythonName.length + 1)),
           ),
         };
       }
@@ -345,7 +362,9 @@ class UserType implements TypeName {
 
       // We'll just make a module-qualified reference at this point.
       return {
-        pythonType: pythonFqn.substring(submodulePythonName.length + 1),
+        pythonType: wrapType(
+          pythonFqn.substring(submodulePythonName.length + 1),
+        ),
       };
     }
 

packages/jsii-pacmak/test/generated-code/__snapshots__/target-python.test.js.snap

@@ -4,6 +4,8 @@ import {
   NamedTypeReference,
   PrimitiveType,
   SchemaVersion,
+  Type,
+  TypeKind,
   TypeReference,
 } from '@jsii/spec';
 
@@ -57,6 +59,11 @@ const assembly: Assembly = {
       fqn: `@foo/bar.other.${OTHER_SUBMODULE_TYPE}`,
       namespace: 'other',
     },
+    [`@foo/bar.Struct`]: {
+      datatype: true,
+      fqn: `@foo/bar.Struct`,
+      kind: TypeKind.Interface,
+    },
   },
 } as any;
 
@@ -78,6 +85,15 @@ describe(toTypeName, () => {
     readonly inSubmodule?: string;
     /** The nesting context in which to generate names (if not provided, none) */
     readonly inNestingContext?: readonly string[];
+    /** Additional context keys to register */
+    readonly context?: Omit<
+      NamingContext,
+      | 'assembly'
+      | 'emittedTypes'
+      | 'surroundingTypeFqns'
+      | 'submodule'
+      | 'typeResolver'
+    >;
   };
 
   const examples: readonly Example[] = [
@@ -221,14 +237,30 @@ describe(toTypeName, () => {
       },
       inSubmodule: `${assembly.name}.submodule`,
     },
+    // ############################# SPECIAL CASES##############################
+    {
+      name: 'Struct parameter type annotation',
+      input: { fqn: `${assembly.name}.Struct` },
+      forwardPythonType: `typing.Union["Struct", typing.Dict[str, typing.Any]]`,
+      pythonType: `typing.Union[Struct, typing.Dict[str, typing.Any]]`,
+      context: {
+        typeAnnotation: true,
+        parameterType: true,
+      },
+    },
   ];
 
   for (const example of examples) {
     const context: NamingContext = {
+      ...example.context,
       assembly,
       emittedTypes: new Set(),
       surroundingTypeFqns: example.inNestingContext,
       submodule: example.inSubmodule ?? assembly.name,
+      typeResolver: (fqn) => {
+        const type = assembly.types?.[fqn];
+        return type ?? ({ fqn } as any as Type);
+      },
     };
     const contextWithEmittedType: NamingContext = {
       ...context,