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
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions