Add networkx stubs

[rhelmot]

networkx is a widely used library for graph analysis in scientific computing. It is a great candidate for type checking because it is absolutely full to the brim of container types. It is also unlikely to have types merged into upstream anytime soon. See discussion in the staging repository for this PR: fmagin/networkx-stubs#8

These stubs are by no means complete. They are complete for my personal use case (digraphs) and I spent about 3 hours trying to bang out correct stubs for everything else, but this library is gigantic. Everything I didn't get to remains the stubgen defaults. If this isn't the convention and I just just delete the unmodified stuff, please let me know!

The main concern I have is that this library has a few optional dependencies and has public interfaces which take types from these dependencies. These dependencies are declared as extras, so I believe the CI machinery here should be able to handle it, but some of them do not themselves have types available through any venue. I am not adding types to scipy. This triggers some type errors, and I don't know if those will be an issue. Please advise :)

cc @fmagin @Avasam

[rhelmot]

I have attempted to fix all the issues!

One problem I ran into is that mypy is very unhappy with the way I tried to express a common pattern in networkx which would be a lot easier with higher-kinded types:

def builder_func(something: SomeCollection[T], create_using: Type[GenericGraph[T]]) -> GenericGraph[T]: ...

GenericGraph here should be a TypeVar bounded to Graph, but that's obviously not an option. Instead. I tried typing four overloads for each function like this, one for Graph and each of its subclasses, but that results in the admonition that the latter overloads will never be used because the first one is broader. How can I work around this?

Another overload-related problem that mypy complains about is the pattern of changing the return type based on a flag parameter, True to enable returning a specialized subclass instead of the simpler base case. For example:

    @overload
    def __call__(
        self,
        nbunch: NBunch[_Node] = ...,
        data: Literal[False] = ...,
        default: Incomplete = ...,
    ) -> OutEdgeView[_Node]: ...
    @overload
    def __call__(
        self,
        nbunch: NBunch[_Node] = ...,
        data: Literal[True] = ...,
        default: Incomplete = ...,
    ) -> OutEdgeDataView[_Node, tuple[_Node, _Node, dict[str, Incomplete]]]: ...
    @overload
    def __call__(
        self, nbunch: NBunch[_Node] = ..., data: str = ..., default: _U | None = None
    ) -> OutEdgeDataView[_Node, tuple[_Node, _Node, _U]]: ...

To me, this seems unambiguous. However, mypy is adamant that Overloaded function signatures 1 and 2 overlap with incompatible return types, ditto for 1 and 3. What can be done?

[Avasam]

@rhelmot Are you still interested in completing this PR? My suggestions above should get you pretty close. I am interested in seeing networkx stubs into typeshed and out of microsoft/python-type-stubs.

[rhelmot]

I am still interested, I just have a lot on my plate. If you'd like to push the project along, feel free to open a pull request to my fork.

[rhelmot]

I am trying to merge in the networkx 3.2 changes. this could take a moment.

[rhelmot]

I would say this is ready to merge even though it still targets an old version.

[Avasam]

@rhelmot Quick update, since I am now a Contributor to the typeshed project on GitHub, I can update your branch directly and apply the above suggestions. If that's something you'd like to save you some time.

I just have a lot on my plate. If you'd like to push the project along, feel free to open a pull request to my fork.

[rhelmot]

Yes, I would appreciate that, thank you!

[github-actions]

According to mypy_primer, this change has no effect on the checked open source code. 🤖🎉

[Avasam]

Thanks a lot @rhelmot for the migration from https://github.com/fmagin/networkx-stubs !

This PR is now in a state I'd feel confortable merging knowing that it is not meant to be a complete stub. Any non-obvious typing decision have been documented as comments. There's a substantial amount of manual typing in some modules, so I'll give a couple weeks for other maintainers to take a quick look, see if I missed anything.

Once merged, the next steps as far as I'm concerned would be:

• Update to 3.2, see Add networkx stubs #10544 (comment) as to why that wasn't done in this PR.
• Use stubgen to add missing symbols and modules
• Ensure parity with https://github.com/microsoft/python-type-stubs/tree/main/stubs/networkx

[Avasam]

It's been a couple weeks and I don't see any objection. In it goes! Thanks again @rhelmot . I'll probably take on parity with https://github.com/microsoft/python-type-stubs/tree/main/stubs/networkx next.