[docs] hex() documentation: mention "%x" % int (issue 26506)

[victor.stinner at gmail.com]

Reviewers: ,


http://bugs.python.org/review/26506/diff/16795/Doc/library/functions.rst
File Doc/library/functions.rst (right):

http://bugs.python.org/review/26506/diff/16795/Doc/library/functions.rst#newcode87
Doc/library/functions.rst:87: '0b11'
I suggest to use less boring numbers in examples, like 12: 0b1100, it
shows the order of bits (which is not documented): most significant bits
first.

http://bugs.python.org/review/26506/diff/16795/Doc/library/functions.rst#newcode94
Doc/library/functions.rst:94: '0b11'
I don't know if this example is needed.

http://bugs.python.org/review/26506/diff/16795/Doc/library/functions.rst#newcode98
Doc/library/functions.rst:98: >>> "{0:b}".format(3)
I suggest to omit 0:

"{:b}".format(3)

http://bugs.python.org/review/26506/diff/16795/Doc/library/functions.rst#newcode104
Doc/library/functions.rst:104: :meth:`__index__` method that returns an
integer.
I suggest to add examples at the end, after this sentence.

http://bugs.python.org/review/26506/diff/16795/Doc/library/functions.rst#newcode674
Doc/library/functions.rst:674: 'ff'
Documenting format() and str.format() seems overkill. I suggest to only
keep one. Since str.format() is more common, I suggest to only keep:
"{:x}".format(255) (without the 0 in the formatting string).

http://bugs.python.org/review/26506/diff/16795/Doc/library/functions.rst#newcode675
Doc/library/functions.rst:675: >>> f'{255:x}'
IMHO this one is not a good usage of f-strings, I suggest to remove it.

http://bugs.python.org/review/26506/diff/16795/Doc/library/functions.rst#newcode918
Doc/library/functions.rst:918: '0o10'
"%#o" % 8 also exists. You may mention it.

http://bugs.python.org/review/26506/diff/16795/Doc/library/functions.rst#newcode925
Doc/library/functions.rst:925: '10'
To be consistent with bin & hex, I also suggest to only document
str.format here:

>>> "{:o}".format(8)
'10'



Please review this at http://bugs.python.org/review/26506/

Affected files:
  Doc/library/functions.rst


diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst
index ef4176a..7cde44d 100644
--- a/Doc/library/functions.rst
+++ b/Doc/library/functions.rst
@@ -80,8 +80,27 @@ are always available.  They are listed here in alphabetical order.
 
 .. function:: bin(x)
 
-   Convert an integer number to a binary string. The result is a valid Python
-   expression.  If *x* is not a Python :class:`int` object, it has to define an
+   Convert an integer number to a binary string prefixed with "0b". 
+   The result is a valid Python expression, for example:
+
+      >>> bin(3)
+      '0b11'
+      >>> bin(-10)
+      '-0b1010'
+
+   It can also be done by using the expression:
+
+      >>> "{0:#b}".format(3)
+      '0b11'
+
+   If prefix "0b" is not desired, you can use either of the following ways:
+
+      >>> "{0:b}".format(3)
+      '11'
+      >>> format(3, 'b')
+      '11'
+
+   If *x* is not a Python :class:`int` object, it has to define an
    :meth:`__index__` method that returns an integer.
 
 
@@ -634,6 +653,28 @@ are always available.  They are listed here in alphabetical order.
       >>> hex(-42)
       '-0x2a'
 
+   It can also be done by using the expression:
+
+      >>> "%#x" % 255
+      '0xff'
+
+   If you want to convert an integer number to an uppercase hexadecimal string
+   prefixed with "0X":
+
+      >>> "%#X" % 255
+      '0XFF'
+
+   If prefix "0x" is not desired, you can use either of the following ways:
+
+      >>> '%x' % 255
+      'ff'
+      >>> format(255, 'x')
+      'ff'
+      >>> "{0:x}".format(255)
+      'ff'
+      >>> f'{255:x}'
+      'ff'
+
    If x is not a Python :class:`int` object, it has to define an __index__()
    method that returns an integer.
 
@@ -865,8 +906,25 @@ are always available.  They are listed here in alphabetical order.
 
 .. function:: oct(x)
 
-   Convert an integer number to an octal string.  The result is a valid Python
-   expression.  If *x* is not a Python :class:`int` object, it has to define an
+   Convert an integer number to an octal string prefixed with "0o".  The result 
+   is a valid Python expression, for example:
+
+      >>> oct(8)
+      '0o10'
+
+   It can also be done by using the expression:
+
+      >>> "{0:#o}".format(8)
+      '0o10'
+
+   If prefix "0o" is not desired, you can use either of the following ways:
+
+      >>> "%o" % 8
+      '10'
+      >>> format(8, 'o')
+      '10'
+
+   If *x* is not a Python :class:`int` object, it has to define an
    :meth:`__index__` method that returns an integer.