Python API docs functions use non-standard syntax

[joeduffy]

The various Python functions -- resource constructors, gets, and data sources -- seem to use non-standard syntax. I'm not sure if this was intentional and this is shorthand syntax I'm unaware of? Examples below.

Resource Constructors:

def Instance(resource_name, opts=None, ami=None, associate_public_ip_address=None, availability_zone=None, cpu_core_count=None, cpu_threads_per_core=None, credit_specification=None, disable_api_termination=None, ebs_block_devices=None, ebs_optimized=None, ephemeral_block_devices=None, get_password_data=None, hibernation=None, host_id=None, iam_instance_profile=None, instance_initiated_shutdown_behavior=None, instance_type=None, ipv6_address_count=None, ipv6_addresses=None, key_name=None, metadata_options=None, monitoring=None, network_interfaces=None, placement_group=None, private_ip=None, root_block_device=None, security_groups=None, source_dest_check=None, subnet_id=None, tags=None, tenancy=None, user_data=None, user_data_base64=None, volume_tags=None, vpc_security_group_ids=None, __props__=None);

I was expecting something like:

class Instance:
    def __init__(self, resource_name, ...)

Resource Getters:

static get(resource_name, id, opts=None, ami=None, arn=None, associate_public_ip_address=None, availability_zone=None, cpu_core_count=None, cpu_threads_per_core=None, credit_specification=None, disable_api_termination=None, ebs_block_devices=None, ebs_optimized=None, ephemeral_block_devices=None, get_password_data=None, hibernation=None, host_id=None, iam_instance_profile=None, instance_initiated_shutdown_behavior=None, instance_state=None, instance_type=None, ipv6_address_count=None, ipv6_addresses=None, key_name=None, metadata_options=None, monitoring=None, network_interfaces=None, outpost_arn=None, password_data=None, placement_group=None, primary_network_interface_id=None, private_dns=None, private_ip=None, public_dns=None, public_ip=None, root_block_device=None, security_groups=None, source_dest_check=None, subnet_id=None, tags=None, tenancy=None, user_data=None, user_data_base64=None, volume_tags=None, vpc_security_group_ids=None, __props__=None);

I was expecting something like:

@staticmethod
def get(resource_name, id, ...)

Data Sources:

function  get_regions(all_regions=None, filters=None, opts=None)

I was expecting something like:

def  get_regions(all_regions=None, filters=None, opts=None)

In all of the above cases, line breaks would be nice, as these signatures scroll a fair bit to the right. Also, we are missing typing annotations -- is there a separate issue for that?

[lukehoban]

A key question (the lack of an answer to which has led to the current state) is whether these lines are intended to look like definitions of the API, or calls to construct an instance, or something else.

We mix the two (and make up a number of things in between) across languages.

new Instance(name: string, args: InstanceArgs, opts?: CustomResourceOptions);

def Instance(resource_name, opts=None, ...)

func NewInstance(ctx *Context, name string, ...)

public Instance(string name, InstanceArgs args,

All of these (except Go) are not real syntax for either the definition or the call site for the thing in question. But it's also not clear that just making it strictly the definition syntax would make (e.g.) TypeScript and Python look better.

But it definitely is worth revisiting this and developing a consistent approach here across languages.