{"id":1250,"library":"jsii","title":"jsii Python Client","description":"jsii is an open-source framework developed by AWS that enables code in any language (such as Python, Java, C#, and Go) to naturally interact with JavaScript classes authored in TypeScript. It is a core technology behind the AWS Cloud Development Kit (CDK), allowing polyglot libraries to be delivered from a single TypeScript codebase. The project is actively maintained by AWS, with frequent updates to the compiler, pacmak (bindings generator), and runtime libraries.","status":"active","version":"1.127.0","language":"python","source_language":"en","source_url":"https://github.com/aws/jsii.git","tags":["aws","typescript","code-generation","interoperability","cdk","runtime"],"install":[{"cmd":"pip install jsii","lang":"bash","label":"Install jsii runtime"}],"dependencies":[{"reason":"Used by authors to generate language bindings from jsii assemblies. It has a peer dependency on jsii-rosetta.","package":"jsii-pacmak","optional":true},{"reason":"Peer dependency of jsii-pacmak for sample code transliteration.","package":"jsii-rosetta"}],"imports":[{"note":"The 'jsii' package itself is typically imported for decorators like @jsii.implements when authoring extensions to jsii-generated types. Application code consuming jsii-generated libraries imports directly from those libraries (e.g., 'from my_jsii_lib import MyClass').","symbol":"jsii","correct":"import jsii"},{"note":"Used as a decorator (@jsii.implements) to explicitly declare Python classes implementing jsii interfaces, avoiding metaclass conflicts.","symbol":"implements","correct":"from jsii import implements"}],"quickstart":{"code":"import os\nfrom some_jsii_generated_lib import HelloJsii\n\n# NOTE: In a real scenario, 'some_jsii_generated_lib' would be a library\n# generated by jsii (e.g., AWS CDK, or your own jsii module) which has\n# 'jsii' as a dependency. The 'HelloJsii' class would be defined in TypeScript.\n\n# Example of using a class from a jsii-generated Python library\ntry:\n    # Assuming HelloJsii class and say_hello method are available\n    # This code is illustrative; replace with actual generated lib usage.\n    hello_instance = HelloJsii()\n    message = hello_instance.say_hello(\"World\")\n    print(message)\nexcept ImportError:\n    print(\"To run this, you need a jsii-generated library installed.\")\n    print(\"For example, 'pip install aws-cdk.core' and then use CDK classes.\")\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")","lang":"python","description":"The `jsii` library itself provides the runtime for generated modules. Python developers primarily interact with packages that have been *generated* by jsii (e.g., AWS CDK constructs). These generated packages depend on `jsii`. The example above illustrates how you would typically use a class from such a generated library."},"warnings":[{"fix":"Ensure your Python environment is version 3.8 or higher. For best compatibility, use Python 3.11+.","message":"The `jsii-pacmak` tool and the Python libraries it generates now require a minimum Python version of 3.8. Previously, this was Python 3.7. It is recommended to upgrade to Python 3.11 or later.","severity":"breaking","affected_versions":"jsii-pacmak >= 1.86.0 (approx)"},{"fix":"Upgrade your Node.js installation to version 18 or higher. For best compatibility, use Node.js 20+.","message":"All `jsii` libraries and tools now require a minimum version of Node.js 18. This was previously Node.js 16. It is recommended to upgrade to Node.js 20 or later, as `jsii` modules rely on an embedded JavaScript VM.","severity":"breaking","affected_versions":"jsii >= 1.127.0 (and related tools)"},{"fix":"Use the `@jsii.implements(IJsiiInterface)` decorator to explicitly declare interface implementation. For example: `import jsii; @jsii.implements(IJsiiInterface) class MyNewClass():`","message":"When implementing interfaces defined by `jsii` modules in Python, traditional multiple inheritance (e.g., `class MyNewClass(IJsiiInterface):`) will likely cause a metaclass conflict. This is due to `jsii`'s `JSIIMeta` metaclass.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Define properties using `@property` and `@<property_name>.setter` decorators.","message":"When extending or implementing types from `jsii` modules, properties must always be implemented using Python's `@property` decorator to ensure the `jsii` runtime correctly processes access to them by the `jsii` kernel.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Where possible, instantiate the `jsii` struct class explicitly instead of relying on implicit `dict` conversion. Consult the specific `jsii`-generated library's documentation for correct struct usage.","message":"Passing Python `dict` literals in places where a `jsii` struct is expected might not always work consistently. This can lead to type-checking errors in the `jsii/kernel` module, incorrect translation of property keys (e.g., snake_case to camelCase), or properties being dropped entirely.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Consider the performance implications for your specific use case. If high-performance is critical, native implementations might be more suitable.","message":"jsii modules, due to their reliance on an embedded JavaScript engine and marshalling costs, are best suited for development and build tools (like AWS CDK) rather than performance-sensitive or resource-constrained applications.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure the `jsii`-generated Python package is correctly installed using pip (e.g., `pip install <package-name>`) and that the Python environment running the script has access to it.","message":"The required `jsii`-generated Python package was not found in the environment. This typically means the package was not installed or the Python environment path is incorrect.","severity":"breaking","affected_versions":"All versions"},{"fix":"Ensure the `jsii`-generated library is installed using `pip install <your-library-name>` or similar package management commands. Verify that the library's installation directory is included in your `PYTHONPATH` or that you are running your script within the activated virtual environment where the library is installed.","message":"The Python interpreter encountered a `ModuleNotFoundError`, indicating that the `jsii`-generated library or one of its dependencies could not be found in the current Python environment. This typically occurs when the library has not been installed, or the Python environment's paths are not correctly configured.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"search_vec":"'activ':62 'allow':48 'author':33 'aw':13,43,65,78 'behind':41 'bind':73 'c':24 'cdk':47,84 'class':32 'client':3 'cloud':44 'code':16,81 'code-gener':80 'codebas':58 'compil':71 'core':39 'deliv':53 'develop':11,45 'enabl':15 'framework':10 'frequent':67 'generat':74,82 'go':26 'interact':29 'interoper':83 'java':23 'javascript':31 'jsii':1,4 'kit':46 'languag':19 'librari':50,77 'maintain':63 'natur':28 'open':8 'open-sourc':7 'pacmak':72 'polyglot':49 'project':60 'python':2,22 'runtim':76,85 'singl':56 'sourc':9 'technolog':40 'typescript':35,57,79 'updat':68","created_at":"2026-04-06T16:56:28.298299+00:00","updated_at":"2026-04-16T15:54:06.778886+00:00","problems":[{"fix":"Ensure all `aws-cdk-lib` packages (or specific CDK modules) and their dependencies are correctly installed and compatible. Run `npm install` in your TypeScript project and `pip install -r requirements.txt` (or equivalent) in your Python project. Consider upgrading to the latest stable versions of AWS CDK and `jsii` related packages.","cause":"This error, or similar 'Cannot find module' errors, occurs when the jsii runtime, often within an AWS CDK application, cannot locate a required JavaScript module, frequently due to version mismatches between CDK packages, missing dependencies, or improper bundling.","error":"jsii.errors.JavaScriptError: Error: Cannot find module '@aws-cdk/cx-api'"},{"fix":"Upgrade your `aws-cdk` and `jsii` packages to compatible versions. Often, updating `pip install aws-cdk-lib jsii` (or `npm update` for the TypeScript source) resolves this. Ensure all CDK-related packages in your `requirements.txt` (for Python) or `package.json` (for TypeScript) are consistent.","cause":"This error typically arises in Python when there is an incompatibility between the installed versions of `jsii` and `aws-cdk` or other jsii-generated libraries, where the Python bindings are expecting different arguments for the constructor.","error":"TypeError: __new__() got an unexpected keyword argument 'jsii_type'"},{"fix":"Update your `jsii` and `cattrs` packages to their latest versions to ensure compatibility with your Python environment. For example, `pip install --upgrade jsii cattrs`. If the issue persists, ensure your Python version is officially supported by the specific `jsii` and CDK versions you are using.","cause":"This Python-specific error happens when an older version of `jsii` or its dependencies (like `cattrs`) tries to import an internal or removed symbol (`_Union`) from Python's standard `typing` module, often encountered with newer Python versions (e.g., Python 3.8+).","error":"ImportError: cannot import name '_Union' from 'typing'"},{"fix":"Verify that your `package.json` file has a correct `main` and `types` field pointing to the actual main TypeScript file (e.g., `src/index.ts` or `lib/index.d.ts`). Ensure the file exists at the specified path. Check your `tsconfig.json` for proper `rootDir` and `outDir` settings.","cause":"This indicates a failure during the jsii compilation process. It typically means that the `jsii` compiler cannot locate the main entry point file for your TypeScript project as specified in your `package.json` or `tsconfig.json` (e.g., `main` or `types` fields).","error":"error JSII4: Could not find \"main\" file: ...index.ts (or similar jsii compilation failed)"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"1.140.0","cli_name":"jsii","cli_version":"sh: 1: jsii: not found","type":"library","homepage":"https://aws.github.io/jsii","github":"https://github.com/aws/jsii","docs":null,"changelog":null,"pypi":"https://pypi.org/project/jsii/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["aws","devops"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-27","next_check":"2026-07-28","install_tag":"verified"}}