Skip to content

[doc] Clarify indexes in String - Format String Syntax #16444

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

Closed
andresdelfino wants to merge 2 commits into from
Closed

[doc] Clarify indexes in String - Format String Syntax #16444

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
eca60a7
Clarify indexes in format
andresdelfino Sep 27, 2019
f8c90d0
Fix markup
andresdelfino Sep 27, 2019
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
8 changes: 5 additions & 3 deletions Doc/library/string.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -229,12 +229,13 @@ keyword. If it's a number, it refers to a positional argument, and if it's a ke
it refers to a named keyword argument. If the numerical arg_names in a format string
are 0, 1, 2, ... in sequence, they can all be omitted (not just some)
and the numbers 0, 1, 2, ... will be automatically inserted in that order.
Because *arg_name* is not quote-delimited, it is not possible to specify arbitrary
dictionary keys (e.g., the strings ``'10'`` or ``':-]'``) within a format string.
The *arg_name* can be followed by any number of index or
attribute expressions. An expression of the form ``'.name'`` selects the named
attribute using :func:`getattr`, while an expression of the form ``'[index]'``
does an index lookup using :func:`__getitem__`.
does an index lookup using :func:`__getitem__`. If *element_index* matches
*index_string*, then a string with value *element_index* will be used as key.
As *element_index* cannot be quote-delimited, it is not possible to use
a string key that matches *digit+* such as ``'10'`` within a format string.

.. versionchanged:: 3.1
The positional argument specifiers can be omitted for :meth:`str.format`,
Expand All @@ -251,6 +252,7 @@ Some simple format string examples::
"My quest is {name}" # References keyword argument 'name'
"Weight in tons {0.weight}" # 'weight' attribute of first positional arg
"Units destroyed: {players[0]}" # First element of keyword argument 'players'.
"Welcome {player[name]}" # Value of key 'name' of keyword argument 'player'

The *conversion* field causes a type coercion before formatting. Normally, the
job of formatting a value is done by the :meth:`__format__` method of the value
Expand Down