jsii-pacmak 1.113.0 → 1.115.0

package/lib/targets/python/requirements-dev.txt

@@ -4,9 +4,9 @@
 # package (wheel, sdist), but not declared as build-system dependencies.
 
 setuptools~=75.3.2 # build-system
-build~=1.2.2.post1 # build-system
+build~=1.3.0 # build-system
 
-twine~=6.1.0
+twine~=6.2.0
 
 # The dependency on packaging is necessary to work around an incompatibility between
 # what setuptools generates and what twine expects. <https://github.com/pypa/twine/issues/1216>

package/lib/targets/python/type-name.d.ts

@@ -1,4 +1,8 @@
 import { Assembly, OptionalValue, TypeReference, Type } from '@jsii/spec';
+import { CodeMaker } from 'codemaker';
+/**
+ * Actually more of a TypeNameFactory than a TypeName
+ */
 export interface TypeName {
     pythonType(context: NamingContext): string;
     requiredImports(context: NamingContext): PythonImports;
@@ -21,6 +25,8 @@ export interface NamingContext {
     readonly typeResolver: (fqn: string) => Type;
     /** The submodule of the assembly in which the PythonType is expressed (could be the module root) */
     readonly submodule: string;
+    /** Holds the set of intersection types used in the current module */
+    readonly intersectionTypes: IntersectionTypesRegistry;
     /**
      * The declaration is made in the context of a type annotation (so it can be quoted)
      *
@@ -70,4 +76,16 @@ export declare function toPythonFqn(fqn: string, rootAssm: Assembly): {
     packageName: string;
     pythonFqn: string;
 };
+/**
+ * Holds a set of intersection types used by the current set of modules
+ */
+export declare class IntersectionTypesRegistry {
+    private readonly types;
+    /**
+     * Return a unique name for a protocol that extends the given types
+     */
+    obtain(types: string[]): string;
+    get typeNames(): string[];
+    flushHelperTypes(code: CodeMaker): void;
+}
 //# sourceMappingURL=type-name.d.ts.map

package/lib/targets/python/type-name.js

@@ -10,8 +10,9 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
     if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
     return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
 };
-var _Dict_element, _List_element, _Optional_wrapped, _Primitive_pythonType, _Union_options, _UserType_fqn;
+var _Dict_element, _List_element, _Optional_wrapped, _Primitive_pythonType, _Union_options, _Intersection_types, _UserType_fqn;
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.IntersectionTypesRegistry = void 0;
 exports.toTypeName = toTypeName;
 exports.toPackageName = toPackageName;
 exports.mergePythonImports = mergePythonImports;
@@ -45,6 +46,13 @@ function toTypeName(ref) {
     else if ((0, spec_1.isNamedTypeReference)(type)) {
         result = new UserType(type.fqn);
     }
+    else if ((0, spec_1.isIntersectionTypeReference)(type)) {
+        const types = type.intersection.types.map(toTypeName);
+        if (types.some((t) => !(t instanceof UserType))) {
+            throw new Error('Only user types are supported in intersections');
+        }
+        result = new Intersection(types);
+    }
     return optional ? new Optional(result) : result;
 }
 /**
@@ -178,6 +186,23 @@ class Union {
     }
 }
 _Union_options = new WeakMap();
+class Intersection {
+    constructor(types) {
+        // eslint-disable-next-line @typescript-eslint/explicit-member-accessibility
+        _Intersection_types.set(this, void 0);
+        __classPrivateFieldSet(this, _Intersection_types, types, "f");
+    }
+    pythonType(context) {
+        // We will be generating a special type to represent the intersection
+        const name = context.intersectionTypes.obtain(__classPrivateFieldGet(this, _Intersection_types, "f").map((t) => t.pythonType(context)).map(stripQuotes));
+        // This will never be in scope already, so always render between quotes
+        return `'${name}'`;
+    }
+    requiredImports(context) {
+        return mergePythonImports(...__classPrivateFieldGet(this, _Intersection_types, "f").map((o) => o.requiredImports(context)));
+    }
+}
+_Intersection_types = new WeakMap();
 class UserType {
     constructor(fqn) {
         // eslint-disable-next-line @typescript-eslint/explicit-member-accessibility
@@ -346,4 +371,37 @@ function findParentSubmodule(type, assm) {
     }
     return namespaceFqn;
 }
+/**
+ * Holds a set of intersection types used by the current set of modules
+ */
+class IntersectionTypesRegistry {
+    constructor() {
+        this.types = new Map();
+    }
+    /**
+     * Return a unique name for a protocol that extends the given types
+     */
+    obtain(types) {
+        const derivedName = `_${types.map(lastComponent).join('_')}`;
+        this.types.set(derivedName, types);
+        return derivedName;
+    }
+    get typeNames() {
+        return Array.from(this.types.keys());
+    }
+    flushHelperTypes(code) {
+        for (const [name, types] of this.types.entries()) {
+            code.line('');
+            code.line(`class ${name}(${types.join(', ')}, typing_extensions.Protocol):`);
+            code.line('    pass');
+        }
+    }
+}
+exports.IntersectionTypesRegistry = IntersectionTypesRegistry;
+function lastComponent(x) {
+    return x.split('.').slice(-1)[0];
+}
+function stripQuotes(x) {
+    return x.replace(/^"|"$/g, '');
+}
 //# sourceMappingURL=type-name.js.map

package/lib/targets/python.d.ts

@@ -40,13 +40,14 @@ type FindModuleCallback = (fqn: string) => spec.AssemblyConfiguration;
 type FindTypeCallback = (fqn: string) => spec.Type;
 declare class TypeResolver {
     private readonly types;
+    private readonly assembly;
     private readonly boundTo?;
     private readonly boundRe;
     private readonly moduleName?;
     private readonly moduleRe;
     private readonly findModule;
     private readonly findType;
-    constructor(types: Map<string, PythonType>, findModule: FindModuleCallback, findType: FindTypeCallback, boundTo?: string, moduleName?: string);
+    constructor(types: Map<string, PythonType>, assembly: spec.Assembly, findModule: FindModuleCallback, findType: FindTypeCallback, boundTo?: string, moduleName?: string);
     bind(fqn: string, moduleName?: string): TypeResolver;
     isInModule(typeRef: spec.NamedTypeReference | string): boolean;
     isInNamespace(typeRef: spec.NamedTypeReference | string): boolean;

package/lib/targets/python.js

@@ -30,6 +30,7 @@ const _utils_1 = require("./_utils");
 const type_name_1 = require("./python/type-name");
 const util_2 = require("./python/util");
 const version_utils_1 = require("./version-utils");
+const rosetta_assembly_1 = require("../rosetta-assembly");
 const index_1 = require("./index");
 // eslint-disable-next-line @typescript-eslint/no-var-requires,@typescript-eslint/no-require-imports
 const spdxLicenseList = require('spdx-license-list');
@@ -54,7 +55,7 @@ class Python extends target_1.Target {
         // shim, but using this actually results in a WinError with Python 3.7 and 3.8 where venv will
         // fail to copy the python binary if it's not invoked as python.exe). More on this particular
         // issue can be read here: https://bugs.python.org/issue43749
-        await (0, util_1.shell)(process.platform === 'win32' ? 'python' : 'python3', [
+        await (0, util_1.subprocess)(process.platform === 'win32' ? 'python' : 'python3', [
             '-m',
             'venv',
             '--system-site-packages', // Allow using globally installed packages (saves time & disk space)
@@ -67,18 +68,18 @@ class Python extends target_1.Target {
         };
         const python = path.join(venvBin, 'python');
         // Install the necessary things
-        await (0, util_1.shell)(python, ['-m', 'pip', 'install', '--no-input', '-r', requirementsFile], {
+        await (0, util_1.subprocess)(python, ['-m', 'pip', 'install', '--no-input', '-r', requirementsFile], {
             cwd: sourceDir,
             env,
             retry: { maxAttempts: 5 },
         });
         // Actually package up our code, both as a sdist and a wheel for publishing.
-        await (0, util_1.shell)(python, ['-m', 'build', '--outdir', outDir, sourceDir], {
+        await (0, util_1.subprocess)(python, ['-m', 'build', '--outdir', outDir, sourceDir], {
             cwd: sourceDir,
             env,
             retry: { maxAttempts: 5 },
         });
-        await (0, util_1.shell)(python, ['-m', 'twine', 'check', path.join(outDir, '*')], {
+        await (0, util_1.shell)(`${python} -m twine check ${path.join(outDir, '*')}`, {
             cwd: sourceDir,
             env,
         });
@@ -404,17 +405,18 @@ class BaseMethod {
                 liftedPropNames.add(toPythonParameterName(prop.name));
             }
         }
+        const typeFacs = this.parameters.map(type_name_1.toTypeName);
         // We need to turn a list of JSII parameters, into Python style arguments with
         // gradual typing, so we'll have to iterate over the list of parameters, and
         // build the list, converting as we go.
         const pythonParams = [];
-        for (const param of this.parameters) {
+        for (const [param, typeFac] of (0, util_1.zip)(this.parameters, typeFacs)) {
             // We cannot (currently?) blindly use the names given to us by the JSII for
             // initializers, because our keyword lifting will allow two names to clash.
             // This can hopefully be removed once we get https://github.com/aws/jsii/issues/288
             // resolved.
             const paramName = toPythonParameterName(param.name, liftedPropNames);
-            const paramType = (0, type_name_1.toTypeName)(param).pythonType({
+            const paramType = typeFac.pythonType({
                 ...context,
                 parameterType: true,
             });
@@ -1161,6 +1163,7 @@ class PythonModule {
         context = {
             ...context,
             submodule: this.fqn ?? context.submodule,
+            intersectionTypes: new type_name_1.IntersectionTypesRegistry(),
             resolver,
         };
         // Before we write anything else, we need to write out our module headers, this
@@ -1288,6 +1291,15 @@ class PythonModule {
                 code.line(`from . import ${submodule}`);
             }
         }
+        context.typeCheckingHelper.flushStubs(code);
+        context.intersectionTypes.flushHelperTypes(code);
+        const interfaces = this.members
+            .filter((m) => m instanceof Interface)
+            .map((m) => m.pythonName);
+        this.emitProtocolStripper(code, [
+            ...interfaces,
+            ...context.intersectionTypes.typeNames,
+        ]);
     }
     /**
      * Emit the bin scripts if bin section defined.
@@ -1329,6 +1341,32 @@ class PythonModule {
         }
         return scripts;
     }
+    /**
+     * Emit a helper that will strip magic jsii elements from all protocol classes
+     *
+     * This is necessary because we attach the `__jsii_proxy_class__` and
+     * `__jsii_type__` fields to Protocols/interfaces, which are then going to
+     * show up when someone calls `typing.get_protocol_members()`, and interfere
+     * with run-time type checking done by `typeguard`.
+     *
+     * `typing.get_protocol_members(x)` reads cached members from
+     * `x.__protocol_attrs__` (put there by the `Protocol` metaclass),  so what we
+     * do is remove our magic members from that cached set.
+     *
+     * This is extremely hacky, and in a hypothetical future rewrite we should
+     * store our metadata off-object (for example in a dict or `WeakKeyDictionary`),
+     * so that our magic members don't interfere with built-in Python functions.
+     * But for now we fiddle with the metadata to hide our magic members wherever
+     * necessary.
+     */
+    emitProtocolStripper(code, protocolNames) {
+        if (protocolNames.length === 0) {
+            return;
+        }
+        code.line('');
+        code.line(`for cls in [${protocolNames.join(', ')}]:`);
+        code.line(`    typing.cast(typing.Any, cls).__protocol_attrs__ = typing.cast(typing.Any, cls).__protocol_attrs__ - set(['__jsii_proxy_class__', '__jsii_type__'])`);
+    }
     isDirectChild(pyMod) {
         if (this.pythonName === pyMod.pythonName ||
             !pyMod.pythonName.startsWith(`${this.pythonName}.`)) {
@@ -1438,7 +1476,6 @@ class Package {
             const filename = path.join('src', pythonModuleNameToFilename(mod.pythonName), '__init__.py');
             code.openFile(filename);
             mod.emit(code, context);
-            context.typeCheckingHelper.flushStubs(code);
             code.closeFile(filename);
             scripts.push(...mod.emitBinScripts(code));
         }
@@ -1606,8 +1643,9 @@ class Package {
     }
 }
 class TypeResolver {
-    constructor(types, findModule, findType, boundTo, moduleName) {
+    constructor(types, assembly, findModule, findType, boundTo, moduleName) {
         this.types = types;
+        this.assembly = assembly;
         this.findModule = findModule;
         this.findType = findType;
         this.moduleName = moduleName;
@@ -1620,7 +1658,7 @@ class TypeResolver {
         }
     }
     bind(fqn, moduleName) {
-        return new TypeResolver(this.types, this.findModule, this.findType, fqn, moduleName !== undefined
+        return new TypeResolver(this.types, this.assembly, this.findModule, this.findType, fqn, moduleName !== undefined
             ? moduleName.startsWith('.')
                 ? `${this.moduleName}${moduleName}`
                 : moduleName
@@ -1678,14 +1716,8 @@ class TypeResolver {
         return this.findType(typeRef);
     }
     toPythonFQN(fqn) {
-        const [assemblyName, ...qualifiedIdentifiers] = fqn.split('.');
-        const fqnParts = [
-            this.findModule(assemblyName).targets.python.module,
-        ];
-        for (const part of qualifiedIdentifiers) {
-            fqnParts.push((0, util_2.toPythonIdentifier)(part));
-        }
-        return fqnParts.join('.');
+        const { pythonFqn } = (0, type_name_1.toPythonFqn)(fqn, this.assembly);
+        return pythonFqn;
     }
 }
 class PythonGenerator extends generator_1.Generator {
@@ -1801,10 +1833,12 @@ class PythonGenerator extends generator_1.Generator {
         }
     }
     convertExample(example, apiLoc) {
+        (0, rosetta_assembly_1.assertSpecIsRosettaCompatible)(this.assembly);
         const translated = this.rosetta.translateExample(apiLoc, example, jsii_rosetta_1.TargetLanguage.PYTHON, (0, jsii_rosetta_1.enforcesStrictMode)(this.assembly));
         return translated.source;
     }
     convertMarkdown(markdown, apiLoc) {
+        (0, rosetta_assembly_1.assertSpecIsRosettaCompatible)(this.assembly);
         return this.rosetta.translateSnippetsInMarkdown(apiLoc, markdown, jsii_rosetta_1.TargetLanguage.PYTHON, (0, jsii_rosetta_1.enforcesStrictMode)(this.assembly));
     }
     getPythonType(fqn) {
@@ -1830,7 +1864,7 @@ class PythonGenerator extends generator_1.Generator {
         this.package.addData(assemblyModule, this.getAssemblyFileName(), undefined);
     }
     onEndAssembly(assm, _fingerprint) {
-        const resolver = new TypeResolver(this.types, (fqn) => this.findModule(fqn), (fqn) => this.findType(fqn));
+        const resolver = new TypeResolver(this.types, assm, (fqn) => this.findModule(fqn), (fqn) => this.findType(fqn));
         this.package.write(this.code, {
             assembly: assm,
             emittedTypes: new Set(),
@@ -1839,6 +1873,7 @@ class PythonGenerator extends generator_1.Generator {
             submodule: assm.name,
             typeCheckingHelper: new TypeCheckingHelper(),
             typeResolver: (fqn) => resolver.dereference(fqn),
+            intersectionTypes: new type_name_1.IntersectionTypesRegistry(),
         });
     }
     /**

package/lib/targets/type-literals.d.ts

@@ -0,0 +1,22 @@
+import * as spec from '@jsii/spec';
+/**
+ * Make a type reference that references exactly a literal.
+ *
+ * This is useful if we don't want to reference a real type but a locally bound
+ * type parameter.
+ *
+ * This is a slightly hacky way to get the rendering functio to render a
+ * literal string, without looking it up. It gets us to embed the notion of
+ * rendering literal type parameters in the existing jsii spec without having to
+ * explicitly model it only for the purpose of a couple of code generators.
+ */
+export declare function makeLiteralTypeReference(typeParameterName: string): spec.NamedTypeReference;
+/**
+ * Return the type parameter name if the type reference is a type literal
+ */
+export declare function literalTypeReference(x: spec.TypeReference): string | undefined;
+/**
+ * Whether the given type is a literal type reference
+ */
+export declare function isLiteralTypeReference(x: spec.TypeReference): boolean;
+//# sourceMappingURL=type-literals.d.ts.map

package/lib/targets/type-literals.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.makeLiteralTypeReference = makeLiteralTypeReference;
+exports.literalTypeReference = literalTypeReference;
+exports.isLiteralTypeReference = isLiteralTypeReference;
+const spec = require("@jsii/spec");
+const LITERAL_TYPE_PREFIX = '$lit:';
+/**
+ * Make a type reference that references exactly a literal.
+ *
+ * This is useful if we don't want to reference a real type but a locally bound
+ * type parameter.
+ *
+ * This is a slightly hacky way to get the rendering functio to render a
+ * literal string, without looking it up. It gets us to embed the notion of
+ * rendering literal type parameters in the existing jsii spec without having to
+ * explicitly model it only for the purpose of a couple of code generators.
+ */
+function makeLiteralTypeReference(typeParameterName) {
+    return { fqn: `${LITERAL_TYPE_PREFIX}${typeParameterName}` };
+}
+/**
+ * Return the type parameter name if the type reference is a type literal
+ */
+function literalTypeReference(x) {
+    if (!spec.isNamedTypeReference(x)) {
+        return undefined;
+    }
+    return x.fqn.startsWith(LITERAL_TYPE_PREFIX)
+        ? x.fqn.slice(LITERAL_TYPE_PREFIX.length)
+        : undefined;
+}
+/**
+ * Whether the given type is a literal type reference
+ */
+function isLiteralTypeReference(x) {
+    return literalTypeReference(x) !== undefined;
+}
+//# sourceMappingURL=type-literals.js.map

package/lib/type-utils.d.ts

@@ -0,0 +1,3 @@
+import * as spec from '@jsii/spec';
+export declare function containsUnionType(typeRef: spec.TypeReference): typeRef is spec.UnionTypeReference | spec.CollectionTypeReference;
+//# sourceMappingURL=type-utils.d.ts.map

package/lib/type-utils.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.containsUnionType = containsUnionType;
+const spec = require("@jsii/spec");
+function containsUnionType(typeRef) {
+    return (spec.isUnionTypeReference(typeRef) ||
+        (spec.isCollectionTypeReference(typeRef) &&
+            containsUnionType(typeRef.collection.elementtype)));
+}
+//# sourceMappingURL=type-utils.js.map

package/lib/type-visitor.d.ts

@@ -0,0 +1,19 @@
+import * as spec from '@jsii/spec';
+export interface TypeReferenceVisitor<A = void> {
+    named(ref: spec.NamedTypeReference): A;
+    primitive(ref: spec.PrimitiveTypeReference): A;
+    collection(ref: spec.CollectionTypeReference): A;
+    union(ref: spec.UnionTypeReference): A;
+    intersection(ref: spec.IntersectionTypeReference): A;
+}
+export declare function visitTypeReference<A>(typeRef: spec.TypeReference, visitor: TypeReferenceVisitor<A>): A;
+export interface TypeVisitor<A = void> {
+    classType(t: spec.ClassType): A;
+    interfaceType(t: spec.InterfaceType): A;
+    dataType(t: spec.InterfaceType): A;
+    enumType(t: spec.EnumType): A;
+}
+export declare function visitType<A>(t: spec.Type, visitor: TypeVisitor<A>): A;
+export declare function isDataType(t: spec.Type): t is spec.InterfaceType;
+export declare function isBehavioralInterfaceType(t: spec.Type): t is spec.InterfaceType;
+//# sourceMappingURL=type-visitor.d.ts.map

package/lib/type-visitor.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.visitTypeReference = visitTypeReference;
+exports.visitType = visitType;
+exports.isDataType = isDataType;
+exports.isBehavioralInterfaceType = isBehavioralInterfaceType;
+const spec = require("@jsii/spec");
+function visitTypeReference(typeRef, visitor) {
+    if (spec.isNamedTypeReference(typeRef)) {
+        return visitor.named(typeRef);
+    }
+    else if (spec.isPrimitiveTypeReference(typeRef)) {
+        return visitor.primitive(typeRef);
+    }
+    else if (spec.isCollectionTypeReference(typeRef)) {
+        return visitor.collection(typeRef);
+    }
+    else if (spec.isUnionTypeReference(typeRef)) {
+        return visitor.union(typeRef);
+    }
+    else if (spec.isIntersectionTypeReference(typeRef)) {
+        return visitor.intersection(typeRef);
+    }
+    throw new Error(`Unknown type reference: ${JSON.stringify(typeRef)}`);
+}
+function visitType(t, visitor) {
+    if (spec.isClassType(t)) {
+        return visitor.classType(t);
+    }
+    else if (spec.isInterfaceType(t) && t.datatype) {
+        return visitor.dataType(t);
+    }
+    else if (spec.isInterfaceType(t)) {
+        return visitor.interfaceType(t);
+    }
+    else if (spec.isEnumType(t)) {
+        return visitor.enumType(t);
+    }
+    throw new Error(`Unknown type: ${JSON.stringify(t)}`);
+}
+function isDataType(t) {
+    return spec.isInterfaceType(t) && !!t.datatype;
+}
+function isBehavioralInterfaceType(t) {
+    return spec.isInterfaceType(t) && !t.datatype;
+}
+//# sourceMappingURL=type-visitor.js.map

package/lib/util.d.ts

@@ -62,7 +62,7 @@ export interface RetryOptions {
      *                            be awaited before making the next attempt (if
      *                            there are attempts left)
      */
-    onFailedAttempt?: (error: unknown, attemptsLeft: number, backoffMilliseconds: number) => void;
+    onFailedAttempt?: (error: Error, attemptsLeft: number, backoffMilliseconds: number) => void;
 }
 export declare class AllAttemptsFailed<R> extends Error {
     readonly callback: () => Promise<R>;
@@ -87,16 +87,28 @@ export interface ShellOptions extends Omit<SpawnOptions, 'shell' | 'stdio'> {
     readonly retry?: RetryOptions;
 }
 /**
- * Spawns a child process with the provided command and arguments. The child
- * process is always spawned using `shell: true`, and the contents of
+ * Spawns a shell with the provided commandline.
+ *
+ * The child process is always spawned using `shell: true`, and the contents of
  * `process.env` is used as the initial value of the `env` spawn option (values
  * provided in `options.env` can override those).
+ */
+export declare function shell(commandLine: string, options?: ShellOptions): Promise<string>;
+/**
+ * Spawns a subprocess with the provided command and arguments.
+ *
+ * The child process is always spawned using `shell: false`, and the contents of
+ * `process.env` is used as the initial value of the `env` spawn option (values
+ * provided in `options.env` can override those).
+ *
+ * To make this work on Windows, if the binary happens to resolve to a batch file
+ * we run it through cmd.exe.
  *
- * @param cmd     the command to shell out to.
+ * @param binary     the command to shell out to.
  * @param args    the arguments to provide to `cmd`
  * @param options any options to pass to `spawn`
  */
-export declare function shell(cmd: string, args: string[], { retry: retryOptions, ...options }?: ShellOptions): Promise<string>;
+export declare function subprocess(binary: string, args: string[], options?: ShellOptions): Promise<string>;
 /**
  * Strip filesystem unsafe characters from a string
  */
@@ -119,4 +131,5 @@ export declare function setExtend<A>(xs: Set<A>, els: Iterable<A>): void;
 export declare function filterAsync<A>(xs: A[], pred: (x: A) => Promise<boolean>): Promise<A[]>;
 export declare function wait(ms: number): Promise<void>;
 export declare function flatten<A>(xs: readonly A[][]): A[];
+export declare function zip<A, B>(xs: A[], ys: B[]): Array<[A, B]>;
 //# sourceMappingURL=util.d.ts.map