| msg177352 - (view) |
Author: rurpy (rurpy2) |
Date: 2012-12-11 20:33 |
| The documentation of the hex() builtin function is poor. Specifically it does not say (directly) that: 1. The resulting string is prefixed with "0x". 2. Any a-f characters used are lower case. 3. Negative integers are converted by prefixing a minus sign to hex() of the absolute value of the argument. 4. It should have a cross reference to the %x format of the "%" operator with a note that it is more veratile than the hex() builtin. 5. It should have a cross reference to the way of performing the inverse operation: hex->int I am not a good writer but here is an attempt at improving it: -------- Convert an integer number to a hexadecimal string. The resulting string is prefixed with "0x" and any alpha characters a-f are lowercase ascii. Negative integers are converted to hex(abs(x)) prefixed with "-". In all cases the result is a valid Python expression. If x is not a Python int object, it has to define an __index__() method that returns an integer. Note: For another more flexible way of converting an integer to hexadecimal see the "x" and "X" conversion types in link:[4.7.2 - printf-style String Formatting] and link:[6.1.3.1 - Format Specification Mini-Language] Note: To convert a hexadecimal string to an integer, use link:[int()] with a radix argument of 16. Note: To obtain a hexadecimal string representation for a float, use the link:[float.hex()] method. -------- |
|
|
| msg177354 - (view) |
Author: Ezio Melotti (ezio.melotti) *  |
Date: 2012-12-11 20:42 |
| +1 |
|
|
| msg177365 - (view) |
Author: Raymond Hettinger (rhettinger) * |
Date: 2012-12-12 06:11 |
| -1 for the suggested text. For some of the points, a couple examples will do a better job of explaining hex() that trying to write-out the full code specification in prose. Overly wordy documentation is harder to use than something short that addresses the primary use case. Also, the suggested "notes" editorialize and venture into the realm of personal coding preferences. |
|
|
| msg177366 - (view) |
Author: Ezio Melotti (ezio.melotti) * |
Date: 2012-12-12 06:24 |
| FTR my +1 was about the suggestion, not the proposed text. The first 3 points can be explained with an example, the last 2 can be added in the prose. I also agree that notes are not necessary (especially if they use the "note" rst directive). |
|
|
| msg177384 - (view) |
Author: rurpy (rurpy2) |
Date: 2012-12-12 18:20 |
| Raymond Hettinger (rhettinger) : > For some of the points, a couple examples will do a better job of explaining hex() that trying to write-out the full code specification in prose. Examples should never substitute for a clear, complete and concise description. Examples serve to illustrate and clarify a description. An example can only describe usage at a single point in the solution space. The prose description (when well written) describes the total solution space. > Overly wordy documentation is harder to use than something short that addresses the primary use case. No comments in this issue have suggested providing an "overly wordy" description. The suggestion was for wording that accurately and concisely describes the behavior of the hex() function. That is what good reference material is supposed to do. Reference documentation should describe the behavior of its subject including any corner cases. Addressing only "the primary use case" is not sufficient. For addressing the primary use case, supplement the prose with an example. > Also, the suggested "notes" editorialize and venture into the realm of personal coding preferences. That characterization is incorrect. There is no editorializing (if this in reference to the word "flexible" in the note). It is a fact that string formatting with the %x specifier also converts to hex and offers more control over the output than the hex() function does. A reader interested in the hex() function should be apprised of this alternative. Perhaps there is some other word that you would find more neutral than "flexible"? There is no venturing into personal coding preferences -- only the factual and appropriate mention of an alternative. One of the cheapest, easiest ways of improving documentation is good cross-referencing to related items. |
|
|
| msg177429 - (view) |
Author: rurpy (rurpy2) |
Date: 2012-12-13 18:22 |
| An ammendment to my proposed doc change. Replace the text (which is unchanged from the current doc), "...the result is a valid Python expression" with, "...the result is a valid Python "hexinteger" literal (see link:[Python Lang Ref, sec 2.4.4. Integer literals]) "Python epression" in the current doc is way more non-specific than it need be. The result is not any old python expression, it is a very specific type of python expression so the doc should say that. |
|
|
| msg178089 - (view) |
Author: rurpy (rurpy2) |
Date: 2012-12-24 19:09 |
| I would like to submit the following post made to c.l.p in support of my claim that a cross-reference to the string formatting "x" format specifier would be desireable in the documentation for the hex() builtin: Newsgroups: comp.lang.python Subject: Re: Integer as raw hex string? Date: Mon, 24 Dec 2012 11:21:15 -0500 https://groups.google.com/group/comp.lang.python/msg/054706d112f6385d?hl=en (In case the link goes away... the post asks how to get the same results as hex() but without the leading "0x".) |
|
|
| msg192786 - (view) |
Author: Michael Dickens (Michael Dickens) |
Date: 2013-07-09 23:57 |
| I used the wording suggested by rurpy with some changes. I also added a few examples. |
|
|
| msg192787 - (view) |
Author: Raymond Hettinger (rhettinger) * |
Date: 2013-07-10 01:03 |
| Personally, I think this is overkill. Can you capture the essence of what you want to say in something short and sweet that gets to the point? We're not looking for a complete spec. You just need to say basically what the function does. |
|
|
| msg213670 - (view) |
Author: Jessica McKellar (jesstess) *  |
Date: 2014-03-15 18:27 |
| Thanks for the patch, Michael! There's a small doc build issue with your patch: the note on int shows up inside the code block for the examples. In response to rhettinger's feedback I've attached a slightly more compact patch that hits the highlights. I checked that the docs build cleanly with the patch and that the output looks visually as expected. I think both patches are an improvement over the current docs. => review |
|
|
| msg213682 - (view) |
Author: Raymond Hettinger (rhettinger) * |
Date: 2014-03-15 20:28 |
| Approved. You can go ahead and apply this. |
|
|
| msg213695 - (view) |
Author: Roundup Robot (python-dev) |
Date: 2014-03-16 01:17 |
| New changeset 464c22bf9fe1 by Antoine Pitrou in branch '3.3': Close #16665: improve documentation for hex(). Patch by Jessica McKellar. http://hg.python.org/cpython/rev/464c22bf9fe1 New changeset d14beaf03f55 by Antoine Pitrou in branch '2.7': Close #16665: improve documentation for hex(). Patch by Jessica McKellar. http://hg.python.org/cpython/rev/d14beaf03f55 New changeset c267f4eb8173 by Antoine Pitrou in branch 'default': Close #16665: improve documentation for hex(). Patch by Jessica McKellar. http://hg.python.org/cpython/rev/c267f4eb8173 |
|
|
| msg213696 - (view) |
Author: Antoine Pitrou (pitrou) * |
Date: 2014-03-16 01:20 |
| Jessica doesn't have commit rights, so I committed this myself. Also added an example of the funny hex(long) behaviour in Python 2. |
|
|