[Python-3000] Fwd: Conventions for annotation consumers

[Talin]

Collin Winter wrote:
> On 8/15/06, Phillip J. Eby <pje at telecommunity.com> wrote:
>> Personally, I thought Guido's original proposal for function annotations,
>> which included a __typecheck__ operator that was replaceable on a
>> per-module basis (and defaulted to a no-op), was the perfect thing --
>> neither too much semantics nor too-little.  I'd like to have it back,
>> please.  :)
> 
> I'd be perfectly happy to go back to talking about "type annotations",
> rather than the more general "function annotations", especially since
> most of the discussion thus far has been about how to multiple things
> with annotations at the same time. Restricting annotations to type
> information would be fine by me.

I'd be happy to do that as well :)

So far, there has been a great deal of confusion and disagreement about 
this proposal. Some people might be surprised by that - however, my 
point from the beginning is that this confusion and disagreement is 
*inherent* in the concept of function annotations as currently envisioned.

What the current discussion demonstrates is that the number of different 
ways in which function annotations can be used is far larger and more 
diverse than anticipated ("Never underestimate the creative power of an 
infinite number of monkeys".) Normally, this wouldn't be seen as a 
problem, but rather a strength of the design. Whenever you have a broad 
and diverse set of use cases for a given feature, that's usually an 
indication that the feature has been designed well.

However, having a vast set of use cases only works if those use cases 
can have some degree of isolation from one another. If I write a 
decorator, I'm not too concerned about what other decorator classes may 
exist; I may not even be too concerned about what other decorators are 
applied to the same function as mine are.

However, function decorators are a little different than the usual case. 
Specifically, they need to be fairly concise, otherwise they are 
obfuscatory (as someone pointed out). One of the ways of achieving this 
conciseness is to remove the requirement to explicitly identify each 
annotation, and instead allow the meanings of the annotations to be 
implicit. (i.e. the use of built-in types rather than a dictionary of 
key/value pairs.)

The problem with implicit identification is that the category boundaries 
for each annotation are no longer clearly defined. This wouldn't be a 
problem if the number of use cases were small and widely separated. 
However, as the recent discussion has shown, the number of use cases is 
vast and diverse. This means that the implicitly defined categories are 
inevitably going to collide.

What I and others are worried about is that it appears that we are 
heading in a direction in which different users of function annotations 
will be forced to jostle elbows with each other - where each consumer of 
annotations, instead of being able to develop their annotation system in 
private, will be forced to consider the other annotation systems that 
exist already. For someone who is developing an annotation library that 
is intended for widespread use, the *mere existence* of other annotation 
libraries impacts their design and must be taken into account. I feel 
that this is an intolerable burden on the designers of such systems.

Some have proposed resolving this by going back to explicit 
identification of annotations, either by keyword or by unique types. 
However, this destroys some of the conciseness and simplicity of the 
annotations, something which others have objected to.

Personally, I think that the function annotation concept suffers from 
being too ambitious, attempting to be all things to all people. I don't 
think we really need docstring annotations - there are other ways to 
achieve the same effect. The same goes for type checkers and lint 
checkers and most of the other ideas for using annotations. All those 
things are nice, but if they never get done I'm not going to worry about 
it -- and none of these things are worth the level of madness and 
confusion generated by an N-way collision of incompatible frameworks.

I'm going to take a somewhat hard line here, and say that if it were up 
to me, I would ask Phillip Eby exactly what annotation features he needs 
to make his overload dispatching mechanism work, and then I would 
restrict the PEP to just that. In other words, rather than saying 
"annotations can be anything the programmer wants", I would instead say 
"This set of annotations is used for dispatching, any other use of 
annotations is undefined." Which is not to say that a programmer can't 
make up their own -- but that programmer should have no expectations 
that their code is going to be able to interoperate with anyone else's.

-- Talin