[issue38351] Modernize email example from %-formatting to f-string

[Tal Einat]

Tal Einat  added the comment:

Thanks for the PR, Andrey!

--
resolution:  -> fixed
stage: patch review -> resolved
status: open -> closed

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue38351] Modernize email example from %-formatting to f-string

[miss-islington]

miss-islington  added the comment:


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


--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue38351] Modernize email example from %-formatting to f-string

[miss-islington]

miss-islington  added the comment:


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


--
nosy: +miss-islington

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue38351] Modernize email example from %-formatting to f-string

[miss-islington]

Change by miss-islington :


--
pull_requests: +16677
pull_request: https://github.com/python/cpython/pull/17168

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue38351] Modernize email example from %-formatting to f-string

[miss-islington]

Change by miss-islington :


--
pull_requests: +16676
pull_request: https://github.com/python/cpython/pull/17167

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue38351] Modernize email example from %-formatting to f-string

[Tal Einat]

Tal Einat  added the comment:


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


--
nosy: +taleinat

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue38351] Modernize email example from %-formatting to f-string

[Andrei Daraschenka]

Change by Andrei Daraschenka :


--
keywords: +patch
pull_requests: +16672
stage: needs patch -> patch review
pull_request: https://github.com/python/cpython/pull/17162

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue38351] Modernize email example from %-formatting to f-string

[Fred Drake]

Fred Drake  added the comment:

Thanks, Julien!

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

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue38351] Modernize email example from %-formatting to f-string

[Julien Palard]

Julien Palard  added the comment:

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.

--
nosy: +mdk

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue38351] Modernize email example from %-formatting to f-string

[Lewis Gaul]

Lewis Gaul  added the comment:

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?

--
nosy: +Lewis Gaul

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue38351] Modernize email example from %-formatting to f-string

[Mariatta]

Mariatta  added the comment:

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

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue38351] Modernize email example from %-formatting to f-string

[Ido Michael]

Ido Michael  added the comment:

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.

--
nosy: +Ido Michael

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue38351] Modernize email example from %-formatting to f-string

[Fred L. Drake, Jr.]

Fred L. Drake, Jr.  added the comment:

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.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue38351] Modernize email example from %-formatting to f-string

[Kyle Stanley]

Kyle Stanley  added the comment:

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

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue38351] Modernize email example from %-formatting to f-string

[Raymond Hettinger]

Raymond Hettinger  added the comment:

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

--
nosy: +rhettinger

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue38351] Modernize email example from %-formatting to f-string

[Fred L. Drake, Jr.]

Fred L. Drake, Jr.  added the comment:

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

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue38351] Modernize email example from %-formatting to f-string

[Eric V. Smith]

Eric V. Smith  added the comment:

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

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue38351] Modernize email example from %-formatting to f-string

[Kyle Stanley]

Kyle Stanley  added the comment:

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

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue38351] Modernize email example from %-formatting to f-string

[Eric V. Smith]

Eric V. Smith  added the comment:

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.

--
nosy: +eric.smith

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue38351] Modernize email example from %-formatting to f-string

[Kyle Stanley]

Kyle Stanley  added the comment:

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

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue38351] Modernize email example from %-formatting to f-string

[Kyle Stanley]

Kyle Stanley  added the comment:

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.

--
nosy: +aeros167

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue38351] Modernize email example from %-formatting to f-string

[Fred L. Drake, Jr.]

Fred L. Drake, Jr.  added the comment:

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.

--
nosy: +JulienPalard

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue38351] Modernize email example from %-formatting to f-string

[Mariatta]

Mariatta  added the comment:

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.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue38351] Modernize email example from %-formatting to f-string

[Fred L. Drake, Jr.]

Fred L. Drake, Jr.  added the comment:

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?

--
nosy: +fdrake

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue38351] Modernize email example from %-formatting to f-string

[Mariatta]

New submission from Mariatta :

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

--
assignee: docs@python
components: Documentation
keywords: easy, newcomer friendly
messages: 353749
nosy: Mariatta, docs@python
priority: normal
severity: normal
stage: needs patch
status: open
title: Modernize email example from %-formatting to f-string
versions: Python 3.7, Python 3.8, Python 3.9

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com