fix: sibling module dependencies are eagerly loaded even if only for type annotations (aws#5172)

## Problem

Every generated `init.py` file has import statements at the top that look like this, for example

```
from .aws_iam import IGrantable as _IGrantable_ef567890
from .aws_kms import IKey as _IKey_abc12345
...
```

and cross-module imports that could look like this. for example
```
import scope.jsii_calc_base
...
```

These load immediately whenever each module loads, which in turn load their own dependencies. This causes a huge cascade of imports at module load time. A large chunk of these imports only exist to satisfy type annotations however, or runtime type checks, and therefore this creates a need for optimization. 

## Solution

Cross-module imports are now deferred using a `typing.TYPE_CHECKING` split plus a lazy import proxy. Instead of importing each symbol eagerly, the generator emits:

```python
class _LazyImport:
    def __init__(self, module_name: str) -> None:
        self._module_name = module_name
        self._module: typing.Any = None
    def __getattr__(self, name: str) -> typing.Any:
        if self._module is None:
            import importlib
            self._module = importlib.import_module(self._module_name)
        return getattr(self._module, name)

if typing.TYPE_CHECKING:
    import jsii_calc.composition as _composition_4f38e801
    import scope.jsii_calc_lib as _scope_jsii_calc_lib_c61f082f
else:
    _composition_4f38e801 = _LazyImport("jsii_calc.composition")
    _scope_jsii_calc_lib_c61f082f = _LazyImport("scope.jsii_calc_lib")
```

mypy and pyright evaluate the if statement, so they see the real module imports and resolve all types normally. At runtime, the `else:` branch executes instead, binding each module alias to a `_LazyImport` proxy. The actual `importlib.import_module()` call is deferred until the first attribute access through the proxy's `__getattr__`.

---

By submitting this pull request, I confirm that my contribution is made under the terms of the [Apache 2.0 license].

[Apache 2.0 license]: https://www.apache.org/licenses/LICENSE-2.0

Author: dgandhi62

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

@@ -25,6 +25,7 @@ import {
   toTypeName,
   PythonImports,
   mergePythonImports,
+  hasImports,
   toPackageName,
   toPythonFqn,
   IntersectionTypesRegistry,
@@ -1777,6 +1778,15 @@ class PythonModule implements PythonType {
     // Before we write anything else, we need to write out our module headers, this
     // is where we handle stuff like imports, any required initialization, etc.
 
+    // Emit PEP 563 (from __future__ import annotations) if this module has
+    // cross-module imports. This makes all annotations strings at definition
+    // time, preventing lazy proxy resolution during module load.
+    // Must be the first statement in the file (after docstring) per Python rules.
+    if (hasImports(this.requiredImports(context))) {
+      code.line('from __future__ import annotations');
+      code.line();
+    }
+
     // If multiple packages use the same namespace (in Python, a directory) it
     // depends on how they are laid out on disk if deep imports of multiple packages
     // will succeed. `pip` merges all packages into the same directory, and deep
@@ -2113,6 +2123,67 @@ class PythonModule implements PythonType {
     }
   }
 
+  /**
+   * Emit the `_LazyImport` helper class that defers `importlib.import_module()`
+   * until first attribute access via `__getattr__`.
+   *
+   * The class is emitted once per module that has cross-module imports. It wraps
+   * a module name string and caches the imported module after first access.
+   * Failed imports are NOT cached, allowing retry on subsequent access.
+   */
+  private emitLazyImportClass(code: CodeMaker) {
+    code.line();
+    code.openBlock('class _LazyImport');
+    // __init__
+    code.openBlock('def __init__(self, module_name: str) -> None');
+    code.line('self._module_name = module_name');
+    code.line('self._module: typing.Any = None');
+    code.closeBlock();
+    // __getattr__
+    code.openBlock('def __getattr__(self, name: str) -> typing.Any');
+    code.openBlock('if self._module is None');
+    code.line('import importlib');
+    code.line('self._module = importlib.import_module(self._module_name)');
+    code.closeBlock();
+    code.line('return getattr(self._module, name)');
+    code.closeBlock();
+    code.closeBlock();
+  }
+
+  /**
+   * Emit `_LazyImport(...)` assignments for all cross-module imports.
+   *
+   * Only processes entries where the items set contains '' (empty string),
+   * indicating a full module import. Parses the sourcePackage string which
+   * has the format "module.name as _alias" to extract the module name and alias.
+   * Sorts assignments by alias for deterministic output.
+   */
+  private emitLazyProxyAssignments(code: CodeMaker, imports: PythonImports) {
+    const assignments = Object.entries(imports)
+      .filter(([, items]) => items.has('')) // Only full module imports (empty string = import the whole module)
+      .map(([sourcePackage]) => {
+        // sourcePackage is like "aws_cdk.aws_iam as _aws_cdk_aws_iam_abcd1234"
+        const match = sourcePackage.match(/^(.+)\s+as\s+(.+)$/);
+        if (match) {
+          const [, moduleName, alias] = match;
+          return { moduleName, alias };
+        }
+        // Fallback: no alias
+        return {
+          moduleName: sourcePackage,
+          alias: `_${sourcePackage.replace(/\./g, '_')}`,
+        };
+      })
+      .sort((a, b) => a.alias.localeCompare(b.alias));
+
+    if (assignments.length > 0) {
+      code.line();
+      for (const { moduleName, alias } of assignments) {
+        code.line(`${alias} = _LazyImport("${moduleName}")`);
+      }
+    }
+  }
+
   /**
    * Emit a mapping from submodule FQNs to their Python module paths.
    *
@@ -2142,8 +2213,28 @@ class PythonModule implements PythonType {
   }
 
   private emitRequiredImports(code: CodeMaker, context: EmitContext) {
-    const requiredImports = this.requiredImports(context);
-    const statements = Object.entries(requiredImports)
+    const allImports = this.requiredImports(context);
+    if (!hasImports(allImports)) {
+      return;
+    }
+
+    // Emit _LazyImport class definition
+    this.emitLazyImportClass(code);
+
+    // Emit TYPE_CHECKING block with original import statements for static type checkers,
+    // and lazy proxy assignments in the else branch for runtime.
+    // This structure ensures pyright/mypy see the real module types while runtime uses lazy proxies.
+    code.line();
+    code.openBlock('if typing.TYPE_CHECKING');
+    this.emitImportStatements(code, allImports);
+    code.closeBlock();
+    code.openBlock('else');
+    this.emitLazyProxyAssignments(code, allImports);
+    code.closeBlock();
+  }
+
+  private emitImportStatements(code: CodeMaker, imports: PythonImports) {
+    const statements = Object.entries(imports)
       .map(([sourcePackage, items]) => toImportStatements(sourcePackage, items))
       .reduce(
         (acc, elt) => [...acc, ...elt],

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

@@ -152,6 +152,13 @@ export function mergePythonImports(
   return result;
 }
 
+/**
+ * Check if a PythonImports object has any entries.
+ */
+export function hasImports(imports: PythonImports): boolean {
+  return Object.keys(imports).length > 0;
+}
+
 function isOptionalValue(
   type: OptionalValue | TypeReference,
 ): type is OptionalValue {
@@ -398,20 +405,18 @@ class UserType implements TypeName {
         .split('.');
       const aliasSuffix = createHash('sha256')
         .update(typeSubmodulePythonName)
-        .update('.')
-        .update(toImport)
+        .update('.*')
         .digest('hex')
         .substring(0, 8);
-      const alias = `_${toImport}_${aliasSuffix}`;
+      const moduleAlias = `_${lastComponent(typeSubmodulePythonName)}_${aliasSuffix}`;
 
       return {
-        pythonType: wrapType([alias, ...nested].join('.')),
+        pythonType: wrapType(
+          `${moduleAlias}.${toImport}${nested.length > 0 ? `.${nested.join('.')}` : ''}`,
+        ),
         requiredImport: {
-          sourcePackage: relativeImportPath(
-            submodulePythonName,
-            typeSubmodulePythonName,
-          ),
-          item: `${toImport} as ${alias}`,
+          sourcePackage: `${typeSubmodulePythonName} as ${moduleAlias}`,
+          item: '',
         },
       };
 
@@ -488,7 +493,7 @@ export function toPythonFqn(fqn: string, rootAssm: Assembly) {
  *  relativeImportPath('A.B.C', 'A.B')     === '..';
  *  relativeImportPath('A.B', 'A.B.C')     === '.C';
  */
-function relativeImportPath(fromPkg: string, toPkg: string): string {
+export function relativeImportPath(fromPkg: string, toPkg: string): string {
   if (toPkg.startsWith(fromPkg)) {
     // from A.B to A.B.C === .C
     return `.${toPkg.substring(fromPkg.length + 1)}`;