From c5975d50e37044d25238d5a724a499ee6976d8ba Mon Sep 17 00:00:00 2001 From: Kaizen Conroy <36202692+kaizencc@users.noreply.github.com> Date: Mon, 10 Jun 2024 11:48:06 -0400 Subject: [PATCH] fix(python): incorrect escaped characters cause warnings (#4538) Fixes #4532. Succinctly, the issue is that the README is copied over into the `__init__.py` file as a python comment. And then python warns that things like `\|` and `\'`, which while not often, do organically and correctly show up in markdown syntax, are invalid escapes. Some people who have set their python config to error on warnings end up erroring on this. The solution is to mark the README string as a raw string `r'''` so python does not try to register the escapes. I'm not sure how to test this in code in this PR. I have done the following to make sure that this works: I copied the repro repo from #4532 [here](https://github.com/kaizencc/cdk_invalid_char/blob/main) and got it to show the warning locally. then, I updated the actual file manually from `'''` to `r'''` and got `pytest -W error` to give me a thumbs up. So that shows that changing `'''` to `r'''` does not expect the escaped characters to be valid. I tested my local jsii-pacmak by using it to package a module in `aws-cdk`, and unzipped the python package and confirmed that the `r'''` raw string indicator shows up for the README string in `__init__.py`, and nothing else. These two combined confirms for me that this solution will work. Again I'm not sure of the best way to test that in jsii-pacmak. --- By submitting this pull request, I confirm that my contribution is made under the terms of the [Apache 2.0 license]. [Apache 2.0 license]: https://www.apache.org/licenses/LICENSE-2.0 --- packages/@jsii/python-runtime/tests/README.md | 2 +- packages/jsii-pacmak/lib/targets/python.ts | 3 ++- .../__snapshots__/target-python.test.js.snap | 10 +++++----- 3 files changed, 8 insertions(+), 7 deletions(-) diff --git a/packages/@jsii/python-runtime/tests/README.md b/packages/@jsii/python-runtime/tests/README.md index 8cfb8ba88c..ef07a15395 100644 --- a/packages/@jsii/python-runtime/tests/README.md +++ b/packages/@jsii/python-runtime/tests/README.md @@ -1,7 +1,7 @@ # Python jsii runtime tests ## Development Iteration -When iterating on the jsii runtime for Python, the develomer must run +When iterating on the jsii runtime for Python, the developer must run `yarn build` before making a subsequent attempt at running `pytest` (e.g: via `yarn test`). This is because the tests run on the code installed in `.env` and this is updated only by `yarn build`. diff --git a/packages/jsii-pacmak/lib/targets/python.ts b/packages/jsii-pacmak/lib/targets/python.ts index 3ebd6c05fe..0a1e6542ce 100644 --- a/packages/jsii-pacmak/lib/targets/python.ts +++ b/packages/jsii-pacmak/lib/targets/python.ts @@ -44,6 +44,7 @@ const requirementsFile = path.resolve( // we use single-quotes for multi-line strings to allow examples within the // docstrings themselves to include double-quotes (see https://github.com/aws/jsii/issues/2569) const DOCSTRING_QUOTES = "'''"; +const RAW_DOCSTRING_QUOTES = `r${DOCSTRING_QUOTES}`; export default class Python extends Target { protected readonly generator: PythonGenerator; @@ -1902,7 +1903,7 @@ class PythonModule implements PythonType { */ private emitModuleDocumentation(code: CodeMaker) { if (this.moduleDocumentation) { - code.line(DOCSTRING_QUOTES); + code.line(RAW_DOCSTRING_QUOTES); // raw string so that python does not attempt to interpret invalid escapes that are valid in markdown code.line(this.moduleDocumentation); code.line(DOCSTRING_QUOTES); } diff --git a/packages/jsii-pacmak/test/generated-code/__snapshots__/target-python.test.js.snap b/packages/jsii-pacmak/test/generated-code/__snapshots__/target-python.test.js.snap index 1cbca68ca2..ab78f626e0 100644 --- a/packages/jsii-pacmak/test/generated-code/__snapshots__/target-python.test.js.snap +++ b/packages/jsii-pacmak/test/generated-code/__snapshots__/target-python.test.js.snap @@ -2072,7 +2072,7 @@ publication.publish() exports[`Generated code for "@scope/jsii-calc-lib": /python/src/scope/jsii_calc_lib/_jsii/jsii-calc-lib@0.0.0.jsii.tgz 1`] = `python/src/scope/jsii_calc_lib/_jsii/jsii-calc-lib@0.0.0.jsii.tgz is a tarball`; exports[`Generated code for "@scope/jsii-calc-lib": /python/src/scope/jsii_calc_lib/custom_submodule_name/__init__.py 1`] = ` -''' +r''' # Submodule Readme This is a submodule readme. @@ -3131,7 +3131,7 @@ setuptools.setup(**kwargs) `; exports[`Generated code for "jsii-calc": /python/src/jsii_calc/__init__.py 1`] = ` -''' +r''' # jsii Calculator This library is used to demonstrate and test the features of JSII @@ -12265,7 +12265,7 @@ publication.publish() `; exports[`Generated code for "jsii-calc": /python/src/jsii_calc/homonymous_forward_references/__init__.py 1`] = ` -''' +r''' Verifies homonymous forward references don't trip the Python type checker This has been an issue when stub functions were introduced to create a reliable source for type checking @@ -14019,7 +14019,7 @@ publication.publish() `; exports[`Generated code for "jsii-calc": /python/src/jsii_calc/submodule/__init__.py 1`] = ` -''' +r''' # Read you, read me This is the readme of the \`jsii-calc.submodule\` module. @@ -14416,7 +14416,7 @@ publication.publish() `; exports[`Generated code for "jsii-calc": /python/src/jsii_calc/submodule/isolated/__init__.py 1`] = ` -''' +r''' # Read you, read me This is the readme of the \`jsii-calc.submodule.isolated\` module.