classification
Title: Modernize email example from %-formatting to f-string
Type: Stage: resolved
Components: Documentation Versions: Python 3.9, Python 3.8, Python 3.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Ido Michael, JulienPalard, LewisGaul, Mariatta, aeros, docs@python, eric.smith, fdrake, mdk, miss-islington, rhettinger, taleinat
Priority: normal Keywords: easy, newcomer friendly, patch

Created on 2019-10-02 16:45 by Mariatta, last changed 2019-11-15 09:16 by taleinat. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 17162 merged dorosch, 2019-11-15 06:21
PR 17167 merged miss-islington, 2019-11-15 09:03
PR 17168 merged miss-islington, 2019-11-15 09:04
Messages (22)
msg353749 - (view) Author: Mariatta (Mariatta) * (Python committer) Date: 2019-10-02 16:45
A string was formatted with %s in the code example 

https://github.com/python/cpython/blob/b3e7045f8314e7b62cd95861d207fe2f97e47198/Doc/includes/email-simple.py#L15 

```
msg['Subject'] = 'The contents of %s' % textfile
```

It would be great to modernize that into fstring.

Doc can be read at: https://docs.python.org/3.7/library/email.examples.html
msg353757 - (view) Author: Fred Drake (fdrake) (Python committer) Date: 2019-10-02 17:25
Does it make sense to change just one example?

I'm not sure what the long-term stance is on whether %-formatting should be replaced at this point, but shouldn't this be a matter of which string formatting approach we want overall, rather than adjusting only specific examples?
msg353762 - (view) Author: Mariatta (Mariatta) * (Python committer) Date: 2019-10-02 18:16
I think updating one isolated code example is less invasive and easier to review, instead of one big PR to change everything from "%s" to str.format or f-string.

I brought up this example code merely because I happen to be reading this page.
msg353787 - (view) Author: Fred Drake (fdrake) (Python committer) Date: 2019-10-02 23:17
I agree that it's less invasive and easier to review.

My question (and it's just that) is whether we've made a decision to prefer one formatting syntax over others (outside of examples discussing the formatting approaches themselves).

If a decision is made to prefer one over others, it's worth making that decision separately, and then using separate PRs to deal with updates to different parts of the docs.

Added Julien Palard to the issue; I'd value input on this.
msg353790 - (view) Author: Kyle Stanley (aeros) * (Python triager) Date: 2019-10-03 00:06
Welcome back from the OOOS break Mariatta!

> My question (and it's just that) is whether we've made a decision to prefer one formatting syntax over others (outside of examples discussing the formatting approaches themselves).

I agree that we should reach a consensus on the preferred string formatting style. However, there seems to be two separate questions here:

1) Should the code examples in the docs be updated to use f-strings?

2) Should ALL instances of the old string formatting be updated to use f-strings? This would affect every *.py; potentially leading to additional code churn, which adds clutter to the commit logs and git blame.

The first one is far less costly and has very minimal risk of breakage. The cost of updating every *.py to use f-strings is worth considering, but is significantly higher and has more potential consequences, especially for the regression tests. I'm personally in favor of updating the code examples first and discussing the second question in a python-dev thread due to the wide impact.

> If a decision is made to prefer one over others, it's worth making that decision separately, and then using separate PRs to deal with updates to different parts of the docs.

Once we reach a decision on the matter, I think this particular issue could serve as a great first PR for a new contributor to become familiar with the workflow, so it would be a good candidate for the "newcomer friendly" label. Most python users are well acquainted with string formatting. I wouldn't mind opening a PR to fix it myself, but I think that leaving it open for a new contributor to work on as an intro to the workflow would be far more beneficial.

Although there may be a benefit to use f-strings instead here, there's certainly no rush to have it completed in a short period of time. I would be in favor of having each PR address a single documentation file. This would help accelerate the review process and provide a valuable learning experience to a greater number of new contributors, in comparison to a single PR that updates every single code example in the docs.
msg353791 - (view) Author: Kyle Stanley (aeros) * (Python triager) Date: 2019-10-03 00:10
> so it would be a good candidate for the "newcomer friendly" label

Never mind, just noticed this was already labeled as newcomer friendly. I only saw the "easy" label at first. (:

If consensus is reached for this, we can open a separate issue for addressing the other doc files, something along the lines of "Update code examples to use f-strings". As mentioned earlier I think it would be worth having each new contributor update all of the instances in a single *.rst in a PR, but it can be a single issue.
msg353794 - (view) Author: Eric V. Smith (eric.smith) * (Python committer) Date: 2019-10-03 00:49
I definitely think we should not modify any code in the stdlib just to switch to f-strings.

I think the code examples in the docs would benefit from a consistent style, and since f-strings are the least verbose way to format strings, I'd endorse using them except where .format or %-formatting is the point of the example.

I agree with Fred that hearing from Julien would be helpful.
msg353797 - (view) Author: Kyle Stanley (aeros) * (Python triager) Date: 2019-10-03 01:35
> I definitely think we should not modify any code in the stdlib just to switch to f-strings.

Does this also apply to updating code to use f-strings in an area that's already being modified for a functional purpose? 

I agree that that we shouldn't update stdlib code for the sole purpose of switching to f-strings, but if a function or method is already being changed for another purpose, I don't think updating the formatting to use f-strings is an issue. This would probably have to be decided on a case-by-case basis though.
msg353801 - (view) Author: Eric V. Smith (eric.smith) * (Python committer) Date: 2019-10-03 01:44
>> I definitely think we should not modify any code in the stdlib just to switch to f-strings.

> Does this also apply to updating code to use f-strings in an area that's already being modified for a functional purpose? 

No. As I said, not just to switch to f-strings. If other changes are also being made, discretion is advised. Just like any other cleanup.
msg353804 - (view) Author: Fred Drake (fdrake) (Python committer) Date: 2019-10-03 01:55
Definitely agree with Eric on this; code modernization is definitely on the risky side, so judicious updates are important. (Of course, not updating is also a risk, eventually. But not much of one in this case.)

This issue is really about whether the docs should be updated to use the newer syntax. In general, I think we should update the docs, and we've delayed long enough for the general application of f-strings.

There will be cases to be wary of, certainly. I'm thinking especially of calls to the logging methods, or anywhere else doing delayed formatting. (Not that I can think of others off the top of my head.)
msg353810 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2019-10-03 03:35
>  (Not that I can think of others off the top of my head.)

For the most part, templating examples can be switched to the .format() style but shouldn't be switched to f-strings.  The former technique is still necessary if someone wants to move templates to an external file or if they need to use gettext() i18n, f-strings don't work well in the latter case.

Also note, there are no plans to completely remove old-style formatting.  AFAICT, it will be around forever, so people still need to see some examples of each.
msg353813 - (view) Author: Kyle Stanley (aeros) * (Python triager) Date: 2019-10-03 05:06
> For the most part, templating examples can be switched to the .format() style but shouldn't be switched to f-strings.

Is there no specific use case for the older "%s" % sub template that .format() doesn't have?

> The former technique is still necessary if someone wants to move templates to an external file

Interesting, I wasn't aware of that. This seems like it might be worth a brief mention in https://docs.python.org/3.9/library/stdtypes.html#str.format. 

> AFAICT, it will be around forever, so people still need to see some examples of each.

To allow users to see examples of each, would you suggest that we should leave the existing .format() examples as is and have more recently created examples use f-strings? I'd be okay with this, as long as there's a balance of both everywhere (particularly in the tutorial).

Personally, I think that the f-string examples should be used more commonly used since they're generally more concise and readable. But, I can definitely understand the purpose of leaving the older ones around as long as they have a specific use case and are still utilized.
msg353814 - (view) Author: Fred Drake (fdrake) (Python committer) Date: 2019-10-03 05:45
I'd like to see consistent usage by default, with specific examples using the older forms as appropriate.  The use cases Raymond identified are worth discussing (and the tutorial may be a good place for this), and well as mentioned in the reference docs for the '%s' % x and ''.format() operations (and string.Template(), of course).

I would not like to see different syntaxes randomly applied to different examples that happen to involve formatting, but where that's not the emphasis.
msg354266 - (view) Author: Ido Michael (Ido Michael) * Date: 2019-10-09 13:02
So what was decided?

I can fix this issue and I can wait for a final conclusion as it wasn't clear from the thread.
msg354273 - (view) Author: Mariatta (Mariatta) * (Python committer) Date: 2019-10-09 14:09
No decision yet. We're waiting for Julien's input. Thanks.
msg355462 - (view) Author: Lewis Gaul (LewisGaul) * Date: 2019-10-27 12:07
Hi all, I'm a newcomer interested in making this small fix, but it looks like this has become a bit of a contentious issue. Are there any advances on whether this is a desirable fix?
msg356629 - (view) Author: Julien Palard (mdk) * (Python committer) Date: 2019-11-14 22:15
So, for newcomers finding this via "easy issues", go for it, you can fix this one :)

On the different subjects discussed:

# Mass-edit the stdlib

We all agree that we should not mass-edit stdlib, (yet upgrading %-formatting to a newer syntax when modifying the same line may sometimes be a good idea).


# Mass-edit the doc

Having an f-string only doc is not possible, as Raymond mentionned (i18n, logging, templating), and not desirable: we need to document all existing formatting syntax. But the question is less "should we move everything to f-strings" than "should we move most examples out of %-formatting".


# Let's not encourage %-formatting

As we introduced str.format to fix issues from %-formatting [1] and allow extending formatting [2], we should not encourage newcomers to %-format strings.

Good news: in the tutorial there's a *single* occurence of %-formatting in a paragraph named "Old string formatting"!

There's probably a bunch of other places where upgrading the syntax in the doc would be a good idea, let's do it as we see them, when we feel it should obviously be upgraded, it also make nice easy issues, exactly as Mariatta did with this one (thanks Mariatta!).


[1]: %-formatting a single value that may or may not be a tuple.
[2]: allowing to format everything thrue __format__, not just the hardcoded list of type recognized by %-formatting.
msg356647 - (view) Author: Fred Drake (fdrake) (Python committer) Date: 2019-11-15 05:21
Thanks, Julien!

Sounds good to me; no reason for a PR addressing this specific issue to be held up once one becomes available.
msg356660 - (view) Author: Tal Einat (taleinat) * (Python committer) Date: 2019-11-15 09:03
New changeset e8acc865a3f112b98417f676c897ca6ec2dac2c7 by Tal Einat (Andrey Doroschenko) in branch 'master':
bpo-38351: Modernize email examples from %-formatting to f-strings (GH-17162)
https://github.com/python/cpython/commit/e8acc865a3f112b98417f676c897ca6ec2dac2c7
msg356661 - (view) Author: miss-islington (miss-islington) Date: 2019-11-15 09:11
New changeset dae27cc8e72106c2eceeff9af83d1e58b2bb68d5 by Miss Islington (bot) in branch '3.8':
bpo-38351: Modernize email examples from %-formatting to f-strings (GH-17162)
https://github.com/python/cpython/commit/dae27cc8e72106c2eceeff9af83d1e58b2bb68d5
msg356663 - (view) Author: miss-islington (miss-islington) Date: 2019-11-15 09:14
New changeset fe67a5354010f33128c4f461da8ffb925e0f4de8 by Miss Islington (bot) in branch '3.7':
bpo-38351: Modernize email examples from %-formatting to f-strings (GH-17162)
https://github.com/python/cpython/commit/fe67a5354010f33128c4f461da8ffb925e0f4de8
msg356664 - (view) Author: Tal Einat (taleinat) * (Python committer) Date: 2019-11-15 09:16
Thanks for the PR, Andrey!
History
Date User Action Args
2019-11-15 09:16:14taleinatsetstatus: open -> closed
resolution: fixed
messages: + msg356664

stage: patch review -> resolved
2019-11-15 09:14:47miss-islingtonsetmessages: + msg356663
2019-11-15 09:11:51miss-islingtonsetnosy: + miss-islington
messages: + msg356661
2019-11-15 09:04:06miss-islingtonsetpull_requests: + pull_request16677
2019-11-15 09:03:59miss-islingtonsetpull_requests: + pull_request16676
2019-11-15 09:03:50taleinatsetnosy: + taleinat
messages: + msg356660
2019-11-15 06:21:26doroschsetkeywords: + patch
stage: needs patch -> patch review
pull_requests: + pull_request16672
2019-11-15 05:21:45fdrakesetmessages: + msg356647
2019-11-14 22:15:12mdksetnosy: + mdk
messages: + msg356629
2019-10-27 12:07:16LewisGaulsetnosy: + LewisGaul
messages: + msg355462
2019-10-09 14:09:01Mariattasetmessages: + msg354273
2019-10-09 13:02:36Ido Michaelsetnosy: + Ido Michael
messages: + msg354266
2019-10-03 05:45:58fdrakesetmessages: + msg353814
2019-10-03 05:06:25aerossetmessages: + msg353813
2019-10-03 03:35:39rhettingersetnosy: + rhettinger
messages: + msg353810
2019-10-03 01:55:29fdrakesetmessages: + msg353804
2019-10-03 01:44:40eric.smithsetmessages: + msg353801
2019-10-03 01:35:44aerossetmessages: + msg353797
2019-10-03 00:49:56eric.smithsetnosy: + eric.smith
messages: + msg353794
2019-10-03 00:10:47aerossetmessages: + msg353791
2019-10-03 00:06:08aerossetnosy: + aeros
messages: + msg353790
2019-10-02 23:17:19fdrakesetnosy: + JulienPalard
messages: + msg353787
2019-10-02 18:16:12Mariattasetmessages: + msg353762
2019-10-02 17:25:51fdrakesetnosy: + fdrake
messages: + msg353757
2019-10-02 16:45:36Mariattacreate