[Python-Dev] Rough idea for adding introspection information for builtins (original) (raw)

Ronald Oussoren ronaldoussoren at mac.com
Sun Jul 7 21:15:23 CEST 2013

On 7 Jul, 2013, at 19:20, Larry Hastings <larry at hastings.org> wrote:

On 07/07/2013 01:42 PM, Ronald Oussoren wrote:

On 7 Jul, 2013, at 13:35, Larry Hastings <larry at hastings.org> wrote:

On 07/07/2013 07:25 AM, Ronald Oussoren wrote:

Signature objects use a name in angled brackets to indicate that a parameter is positional only, for example "input()". That might be an alternative to adding a "/" in the argument list in pydoc's output.

I wasn't aware that Signature objects currently had any support whatsoever for positional-only parameters. Yes, in theory they do, but in practice they have never seen one, because positional-only parameters only occur in builtins and Signature objects have no metadata for builtins. (The very problem Argument Clinic eventually hopes to solve!) Can you cite an example of this, so I may examine it? I have a branch of PyObjC that uses this: <https://bitbucket.org/ronaldoussoren/pyobjc-3.0-unstable/overview> . That branch isn't quite stable yet, but does add a signature slot to objc.selector and objc.function (basicly methods of Cocoa classes and automaticly wrapped global functions), both of which only have positional-only arguments. With the patch for pydoc/inspect I mentioned earlier I can then generate somewhat useful documentation for Cocoa classes using pydoc. A word of warning though: the PyObjC source code isn't the most approachable, the code that generates the Signature object is actually in python (callablesignature in pyobjc-core/Lib/objc/callabledocstr.py) Ah. In other words, you have proposed it yourself in an external project. I thought you were saying this was something Python itself already did.

I wasn't clear enough in what I wrote. The stdlib contains support for positional-only arguments in Signature objects (see Lib/inspect.py, line 1472, which says "_POSITIONAL_ONLY = _ParameterKind(0, name='POSITIONAL_ONLY')". The str of Parameter amongst other says:

    if kind == _POSITIONAL_ONLY:
        if formatted is None:
            formatted = ''
        formatted = '<{}>'.format(formatted)

That is, it adds angled brackets around the names of positional-only parameters. I pointed to PyObjC as an example of code that actually creates Signature objects with positional-only arguments, as far as I know the stdlib never does this because the stdlib can only create signatures for plain python functions and those cannot have such arguments.

In that case, I think I will stick with Guido's suggested syntax. Consider window.border in the curses module: eight positional-only parameters, each in its own optional parameter group. Adding sixteen angle-brackets to that already unreadable morass will make it even worse. But with "/" we add only a single extra character, in an easy-to-find place (the end).

Using Guido's suggestion is fine by me, I agree that there is a clear risk of angle-bracket overload for functions with a lot of arguments. I do think that the str for Signatures should be changed to match the convention.

And to be clear: I'm looking forward to having Argument Clinic and signature objects on built-in functions, "funcname(...)" in the output pydoc is somewhat annoying, especially for extensions where the author hasn't bothered to provide a docstring. That's one reason I wrote the signature support in PyObjC in the first place (and the patch for pydoc to actually use the signature information)

Ronald

More information about the Python-Dev mailing list