Little documentation of annotations

[JJeffries]

BPO	12195
Nosy	@rhettinger, @merwok

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = 'https://github.com/rhettinger'
closed_at = <Date 2011-08-26.16:49:10.599>
created_at = <Date 2011-05-27.12:22:12.863>
labels = ['docs']
title = 'Little documentation of annotations'
updated_at = <Date 2011-08-26.16:49:10.598>
user = 'https://bugs.python.org/JJeffries'

bugs.python.org fields:

activity = <Date 2011-08-26.16:49:10.598>
actor = 'rhettinger'
assignee = 'rhettinger'
closed = True
closed_date = <Date 2011-08-26.16:49:10.599>
closer = 'rhettinger'
components = ['Documentation']
creation = <Date 2011-05-27.12:22:12.863>
creator = 'JJeffries'
dependencies = []
files = []
hgrepos = []
issue_num = 12195
keywords = []
message_count = 4.0
messages = ['137047', '137050', '141960', '143021']
nosy_count = 4.0
nosy_names = ['rhettinger', 'eric.araujo', 'docs@python', 'JJeffries']
pr_nums = []
priority = 'normal'
resolution = 'rejected'
stage = None
status = 'closed'
superseder = None
type = None
url = 'https://bugs.python.org/issue12195'
versions = ['Python 3.2']

[JJeffries]

There are very few pages relating to annotations in the documentation. Making it very unclear how they work and what they could be used for other than the original PEP.

[rhettinger]

We could beef this up a little bit, but it was intentional that we leave it completely open on how to use it.

[JJeffries]

While I understand the reluctance to unintentionally push people along a particular path, but I think there is being open on how to use it and not mentioning it. I think that currently the current documentation is the latter and some simple examples showing the syntax would go a long way.

Most of my understanding of annotations has come from the PEP for it and mailing lists.

[rhettinger]

some simple examples showing the syntax would go a long way.

Sorry, there as just too many ways to go and we are intentionally not stating which way is preferred. I've seen many variants a:[Integral] for a list of integers, a:(int,str) for a 2-tuple of an int and a string, a:(str,file,None) for something that is a string or a file or None, a:'light_years' to indicate units of measure, a:range_check(10.5, 20.1) for range validation, and some variants for converters, adapters, factory functions, documentation aids, etc.

If you want to advance the state of the art, perhaps write a blog post on what you consider to be a best practice. If a consensus emerges, we
will follow.