chore: add python docs

[wtfzambo]

Description

Add instructions for python

Related Issue

See comment on ADAP-602

Motivation and Context

Not immediately clear how to use interfaces with Python

How Has This Been Tested?

MR !504

[shahinism]

This is a weird requirement. The whole CDK stack in Python runs on jsii, and we don't need to pass anything to it using this method. Can you please share related resources here?

[shahinism]

If needed, we should abstract this away from the final consumer.

[wtfzambo]

@shahinism
related (re)-sources (also included in the docs):

• https://aws.github.io/jsii/user-guides/lib-user/language-specific/python/
• python: implementing interface property requires a @property declaration aws/jsii#1027

we should abstract this away from the final consumer.

I don't think this is possible in a pure Typescript implementation, unless you want to create a dedicated Python one

[rehanvdm]

I am not sure about the Python usage, but like @shahinism mentions. When you are using the construct you should not be concerned about anything JSII, it should just be normal Python usage. In an ideal world. So I don't know about this one.

[rehanvdm]

I might be wrong but is your Python example in the doc using the construct or inheriting from it? Maybe that edge case only exists if you inherit in Python?

[wtfzambo]

is your Python example in the doc using the construct or inheriting from it?

@rehanvdm
Are you referring specifically to the interface IApplicationCostMonitoring? In that case, neither.

Inheritance doesn't work, nor does it work to use the "interface" directly:

1. in the first case, inheritance, the program will crash with error: TypeError: Don't know how to convert object to JSON
2. in the second case, using the construct directly, you can't because the program considers it an abstract class.

The CDK run will fail nonetheless because lack of permissions, but the only case in which it fails because of a permission error rather than some type error or other programmatic issues is the one documented here.

[shahinism]

* [python: implementing interface property requires a `@property` declaration aws/jsii#1027](https://github.com/aws/jsii/issues/1027)

The concern in this link is implementing the interface directly in Python instead of using one in TS. Am I wrong?

[shahinism]

I also spent some time this morning reviewing some of the constructs available at https://constructs.dev/
We can check any supporting Python construct without taking extra care with JSII. Let's see what they are doing differently at the library level.

[wtfzambo]

I've spent some time going through the cdk code as suggested. Here's my findings (in no particular order):

• Constructs that have Interfaces in the constructor, when translated to python, expect an object that matches that interface. A good example to follow is the IConnection interface and related Connection class (here and here).
• Notice how Connection has subnet and security_groups args, but it expects proper ec2.Subnet() and ec2.SecurityGroup() objects, rather than some dictionary.
• To pass props to a construct and avoid the jsii.implements shenanigans in python, we need to add an extra step (basically what I did in python, but in typescript). See again the Connection class:

export class Connection extends cdk.Resource implements IConnection {

and how it's exported in python:

@jsii.implements(IConnection)
class Connection(
    _aws_cdk_ceddda9d.Resource,
    metaclass=jsii.JSIIMeta,
    jsii_type="@aws-cdk/aws-glue-alpha.Connection",
):

• The same goes for the ISecurityGroup and ISubnet mentioned above (see here, for instance)

[rehanvdm]

Yeah it is something wrong with the component, I think that here instead of

export class ApplicationCostMonitoring extends IBudgetStrategy {

It should be

export class ApplicationCostMonitoring extends Construct implements IBudgetStrategy {

Somewhere something goes wrong and JSII does not produce the right Python.

VS something in the standard CDK lib, an SQS to be specific.