Provide stub files

[moepman]

I wonder if it would be possible to provide stub files [1] which would help type checkers such as mypy or code completion for IDEs such as PyCharm [2].

[1] https://www.python.org/dev/peps/pep-0484/#stub-files
[2] https://youtrack.jetbrains.com/issue/PY-51039

[svinota]

Technically I see no reason not to provide; but I might be limited in resources and I'm not sure I can provide these files in a timely manner.

Let me try to investigate. And for sure any PR:s are more than welcome.

Though we have to be careful reviewing supported Python versions under 3.9.

[svinota]

@moepman I've tried to autogenerate the stub files, but it looks like full auto is difficult next to impossible — I have to fix the stub files manually in order to have it working.

So any help in automation is more than appreciated. I see no possibility to manually maintain this big set of the stub files.

[vincentchov]

Will this go somewhere on the project roadmap? I'm not familiar enough with how the project works to do it, but if there could be a developer's guide on how you generate the stubs and test them, along with priorities, that would be helpful to have multiple people work on little pieces at a time.

My use case for typing might be simpler than others', but I'm not sure. I want Docker containers running in the default bridge mode (but with user-defined networks, as the Docker documentation recommends using) to be able to find the IP of the host so it can make requests to services on the host that:

• aren't running in Docker, or
• to containers using host networking, which therefore can be reached by referring to the host IP

I try to do that by finding the container's bridge network's gateway IP (ie 172.18.0.1) so it can be used in place of localhost without having to manually use docker network inspect and passing in the IP. For context, calling localhost from inside a Docker container using default bridge networking will go to localhost of the container, not the host.

The type error I get says "NDB" is not a known member of module". If the type checker could be aware of NDB and be aware of the properties ndb.routes, ndb.routes.summary, and routes_summary.select_records without necessarily caring about the function parameter types, that should be good enough for me, at least for a start.

Here's my code:

def find_host_ip_from_docker():
    ndb = pyroute2.NDB()
    routes_summary = ndb.routes.summary()
    routes_summary.select_records(
        gateway=lambda g: bool(g),
        ifname=lambda i: i == "eth0",
        target=lambda t: t == "localhost",
    )
    routes = list(routes_summary)
    route = routes[0]
    return route.gateway

Thanks and I hope I can be of some help!

[uSpike]

Are you open to in-line type hints? Stubs are OK but they can be more work to keep up to date.

[svinota]

I'm open to anything :) I plan also to move back to the static re-exports in the __init__ files instead of entry points. I just have to make it working for the two package versions (full and minimal), this should be done soon.

[svinota]

The static library init is available on the branch https://github.com/svinota/pyroute2/tree/svinota-static-loader-1076

If there will be no negative feedback, it will be merged into the master branch this week. Personally I like it less than usin entry points 'cause of possible CI issues, but if this will help you, then it's ok, as in the end the library is for users, not for the CI :)