[Python-ideas] Better Type Hinting

[Stephen Hansen]

On Thu, Jun 4, 2015, at 11:01 PM, Andrew Barnert via Python-ideas wrote:
> On Jun 4, 2015, at 22:36, Thomas Güttler <guettliml at thomas-guettler.de>
> wrote:
> > 
> > It would be great to have better type hinting in IDEs.
> 
> Is PEP 484 not sufficient for this purpose?

It's really not.

For one thing, PEP 484 isn't going to result in the standard library
being hinted all up (though I assume someone may make stubs). But
really, the specific issue that the OP is running into is because of the
signature of logging.warn --  msg, *args, **kwargs.

These kinds of signatures are very useful in certain circumstances but
they are also completely opaque. They're intentionally taking "anything"
and passing it off to another function. PEP 484 doesn't say anything
about the realities of logging.warn, as all the work is being done in
the private _log where we can examine and learn that it takes two
optional keyword parameters named "exc_info" and "extra", or what those
mean or what valid values are for them.

All my preferred IDE tells me is, "msg, *args, **kwargs", which leaves
me befuddled if I don't remember the signature or have the docs in hand.
If it were to display the docstring too, I'd know "exc_info" is a valid
keyword argument that does something useful, but I'd still have no idea
about "extra" (and I actually have no idea what extra does and am not
looking it up right now on purpose).

I don't really think that this is a problem for Python the language, but
maybe the style guide: don't use *args or **kwargs unless you either
document the details of what those should be, ooor, maybe include a
@functools.passes (fictional device) that in some fashion documents
"look
at this other function for the things I'm passing along blindly).

The problem the OP is demonstrating is really completely out of scope
for what PEP 484 is addressing, I think. It has little to do with type
hinting and more to do with, IMHO, "should the stdlib provide more
introspectable signatures" (which then IDE's could use).

-- 
  Stephen Hansen
  m e @ i x o k a i . i o