Try to use type hints

[Zeroto521]

Since Python3.5 supports for type hints. It could be better than writing docstring at sometimes.

Such as follow example. We can learn from code a lot directly rather than docstring.

Before

def get(url, qsargs=None, timeout=5.0):
    """Send an HTTP GET request.

    :param url: URL for the new request.
    :type url: str
    :param qsargs: Converted to query string arguments.
    :type qsargs: dict
    :param timeout: In seconds.
    :rtype: mymodule.Response
    """
    return request('get', url, qsargs=qsargs, timeout=timeout)

Later

from typing import Dict, Optional

def get(url: str, qsargs: Optional[Dict] = None, timeout: float = 5.0) -> mymodule.Response:
    """Send an HTTP GET request.

    :param url: URL for the new request.
    :param qsargs: Converted to query string arguments.
    :param timeout: In seconds.
    """
    return request('get', url, qsargs=qsargs, timeout=timeout)

[amontalenti]

Love this suggestion! Thanks @Zeroto521.

This is also related to #45 which I opened a couple weeks ago, and to PR #4 (which has been open way too long, I realize).

I also recently discovered myst-parser (as I tweeted here) which seems like it provides a Markdown-ish way to provide docstrings and have them still be compatible with Sphinx. The question of how & whether to mix standard reST, Markdown, typing, and sphinx is definitely a question of style and deserves good coverage here!