[Python-3000] Draft pre-PEP: function annotations (original) (raw)

Collin Winter collinw at gmail.com
Mon Aug 14 21:41:11 CEST 2006

On 8/13/06, Paul Prescod <paul at prescod.net> wrote:

"In order for processors of function annotations to work interoperably, they must use a common interpretation of objects used as annotations on a particular function. For example, one might interpret string annotations as docstrings. Another might interpet them as path segments for a web framework. For this reason, function annotation processors SHOULD avoid assigning processor-specific meanings to types defined outside of the processor's framework. For example, a Django processor could process annotations of a type defined in a Zope package, but Zope's creators should be considered the authorities on the type's meaning for the same reasons that they would be considered authorities on the semantics of classes or methods in their packages."

The way I read this, it forces (more or less) each annotation-consuming library to invent new ways to spell Python's built-in types.

I read all this as saying that annotation processors should avoid using Python's lists, tuples and dicts in annotations (since whatever semantics the Python developers come up with will inevitably be incompatible with what some library writer needs/wants). Each processor library will then define my_processor.List, my_processor.Tuple, my_processor.Dict, etc as alternate spellings for [x, y, z], (x, y, z), {x: y} and so on.

"This implies that the interpretation of built-in types would be controlled by Python's developers and documented in Python's documentation.

The inherent difficulty in defining a standard interpretation for these types is what motivated me to leave this up to the authors of annotation consumers. I don't mean "it was hard so I gave up"; I can easily come up with a standard, but it will probably be of limited or no utility to some section of the possible userbase.

If you have an idea, though, feel free to propose something concrete.

"In Python 3000, semantics will be attached to the following types: objects of type string (or subtype of string) are to be used for documentation (though they are not necessarily the exclusive source of documentation about the type). Objects of type list (or subtype of list) are to be used for attaching multiple independent annotations."

Does this mean all lists "are to be used for attaching multiple independent annotations", or just top-level lists (ie, "def foo(a: [x, y])" indicates two independent annotations)? What does "def foo(a: [x, [y, z]])" indicate?

Collin Winter

More information about the Python-3000 mailing list