[Python-Dev] PEP 362: 4th edition

[Yury Selivanov]

On 2012-06-16, at 11:27 AM, Nick Coghlan wrote:

> On Sat, Jun 16, 2012 at 1:56 PM, Jim J. Jewett <jimjjewett at gmail.com> wrote:
>> 
>> Summary:
>> 
>>    *Every* Parameter attribute is optional, even name.  (Think of
>>    builtins, even if they aren't automatically supported yet.)
>>    So go ahead and define some others that are sometimes useful.
> 
> No, that's not the right attitude to take when designing a new API.
> Add only stuff we know is interesting and useful. Call YAGNI on
> everything else. If we later decided we missed something, then we can
> add it easily. If something we add up front turns out to be useless
> (or, worse, an attractive nuisance), then it's a pain to eliminate.
> 
> For parameters, that list is only:
> 
> - kind
> - name (should be given meaningful content, even for POSITIONAL_ONLY parameters)

+1.

>>> A Signature object has the following public attributes and methods:
>> 
>>> * return_annotation : object
>>>    The annotation for the return type of the function if specified.
>>>    If the function has no annotation for its return type, this
>>>    attribute is not set.
>> 
>> This means users must already be prepared to use hasattr with the
>> Signature as well as the Parameters -- in which case, I don't see any
>> harm in a few extra optional properties.
> 
> No, this gets the reasoning wrong. The optional properties are
> optional solely because "None" and "not present" don't mean the same
> thing - the attributes potentially being missing represents the fact
> that annotations and default values may be omitted altogether.

Exactly.  And I'd stay away from adding back 'has_annotation' and 
'has_default' attributes.  It's easy enough to call 'hasattr' or do
try-catch-else.

>> I would personally prefer to see the name (and qualname) and docstring,
>> but it would make perfect sense to implement these by keeping a weakref
>> to the original callable, and just delegating there unless/until the
>> properties are explicitly changed.  I suspect others will have a use
>> for additional delegated attributes, such as the self of boundmethods.
> 
> It is expected that higher level interfaces will often compose the
> signature object with more information from the callable. That is
> already well supported today, and is not the role of the signature
> object. The signature object is being added purely to provide a
> standard way to describe how a callable binds the supplied arguments
> to the expected parameters, that's all.
> 
>> I do agree that __eq__ and __hash__ should depend at most on the
>> parameters (including their order) and the annotation.

Actually, Signature and Parameter are currently non-hashable (they are
mutable).  I'm not sure if it was a right decision.

>> I think it should state explicitly that by default, the return value
>> will be a string that could be used to declare an equivalent function,
>> if "Signature" were replaced with "def funcname".
>> 
>> There are enough customization parameters that would often be changed
>> together (e.g., to produce HTML output) that it might make sense to use
>> overridable class defaults -- or even to make format a class itself.
>> 
>> I also think it would make sense to delegate formatting the individual
>> parameters to the parameter objects.  Yes, this does mean that the
>> subclasses would be more than markers classes.
> 
> I'd like to see support for customising the formatted output dropped
> from the PEP entirely. We can add that later after seeing how people
> use the class, there's no need to try to guess in advance.

I'd be OK with that, as I don't like the current 'format()' design either.
But we should keep the Signature.__str__.

>>> The structure of the Parameter object is:
>> 
>>> * name : str
>>>     The name of the parameter as a string.
>> 
>> If there is no name, as with some builtins, will this be "", None or
>> not set?
> 
> Positional parameters should still be given a meaningful name
> (preferably matching the name used in their docstring and prose
> documentation).

Again, +1 on the required name for positional-only args.

-
Yury