AWS cdk documentation change
Summary
Formatting updates: replaced straight quotes with curly quotes, added shell prompt symbols ($) to commands, standardized code formatting (backticks instead of bold), removed redundant 'Topics' section, and minor grammatical corrections.
Security assessment
The changes are primarily formatting improvements, documentation structure adjustments, and command-line example clarifications. No explicit references to security vulnerabilities, mitigations, or security features were introduced. Changes focus on readability and consistency rather than addressing security concerns.
Diff
diff --git a/cdk/v2/guide/work-with-cdk-python.md b/cdk/v2/guide/work-with-cdk-python.md index 7efd15228..ab3981a84 100644 --- a//cdk/v2/guide/work-with-cdk-python.md +++ b//cdk/v2/guide/work-with-cdk-python.md @@ -15,15 +14,0 @@ You can use any editor or IDE. Many AWS CDK developers use [Visual Studio Code]( -###### Topics - - * Get started with Python - - * Creating a project - - * Managing AWS Construct Library modules - - * Managing dependencies in Python - - * AWS CDK idioms in Python - - - - @@ -34 +19 @@ To work with the AWS CDK, you must have an AWS account and credentials and have -Python AWS CDK applications require Python 3.6 or later. If you don't already have it installed, [download a compatible version](https://www.python.org/downloads/) for your operating system at [python.org](https://www.python.org/). If you run Linux, your system may have come with a compatible version, or you may install it using your distro's package manager (`yum`, `apt`, etc.). Mac users may be interested in [Homebrew](https://brew.sh/), a Linux-style package manager for macOS. +Python AWS CDK applications require Python 3.6 or later. If you don’t already have it installed, [download a compatible version](https://www.python.org/downloads/) for your operating system at [python.org](https://www.python.org/). If you run Linux, your system may have come with a compatible version, or you may install it using your distro’s package manager (`yum`, `apt`, etc.). Mac users may be interested in [Homebrew](https://brew.sh/), a Linux-style package manager for macOS. @@ -51 +36 @@ If you encounter a permission error, run the above commands with the `--user` fl -It is common for Linux distros to use the executable name `python3` for Python 3.x, and have `python` refer to a Python 2.x installation. Some distros have an optional package you can install that makes the `python` command refer to Python 3. Failing that, you can adjust the command used to run your application by editing `cdk.json` in the project's main directory. +It is common for Linux distros to use the executable name `python3` for Python 3.x, and have `python` refer to a Python 2.x installation. Some distros have an optional package you can install that makes the `python` command refer to Python 3. Failing that, you can adjust the command used to run your application by editing `cdk.json` in the project’s main directory. @@ -55 +40 @@ It is common for Linux distros to use the executable name `python3` for Python 3 -On Windows, you may want to invoke Python (and **pip**) using the **py** executable, the [>Python launcher for Windows](https://docs.python.org/3/using/windows.html#launcher). Among other things, the launcher allows you to easily specify which installed version of Python you want to use. +On Windows, you may want to invoke Python (and `pip`) using the `py` executable, the [Python launcher for Windows](https://docs.python.org/3/using/windows.html#launcher). Among other things, the launcher allows you to easily specify which installed version of Python you want to use. @@ -57 +42 @@ On Windows, you may want to invoke Python (and **pip**) using the **py** executa -If typing **python** at the command line results in a message about installing Python from the Windows Store, even after installing a Windows version of Python, open Windows' Manage App Execution Aliases settings panel and turn off the two App Installer entries for Python. +If typing `python` at the command line results in a message about installing Python from the Windows Store, even after installing a Windows version of Python, open Windows' Manage App Execution Aliases settings panel and turn off the two App Installer entries for Python. @@ -64,3 +49,3 @@ You create a new AWS CDK project by invoking `cdk init` in an empty directory. U - mkdir my-project - cd my-project - cdk init app --language python + $ mkdir my-project + $ cd my-project + $ cdk init app --language python @@ -70 +55 @@ You create a new AWS CDK project by invoking `cdk init` in an empty directory. U -To work with the new project, activate its virtual environment. This allows the project's dependencies to be installed locally in the project folder, instead of globally. +To work with the new project, activate its virtual environment. This allows the project’s dependencies to be installed locally in the project folder, instead of globally. @@ -73 +58 @@ To work with the new project, activate its virtual environment. This allows the - source .venv/bin/activate + $ source .venv/bin/activate @@ -83 +68 @@ If you initialized your AWS CDK project using CDK Toolkit v1.70.0 or earlier, yo -Activate the project's virtual environment whenever you start working on it. Otherwise, you won't have access to the modules installed there, and modules you install will go in the Python global module directory (or will result in a permission error). +Activate the project’s virtual environment whenever you start working on it. Otherwise, you won’t have access to the modules installed there, and modules you install will go in the Python global module directory (or will result in a permission error). @@ -85 +70 @@ Activate the project's virtual environment whenever you start working on it. Oth -After activating your virtual environment for the first time, install the app's standard dependencies: +After activating your virtual environment for the first time, install the app’s standard dependencies: @@ -88 +73 @@ After activating your virtual environment for the first time, install the app's - python -m pip install -r requirements.txt + $ python -m pip install -r requirements.txt @@ -92 +77 @@ After activating your virtual environment for the first time, install the app's -Use the Python package installer, **pip** , to install and update AWS Construct Library modules for use by your apps, as well as other packages you need. **pip** also installs the dependencies for those modules automatically. If your system does not recognize **pip** as a standalone command, invoke **pip** as a Python module, like this: +Use the Python package installer, `pip`, to install and update AWS Construct Library modules for use by your apps, as well as other packages you need. `pip` also installs the dependencies for those modules automatically. If your system does not recognize `pip` as a standalone command, invoke `pip` as a Python module, like this: @@ -95 +80 @@ Use the Python package installer, **pip** , to install and update AWS Construct - python -m pip PIP-COMMAND + $ python -m pip <PIP-COMMAND> @@ -97 +82 @@ Use the Python package installer, **pip** , to install and update AWS Construct -Most AWS CDK constructs are in `aws-cdk-lib`. Experimental modules are in separate modules named like `aws-cdk.`SERVICE-NAME`.alpha`. The service name includes an _aws_ prefix. If you're unsure of a module's name, [search for it at PyPI](https://pypi.org/search/?q=aws-cdk). For example, the command below installs the AWS CodeStar library. +Most AWS CDK constructs are in `aws-cdk-lib`. Experimental modules are in separate modules named like `aws-cdk.<SERVICE-NAME>.alpha`. The service name includes an _aws_ prefix. If you’re unsure of a module’s name, [search for it at PyPI](https://pypi.org/search/?q=aws-cdk). For example, the command below installs the AWS CodeStar library. @@ -100 +85 @@ Most AWS CDK constructs are in `aws-cdk-lib`. Experimental modules are in separa - python -m pip install aws-cdk.aws-codestar-alpha + $ python -m pip install aws-cdk.aws-codestar-alpha @@ -131 +116 @@ We recommend the following practices when importing AWS CDK classes and AWS Cons -After installing a module, update your project's `requirements.txt` file, which lists your project's dependencies. It is best to do this manually rather than using `pip freeze`. `pip freeze` captures the current versions of all modules installed in your Python virtual environment, which can be useful when bundling up a project to be run elsewhere. +After installing a module, update your project’s `requirements.txt` file, which lists your project’s dependencies. It is best to do this manually rather than using `pip freeze`. `pip freeze` captures the current versions of all modules installed in your Python virtual environment, which can be useful when bundling up a project to be run elsewhere. @@ -137 +122 @@ You can edit `requirements.txt` to allow upgrades; simply replace the `==` prece -With `requirements.txt` edited appropriately to allow upgrades, issue this command to upgrade your project's installed modules at any time: +With `requirements.txt` edited appropriately to allow upgrades, issue this command to upgrade your project’s installed modules at any time: @@ -140 +125 @@ With `requirements.txt` edited appropriately to allow upgrades, issue this comma - pip install --upgrade -r requirements.txt + $ pip install --upgrade -r requirements.txt @@ -147,2 +132,2 @@ In Python, you specify dependencies by putting them in `requirements.txt` for ap - pip command options - python -m pip command options + pip <command options> + python -m pip <command options> @@ -150 +135 @@ In Python, you specify dependencies by putting them in `requirements.txt` for ap -The **python -m pip** invocation works on most systems; **pip** requires that PIP's executable be on the system path. If **pip** doesn't work, try replacing it with **python -m pip**. +The `python -m pip` invocation works on most systems; `pip` requires that PIP’s executable be on the system path. If `pip` doesn’t work, try replacing it with `python -m pip`. @@ -152 +137 @@ The **python -m pip** invocation works on most systems; **pip** requires that PI -The **cdk init --language python** command creates a virtual environment for your new project. This lets each project have its own versions of dependencies, and also a basic `requirements.txt` file. You must activate this virtual environment by running **source .venv/bin/activate** each time you begin working with the project. On Windows, run **.\venv\Scripts\activate** instead +The `cdk init --language python` command creates a virtual environment for your new project. This lets each project have its own versions of dependencies, and also a basic `requirements.txt` file. You must activate this virtual environment by running `source .venv/bin/activate` each time you begin working with the project. On Windows, run `.\venv\Scripts\activate` instead @@ -162 +147 @@ The following is an example `requirements.txt` file. Because PIP does not have a -Installing a module with **pip install** does not automatically add it to `requirements.txt`. You must do that yourself. If you want to upgrade to a later version of a dependency, edit its version number in `requirements.txt`. +Installing a module with `pip install` does not automatically add it to `requirements.txt`. You must do that yourself. If you want to upgrade to a later version of a dependency, edit its version number in `requirements.txt`. @@ -164 +149 @@ Installing a module with **pip install** does not automatically add it to `requi -To install or update your project's dependencies after creating or editing `requirements.txt`, run the following: +To install or update your project’s dependencies after creating or editing `requirements.txt`, run the following: @@ -171 +156 @@ To install or update your project's dependencies after creating or editing `requ -The **pip freeze** command outputs the versions of all installed dependencies in a format that can be written to a text file. This can be used as a requirements file with `pip install -r`. This file is convenient for pinning all dependencies (including transitive ones) to the exact versions that you tested with. To avoid problems when upgrading packages later, use a separate file for this, such as `freeze.txt` (not `requirements.txt`). Then, regenerate it when you upgrade your project's dependencies. +The `pip freeze` command outputs the versions of all installed dependencies in a format that can be written to a text file. This can be used as a requirements file with `pip install -r`. This file is convenient for pinning all dependencies (including transitive ones) to the exact versions that you tested with. To avoid problems when upgrading packages later, use a separate file for this, such as `freeze.txt` (not `requirements.txt`). Then, regenerate it when you upgrade your project’s dependencies. @@ -202 +187 @@ In Python, `lambda` is a language keyword, so you cannot use it as a name for th -By convention, the second argument to AWS CDK constructs is named `id`. When writing your own stacks and constructs, calling a parameter `id` "shadows" the Python built-in function `id()`, which returns an object's unique identifier. This function isn't used very often, but if you should happen to need it in your construct, rename the argument, for example `construct_id`. +By convention, the second argument to AWS CDK constructs is named `id`. When writing your own stacks and constructs, calling a parameter `id` "shadows" the Python built-in function `id()`, which returns an object’s unique identifier. This function isn’t used very often, but if you should happen to need it in your construct, rename the argument, for example `construct_id`. @@ -212 +197 @@ In Python, props are expressed as keyword arguments. If an argument contains nes -For example, in a Amazon S3 bucket's `add_lifecycle_rule` method, the `transitions` property is a list of `Transition` instances. +For example, in a Amazon S3 bucket’s `add_lifecycle_rule` method, the `transitions` property is a list of `Transition` instances. @@ -224 +209 @@ For example, in a Amazon S3 bucket's `add_lifecycle_rule` method, the `transitio -When extending a class or overriding a method, you may want to accept additional arguments for your own purposes that are not understood by the parent class. In this case you should accept the arguments you don't care about using the `**kwargs` idiom, and use keyword-only arguments to accept the arguments you're interested in. When calling the parent's constructor or the overridden method, pass only the arguments it is expecting (often just `**kwargs`). Passing arguments that the parent class or method doesn't expect results in an error. +When extending a class or overriding a method, you may want to accept additional arguments for your own purposes that are not understood by the parent class. In this case you should accept the arguments you don’t care about using the **kwargs idiom, and use keyword-only arguments to accept the arguments you’re interested in. When calling the parent’s constructor or the overridden method, pass only the arguments it is expecting (often just **kwargs). Passing arguments that the parent class or method doesn’t expect results in an error. @@ -232 +217 @@ When extending a class or overriding a method, you may want to accept additional -A future release of the AWS CDK could coincidentally add a new property with a name you used for your own property. This won't cause any technical issues for users of your construct or method (since your property isn't passed "up the chain," the parent class or overridden method will simply use a default value) but it may cause confusion. You can avoid this potential problem by naming your properties so they clearly belong to your construct. If there are many new properties, bundle them into an appropriately-named class and pass it as a single keyword argument. +A future release of the AWS CDK could coincidentally add a new property with a name you used for your own property. This won’t cause any technical issues for users of your construct or method (since your property isn’t passed "up the chain," the parent class or overridden method will simply use a default value) but it may cause confusion. You can avoid this potential problem by naming your properties so they clearly belong to your construct. If there are many new properties, bundle them into an appropriately-named class and pass it as a single keyword argument. @@ -236 +221 @@ A future release of the AWS CDK could coincidentally add a new property with a n -The AWS CDK uses `None` to represent missing or undefined values. When working with `**kwargs`, use the dictionary's `get()` method to provide a default value if a property is not provided. Avoid using `kwargs[...]`, as this raises `KeyError` for missing values. +The AWS CDK uses `None` to represent missing or undefined values. When working with **kwargs, use the dictionary’s `get()` method to provide a default value if a property is not provided. Avoid using `kwargs[…]`, as this raises `KeyError` for missing values. @@ -246 +231 @@ Some AWS CDK methods (such as `tryGetContext()` to get a runtime context value) -Python doesn't have an interface feature as some other languages do, though it does have [abstract base classes](https://docs.python.org/3/library/abc.html), which are similar. (If you're not familiar with interfaces, Wikipedia has [a good introduction](https://en.wikipedia.org/wiki/Interface_\(computing\)#In_object-oriented_languages).) TypeScript, the language in which the AWS CDK is implemented, does provide interfaces, and constructs and other AWS CDK objects often require an object that adheres to a particular interface, rather than inheriting from a particular class. So the AWS CDK provides its own interface feature as part of the [JSII](https://github.com/aws/jsii) layer. +Python doesn’t have an interface feature as some other languages do, though it does have [abstract base classes](https://docs.python.org/3/library/abc.html), which are similar. (If you’re not familiar with interfaces, Wikipedia has [a good introduction](https://en.wikipedia.org/wiki/Interface_\(computing\)#In_object-oriented_languages).) TypeScript, the language in which the AWS CDK is implemented, does provide interfaces, and constructs and other AWS CDK objects often require an object that adheres to a particular interface, rather than inheriting from a particular class. So the AWS CDK provides its own interface feature as part of the [JSII](https://github.com/aws/jsii) layer. @@ -261 +246 @@ To indicate that a class implements a particular interface, you can use the `@js -Python uses dynamic typing, where all variables may refer to a value of any type. Parameters and return values may be annotated with types, but these are "hints" and are not enforced. This means that in Python, it is easy to pass the incorrect type of value to a AWS CDK construct. Instead of getting a type error during build, as you would from a statically-typed language, you may instead get a runtime error when the JSII layer (which translates between Python and the AWS CDK's TypeScript core) is unable to deal with the unexpected type. +Python uses dynamic typing, where all variables may refer to a value of any type. Parameters and return values may be annotated with types, but these are "hints" and are not enforced. This means that in Python, it is easy to pass the incorrect type of value to a AWS CDK construct. Instead of getting a type error during build, as you would from a statically-typed language, you may instead get a runtime error when the JSII layer (which translates between Python and the AWS CDK’s TypeScript core) is unable to deal with the unexpected type.