[REQ] Static typing in Python client

[HeshamMeneisi]

Is your feature request related to a problem? Please describe.

Python clients contain types in the method docs but not in the definition

Describe the solution you'd like

Types should be included in the definition.

Additional context

This can be controlled by a Python target version config (3.7+ contains static types)

I'm ready to work on this if someone just points me to where to start (docs, project setup instructions, etc).

[wing328]

Types should be included in the definition.

Can you please elaborate with an example (current output vs expected output)?

[HeshamMeneisi]

Output

def query_skus(self, **kwargs):  # noqa: E501
        """query_skus  # noqa: E501
        This method makes a synchronous HTTP request by default. To make an
        asynchronous HTTP request, please pass async_req=True
        >>> thread = api.query_skus(async_req=True)
        >>> result = thread.get()
        :param brand_id:
        :type brand_id: int
        :param brand_code:
        :type brand_code: str
        :param seller_id:
        :type seller_id: int
        :param page:
        :type page: int
        :param per_page:
        :type per_page: int
        :param async_req: Whether to execute the request asynchronously.
        :type async_req: bool, optional
        :param _preload_content: if False, the urllib3.HTTPResponse object will
                                 be returned without reading/decoding response
                                 data. Default is True.
        :type _preload_content: bool, optional
        :param _request_timeout: timeout setting for this request. If one
                                 number provided, it will be total request
                                 timeout. It can also be a pair (tuple) of
                                 (connection, read) timeouts.
        :return: Returns the result object.
                 If the method is called asynchronously,
                 returns the request thread.
        :rtype: QueryInventoryResponse
        """
        kwargs['_return_http_data_only'] = True
        return self.query_skus_with_http_info(**kwargs)  # noqa: E501

Desired

def query_skus(self, brand_id: int, brand_code: str, seller_id: int, per_page: int, page: int, **kwargs) -> QueryInventoryResponse: 
...

@wing328

[spacether]

@HeshamMeneisi please check your spec definition.
Optional parameters are in kwargs. Required parameters are set as positional args. We do this because optional arguments are unset. If you make your spec args required then they will be positional args in your fn signature. Can you please share your opeanpi spec json or yaml file? You only share auto generated code.

You can see required args showing up as positional args here with
api_client.test_body_with_query_params(query, user, **kwargs)
Dropping in dataType values may not work though.
We use run time type checking in our client and we use:

• tuples to store typing.Union values
• {} to store dicts rather than typing.Dict[]
• [] to store lists rather than typing.List[]

So to drop in the values one would need to change:

• the values to use type hint syntax
• our type checking code to work with those updated values

Do you want to post a PR adding type hints to those endpoints?
You can edit our template on it here: https://github.com/OpenAPITools/openapi-generator/blob/master/modules/openapi-generator/src/main/resources/python/api.mustache#L39

[bflaton]

@HeshamMeneisi I think part of what you'd like to see changed was done recently by one of my pull requests (10339). I was actually considering making additional improvements to also add method return type hints. Moreover, the generated model classes should have static attribute definitions, rather than adding them runtime through setattr() calls, because this makes the generated code much more user friendly when used in modern IDEs, like PyCharm.

[HeshamMeneisi]

@bflaton It helps a lot with IDE support yes! What I was describing here would require a static_typing config flag to be backward compatible. Then the format here would be quite different based on that. For example, all parameters have to be defined, not just required. It would look something like {{paramName}}:{{dataType}} = {{{defaultValue}}} for params and ): -> {{returnType}} for return type. When it's not a required param (or default is None, generally speaking) the type should be Optional[{{returnType}}].

I'm no longer working with the Python generator though so unlikely to add this myself soon 😅

[johnthagen]

3.7+ contains static types

As an FYI, type hinting in Python was added in 3.5: https://docs.python.org/3.5/library/typing.html

Though, it has evolved in small ways in each release. The typing-extensions PyPI package can be used to use new typing features in older versions of Python: https://pypi.org/project/typing-extensions/

[johnthagen]

Related to #4807

[johnthagen]

As inspiration, openapi-python-client is an OpenAPI Python client generator that generates statically typed models and functions.

[spacether]

Static typing is great and is something that I am working on.

dataclasses are great but I think that it would be hard to use them to cover all of our use cases with them:

• Payloads can be AnyType [str, number, dict, list, null]
• discriminated models dynamically validate against other schemas
• Composed schema payloads combine multiple schemas which are dynamically validated against
  • those schemas can be of any type, composed, list object etc and one needs to conditionally validate the payload agains the allOf/oneOf/anyOf constraints
• after ingesting a payload instances should not be mutable because if multiple schemas were validated to, changing a value could invalidate the validates which were verified (imagine changing a discriminator propertyname)

This is a difficult problem and I am working on it in:

• Adds python-experimental which uses dynamic base classes #8325
  In that PR:
• required arguments are positional and typed
• optional arguments have a default value of a sentinel unset value and are typed
  • unset values are omitted during assignment, this allows users to pass in None if it is a valid value

[spacether]

@HeshamMeneisi @shotat @johnthagen @mcdenhoed @theryangeary can you try the python-experimental generator?
It includes type hints for model instantiation and endpoints. It was added in: #8325

[spacether]

Closing this issue because the python-experimental generator has type hints for all model instantiation, endpoint inputs, and endpoint responses.

One can see the type hints in our samples here like:

class FindPetsByStatus(api_client.Api):

    def find_pets_by_status(
        self: api_client.Api,
        query_params: RequestQueryParams = frozendict(),
        accept_content_types: typing.Tuple[str] = _all_accept_content_types,
        stream: bool = False,
        timeout: typing.Optional[typing.Union[int, typing.Tuple]] = None,
        skip_deserialization: bool = False,
    ) -> typing.Union[
        ApiResponseFor200,
        api_client.ApiResponseWithoutDeserialization
    ]: