Unclear python signature when function accepts multiple structs

[iliapolo]

I'm trying to figure out if jsii behaves as expected in the following scenario.

Here is my TypeScript code:

export interface SecretValue {
  readonly secret: ISecret;
  readonly key: string;
}

export interface EnvValueFromSecretOptions {
  readonly optional?: boolean;
}

public static fromSecretValue(secretValue: secret.SecretValue, options: EnvValueFromSecretOptions = {}): EnvValue {
  ...
  ...
}

Notice the method accepts two structs. And this is what jsii generates for python:

@jsii.member(jsii_name="fromSecretValue")
@builtins.classmethod
def from_secret_value(
    cls,
    secret_value: typing.Union["SecretValue", typing.Dict[builtins.str, typing.Any]],
    *,
    optional: typing.Optional[builtins.bool] = None,
) -> "EnvValue":
  ...
  ...

So the last struct argument is expanded into its keys, which is expected. But I am a bit surprised by the translation to a union type for the first struct argument. Is this intentional so that we can support the following invocation patterns?

secret = kplus.Secret(self, 'Secret', string_data={'key': 'value'})

// pass as a dict
kplus.EnvValue.from_secret_value(secret_value={
  'secret': secret,
  'key': 'key'
})

// pass as a class
kplus.EnvValue.from_secret_value(secret_value=kplus.SecretValue(secret=secret, key='key')),

If so, there's a bug with jsii-docgen, which currently generates the following signature for this case:

cdk8s_plus_25.EnvValue.from_secret_value(
  key: str,
  secret: ISecret,
  optional: bool = None
)

[RomainMuller]

Code-gen is correct, we allow dicts to be passed in lieu of structs.

But doc-gen is wrong because structs are only turned into kwargs if they are at the last argument position.

[iliapolo]

Thanks @RomainMuller. Opened a jsii-docgen bug: cdklabs/jsii-docgen#865