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

Created on 2019-10-02 16:45 by Mariatta, last changed 2019-10-09 14:09 by Mariatta.

Messages (15)
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.
History
Date User Action Args
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