RetroSearch Browse

Sun Jul 7 21:15:23 CEST 2013 · https://mail.python.org/pipermail/python-dev/2013-July/127248.html

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(<prompt>)". 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 (callable_signature in pyobjc-core/Lib/objc/_callable_docstr.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

Home - News ( United States | United Kingdom | Italy | Germany ) - Football scores

Showing content from https://mail.python.org/pipermail/python-dev/2013-July/127248.html below:

[Python-Dev] Rough idea for adding introspection information for builtins