3 ms·
The number of times I've stared at some random Python function deep inside a library wondering what does this function return? Even the docs often don't say.
by rwmj 5y ago
The number of times I've stared at some random Python function deep inside a library wondering what does this function return? Even the docs often don't say.
- oriolid 5y agoIt was very productive for the person who wrote the library.
- wheelerof4te 5y agoWell, 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.
- oriolid 5y ago> Otherwise, write your own equivalent. And be judged for wasting time reinventing a wheel?
- wheelerof4te 5y agoHey, it is still your wheel, built according to your use-cases. That is never a waste of time.
- CraigJPerry 5y agoWould 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.
- rwmj 5y agoI 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/e16beb210c03c6f5ce4e0908bddb6556442b6a37/src/urllib3/connection.py#L200 https://github.com/urllib3/urllib3/blob/e16beb210c03c6f5ce4e... def _new_conn(self) -> socket.socket: ... So a small victory for type annotations there.
- CraigJPerry 5y agoWhen 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.