classification
Title: UUID docs should say how to get "standard form"
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.7, Python 3.6, Python 3.5
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: abarnert, ammar2, berker.peksag, docs@python, georg.brandl, python-dev, tuxtimo
Priority: normal Keywords: easy, patch

Created on 2016-02-02 18:43 by abarnert, last changed 2016-12-31 17:07 by berker.peksag. This issue is now closed.

Files
File name Uploaded Description Edit
uuiddocs.diff ammar2, 2016-07-06 21:48 review
uuiddocs.diff2 ammar2, 2016-08-02 22:20
uuiddocs.diff3 ammar2, 2016-08-02 22:31 review
uuiddocs.diff4 ammar2, 2016-08-03 07:21 review
uuiddocs.diff5 ammar2, 2016-12-09 00:44 review
Messages (15)
msg259414 - (view) Author: Andrew Barnert (abarnert) * Date: 2016-02-02 18:43
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].
msg259419 - (view) Author: SilentGhost (SilentGhost) * (Python triager) Date: 2016-02-02 19:08
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
msg259420 - (view) Author: Andrew Barnert (abarnert) * Date: 2016-02-02 19:09
> 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.
msg259425 - (view) Author: SilentGhost (SilentGhost) * (Python triager) Date: 2016-02-02 19:38
Well, you seem to suggest we add something to documentation to accommodate people who don't read it in the first place.
msg259430 - (view) Author: Andrew Barnert (abarnert) * Date: 2016-02-02 21:02
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.
msg259432 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2016-02-02 21:13
Andrew is right, this should be documented "properly".
msg269910 - (view) Author: Ammar Askar (ammar2) * (Python triager) Date: 2016-07-06 21:48
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.
msg271862 - (view) Author: Ammar Askar (ammar2) * (Python triager) Date: 2016-08-02 22:20
Fixed the str() representation as per Evelyn's comment.
msg271863 - (view) Author: Ammar Askar (ammar2) * (Python triager) Date: 2016-08-02 22:31
Whoops, didn't export the patch properly there so it didn't get picked up by the review tool, this should fix it.
msg271876 - (view) Author: Berker Peksag (berker.peksag) * (Python committer) Date: 2016-08-03 06:59
> 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.
msg271879 - (view) Author: Ammar Askar (ammar2) * (Python triager) Date: 2016-08-03 07:21
Done.

As a side question, are changes like those indentation problems tracked somewhere else/merged in bulk like spelling changes?
msg271880 - (view) Author: Berker Peksag (berker.peksag) * (Python committer) Date: 2016-08-03 07:49
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.
msg282747 - (view) Author: Ammar Askar (ammar2) * (Python triager) Date: 2016-12-09 00:44
I've updated the patch to document the comparison operators in prose instead of with markup as requested.
msg284400 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2016-12-31 17:06
New changeset 1a25c639f81e by Berker Peksag in branch '3.5':
Issue #26267: Improve uuid.UUID documentation
https://hg.python.org/cpython/rev/1a25c639f81e

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

New changeset 8b19c2a1b197 by Berker Peksag in branch 'default':
Issue #26267: Merge from 3.6
https://hg.python.org/cpython/rev/8b19c2a1b197
msg284401 - (view) Author: Berker Peksag (berker.peksag) * (Python committer) Date: 2016-12-31 17:07
Thanks, Ammar.
History
Date User Action Args
2016-12-31 17:07:33berker.peksagsetstatus: open -> closed
versions: + Python 3.7
messages: + msg284401

resolution: fixed
stage: patch review -> resolved
2016-12-31 17:06:59python-devsetnosy: + python-dev
messages: + msg284400
2016-12-09 00:44:23ammar2setfiles: + uuiddocs.diff5

messages: + msg282747
2016-08-03 07:49:27berker.peksagsetmessages: + msg271880
2016-08-03 07:21:57ammar2setfiles: + uuiddocs.diff4

messages: + msg271879
2016-08-03 06:59:06berker.peksagsetnosy: + berker.peksag

messages: + msg271876
stage: needs patch -> patch review
2016-08-02 22:31:06ammar2setfiles: + uuiddocs.diff3

messages: + msg271863
2016-08-02 22:20:08ammar2setfiles: + uuiddocs.diff2

messages: + msg271862
2016-07-06 21:48:56ammar2setfiles: + uuiddocs.diff

nosy: + ammar2
messages: + msg269910

keywords: + patch
2016-03-20 15:01:58SilentGhostsetnosy: - SilentGhost
2016-03-20 14:46:35berker.peksagsetkeywords: + easy
stage: needs patch
versions: + Python 3.5, Python 3.6
2016-02-02 21:13:38georg.brandlsetnosy: + georg.brandl
messages: + msg259432
2016-02-02 21:02:01abarnertsetmessages: + msg259430
2016-02-02 19:38:53SilentGhostsetmessages: + msg259425
2016-02-02 19:23:30tuxtimosetnosy: + tuxtimo
2016-02-02 19:09:30abarnertsetmessages: + msg259420
2016-02-02 19:08:09SilentGhostsetnosy: + SilentGhost
messages: + msg259419
2016-02-02 18:43:09abarnertcreate