Hacker News Reader

Comment by snovv_crash | Hacker News Reader

Coming from statically typed languages, I've really struggled with the Python docs, because they aren't really clear with what is returned from a lot of functions, and which arguments are allowed. I end up finding an example where it is being used, then deducing from what they do with the result what was actually returned.

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.

View on HN

To provide a counterexample, it takes me forever to figure out how to do something after reading Java/Cpp docs, but I instantly know how to do it in Python after reading the docs.

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.

That's more to do with coding style. I abhor reflection and factories, so if I write Java I don't use them. That said, you can end up writing a RandomNumberGeneratorFactory in Python just as easily if you are trying to achieve the same scaling and re-usability requirements that the Java program is.

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.

> I abhor reflection and factories, so if I write Java I don't use them.

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?

I've been lucky enough to use Java for fun, not work, and as such I have the time to write things the way I feel they make the most sense.

The advantage of Python is that you do not need to think about type labels: "If it looks like a duck, swims like a duck, and quacks like a duck, then it probably is a duck."

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

Wholly agreed about not writing Java in Python, and I do write idiomatic Python. The problem is that I don't know what methods the returned objects have available, and as such whether they are a duck or a tiger. The examples show that it has a mouth and eyes, but I need to know whether it has wings or claws, and Python's docs don't make that clear.

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.

"The problem is that I don't know what methods the returned objects have available, and as such whether they are a duck or a tiger."

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

Now you can try each of those things and explore their methods.

    >>> import requests
    Traceback (most recent call last):
      File "<stdin>", line 1, in <module>
    ImportError: No module named 'requests'

Now, what was your question?

Because I'm not always scripting - sometimes the work I'm doing takes 10 minutes of runtime to get to the end and I want to know what I'm writing before I run it.

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.

If you don't know whether a method returns an iterator or a mutable/immutable sequence (regardless of the specific type) then the documentation is incomplete (it is a bug). If it is in stdlib; you could submit a documentation patch for a *.rst file on https://bugs.python.org/ See https://docs.python.org/devguide/docquality.html

Python also uses autogeneration for most of the documentation, but the documentation itself is not fully autogenerated. You write your documentation and you say to Sphinx: put the generated documentation for this module here.

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

Agreed, but my point is that argument and return types are badly documented, and in Python autogen doesn't help this.

Usually there are examples for everything. Sometimes you have to scroll down, though. What the function returns is usually stated in the description. But I know what you are saying, actually most 3-party libs do document types.

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 am 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.

Reply on news.ycombinator.com