UUID docs should say how to get "standard form"

[abarnert]

BPO	26267
Nosy	@birkenfeld, @berkerpeksag, @timofurrer, @ammaraskar
Files	uuiddocs.diff uuiddocs.diff2 uuiddocs.diff3 uuiddocs.diff4 uuiddocs.diff5

^{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 = None
closed_at = <Date 2016-12-31.17:07:33.596>
created_at = <Date 2016-02-02.18:43:09.382>
labels = ['easy', 'type-feature', '3.7', 'docs']
title = 'UUID docs should say how to get "standard form"'
updated_at = <Date 2016-12-31.17:07:33.594>
user = 'https://bugs.python.org/abarnert'

bugs.python.org fields:

activity = <Date 2016-12-31.17:07:33.594>
actor = 'berker.peksag'
assignee = 'docs@python'
closed = True
closed_date = <Date 2016-12-31.17:07:33.596>
closer = 'berker.peksag'
components = ['Documentation']
creation = <Date 2016-02-02.18:43:09.382>
creator = 'abarnert'
dependencies = []
files = ['43647', '43979', '43980', '43988', '45807']
hgrepos = []
issue_num = 26267
keywords = ['patch', 'easy']
message_count = 15.0
messages = ['259414', '259419', '259420', '259425', '259430', '259432', '269910', '271862', '271863', '271876', '271879', '271880', '282747', '284400', '284401']
nosy_count = 7.0
nosy_names = ['georg.brandl', 'docs@python', 'python-dev', 'berker.peksag', 'abarnert', 'tuxtimo', 'ammar2']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue26267'
versions = ['Python 3.5', 'Python 3.6', 'Python 3.7']

[abarnert]

Most real-world code that uses the UUID module wants either the standard format '{12345678-1234-5678-1234-567812345678}', or the same thing without the braces.

There are a number of different documented accessors, but none of them give you either of these. The simplest way I can think of to guarantee the standard format from what's documented is '{%08x-%04x-%04x-%02x%02x-%12x}' % u.fields.

It might be nice to add accessors for standard form and braceless standard form, but that probably isn't necessary--as long as there's documentation saying that __str__ returns the braceless standard form.

The example code does say that, but I don't think people can trust that a comment in an example is binding documentation--plus, plenty of people don't read the examples looking for more information about things that aren't documented. And I've seen people come up with buggy versions of the format string that miss leading zeros, or horrible things like repr(u)[6:42].

[SilentGhost]

The docs seem to clearly show a str(x) as the way to produce the desired form (without braces). https://docs.python.org/3/library/uuid.html#example

[abarnert]

The docs seem to clearly show a str(x) as the way to produce the desired form (without braces). https://docs.python.org/3/library/uuid.html#example

Please read the last paragraph of the original message.

[SilentGhost]

Well, you seem to suggest we add something to documentation to accommodate people who don't read it in the first place.

[abarnert]

No, I suggest we add something for users who don't think that a comment in an example is the place to look for documentation, but do think that actual documentation of a class or method is.

[birkenfeld]

Andrew is right, this should be documented "properly".

[ammaraskar]

This patch adds documentation for the str(uuid) operator along with documenting the fact that UUID instances support comparisons with > and <.

It also indents the attributes and descriptions to emphasize that they are part of the UUID instance, not the uuid module.

I followed https://docs.python.org/3/library/stdtypes.html#set for documenting the operators, hope it's fine.

[ammaraskar]

Fixed the str() representation as per Evelyn's comment.

[ammaraskar]

Whoops, didn't export the patch properly there so it didn't get picked up by the review tool, this should fix it.

[berkerpeksag]

It also indents the attributes and descriptions to emphasize that they are part of the UUID instance, not the uuid module.

Thanks for the patch, but please revert unrelated changes.

[ammaraskar]

Done.

As a side question, are changes like those indentation problems tracked somewhere else/merged in bulk like spelling changes?

[berkerpeksag]

I wouldn't consider it a problem since both forms are supported. Also note that you don't need to specify the "UUID." prefix when you use the indented form:

.. class:: UUID(...)

   .. attribute:: bytes

I don't think the benefit here is worth the amount of code churn.

[ammaraskar]

I've updated the patch to document the comparison operators in prose instead of with markup as requested.

[python-dev]

New changeset 1a25c639f81e by Berker Peksag in branch '3.5':
Issue bpo-26267: Improve uuid.UUID documentation
https://hg.python.org/cpython/rev/1a25c639f81e

New changeset c9e944cc6301 by Berker Peksag in branch '3.6':
Issue bpo-26267: Merge from 3.5
https://hg.python.org/cpython/rev/c9e944cc6301

New changeset 8b19c2a1b197 by Berker Peksag in branch 'default':
Issue bpo-26267: Merge from 3.6
https://hg.python.org/cpython/rev/8b19c2a1b197

[berkerpeksag]

Thanks, Ammar.