Skip to content

Wrong return type in doc creation docstrings, provides incorrect guidance to type checkers #18

@bennylope

Description

@bennylope

The DocApi.create_doc() method's docstring includes the wrong return type:

:return: Returns the result object.
If the method is called asynchronously,
returns the request thread.
:rtype: str

Similarly for DocApi.create_doc_with_http_info:

:return: Returns the result object.
If the method is called asynchronously,
returns the request thread.
:rtype: tuple(str, status_code(int), headers(HTTPHeaderDict))

The correct return type here are bytes and tuple(bytes, status_code(int), headers(HTTPHeaderDict)), respectively.

Since Python 3, str is reserved for unicode strings, not the byte strings return by HTTP calls.

I know a picture isn't proof but absent a share environment, here's the best I can do.

CleanShot 2023-09-15 at 16 07 57@2x

Why does this matter?

It doesn't affect the working of the library, but it does anyone using any type checking or type hints, e.g. PyCharm below:

CleanShot 2023-09-15 at 16 01 48@2x

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions