[Python APIView] docstring and annotations with *args are being mixed

[swathipil]

The [APIView] for the following method seems to be mixing docstring and annotations in the signature:

class InvalidContentError(ValueError):
    """Error during encoding or decoding content with a schema.

    :param str message: The message object stringified as 'message' attribute
    :keyword dict[str, str] or None details: The error details. Depending on the error, this may include
     information like: `schema_id`, `schema_definition`, `message_content`.
    :keyword error: The original exception, if any.

    :ivar str message: A stringified version of the message parameter
    :ivar dict[str, str] details: The error details. Depending on the error, this may include
     information like: `schema_id`, `schema_definition`, `message_content`.
    """

    def __init__(self, message: str, *args: Any, **kwargs: Any) -> None:

APIView:

    def __init__(
    self,
    message: str,
    *args: Any,
    *,
    error = ...
    **kwargs: Any
    ) -> None:

I would expect that the APIView method signature looks entirely like the method signature and not the docstring. Should I update this method/docstring in some way or is this is an APIView bug? Thanks!

[swathipil]

Additionally, since *args is included in the APIView, another * after that is not needed. It is implied that the arguments following * are kwargs. Expected APIView:

  def __init__(
    self,
    message: str,
    *args: Any,
    error = ...
    **kwargs: Any
    ) -> None:

[kurtzeborn]

@tjprescott, we believe this is in the Python parser. If you find that's not true, go ahead and reassign to @chidozieononiwu

[tjprescott]

@swathipil yes, APIView does very purposefully pull param and type info from docstrings because it does not render the docstrings. This is certainly a parser bug.

[tjprescott]

I'm not sure why only error and messages are appearing, but are you intending to use a mix of keyword and ivar?

[swathipil]

Hi @tjprescott - Sorry for the late response! Didn't see this until just now. Yes, we're using both keywords and ivars. For example, the keyword message will also be an ivar.

[swathipil]

All docstring should be using Python 3 typehints/syntax now. The Schema Registry method now looks like:

 """Error during encoding or decoding content with a schema.

    :param str message: The message object stringified as 'message' attribute
    :keyword dict[str, str] or None details: The error details. Depending on the error, this may include
     information like: `schema_id`, `schema_definition`, `message_content`.

    :ivar str message: A stringified version of the message parameter
    :ivar dict[str, str] details: The error details. Depending on the error, this may include
     information like: `schema_id`, `schema_definition`, `message_content`.
    """

    def __init__(self, message: str, *args: Any, details: Optional[Dict[str, str]] = None) -> None:

ivar with an argtype including a comma or space is still not parsed correctly.