Skip to content
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

chore: add python docs #20

Closed
wants to merge 4 commits into from
Closed
Changes from 3 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
86 changes: 86 additions & 0 deletions docs/python.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,86 @@
# Introduction

> [!NOTE]
> The following is valid as of 2024-03-18. Future versions of `jsii` might provide a more Pythonic approach.

Using the python version of this package requires some extra steps to ensure everything works as expected.
This document highlights only those steps, so for the basics, please refer to the [main README](../README.md), the [API docs](../API.md) and the [Typescript docs](typescript.md).

## How to implement interfaces

Since this package is written in Typescript and then exported to Python via `jsii`, using interfaces to pass props is not as straightforward as it should be.

Whereas in Typescript you can simply pass the props like this:

```ts
const costMonitoring = new ApplicationCostMonitoring(
monitoringStack,
// ⬇︎⬇︎⬇︎ The props ⬇︎⬇︎⬇︎
{
applicationName: "my-application",
monthlyBudget: 200,want)
wtfzambo marked this conversation as resolved.
Show resolved Hide resolved
otherStacksIncludedInBudget: [secondStack, firstStack],
subscribers: ["[email protected]"],
}
);
```

In python it is not so simple.

The correct, and ONLY working approach is to:

1. Create a new class (no inheritance)
2. Decorate it with `@jsii.implements(<IMyInterface>)`
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor Author

@wtfzambo wtfzambo Mar 18, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

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

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Copy link
Contributor Author

@wtfzambo wtfzambo Mar 18, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

* [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?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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)

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.
image

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

image

3. Use getters and setters to define properties

Example:

```py
import jsii

from cost_monitoring_construct import IApplicationCostMonitoringProps

@jsii.implements(IApplicationCostMonitoringProps)
class CostMonitoringProps:
def __init__(self, props: dict[str, Any]) -> None:
self.props = props


@property
def application_name(self):
return self.props["application_name"]

@application_name.setter
def application_name(self, value: str):
self.props["application_name"] = value

@property
def default_topic(self):
return self.props.get("default_topic")

@default_topic.setter
def default_topic(self, value: str | None):
self.props["default_topic"] = value

# etc...
```

Later you can use this class directly in the `ApplicationCostMonitoring`:

```py
cost_monitoring = ApplicationCostMonitoring(
stack_to_monitor,
props=CostMonitoringProps(
{
"application_name": "my_app",
"monthly_limit_in_dollars": 100,
"subscribers": ["[email protected]"]
}
)
)
```

## Sources and additional info

- <https://aws.github.io/jsii/user-guides/lib-user/language-specific/python/>
- <https://github.com/aws/jsii/issues/1027>
Loading