-
Notifications
You must be signed in to change notification settings - Fork 246
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
[info] Example automatically generated #826
Comments
The initial PR is here: #827 |
How is this effort going? My team would absolutely love working python examples on the docs. For now we are relying on the excellent aws-cdk-examples for python, but it would be nice to have working examples inlined in the docs: I found the issue above under the FileAssetLocation for python :-S |
Good catch, that needs to be sorted as well. |
Ex: https://pypi.org/project/aws-cdk.aws-lambda/ should be
Like the aws-sdk-examples do. Ex: https://github.com/aws-samples/aws-cdk-examples/blob/master/python/lambda-cron/app.py |
The Java examples seem to have a lot of issues as well with Classes/Builders and imports: https://docs.aws.amazon.com/cdk/api/latest/java/index.html?software/amazon/awscdk/services/dynamodb/package-summary.html
should be
|
Static methods should not have arn = "arn:aws:..."
certificate = Certificate.from_certificate_arn(self, "Certificate", arn) |
Sorry to do this to your @RomainMuller but since you're working on Rosetta right now anyway, might as well work in these bug reports at the same time? 😇 |
Leaving a note here that I recently came across an issue which involved a python example that does not compile and can lead to some confusion. # Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
from aws_cdk.core import CustomResource
import aws_cdk.aws_logs as logs
import aws_cdk.aws_iam as iam
import aws_cdk.custom_resources as cr
on_event = lambda_.Function(self, "MyHandler")
my_role = iam.Role(self, "MyRole")
my_provider = cr.Provider(self, "MyProvider",
on_event_handler=on_event,
is_complete_handler=is_complete, # optional async "waiter"
log_retention=logs.RetentionDays.ONE_DAY, # default is INFINITE
role=my_role
)
CustomResource(self, "Resource1", service_token=my_provider.service_token)
CustomResource(self, "Resource2", service_token=my_provider.service_token) This example requires some modifications in order to compile. Here's is a modified version of the above example that works. (Given the 2 lambda handlers are provided in external files) from aws_cdk import core as cdk
import aws_cdk.aws_lambda as lambda_
import aws_cdk.aws_logs as logs
import aws_cdk.aws_iam as iam
import aws_cdk.custom_resources as cr
class FooStack(cdk.Construct):
def __init__(self, scope: cdk.Construct, id: str, **kwargs) -> None:
super().__init__(scope, id, **kwargs)
with open("src/lambda_handlers/on_event.py", encoding="utf-8") as fp:
on_event_code_body = fp.read()
on_event = lambda_.Function(self, "on_event",
runtime=lambda_.Runtime.PYTHON_3_7,
handler="index.on_event",
code=lambda_.InlineCode(on_event_code_body),
)
with open("src/lambda_handlers/is_complete.py", encoding="utf-8") as fp:
is_complete_code_body = fp.read()
is_complete = lambda_.Function(self, "is_complete",
runtime=lambda_.Runtime.PYTHON_3_7,
handler="index.is_complete",
code=lambda_.InlineCode(is_complete_code_body),
)
my_role = iam.Role(self, "MyRole",
assumed_by=iam.ServicePrincipal("lambda.amazonaws.com")
)
my_provider = cr.Provider(self, "MyProvider",
on_event_handler=on_event,
is_complete_handler=is_complete, # optional async "waiter"
log_retention=logs.RetentionDays.ONE_DAY, # default is INFINITE
role=my_role
)
cdk.CustomResource(self, "Resource1", service_token=my_provider.service_token)
cdk.CustomResource(self, "Resource2", service_token=my_provider.service_token) |
Bug with Python translation of JavaScript assert(bucket.encryption_key instanceof kms.Key) Python doesn't have the assert(isinstance(bucket.encryption_key, kms.Key)) |
Bug with Python translation of JavaScript uniqueid = "GloballyUniqueIdForSingleton"return stack.node.try_find_child(uniqueid) ?? sns.Topic(stack, uniqueid) It should be uniqueid = "GloballyUniqueIdForSingleton"
return stack.node.try_find_child(uniqueid) or sns.Topic(stack, uniqueid) (Also, there's a missing newline between the string literal and the |
Just noted:
Looks wrong to me. |
The examples we copy into docblocks may contain block comments themselves. However, the docblock renderer does not escape the docblock *closing* text, so the doc block gets terminated early and compiling fails: ```java /** * Initialization props for the `NestedStack` construct. * <p> * Example: * <p> * <blockquote><pre>{@code * // Example automatically generated. See aws/jsii#826 * import software.amazon.awscdk.core.App; * import software.amazon.awscdk.core.CfnOutput; * import software.amazon.awscdk.core.NestedStack; * import lib.RestApi; * import lib.Stage; * /** * * This file showcases how to split up a RestApi's Resources and Methods across nested stacks. * * * * The root stack 'RootStack' first defines a RestApi. * * Two nested stacks BooksStack and PetsStack, create corresponding Resources '/books' and '/pets'. * * They are then deployed to a 'prod' Stage via a third nested stack - DeployStack. * * * * To verify this worked, go to the APIGateway * */ <------------ OOOPS! * public class RootStack extends Stack { * public RootStack(Construct scope) { * super(scope, "integ-restapi-import-RootStack"); * RestApi restApi = RestApi.Builder.cre ``` Revert this until we can address the quoting issue. Reverts #17191
Another instance where JSII doesn't play nice with python, in aws-cdk python docs.
but when actually running cdk commands the field
Seems odd to me since most python translations are snake case. |
Another issue here in the docs Specifically, property_groups=PropertyGroups(
FlinkApplicationProperties={
"input_stream_name": "my-input-kinesis-stream",
"output_stream_name": "my-output-kinesis-stream"
}
) Mimic this example and you will fail with this error: More information can be found about this issue in this comment here |
The examples we copy into docblocks may contain block comments themselves. However, the docblock renderer does not escape the docblock *closing* text, so the doc block gets terminated early and compiling fails: ```java /** * Initialization props for the `NestedStack` construct. * <p> * Example: * <p> * <blockquote><pre>{@code * // Example automatically generated. See aws/jsii#826 * import software.amazon.awscdk.core.App; * import software.amazon.awscdk.core.CfnOutput; * import software.amazon.awscdk.core.NestedStack; * import lib.RestApi; * import lib.Stage; * /** * * This file showcases how to split up a RestApi's Resources and Methods across nested stacks. * * * * The root stack 'RootStack' first defines a RestApi. * * Two nested stacks BooksStack and PetsStack, create corresponding Resources '/books' and '/pets'. * * They are then deployed to a 'prod' Stage via a third nested stack - DeployStack. * * * * To verify this worked, go to the APIGateway * */ <------------ OOOPS! * public class RootStack extends Stack { * public RootStack(Construct scope) { * super(scope, "integ-restapi-import-RootStack"); * RestApi restApi = RestApi.Builder.cre ``` Revert this until we can address the quoting issue. Reverts aws#17191
I've just hit this when trying to use I'd be more than happy to contribute to the docs if I manage to find a solution.
@jsii.implements(ILocalBundling)
class LocalPipInstall:
@staticmethod
@jsii.member(jsii_name="tryBundle")
def try_bundle(output_dir: str, **kwargs) -> bool:
install_command = f'pip install .\[pydantic\] --platform manylinux1_x86_64 --only-binary=:all: -t {output_dir}'
subprocess.run(install_command, shell=True)
return True
# try this too to no avail. Omitting staticmethod returns a Callable signature error
@staticmethod
@jsii.member(jsii_name="tryBundle")
def tryBundle(output_dir: str, **kwargs) -> bool:
install_command = f'pip install .\[pydantic\] --platform manylinux1_x86_64 --only-binary=:all: -t {output_dir}'
subprocess.run(install_command, shell=True)
return True
....
code=Code.from_asset(
path=str(SOURCE_CODE_ROOT_PATH),
bundling=BundlingOptions(
image=DockerImage.from_build(
str(Path(__file__).parent),
build_args={"IMAGE": PythonVersion[PYTHON_RUNTIME_VERSION].value["image"]},
),
command=["bash", "-c", " && ".join(build_commands)],
# Here
local=LocalPipInstall(),
),
), |
This issue is now closed. Comments on closed issues are hard for our team to see. |
In order to provide CDK users with code samples in every language, we automatically translate snippets of TypeScript sample code into other languages.
You can recognize these translated example blocks by them starting with a text similar to the following:
This translation is currently experimental, and we'd like you to let us know how this is working out for you. Please comment on this issue if there's something you would like to discuss.
Examples we couldn't compile
We try compiling all the samples before translating them. This is necessary to extract type information that is necessary to render the correct translation of non-TypeScript languages.
However, compilation of sample code requires some setup that we haven't been able to do for all of our code samples yet. That means that many samples are translated without complete type information, and may hence be incorrect. You can recognize them by starting with a comment similar to:
If you encounter issues with some of these samples that are caused by its lack of compilation, we'd love it if you could help out by submitting a Pull Request to make the samples compile! See the following section to figure out what to expect.
Translation mistakes in uncompiled samples
The most common mistake in uncompiled samples is going to be around Structs, which are pure data objects passed to constructors and methods. They are typically called something like
FooProps
orFooOptions
, and in samples they appear something like this:MISTAKE 1: is it a struct or a map?
Mistake 1 the translator may make in translating the preceding code example without having any type information available, is that it can't know whether the argument to
new SomeClass
is intended to be of type{[key: string]: string}
(i.e., a map ofstring
tostring
), or of typeinterface SomeClassProps
(i.e., a struct).The caller side for both types looks exactly the same in TypeScript, so the translator can't distinguish between them, and so it is forced to guess.
In most cases uses like this will be structs, so that's what the translator will guess given no other information. However, some classes legitimately take a map as argument (for example,
GenericLinuxImage
takes a map of region-to-ami), and in those cases the translator will have guessed wrong and produce an incorrect translation.MISTAKE 2: what is the struct's name?
When the translator guesses that something is a struct, it needs to translate it. In a language like Python, structs get translated into keyword arguments and so they don't need names. In other languages like Java and C#, structs get translated into data classes, and you need their name to instantiate them. Unfortunately, the name of the structs doesn't appear in the code sample and since we have no type information we can't look it up.
In those cases, the translator will generate a placeholder name called
Struct
, with the understanding that you will need to go and look up the actual name when using this code. For example, the C# translator will have translated the above snippet into:You will need to go and look at the documentation of
SomeClass
to figure out thatnew Struct
actually needs to benew SomeClassProps
, or something to that effect.How to make samples compile successfully
We'd rather have all samples compile successfully. To achieve that, modules need some boilerplate added to make it possible to compile the examples. Typically, this boilerplate file will just import some names or set up some variables. This is called a fixture.
For example, making our running example compilable would look something like this.
Add a file to the package called
rosetta/my-fixture.ts-fixture
, and put the following into it:And update the example to look like this:
The example code will be inserted into the fixture file at the location marked by
/// here
, and the resulting complete file should compile.For more information, see the "Examples" section of aws-cdk's Contribution Guide or the "Fixtures" section of the rosetta tool.
Known Issues
The following are known issues with the translation tool:
Language keywords are not respected: Sometimes TypeScript code uses identifiers which are reserved keywords in other languages. The translated code may copy those identifiers without modification, leading to code that won't compile (example:
import aws_cdk.aws_lambda as lambda
won't actually work in Python aslambda
is a reserved keyword).Single values are interpreted as code snippets: The
@example
doc comment directive is used both for code snippets, as well as exemplar values for properties. The translator tries to translate the sample values, which will maul them (example).The text was updated successfully, but these errors were encountered: