Path: csiph.com!usenet.pasdenom.info!weretis.net!feeder4.news.weretis.net!rt.uk.eu.org!newsfeed.xs4all.nl!newsfeed3a.news.xs4all.nl!xs4all!newsgate.cistron.nl!newsgate.news.xs4all.nl!post.news.xs4all.nl!not-for-mail
Return-Path: <rosuav@gmail.com>
X-Original-To: python-list@python.org
Delivered-To: python-list@mail.python.org
X-Spam-Status: OK 0.018
X-Spam-Evidence: '*H*': 0.96; '*S*': 0.00; 'else:': 0.03; 'debug': 0.07; 'subject:code': 0.07; 'subject:help': 0.08; 'arguments': 0.09; 'arguments,': 0.09; 'instance.': 0.09; 'subject:How': 0.10; 'cc:addr:python-list': 0.11; 'def': 0.12; 'args,': 0.16; 'docstring': 0.16; 'finney': 0.16; 'from:addr:rosuav': 0.16; 'from:name:chris angelico': 0.16; 'ought': 0.16; 'subject:when': 0.16; 'wrote:': 0.18; 'written': 0.21; 'cc:addr:python.org': 0.22; 'print': 0.22; 'mon,': 0.24; 'cc:2**0': 0.24; 'pass': 0.26; 'gets': 0.27; 'header:In-Reply-To:1': 0.27; 'function': 0.29; 'am,': 0.29; 'message-id:@mail.gmail.com': 0.30; 'bunch': 0.31; 'informative': 0.31; 'class': 0.32; 'another': 0.32; 'cases': 0.33; 'problem': 0.35; 'common': 0.35; 'but': 0.35; 'received:google.com': 0.35; 'there': 0.35; 'version': 0.36; 'functions.': 0.36; 'keyword': 0.36; 'useful': 0.36; 'wrong': 0.37; 'too': 0.37; 'two': 0.37; 'ben': 0.38; 'issue': 0.38; 'unable': 0.39; 'skip:u 10': 0.60; 'most': 0.60; 'lost': 0.61; 'skip:* 10': 0.61; 'information': 0.63; 'skip:n 10': 0.64; 'become': 0.64; 'more': 0.64; 'forward': 0.65; 'needing': 0.65; 'skip:\xe2 10': 0.65; '8bit%:40': 0.68; 'jul': 0.74; 'subject:your': 0.76; 'subject:you': 0.87; 'crucial': 0.91; 'migrating': 0.91; 'to:none': 0.92
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=mime-version:in-reply-to:references:date:message-id:subject:from:cc :content-type:content-transfer-encoding; bh=KWMZZSAtQqYG8fS7IlEXYcLpUM59JJc5sCicfMuRj1o=; b=KIaq79UGuJF6Lm6kQEHPgVUNdv8lufJgyf+icg2s7EKnVcYUQpZtII+a+wQzFj8z9P LcRMdnSDY4L6vpc0pmptmbWQnOZ6HMfdJT4m6LpZx/sz4FC6CoMLsHDs6DUK190FEzgm X0RE/keg+VG87b+oNVnOsAVvpTutpfNr7W9O4XTMmgvLlipsV2Wnd9dfuHtKXbeRO5Um Lu1tv9YiQERqdig4IcoG7AtEb06WSHqLcOi67NIPujmXrNHsEfx3DWHsz01MD7DrtT6K qdiCZXpNeSqDCcajWx+Dnotdr3ykTO51+0c/PGocLnsUXunnBwtbTgRdQYmdpsdqMW1J gVjQ==
MIME-Version: 1.0
X-Received: by 10.52.171.18 with SMTP id aq18mr8429779vdc.45.1404701887229; Sun, 06 Jul 2014 19:58:07 -0700 (PDT)
In-Reply-To: <85a98mvvkj.fsf@benfinney.id.au>
References: <CAJQX3DwnP24cnhofL2P90V3ux2oz2jT0p2KBDVOaUcWuteijbw@mail.gmail.com> <85a98mvvkj.fsf@benfinney.id.au>
Date: Mon, 7 Jul 2014 12:58:07 +1000
Subject: Re: How do you use `help` when write your code
From: Chris Angelico <rosuav@gmail.com>
Cc: "python-list@python.org" <python-list@python.org>
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: quoted-printable
X-BeenThere: python-list@python.org
X-Mailman-Version: 2.1.15
Precedence: list
List-Id: General discussion list for the Python programming language <python-list.python.org>
List-Unsubscribe: <https://mail.python.org/mailman/options/python-list>, <mailto:python-list-request@python.org?subject=unsubscribe>
List-Archive: <http://mail.python.org/pipermail/python-list/>
List-Post: <mailto:python-list@python.org>
List-Help: <mailto:python-list-request@python.org?subject=help>
List-Subscribe: <https://mail.python.org/mailman/listinfo/python-list>, <mailto:python-list-request@python.org?subject=subscribe>
Newsgroups: comp.lang.python
Message-ID: <mailman.11569.1404701890.18130.python-list@python.org>
Lines: 33
NNTP-Posting-Host: 2001:888:2000:d::a6
X-Trace: 1404701890 news.xs4all.nl 2901 [2001:888:2000:d::a6]:48439
X-Complaints-To: abuse@xs4all.nl
Xref: csiph.com comp.lang.python:74070

On Mon, Jul 7, 2014 at 10:53 AM, Ben Finney <ben@benfinney.id.au> wrote:
> There are two common cases where =E2=80=98help(foo)=E2=80=99 is unable to=
 help:
>
> * If =E2=80=98foo=E2=80=99 is a function written without using keyword-on=
ly args, but
>   needing to have a bunch of keyword arguments, the signature will often
>   be the uninformative =E2=80=98foo(*args, **kwargs)=E2=80=99. A docstrin=
g 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 =E2=80=98help=E2=80=99.

Most common cause of this problem is when a function ought to have
functools.wraps but didn't.

if DEBUG:
    debug =3D print
else:
    @functools.wraps(print)
    def debug(*a, **kw): pass

Without wraps(), the non-debug-mode version of debug() is completely unhelp=
ful.

There's another issue with help(), and that's when it's used on a
large class - it's not that it's unhelpful, it's more that the useful
information gets lost in the spam of a pile of dunder functions. Check
out help(1) for instance.

ChrisA