Metadata-Version: 2.4
Name: cdk-lazy-import
Version: 1.0.0
Summary: Lazy-load aws_cdk submodules to speed up CDK synth
Project-URL: Homepage, https://github.com/schlarpc/cdk-lazy-import
Project-URL: Repository, https://github.com/schlarpc/cdk-lazy-import
Project-URL: Issues, https://github.com/schlarpc/cdk-lazy-import/issues
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Classifier: Typing :: Typed
Requires-Python: >=3.12
Description-Content-Type: text/markdown

# cdk-lazy-import

Speed up AWS CDK synth in Python by lazy-loading `aws_cdk.aws_*` service modules.

## The problem

The AWS CDK for Python uses [jsii] to bridge between JavaScript and Python. When you
`import aws_cdk.aws_s3`, jsii eagerly loads the module and all of its dependencies.
A typical CDK app imports a handful of service modules, but each one pulls in shared
machinery that touches all ~300 service packages. This means `cdk synth` spends several
seconds just on imports before it even starts synthesizing your stack.

## How it works

`cdk-lazy-import` installs a [meta path finder] that intercepts `import aws_cdk.aws_*`
statements. Instead of loading the real module immediately, it returns a lightweight stub.
The stub defers all work until your code actually accesses an attribute (like `aws_s3.Bucket`),
at which point the real module is loaded transparently.

Non-service submodules (`aws_cdk.cx_api`, `aws_cdk.pipelines`, `aws_cdk._jsii`, etc.) are
not intercepted and load normally. Deeper imports like `aws_cdk.aws_s3.notifications` are
also handled normally once their parent resolves.

The result is byte-identical CloudFormation output with ~30-40% faster synth times in
limited testing (~5.8s vs ~9.0s).

## Installation

```shell
pip install cdk-lazy-import
```

That's it. The package includes a `.pth` file that activates the lazy-loading hook
automatically at interpreter startup. No code changes, no configuration, no manual imports.

If `aws-cdk-lib` is not installed in the environment, the hook is a silent no-op.

## Uninstallation

```shell
pip uninstall cdk-lazy-import
```

Removing the package removes the `.pth` file and restores default import behavior.

## API

For most users, installing the package is sufficient. If you need manual control:

```python
import cdk_lazy_import

# The .pth file calls this automatically, but you can call it yourself
# if you need to install the hook at a specific point. It's a no-op if
# the hook is already installed or aws_cdk is not available.
cdk_lazy_import.install()
```

## Caveats

- Only `aws_cdk.aws_*` submodules are lazified. Other submodules load normally.
- The hook must be installed before any `aws_cdk.aws_*` imports. The `.pth` file
  ensures this happens at interpreter startup, but if something imports CDK modules
  before `.pth` files are processed (unusual), those modules won't be lazified.
- Performance gains depend on how many service modules your app uses. Apps that
  import nearly every service module will see less benefit.

[jsii]: https://github.com/aws/jsii
[meta path finder]: https://docs.python.org/3/reference/import.html#the-meta-path
