jsii Python Client

Warnings

• breaking 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.
  Fix: Ensure your Python environment is version 3.8 or higher. For best compatibility, use Python 3.11+.
• breaking 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.
  Fix: Upgrade your Node.js installation to version 18 or higher. For best compatibility, use Node.js 20+.
• gotcha 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.
  Fix: Use the `@jsii.implements(IJsiiInterface)` decorator to explicitly declare interface implementation. For example: `import jsii; @jsii.implements(IJsiiInterface) class MyNewClass():`
• gotcha 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.
  Fix: Define properties using `@property` and `@<property_name>.setter` decorators.
• gotcha 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.
  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.
• gotcha 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.
  Fix: Consider the performance implications for your specific use case. If high-performance is critical, native implementations might be more suitable.

Install

• pip install jsii Install jsii runtime

Imports

• jsii

  import jsii

  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').
• implements

  from jsii import implements

  Used as a decorator (@jsii.implements) to explicitly declare Python classes implementing jsii interfaces, avoiding metaclass conflicts.

Quickstart

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.

import os
from some_jsii_generated_lib import HelloJsii

# NOTE: In a real scenario, 'some_jsii_generated_lib' would be a library
# generated by jsii (e.g., AWS CDK, or your own jsii module) which has
# 'jsii' as a dependency. The 'HelloJsii' class would be defined in TypeScript.

# Example of using a class from a jsii-generated Python library
try:
    # Assuming HelloJsii class and say_hello method are available
    # This code is illustrative; replace with actual generated lib usage.
    hello_instance = HelloJsii()
    message = hello_instance.say_hello("World")
    print(message)
except ImportError:
    print("To run this, you need a jsii-generated library installed.")
    print("For example, 'pip install aws-cdk.core' and then use CDK classes.")
except Exception as e:
    print(f"An error occurred: {e}")