3 ms·
Started to use python recently, coming from Go, I found: - the official docs are useless, return types are often not documented (wtf ?) and docs aren't structu
by aikah 10y ago
Started to use python recently, coming from Go, I found:
- the official docs are useless, return types are often not documented (wtf ?) and docs aren't structured and clean. Python documentation is a giant mess.
- mypy is a god sent I used it from day one to document my Python code, but it needs better integration with python doc tools, 3rd party linters and co.
I'm ok with optional type checking. A team can make it mandatory during continuous integration while not breaking legacy code, but I hope mypy will be directly integrated to Python in the future and not a 3rd party tool.
- ubernostrum 10y agoCould you give some examples of functions in the standard library (or built-ins) which don't document their return types?
- hawski 10y agoI sometimes have to write some python script. The documentation documents return (and expected) types, but in a manner that is a bit alien to C or C++ programmers. It is more talky. It is probably in dynamic nature of python. Instead of a list of possible returns with some kind of prototypes you may be left with description: "The returned object is always a file-like object whose file attribute is the underlying true file object.". See for example documentation for tempfile.NamedTemporaryFile [1]. This time possible returns are not in the separate paragraph as is in many other cases. You can't click anything expect TemporaryFile(), so you have to search for proper reference. The information is there, but instead of quick glance you have to parse and search more text. [1] https://docs.python.org/3.6/library/tempfile.html https://docs.python.org/3.6/library/tempfile.html
- orf 10y agoThe python3 docs are great, do you have any specific pages that you found issues with?