Modernize email example from %-formatting to f-string

[Mariatta]

BPO	38351
Nosy	@freddrake, @rhettinger, @taleinat, @ericvsmith, @JulienPalard, @Mariatta, @miss-islington, @aeros, @idomic, @LewisGaul
PRs	bpo-38351: Modernize email example from %-formatting to f-string #17162 [3.8] bpo-38351: Modernize email examples from %-formatting to f-strings (GH-17162) #17167 [3.7] bpo-38351: Modernize email examples from %-formatting to f-strings (GH-17162) #17168

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2019-11-15.09:16:14.392>
created_at = <Date 2019-10-02.16:45:36.656>
labels = ['easy', '3.7', '3.8', '3.9', 'docs']
title = 'Modernize email example from %-formatting to f-string'
updated_at = <Date 2019-11-15.09:16:14.390>
user = 'https://github.com/Mariatta'

bugs.python.org fields:

activity = <Date 2019-11-15.09:16:14.390>
actor = 'taleinat'
assignee = 'docs@python'
closed = True
closed_date = <Date 2019-11-15.09:16:14.392>
closer = 'taleinat'
components = ['Documentation']
creation = <Date 2019-10-02.16:45:36.656>
creator = 'Mariatta'
dependencies = []
files = []
hgrepos = []
issue_num = 38351
keywords = ['patch', 'easy', 'newcomer friendly']
message_count = 22.0
messages = ['353749', '353757', '353762', '353787', '353790', '353791', '353794', '353797', '353801', '353804', '353810', '353813', '353814', '354266', '354273', '355462', '356629', '356647', '356660', '356661', '356663', '356664']
nosy_count = 12.0
nosy_names = ['fdrake', 'rhettinger', 'taleinat', 'eric.smith', 'docs@python', 'JulienPalard', 'mdk', 'Mariatta', 'miss-islington', 'aeros', 'Ido Michael', 'LewisGaul']
pr_nums = ['17162', '17167', '17168']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = None
url = 'https://bugs.python.org/issue38351'
versions = ['Python 3.7', 'Python 3.8', 'Python 3.9']

[Mariatta]

A string was formatted with %s in the code example

cpython/Doc/includes/email-simple.py

Line 15 in b3e7045

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

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

[freddrake]

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?

[Mariatta]

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.

[freddrake]

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.

[aeros]

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.

[aeros]

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.

[ericvsmith]

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.

[aeros]

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.

[ericvsmith]

> 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.

[freddrake]

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.)

[rhettinger]

(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.

[aeros]

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.

[freddrake]

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.

[idomic]

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.

[Mariatta]

No decision yet. We're waiting for Julien's input. Thanks.

[LewisGaul]

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?

[JulienPalard]

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.

[freddrake]

Thanks, Julien!

Sounds good to me; no reason for a PR addressing this specific issue to be held up once one becomes available.

[taleinat]

New changeset e8acc86 by Tal Einat (Andrey Doroschenko) in branch 'master':
bpo-38351: Modernize email examples from %-formatting to f-strings (GH-17162)
e8acc86

[miss-islington]

New changeset dae27cc by Miss Islington (bot) in branch '3.8':
bpo-38351: Modernize email examples from %-formatting to f-strings (GH-17162)
dae27cc

[miss-islington]

New changeset fe67a53 by Miss Islington (bot) in branch '3.7':
bpo-38351: Modernize email examples from %-formatting to f-strings (GH-17162)
fe67a53

[taleinat]

Thanks for the PR, Andrey!