3 ms·

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 functio

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.

vbernat 10y ago
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 https://docs.python.org/2/library/re.html#module-contents
- snovv_crash 10y ago
  Agreed, but my point is that argument and return types are badly documented, and in Python autogen doesn't help this.
  - nitely 10y ago
    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.
    - snovv_crash 10y ago
      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.
lqdc13 10y ago
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.
- snovv_crash 10y ago
  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.
  - int_19h 10y ago
    > 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?
d0mine 10y ago
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 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 https://gist.github.com/non/ec48b0a7343db8291b92
- snovv_crash 10y ago
  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.

vbernat 10y ago

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 https://docs.python.org/2/library/re.html#module-contents

snovv_crash 10y ago
Agreed, but my point is that argument and return types are badly documented, and in Python autogen doesn't help this.
- nitely 10y ago
  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.
  - snovv_crash 10y ago
    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.

lqdc13 10y ago

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.

snovv_crash 10y ago
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.
- int_19h 10y ago
  > 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?

d0mine 10y ago

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 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 https://gist.github.com/non/ec48b0a7343db8291b92

snovv_crash 10y ago
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.