It was very productive for the person who wrote the library.

Would you be able to share an example of this?

I took a random stab in pandas but they’ve adopted type annotations so that defeats the point. So i thought old-school code bases - zope sprang to mind, but that’s not a good example either because they use docstrings and it’s kind of obvious. So i tried gunicorn on a whim and they have even more attention spent on their docstrings.

I just want to sample this feeling of lost confusion in python so that i can figure out how I’d deal with it.

I was actually looking at urllib3 yesterday trying to work out the return value from HTTPConnection.connect which calls this _new_conn function internally:

    def _new_conn(self):
        """Establish a socket connection and set nodelay settings on it.

        :return: New socket connection.
        """
  ...
        try:
            conn = connection.create_connection(
                (self._dns_host, self.port), self.timeout, **extra_kw
            )
  ...
        return conn

(I've chopped it down a bit to emphasise the important bits)

What's the type of "conn"? It certainly wasn't clear to me that it's a socket.

But just now I looked at upstream and I notice they've added type annotations, which do greatly improve things:

https://github.com/urllib3/urllib3/blob/e16beb210c03c6f5ce4e...

    def _new_conn(self) -> socket.socket:
  ...

So a small victory for type annotations there.

When i hover over connection.create_connection i get a docstring that says it returns a socket.

That docstring isn’t enough for the problem you had though, e.g. I wasn’t clear from that if they meant a socket.socket or maybe some special socket derivative type so i hit go to definition and create_connection is a short method - i can see it is indeed a socket.socket being created, configured and returned.

I’m guessing you’re not using any developer tooling, maybe a straight text editor i guess?

This kind of tooling has been around for a long time, i remember using rope and jedi in vim back around the late 2000’s i think. It’s gotten a LOT better since PyCharm appeared mid 2010’s i think - first i recall using it must have been around 2014-ish. These days, it’s even better. I would really strongly encourage adopting some kind of tooling that lets you navigate and has some basic refactoring - rename is usually 80%+ of the value there so it doesn’t need to be complex. A few ergonomics like having the ability to jump to test and call from repl with a keystroke - you’ll turbo charge your comfort and productivity.

That has to be our difference i think because it took one mouse move and one key chord to completely bottom out.

Well, the author of that undocumented function maybe did not mean for it to become widely used.

There are a lot of "libraries" people write for their use only, who then put them on Github as a token of good will.

You as a user of someone else's library can either contribute to it or learn to use it. Otherwise, write your own equivalent.

> Otherwise, write your own equivalent.

And be judged for wasting time reinventing a wheel?

Hey, it is still your wheel, built according to your use-cases.

That is never a waste of time.