Survey: improving the Python std lib docs

[Chris Angelico]

On Thu, May 18, 2017 at 8:11 AM, Michael Torrie <torriem at gmail.com> wrote:
> On 05/17/2017 02:31 PM, Ned Batchelder wrote:
>> Can you give an example of such a method? Often, that signature is used
>> because there is no pre-conception of what the arguments might be.
>
> I'm not sure if this afflicts the standard library, but in my own code,
> since Python doesn't support constructors with different signatures, you
> pretty much have to rely on kwargs with __init__() to handle different
> permutations of construction arguments.  Not that we don't know what the
> arguments might be, we just don't know which of them we'll have to deal
> with.  Maybe the standard library is better designed than my own code,
> but I find I have to implement __init__(self, **kwargs) all the time.

Also worth noting is that decorators sometimes have to go *a,**kw on
their functions. Until a couple of versions ago, help() would always
just show *a,**kw, but now there's a protocol between
functools.wraps() and help() that carries the original signature
through. Depending on exactly where you're viewing the info, eg
whether it uses inspect.getsignature or not, you might see the carried
original, or you might see *a,**kw.

ChrisA