From 1153d95717c1d65faf66d660ff68f760f0065584 Mon Sep 17 00:00:00 2001
From: Pahud Hsieh <pahudnet@gmail.com>
Date: Thu, 30 Oct 2025 14:50:41 -0400
Subject: [PATCH] docs(python-guide): Add type checking guidance for AWS CDK
 Python development

- Expand section on preventing type errors in Python CDK development
- Add detailed instructions for IDE type checking with VS Code and PyCharm
- Include command-line type checking methods using MyPy and Pyright
- Provide recommended workflow for type checking during development and CI/CD
- Enhance documentation to help developers catch and prevent type-related errors early
---
 v2/guide/work-with-cdk-python.adoc | 46 +++++++++++++++++++++++++++++-
 1 file changed, 45 insertions(+), 1 deletion(-)

diff --git a/v2/guide/work-with-cdk-python.adoc b/v2/guide/work-with-cdk-python.adoc
index 7a96eae..b6bc093 100644
--- a/v2/guide/work-with-cdk-python.adoc
+++ b/v2/guide/work-with-cdk-python.adoc
@@ -322,4 +322,48 @@ In our experience, the type errors Python programmers make tend to fall into the
 * Passing a single value where a construct expects a container (Python list or dictionary) or vice versa.
 * Passing a value of a type associated with a layer 1 (`CfnXxxxxx`) construct to a L2 or L3 construct, or vice versa.
 
-The {aws} CDK Python modules do include type annotations, so you can use tools that support them to help with types. If you are not using an IDE that supports these, such as  https://www.jetbrains.com/pycharm/[PyCharm], you might want to call the http://mypy-lang.org/[MyPy] type validator as a step in your build process. There are also runtime type checkers that can improve error messages for type-related errors.
\ No newline at end of file
+== Preventing type errors
+
+The AWS CDK Python modules include type annotations, so you can use tools that support them to catch type errors before deployment.
+
+=== IDE integration (recommended)
+
+Visual Studio Code with Pylance provides real-time type checking as you write code:
+
+1. Install the https://marketplace.visualstudio.com/items?itemName=ms-python.vscode-pylance[Pylance extension]
+2. Configure strict type checking in `.vscode/settings.json`:
++
+[source,json]
+----
+{
+  "python.languageServer": "Pylance",
+  "python.analysis.typeCheckingMode": "strict"
+}
+----
+3. Type errors now appear immediately with red squiggles and detailed error messages
+
+https://www.jetbrains.com/pycharm/[PyCharm] also provides built-in type checking with similar capabilities.
+
+=== Command-line type checking
+
+For CI/CD pipelines or pre-commit validation, use one of these type checkers:
+
+*MyPy (Python-based):*
+[source,bash]
+----
+pip install mypy
+mypy app.py
+----
+
+*Pyright (faster, JavaScript-based, same engine as Pylance):*
+[source,bash]
+----
+npm install -g pyright
+pyright app.py
+----
+
+=== Recommended workflow
+
+1. During development: Use Pyright or Pylance for instant feedback
+2. Before commit: Run `mypy app.py` or `pyright app.py`
+3. In CI/CD: Make type checking a required step before deployment
\ No newline at end of file