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

bpo-33828: Add missing versionchanged note for string.Formatter. #7668

Merged
merged 2 commits into from Jun 13, 2018
Merged

bpo-33828: Add missing versionchanged note for string.Formatter. #7668

merged 2 commits into from Jun 13, 2018

Conversation

zhangyangyu
Copy link
Member

@zhangyangyu zhangyangyu commented Jun 12, 2018 •
edited by bedevere-bot

string.Formatter auto-numbering feature was added in 3.4 and there
is no versionchanged not in its documentation, making the documentation
ambiguous about which version the feature is available.

https://bugs.python.org/issue33828

@zhangyangyu
bpo-33828: Add missing versionchanged note for string.Formatter.
2f0b70f 
string.Formatter auto-numbering feature was added in 3.4 and there
is no versionchanged not in its documentation, making the documentation
ambiguous about which version the feature is available.
@zhangyangyu zhangyangyu added needs backport to 3.6 docs Documentation in the Doc dir skip news labels Jun 12, 2018
ericvsmith
ericvsmith reviewed Jun 12, 2018
View reviewed changes
Copy link
Member

@ericvsmith ericvsmith left a comment

Choose a reason for hiding this comment

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

A few small comments, but otherwise looks good.

Doc/library/string.rst Outdated
@@ -231,8 +231,11 @@ attribute using :func:`getattr`, while an expression of the form ``'[index]'``
does an index lookup using :func:`__getitem__`.

.. versionchanged:: 3.1
The positional argument specifiers can be omitted, so ``'{} {}'`` is
equivalent to ``'{0} {1}'``.
The positional argument specifiers can be omitted, for :meth:`str.format`,
Copy link
Member

Choose a reason for hiding this comment

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

I would delete the first comma in that sentence.

Doc/library/string.rst Outdated
so ``'{} {}'`` is equivalent to ``'{0} {1}'``.

.. versionchanged:: 3.4
The positional argument specifiers can be omitted, for :class:`Formatter`.
Copy link
Member

Choose a reason for hiding this comment

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

Similarly, I would delete the comma in this sentence.

Doc/library/string.rst Outdated
The positional argument specifiers can be omitted, so ``'{} {}'`` is
equivalent to ``'{0} {1}'``.
The positional argument specifiers can be omitted, for :meth:`str.format`,
so ``'{} {}'`` is equivalent to ``'{0} {1}'``.
Copy link
Member

Choose a reason for hiding this comment

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

Since you're now referencing both str.format() and Formatter in close proximity, I'd change this example to actually reference .format() . So something like: '"{} {}'.format(a, b) is equivalent to '{0} {1}'.format(a, b)".

ericvsmith
ericvsmith approved these changes Jun 13, 2018
View reviewed changes
Copy link
Member

@ericvsmith ericvsmith left a comment

Choose a reason for hiding this comment

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

Looks good to me. Thanks!

@zhangyangyu zhangyangyu merged commit b9d8ad5 into python:master Jun 13, 2018
@miss-islington
Copy link
Contributor

Thanks @zhangyangyu for the PR 🌮🎉.. I'm working now to backport this PR to: 2.7, 3.6, 3.7.
🐍🍒⛏🤖 I'm not a witch! I'm not a witch!

@zhangyangyu zhangyangyu deleted the bpo-33828 branch June 13, 2018 01:42
@bedevere-bot
Copy link

GH-7674 is a backport of this pull request to the 3.7 branch.

miss-islington pushed a commit to miss-islington/cpython that referenced this pull request Jun 13, 2018
@zhangyangyu @miss-islington
bpo-33828: Add missing versionchanged note for string.Formatter. (pyt…
345245e 
…honGH-7668)

string.Formatter auto-numbering feature was added in 3.4 and there
is no versionchanged note in its documentation, making the documentation
ambiguous about which version the feature is available.
(cherry picked from commit b9d8ad5)

Co-authored-by: Xiang Zhang <angwerzx@126.com>
@bedevere-bot
Copy link

GH-7675 is a backport of this pull request to the 3.6 branch.

miss-islington pushed a commit to miss-islington/cpython that referenced this pull request Jun 13, 2018
@zhangyangyu @miss-islington
bpo-33828: Add missing versionchanged note for string.Formatter. (pyt…
0a28bb7 
…honGH-7668)

string.Formatter auto-numbering feature was added in 3.4 and there
is no versionchanged note in its documentation, making the documentation
ambiguous about which version the feature is available.
(cherry picked from commit b9d8ad5)

Co-authored-by: Xiang Zhang <angwerzx@126.com>
@miss-islington
Copy link
Contributor

Sorry, @zhangyangyu, I could not cleanly backport this to 2.7 due to a conflict.
Please backport using cherry_picker on command line.
cherry_picker b9d8ad5130e0f77be28a3dec6d468e6470835573 2.7

@ericvsmith
Copy link
Member

Actually, I'm not sure this should be backported to 2.7. Do we normally document Python 3 changes there? I'm not sure the Formatter change got made to 2.7.

zhangyangyu added a commit that referenced this pull request Jun 13, 2018
@zhangyangyu
[2.7] bpo-33828: Add missing versionchanged note for string.Formatter. (
114ff0d 
GH-7668)

string.Formatter auto-numbering feature was added in 3.4 and there
is no versionchanged note in its documentation, making the documentation
ambiguous about which version the feature is available.
@bedevere-bot
Copy link

GH-7676 is a backport of this pull request to the 2.7 branch.

@zhangyangyu
Copy link
Member Author

@ericvsmith No, it's not backport. We won't mention the Python 3 feature in Python 2 doc. But I would like to make it clear that the feature is only available to str.format and unicode.format. Actually it's the Python 2 documentation makes me confused and thought maybe there is some implementation bug with string.Formatter. Pls check GH-7676.

miss-islington added a commit that referenced this pull request Jun 13, 2018
@miss-islington @zhangyangyu
bpo-33828: Add missing versionchanged note for string.Formatter. (GH-…
29fdea5 
…7668)

string.Formatter auto-numbering feature was added in 3.4 and there
is no versionchanged note in its documentation, making the documentation
ambiguous about which version the feature is available.
(cherry picked from commit b9d8ad5)

Co-authored-by: Xiang Zhang <angwerzx@126.com>
miss-islington added a commit that referenced this pull request Jun 13, 2018
@miss-islington @zhangyangyu
bpo-33828: Add missing versionchanged note for string.Formatter. (GH-…
439a9b6 
…7668)

string.Formatter auto-numbering feature was added in 3.4 and there
is no versionchanged note in its documentation, making the documentation
ambiguous about which version the feature is available.
(cherry picked from commit b9d8ad5)

Co-authored-by: Xiang Zhang <angwerzx@126.com>
zhangyangyu added a commit that referenced this pull request Jun 13, 2018
@zhangyangyu
[2.7] bpo-33828: Clarify auto-numbering is not available to string.Fo…
fc8ea20 
…rmatter. (GH-7668) (GH-7676)

string.Formatter auto-numbering feature was added in 3.4 and not
available in 2.7. Make the documentation unambiguous.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@ericvsmith ericvsmith ericvsmith approved these changes

Assignees

@zhangyangyu zhangyangyu

Labels
docs Documentation in the Doc dir skip news
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

None yet
5 participants
@zhangyangyu @miss-islington @bedevere-bot @ericvsmith @the-knights-who-say-ni