Doc: inputoutput tutorial improvements

[adorilson]

Just two little improvements: typo and make clear that sprintf is a C function.

[aeros]

Thanks for the PR @adorilson.

[aeros]

Within this context, the sentence is correct with or without the period since it's referring to an example, but I think your change is okay.

[adorilson]

More or less. Periods before an example always ends with a "." or with a ":". Right?
I chose the first one for no special reason.

[aeros]

@adorilson:

More or less. Periods before an example always ends with a "." or with a ":". Right?

Here are all of the correct ways to use examples within the Python docs (as far as I'm aware):

This can be done by simply passing the dict and using square brackets ``'[]'``
to access the keys::

This can be done by simply passing the dict and using square brackets ``'[]'``
to access the keys. For example::

This can be done by simply passing the dict and using square brackets ``'[]'``
to access the keys. ::

Those types of formatting corrections aren't worth their own PR, but it can be useful to touch up on them if you're working on a nearby area for something more significant (such as with this PR). The quote used in PEP 8, "A foolish consistency is the hobgoblin of little minds", would be applicable to changing a section exclusively to use the correct formatting conventions.

[aeros]

+1 on making this section more specific, any reader not familiar with C may not recognize that sprintf() is a C function. Particularly since this is in the tutorial, this should aim to be a new-user friendly as possible and not expect prior knowledge.

As a minor grammar correction, the "to" is not needed and the "a" should remain. However, I noticed that the sentence seems to run on a bit excessively. The ", and" part should be split into a second sentence.

Additionally, the Sphinx role does not accomplish anything here. This can be seen by referring to the documentation (https://docs.python.org/3.9/tutorial/inputoutput.html#old-string-formatting), it provides no link. Therefore, it should be converted into inline code blocks.

Here are the full changes that I would recommend:

It interprets the left argument much like a C ``sprintf()``-style format string
to be applied to the right argument. Then, the string resulting from the
formatting operation is returned.

Note: I did not include the word wrapping since I was just focusing on that individual sentence.

[adorilson]

I'm accord this a lot

this should aim to be a new-user friendly as possible and not expect prior knowledge.

What if we removed the sprintf mention? Something like this:

The % operator (modulo) can also be used for string formatting. Given ``string % values``, % conversion specifications in ``string`` are replaced with zero or more elements of ``values``. This is also known as interpolation operator. For example:

Additionally, this section already has a link to https://docs.python.org/3/library/stdtypes.html#printf-style-string-formatting.

[aeros]

@adorilson:

What if we removed the sprintf mention? Something like this:

Hmm, this is an interesting idea. String interpolation is a far more universal concept across several languages, and is likely to be more relatable to users of other languages without requiring the prior knowledge.

My suggestion would be to change:

This is also known as interpolation operator.

To this:

This operation is commonly known as string interpolation.

While "interpolation operator" is not incorrect, I've seen "string interpolation" mentioned far more commonly. See https://en.wikipedia.org/wiki/String_interpolation and https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/tokens/interpolated. In any search engine, using the query string interpolation <language> is pretty much guaranteed to find the correct results for any widely used programming language.

Also as a more minor suggestion, I would recommend changing:

Given ``string % values``, % conversion specifications in ``string`` are replaced with zero or more elements of ``values``.

To this:

Given ``'string' % values``, instances of ``%`` in ``string`` are replaced with zero or more elements of ``values``.

I think this phrasing will make a bit more sense to readers and adds a bit of clarity with the formatting.

Good idea overall though, I'm definitely on board with it myself. +1

[adorilson]

Great. I will do this. But, I have a question. In my local branch, Do I must revert this commit or just add a new?

[aeros]

@adorilson:

In my local branch, Do I must revert this commit or just add a new?

Either way works. Since this will all get squashed into a single commit when/if the PR is merged, the actual commit log within the PR branch doesn't matter much. I usually prefer to add commits so that I can revert back to it at a later point in time if needed, but it's up to personal preference.

[adorilson]

@aeros167 It's done. Thanks for suggestions.

[aeros]

Since this section also exists in the 3.8 and 3.7 docs, these changes should be able to automatically backport without any merge conflicts.

[csabella]

@aeros, would you like to merge this? Thanks!

[aeros]

Sure! Thanks for reminding me about this PR @csabella, it's a bit easy for me to lose track of the ones I approved prior to getting commit privileges. :-)

[miss-islington]

Thanks @adorilson for the PR, and @aeros for merging it 🌮🎉.. I'm working now to backport this PR to: 3.7, 3.8.
🐍🍒⛏🤖

[bedevere-bot]

GH-20475 is a backport of this pull request to the 3.8 branch.

[miss-islington]

Thanks @adorilson for the PR, and @aeros for merging it 🌮🎉.. I'm working now to backport this PR to: 3.8.
🐍🍒⛏🤖 I'm not a witch! I'm not a witch!

[miss-islington]

Thanks @adorilson for the PR, and @aeros for merging it 🌮🎉.. I'm working now to backport this PR to: 3.9.
🐍🍒⛏🤖

[bedevere-bot]

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

[bedevere-bot]

GH-20477 is a backport of this pull request to the 3.9 branch.