Improve the documentation for template strings #856
Conversation
|
@warsaw, thanks for your PR! By analyzing the history of the files in this pull request, we identified @birkenfeld, @ncoghlan and @benjaminp to be potential reviewers. |
Doc/library/string.rst
Outdated
| Template strings provide simpler string substitutions as described in | ||
| :pep:`292`. The primary use case for template strings is for | ||
| internationalization (i18n) since in those contexts, the more featured yet | ||
| complex formatting languages for f-strings and ``str.format()`` can make |
There was a problem hiding this comment.
The informal term "f-string" is not used in the documentation. It would be better to write "formatted string literals".
Doc/library/string.rst
Outdated
| :pep:`292`. The primary use case for template strings is for | ||
| internationalization (i18n) since in those contexts, the more featured yet | ||
| complex formatting languages for f-strings and ``str.format()`` can make | ||
| translations more difficult to implement. As an example of a library for i18n |
There was a problem hiding this comment.
And f-strings can't be used for internationalization at all. This is a syntax, not format string. printf-like formatting can be mentioned. It is used for internationalization and is more powerful and more complex than Template.
There was a problem hiding this comment.
f-strings were originally touted for translations, but I did point out the inappropriateness of them for that purpose. Maybe we don't mention any of them explicitly, and just say "other built-in string formatting features".
| Advanced usage: you can derive subclasses of :class:`Template` to customize | ||
| the placeholder syntax, delimiter character, or the entire regular expression | ||
| used to parse template strings. To do this, you can override these class | ||
| attributes: |
There was a problem hiding this comment.
Is it worth to mention that that attributes should be set before finalizing the class creation (see bpo-12518)?
There was a problem hiding this comment.
Yep, good catch. I'll handle that in this PR too.
Also, add bpo-12518 to the list of issues fixed by this PR.
|
On Mar 27, 2017, at 10:31 PM, Serhiy Storchaka wrote:
LGTM.
Thanks for reviewing!
I should add that I used Template for user customization of the output. For
example, the user can specify the format string to output a limited set of
variables in the status bar. This may include translation, but not
necessarily.
I think I'll just change "The primary use case" to "A primary use case", then
land this branch.
|
bpo-20314
bpo-19824