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

[Terry Reedy]

On 7/7/2013 7:35 AM, Larry Hastings wrote:
>
>
> On 07/07/2013 07:19 AM, Ronald Oussoren wrote:
>> Not entirely on topic, but close enough: pydoc currently doesn't use
>> the __signature__ information at all. Adding such support would be
>> easy enough, see #17053 for an implementation ;-)
>
> True, it doesn't use inspect.signature, it uses inspect.getfullargspec.

This is currently true of Idle calltips. But with 3.2 out of the way, I 
plan to switch sometime and not worry about 2.7.

> Since I don't propose modifying inspect.getfullargspec to add the
> optional parameter group information, 17053 or something like it would
> have to happen.
>
>
> On 07/07/2013 07:25 AM, R. David Murray wrote:
>> Sorry to make your life more complicated, but unless I'm misunderstanding
>> something, issue 18220 (http://bugs.python.org/issue18220) throws another
>> monkey-wrench in to this.  If I'm understanding this discussion correctly,
>> that example:
>>
>>      islice(stop)
>>      islice(start, stop [, step])
>>
>> requires the multiple-signature approach.
>>
>> Note also that the python3 documentation has moved away from the []
>> notation wherever possible.
>
> It depends on what problem you're addressing.  In terms of the Argument
> Clinic DSL, and in terms of the static introspection information stored
> for builtins, someone (Nick?) suggested a refinement to the semantics:
> in the face of ambiguity, prefer the leftmost group(s) first.  That
> means that range() and islice() could be specified as follows:
>
>     range([start,] stop, [step])

This is how it was until last September. See #15831, which also changed 
max, min, and slice entries to use two lines. The multiple lines for 
bytes and str signatures in the docstrings were another issue.

> In terms of the documentation, it might be better to preserve the
> multiple-lines approach, as perhaps that's more obvious to the reader.

It seems that signatures that do not match what one can do with a def 
statement are confusing. The header line for the Python version of the 
above is
	def range(start_or_stop, stop=None, step=1):
My suggestion to use this, which is the actual signature, was rejected 
in favor of using two lines. This is fine with me, as it documents the 
calling signatures rather than the hybrid definition signature used to 
implement the call signatures.

> On the other hand: in Python 3, help(itertools.islice) uses solely the
> optional group syntax, on one line.

Because it has not yet been changed ;-).

> 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!)

I look forward to the day when accurate (auto-generated) call data is 
also available for C-coded functions.

-- 
Terry Jan Reedy