[pyos][suggestion] Type hints on i/o functions

[sneakers-the-rat]

Not going to suggest going through and adding type hints to all possible functions, but I think they would be especially useful on the i/o functions since you are traversing libraries and types - this would help the already good interoperability in mixed contexts where people are converting to and from different types, help people know what to expect with static analysis tools. I recognize that you might not have the correct packages imported/installed since they are optionals, but there are a few strategies that might work there -- splitting up the i/o module into a package with submodules where you try and import the necessary packages at the module level and then use string type hints:

something like...

IMPORTED = False
try:
    import networkx as nx
    from networkx.classes.digraph import DiGraph
    IMPORTED = True
except ImportError as e:
    # probably some logging idk
    raise e
    

def to_networkx(m, edge_attribute:str='weight') -> 'DiGraph':
    ...

that's pretty clumsy but hopefully illustrates the idea.

part of: pyOpenSci/software-submission#81

[eriknw]

We've been (slowly) exploring type annotations for a while now in #179.

The argument and return types are already in the numpydoc-style docstrings, so how useful is it to have inline type annotations as well?

I think the approach we are leaning toward is to add stub files for type annotations. If we do this, does it make sense to add inline annotations to some functions?

splitting up the i/o module into a package with submodules

This actually sounds reasonable to me.

Another approach for doing what you want may be to add e.g.:

import typing

if typing.TYPE_CHECKING:
    try:
        from networkx import DiGraph, Graph
    except importError:
        ...