Contrast this with the ugly-but-functional JavaDocs, which can be auto-generated, and easily shows all return types and arguments for every publicly exposed function and member variable. I understand why this can't be done automatically in Python, but at least they could put the time in to make it clear in their standard libraries.
IMO, this is something positive. You can decide the structure of your documentation and include only the most relevant references.
For example, this part of the documentation for the re module is autogenerated from code: https://docs.python.org/2/library/re.html#module-contents
IMHO, python docs are ok. If you struggle with them as a beginner I don't see what would change as an advanced programmer.
I shouldn't have to read code snippets to figure out if a function returns a tuple or a 'group' which can be iterated over, but can't be indexed. This is something which would be fixed if the documentation included types, because then I could check what all the allowable operations on 'group' are directly without searching for a code snippet which does what I want or just running it and praying I got it right.
Typical workflow for Java: This function takes in these object types as inputs... Then you have to wonder how to get those object types so you scour through 10 more pages of docs to figure that out. You end up creating a factory of a factory of a factory to make that input object only to find out that it has to be further preprocessed by sending it somewhere else.
Typical workflow for Python: read docs, try out an example in the interpreter by passing a basic object type to the function (such as string or dict), copy code from interpreter into text editor. You are done.
I really love Python docs. It takes me seconds to find what I want and figure out how to use it. I hope they don't change anything.
The issue I run into in Python is that I need to call something which takes * args or * * kwargs, and the only way I know any of the arguments exist at all is because of some snippet of code on github, probably by the person who implemented the feature in the first place. Even if the argument is named I don't know if it should be a magic number which is defined in some enum-like class, a boolean, or a string to describe the name of what I want and pray that the library maintainers used the same capitalisation and localisation that I think is most logical. In fact, without looking at example code, I literally have no clue how to do anything.
As such, with Python I end up doing copy-paste programming which is dependant on my internet speed and how many other people had the same problem already. With C/C++/Java I tend to do a more build-it-from-scratch style programming, driven mostly I think by the style of the documentation.
But factories etc are idiomatic Java. You can avoid it in the code that you write, sure, but how do you avoid it in the third-party libraries that you use?
For example, the builtin print() function accepts any object with write(string) method as the file parameter. There are ABCs classes that capture the "duck" essence but it would be an unnecessary pessimization to require a io.TextIOBase instance as the file parameter in this case. Don't write Java in Python. Go's io.Writer would work in this case (the type label as the documentation and the exact specification) but if you don't mind thinking about type labels and/or believe that the type of bugs that can be found by a compiler worth the trouble instead of just writing tests and expressing directly what you want the code to do then using a statically typed language make sense.
Though there are type hints (proposed by BDFL) in the recent Python (to enable better static analysis, IDEs code completion and refactoring) https://docs.python.org/3/library/typing.html If its usage is not limited (e.g., through Python culture convention); it could be a regression in Python evolution. If your API is so enormous that you need type labels; you should split it. Python code should communicate the intent to a human first over a compiler/static analysis tool.
Here's a static typing programmer perspective (how it feels) on dynamic languages "What is the appeal of dynamically-typed languages?" https://gist.github.com/non/ec48b0a7343db8291b92
Can I index the returned object, or only iterate over it? Is it mutable? Is it a dict or a tuple of (key,value) tuples? Did the author think it was worth it to make its own class for the return type, because they want the indexes where the value was found as well as the metadata?
Python, to a degree, brushes over these problems by being able to print out most types of data and then figure out where the problem is, but TBH I'd prefer to write the correct code to begin with, and the docs don't give me enough information to do so. As such, Python turns into a dodge-the-error-driven-programming, and I feel much less productive than I could be.
Yes, duck-typing gets you part of the way, but it doesn't let you pretend type doesn't exist entirely.
I feel like using Go's interfaces would be more powerful for a duck-typing language than having type-annotations.
I don't get this... Why not do the following:
In [1]: import requests
In [2]: resp = requests.get('http://www.google.com')
In [3]: resp.
resp.apparent_encoding resp.iter_lines
resp.close resp.json
resp.connection resp.links
resp.content resp.ok
resp.cookies resp.raise_for_status
resp.elapsed resp.raw
resp.encoding resp.reason
resp.headers resp.request
resp.history resp.status_code
resp.is_permanent_redirect resp.text
resp.is_redirect resp.url
resp.iter_content
>>> import requests
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
ImportError: No module named 'requests'
If Python wants to remain a scripting language forever then the docs are sufficient. But if it wants to graduate, and it seems a lot of people think it already has, then the libraries need to be better documented.
They might not be the best, but they aren't what the author says like 'we just can't understand shit'
Python's docs have improved, but they're not amazing. Then again, neither are the docs for many other languages. For example, I'm a big fan of Clojure, but many of the docs there have me really appreciating Python's docs ;-)
I think once you get used to Pythons docs, they're pretty easy to follow, although I agree that type information on arguments/return values would be great and I also largely work from examples unless I'm already familiar with a library and am just looking for reference material.