Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

gh-100428: Make int documentation more accurate #100436

Merged
merged 5 commits into from
Jan 2, 2023
Merged

gh-100428: Make int documentation more accurate #100436

Changes from 2 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
6678637
gh-100428: Make int documentation more accurate
hauntsaninja Dec 22, 2022
08ef087
further clarify unicode decimal digit
hauntsaninja Dec 24, 2022
231574a
address feedback, except for adding a formal grammar
hauntsaninja Jan 1, 2023
d773d7f
phrasing nitpick
hauntsaninja Jan 1, 2023
e7ba3a9
add missing word
hauntsaninja Jan 2, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 14 additions & 11 deletions Doc/library/functions.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -890,17 +890,20 @@ are always available. They are listed here in alphabetical order.
For floating point numbers, this truncates towards zero.

If *x* is not a number or if *base* is given, then *x* must be a string,
:class:`bytes`, or :class:`bytearray` instance representing an :ref:`integer
literal <integers>` in radix *base*. Optionally, the literal can be
preceded by ``+`` or ``-`` (with no space in between) and surrounded by
whitespace. A base-n literal consists of the digits 0 to n-1, with ``a``
to ``z`` (or ``A`` to ``Z``) having
values 10 to 35. The default *base* is 10. The allowed values are 0 and 2--36.
Base-2, -8, and -16 literals can be optionally prefixed with ``0b``/``0B``,
``0o``/``0O``, or ``0x``/``0X``, as with integer literals in code. Base 0
means to interpret exactly as a code literal, so that the actual base is 2,
8, 10, or 16, and so that ``int('010', 0)`` is not legal, while
``int('010')`` is, as well as ``int('010', 8)``.
:class:`bytes`, or :class:`bytearray` instance representing an integer
literal in radix *base*. Optionally, the literal can be
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Now that we're no longer linking to the Python grammar, I think we could drop the use of literal, which is somewhat misleading. For the first use, [ ...] representing an integer in radix *base* [...] seems clear enough. But other uses might require some more reworking below, though. Rather than expressing in words, it may be clearest to re-introduce a formal grammar production, analogous to what's now in the float description. (Maybe with "digit" as a terminal, where valid digits are then expressed in text.)

Without the link to the grammar, we're also missing information about the rules for underscores. (I'm not suggesting putting that link back in, but rather, finding a way to include the information about underscores in this text.)

preceded by ``+`` or ``-`` (with no space in between), have leading zeros,
or be surrounded by whitespace.
hauntsaninja marked this conversation as resolved.
Show resolved Hide resolved

A base-n literal consists of digits representing 0 to n-1. The values 0--9
can be represented by any Unicode decimal digit. The values 10--35 can be
represented by ``a`` to ``z`` (or ``A`` to ``Z``). The default *base* is 10.
The allowed bases are 0 and 2--36. Base-2, -8, and -16 literals can be
optionally prefixed with ``0b``/``0B``, ``0o``/``0O``, or ``0x``/``0X``, as
with integer literals in code. Base 0 means to interpret similar to a
hauntsaninja marked this conversation as resolved.
Show resolved Hide resolved
:ref:`code literal <integers>`, in that the actual base is 2, 8, 10, or 16 as
determined by the prefix. Base 0 also disallows leading zeros: ``int('010',
0)`` is not legal, while ``int('010')`` and ``int('010', 8)`` are.

The integer type is described in :ref:`typesnumeric`.

Expand Down