18 thoughts on “When Python sucks: how you call a function and document it”

1. Interfaces should help, right?

2. imo,

   > When Python sucks…
   python doesn’t sucks.

   > Because of duck-typing
   You may have forgotten how hard it is to use a strong typed language. How easy it is to make a mock object with python ? Dynamic typing is just what I really like with Python. “I’m in jail with Java”.

   > Most open source Python projects do the exact opposite
   You should remove the word Python from this sentence, it will still be true. But anyone can contribute !

   > Doctests are not documentation. They are tests.
   No, they are both, a documentation that tell a story. A doctest is a great answer for developer who want to know “how to use this ?”.

   Last but not least, opensource is about sharing great stuff, not complain about it.

3. This *is* improving as far as the standard library documentation goes. For 3.2, logging acquired extensive “how to” documentation that should hopefully make it easier for newcomers to pick up and use.

   The urllib how to has also been included as part of the documentation suite, but still needs to be better linked from the normal API reference documentation (patches to address http://bugs.python.org/issue11710 would be welcome).

   Most of the standard library is actually pretty good when it comes to stating API expectations, and the introduction of ABCs makes these criteria even easier to document accurately.

4. “You may have forgotten how hard it is to use a strong typed language. How easy it is to make a mock object with python ? Dynamic typing is just what I really like with Python. “I’m in jail with Java”.”
   Yes,but we always can improve.

   “You should remove the word Python from this sentence, it will still be true. But anyone can contribute !”
   But we can still improve

   “No, they are both, a documentation that tell a story. A doctest is a great answer for developer who want to know “how to use this ?”.”
   the problem here, some tests can be understood only if you know Python!

   “Last but not least, opensource is about sharing great stuff, not complain about it.”
   Complaining is part of OpenSource project “process”. Otherwise, how could it be improved ? Everybody is a potencial contributor, and for sure everybody is a customer.

5. > Because of duck-typing, you should rigorously document how methods should be called

   “How methods should be called” isn’t necessarily clear, especially without 2.7’s abcs: how do you express that you only care for __getitem__? Now how do you express it clearly and unambiguously?

   > (try epytext and its fields).

   Since you should have a Sphinx documentation and Sphinx has autodoc, write your docstrings using reStructuredText and Sphinx’s info fields (http://sphinx.pocoo.org/domains.html#info-field-lists) instead.

   > Most open source Python projects do the exact opposite

   What does that even mean?

   > Even Python standard library is poorly documented and sets a very bad example (missing manual ???)

   The missing manual you link to has nothing to do with input types, why do you even link to it?

   > The exception is something like Facebook or Google whose sole purpose is to attract new users their platform bringing in new €€€.

   Oh come on, you’re full of shit here. Projects like Django or Flask are exceptionally well documented, and stuff like ReadTheDocs are precisely trying to broadcast the importance of good documentations.

   > Doctests are not documentation. They are tests. They are extremely unreadable way to say “how I should use this thing”, because doctests are often executed in the context of test stubs which do not reflect connections to the other parts of the framework or real contexts.

   That’s incredibly stupid. Sure not all doctests are good examples/documentations (just as not all tests are good tests and not all documentation is good documentation), but the point of doctests is very much to be examples and part of the documentations. That’s why they are *doc* tests, not unittest test cases: they can be included in docstrings, in documentation body, etc… and demonstrate how the code is supposed to work, be used and “look”.

   Doctests are very much executable documentation and should be treated as such, they are essential tools of Python code documentation (not sufficient, note).

   > “Buy a book – it tells you everything” business model is not feasible in long run. Books get old. Books are not searchable. People don’t buy books.

   Are you still talking about Python at this point? I’ve rarely seen that attitude there (off the top of my head, web2py was the only major project that did this). Quite the opposite in fact.

6. I agree it is a pain. But if you go in the direction of verbose formal documentation, then you end up with Java-like Python. You loose Pythonic simplicity, and never will get fully working Java-like formalism. This is simply what Python is – you cannot add formalisms/static typing preserving “pythonic Python”.

   It’s why Python isn’t a good language for big, monolithic frameworks with deep abstractions like Zope…

   Of course complete lack of documentation isn’t “pythonic”. Or things like “**kwargs” instead of argument names. But requiring Javadoc/Epydoc style documentation would be unpythonic..

7. I suggest for all the comment writers to read the original linked article. Do not take it so seriously if I criticize a minor part of Python. I am a big Python lover and write a lot of documentation, after all 🙂

8. Also fixed the blank page after leaving a comment post. Was a problem with XDV and wordpress theming.

9. > Since you should have a Sphinx documentation and Sphinx has autodoc, write your docstrings using reStructuredText and Sphinx’s info fields (http://sphinx.pocoo.org/domains.html#info-field-lists) instead.

   Epytext’s fields are effectively same as Sphinx’s info fields. The major difference is that Sphinx docs are usually separated from the souce code whereas Epytext documents are generated from the source code. Please correct me if I am wrong. I have been doing both Epytext and Sphinx documentation and I found epytext approach nicer as I don’t need to keep separate files for API documentation – this way the documentation is more likely to stay up-to-date.

   > Most open source Python projects do the exact opposite

   Python community has not encouraging you to write good documentation. From my experience, documentation is often bad than it is good. As you mentioned, this situation is slowly being healed by ReadTheDocs and such projects. I wanted to highlight the importance of the documentation of API calls in this post.

   > The missing manual you link to has nothing to do with input types, why do you even link to it?

   I wanted to point out an example which some other author had seen. urllib module documentation was one of the most severe examples, how badly documented Python standard library can be. However, as other commenter pointed out, this thing is being fixed. Unfortunately I was not aware of this before, but hearing it made me very happy.

   > Oh come on, you’re full of shit here. Projects like Django or Flask are exceptionally well documented

   I think I mentioned in this my post, but let me repeat just in case that I agree with you here fully 🙂

10. sphinx can do both, extra documentation in rest, and source, reference documentation from docstrings (a la epydoc)

    autosummary extension to sphinx and online community editing (and several years of pushing to improve documentation)

    take numpy, scipy for example, or matplotlib (good documentation but still many **kwargs)

    http://docs.scipy.org/doc/numpy/reference/routines.statistics.html
    http://matplotlib.sourceforge.net/

    No problem with python, and documentation with opensource can be made to work

11. Hmm,
    I’ve tried to wade through Java ‘documentation’ for those large projects that consists of little more than extracted type signatures and maybe a list of what calls what.

    Due to Java’s penchant for turning even the simple task into a large reply withLongAndSoTheyMustBeBetterNames, as well as a mindset of “It compiles therefore it is good”, very little of it is reusable.

    Far better to have a succinct Python solutionwhere they know that if you don’t test – you don’t have anything; and where the language and community support documentation through docstrings and easy testing through doctests.

    Yes, Java may be optimised for large projects, but equally the language/community seems to attract those who turn most problems into large solutions.

    Java is no panacea. Python with C, C++, Fortran, Java, C#, D, … will be a better choice for more problems! (There are advantages to being a scripting language – they are made to embed and be embedded by other languages too).

12. I agree. I love python. i’m a beginner/hobbyist programmer and struggle with docs for the standard or outside written libs. They are written for experienced programmers. Same goes for some of the frameworks out there. People write these awesome web frameworks and make them public but have little to no docs for them. You have to be a seasoned python programmer who can traverse the source to be able to use these frameworks. I view these as web frameworks that are not written for serious public use but for the select skilled python groups only.

13. I do agree with the sentiment that documentation can always be better. Like many writing tasks you need to take the audience into account. I think even extensive documentation may not work for all users at various skill and experience levels.

    I wonder if Python3’s function annotations (http://www.python.org/dev/peps/pep-3107/) might help by adding very visible hooks for information about parameters and return values as well as better hooks for tools that want to introspect the code for that information.

14. Pingback: How does it do a date picker widget? | Open Source Hacker

15. > You may have forgotten how hard it is to use a strong typed language. How easy it is to make a mock object with python ? Dynamic typing is just what I really like with Python. “I’m in jail with Java”.
    I’d like to draw your attention to an happy medium between Python’s dynamic typing and Java’s nominal one : structural (sub-)typing, with type inference. It gives quite the ease of Python, without the silly interfaces and type declarations of Java (although for complex cases some local type annotations may be necessary).

    Some languages (like the object part of OCaml) already implements it, if you need an example : in the following, I define a function, wich argument is supposed to implement a `quack` method. OCaml infers the types by itself, without restriction (please notice the `..` in the inferred type for `x`).

    # let print_duck x =
    print_endline x#quack;;
    val print_duck : -> unit =

    I’m not trying to sell you OCaml. It obviously doesn’t make you as productive as Python. However, I would like to know what Python programmers think of this approach.

16. Amen!

    IMHO Python has a real weakness when it comes to documenting function input and outputs.

    Even in the standard library I often find myself wondering what type a function returns and how to interpret it. The upshot is that a simple documentation lookup takes too long time.

17. I know it is a late comment, but I wanted to say, that strong typed languages are hard to use is a retarded argument. Type errors are serious errors, it means that parts of your program won’t interoperate with other parts of your program. And it also means, that you haven’t understood parts of the program, that it works differently than you intended.

    Java is not hard because it is stongly typed, it is hard, because the language doesn’t offer the programmer enough tools to work with it. The language simply sucks. Eg: C++(11) is a breeze compared with java and offers a lot of tools, which makes typing easier.

18. @pipo, Python *is* strongly typed, as well as being dynamically typed. Did you intend to make a distinction between manifestly statically typed languages and others?