How do you use `help` when write your code
ben at benfinney.id.au
Mon Jul 7 02:53:00 CEST 2014
Shiyao Ma <i at introo.me> writes:
> My normal workflow is use ipython, obj? or obj?? for quick look up or
> use docs.python.org for a detailed read.
I don't use IPython. I'm glad it exists for those who want it.
I frequently use Python on hosts not entirely under my control, where I
don't have authority to install new packages, and which only have stock
Python installed. So I have to be familiar with IDLE and the standard
Python interactive shell.
I also find IPython of questionable value when teaching Python to
newcomers: its interactive features diverge quite markedly from what is
available when writing Python code in a file, so it turns out to be too
distracting for someone learning the language.
Using the standard Python interactive shell, at least, means what a
newcomer learns t the shell is almost entirely transferable to what they
need to do to get code into a module's source code.
As for the powerful features available in IPython, I find that I get
most of them from a Python-aware programmer's editor like Emacs, which
also gives me a powerful interactive environment that does more than
only Python code.
So it would be, IMO, a mistake for me to become too reliant on
IPython-specific functionality. It's a high, specific investment that
doesn't pay off well on other machines (which commonly don't have it
immediately available) or other languages which I need to use.
> Do you use `help`? How does it integrate into your workflow?
I very often use ‘help(foo)’ at the Python interactive prompt, to get a
quick reference to what an object's attributes and features are.
There are two common cases where ‘help(foo)’ is unable to help:
* If ‘foo’ is a function written without using keyword-only args, but
needing to have a bunch of keyword arguments, the signature will often
be the uninformative ‘foo(*args, **kwargs)’. A docstring is crucial
here, but it's too often wrong or absent.
I look forward to more and more functions migrating to use
keyword-only arguments for these cases, so the function signature can
become much more informative in ‘help’.
* If ‘foo’ is a function implemented in an extension (non-Python)
module, the signature ‘foo(...)’ is utterly useless. Here, again, the
docstring is crucial; and it is frequently just a terse one-liner with
no good explanation. Even the standard library is rife with unhelpful
function docstrings of this kind.
Other than those caveats, I find browsing ‘help(foo)’ output is very
helpful in an interactive session, not least for getting information
quickly about an unknown object I've generated from some third-party
It is a very good feature that ‘help(foo)’ for a class instance shows
the help of the class: it can be used indiscriminately, and is thus
easier to recommend as a mental habit.
> Or instead, what similar tools do you use?
I have the ‘python-doc’ and ‘python3-doc’ packages installed locally,
and this gives instant access to the whole Python documentation in my
browser without any lag or network dependency.
The ‘logging’ module is a standard feature and makes it much easier to
emit informative debugging statements that (unlike ad-hoc ‘print’ calls)
*don't* need to be removed later. Logging can also reveal a lot about
the objects while the program is running, as a valuable complement to
the ‘help’ feature and online documentation.
\ “Puritanism: The haunting fear that someone, somewhere, may be |
`\ happy.” —Henry L. Mencken |
More information about the Python-list