Extra () after NewType

[miohtama]

I am maintaining some Python API documentation for Ethereum and Web3.py ecosystem.

To improve the readability of the API documentation, I stumbled upon on your very useful sphinx-autodoc-typehints plugin. IMHO I feel this should be a core feature for apidocs.

I am generating some docs on Python 3.9 that use "custom" types. However, an unnecessary NewType() appears in the generated doc output. This comes form the custom types defined in eth-typing modules.

Any way to suppress this or hack around this?

Here is the function signature.:

from eth_typing import ChecksumAddress, BlockNumber, HexAddress
from web3 import Web3

def fetch_erc20_balances(web3: Web3, owner: HexAddress, last_block_num: Optional[BlockNumber] = None) -> Dict[HexAddress, int]:
    """Get all current holdings of an account.

    We attempt to build a list of token holdings by analysing incoming ERC-20 Transfer events to a wallet.

    The blockchain native currency like `ETH` or `MATIC` is not included in the analysis, because native
    currency transfers do not generate events.

    We are not doing any throttling: If you ask for too many events once this function and your
    Ethereum node are likely to blow up.

    Example:

    .. code-block:: python

        # Load up the user with some tokens
        usdc.functions.transfer(user_1, 500).transact({"from": deployer})
        aave.functions.transfer(user_1, 200).transact({"from": deployer})
        balances = fetch_erc20_balances(web3, user_1)
        assert balances[usdc.address] == 500
        assert balances[aave.address] == 200

    :param web3: Web3 instance
    :param owner: The address we are analysis
    :param last_block_num: Set to the last block, inclusive, if you want to have an analysis of in a point of history.
    :return: Map of (token address, amount)
    """

Here is the example output:

[gaborbernat]

This is working as expected, the Hexstr is not a class, but a new type instance that makes a restriction in strings. https://docs.python.org/3/library/typing.html#newtype

The one thing that does seem strange is a superfluous () after new type.

[miohtama]

Can I somehow instruct sphinx-autodoc-typehints not to expand new type instances, because in my particular case it reduced the readability of the documentation?

[gaborbernat]

No, that would be contrary to the current design philosophy. The same way type aliases are extended this is too. One could add a flag for this but adding such feature might be quite involved PR, you're free to try to create that.

[miohtama]

Thank you so much @gaborbernat - I am choosing not to fight on this hill for now.

[gaborbernat]

I'll keep this issue open to remove the extra () after the NewType.