Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > comp.lang.python > #74065 > unrolled thread

Re: How do you use `help` when write your code

Back to article view | Back to comp.lang.python

This discussion starts older than the indexed window; earlier articles aren't shown. The article labeled Started by below is the oldest one visible, not the original post.

Contents

  Re: How do you use `help` when write your code Ben Finney <ben@benfinney.id.au> - 2014-07-07 10:53 +1000

#74065 — Re: How do you use `help` when write your code

Shiyao Ma <i@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
function call.

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 |
_o__)                                                                  |
Ben Finney

[toc] | [standalone]

Back to top | Article view | comp.lang.python

csiph-web