classification
Title: string.Template: Rewrite docs to emphasize i18n use case
Type: enhancement Stage: resolved
Components: Documentation Versions:
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: barry Nosy List: alex, barry, docs@python, r.david.murray, serhiy.storchaka, techtonik
Priority: normal Keywords:

Created on 2013-11-28 17:07 by techtonik, last changed 2017-03-28 14:04 by barry. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 856 merged barry, 2017-03-27 22:36
Messages (12)
msg204677 - (view) Author: anatoly techtonik (techtonik) Date: 2013-11-28 17:07
http://docs.python.org/2/library/string.html#template-strings

This class could be more useful with the following example:

>>> from string import Template
>>> t = Template('$who likes $what')
>>> who = 'tim'
>>> what = 'kung pao'
>>> t.substitute(locals())
'tim likes kung pao'

This will help PHP folks to transition their .php files.
msg204682 - (view) Author: Barry A. Warsaw (barry) * (Python committer) Date: 2013-11-28 17:35
On Nov 28, 2013, at 05:07 PM, anatoly techtonik wrote:

>This class could be more useful with the following example:
>
>>>> from string import Template
>>>> t = Template('$who likes $what')
>>>> who = 'tim'
>>>> what = 'kung pao'
>>>> t.substitute(locals())
>'tim likes kung pao'
>
>This will help PHP folks to transition their .php files.

I'm not sure what you want to add to the class.  Your example works out of the
box.  See this for an approach my third party library takes:

http://pythonhosted.org/flufl.i18n/docs/using.html#substitutions-and-placeholders
msg204686 - (view) Author: anatoly techtonik (techtonik) Date: 2013-11-28 17:59
There is nothing to add to the class itself. It is about expanding docs section with helpful examples. `string.Template` is undervalued, because it is hard to see how it can be more useful than standard string formatting functions. But for people coming from PHP world, this can be a good start. The docs just need an entrypoint that shows how to use locally defined variables in template string. PHP does this for strings automatically.
msg204687 - (view) Author: Alex Gaynor (alex) * (Python committer) Date: 2013-11-28 18:00
Using locals() in this fashion is a serious anti-pattern, I'm -∞ on the docs suggesting it.
msg204695 - (view) Author: anatoly techtonik (techtonik) Date: 2013-11-28 20:00
@Alex, have you seen http://pythonhosted.org/flufl.i18n/docs/using.html#substitutions-and-placeholders? I really like the brevity, and it is the function that does the magic, so it is fully transparent and you don't need to instantiate string.Template every time. I think its awesome.

Do you have some explanations why passing locals() to string.Template is anti-pattern? I understand that passing "all that you have" is not good, but from my past experience with PHP I can't remember any problems that there are more names than I used. It is templating after all - what do you want to protect from?
msg204700 - (view) Author: Barry A. Warsaw (barry) * (Python committer) Date: 2013-11-28 21:12
A few notes about flufl.i18n's style.  We chose this (extracted from the GNU
Mailman project) because $strings are *way* less error prone for translators
than %s strings, especially when you consider that some languages change the
order of placeholders.  The automatic extraction of substitutions from locals
and globals (under the hood, via the sys._getframe() hack) was critical to
making the source code readable, by avoiding not just duplication, but
triplication of names.

There is a potential security hole though - a malicious translator with access
to the source could analyze the local and global context in which the
translation+substitution is being made, and craft a gettext catalog that adds
some new substitutions that expose sensitive information.  Given that most
translations get little scrutiny, this could be used as an attack vector for
users of some languages (though not English, since it's typically the source
language and thus not translated).

We've decided to accept the risks in exchange for the huge convenience.  We've
never seen such an attack and if we did, we'd address it in the code by
manipulating the globals and locals to avoid the possibility of a leak.  (We'd
also learn to never trust the translators that added the hack.)
msg290547 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2017-03-26 19:17
Formatting with locals() and globals() should be used with careful. This is not the most idiomatic way of formatting. I think that the post in specialised blog would be better place for describing it than Python stdlib documentation.

Peoples coming from PHP world can use f-strings.
msg290548 - (view) Author: Barry A. Warsaw (barry) * (Python committer) Date: 2017-03-26 20:17
We should really restructure string.Template documentation to emphasize i18n.  That's always been its prime use case, and f-strings don't change that (because f-strings are not really appropriate for translations).  Before f-strings, string.Template had other common uses. But f-strings do fulfill most other cases where people were using string.Template, so let's make sure that distinction is clear to people.
msg290552 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2017-03-27 00:48
Let's retitle this, then.
msg290563 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2017-03-27 05:38
In that case issue20314 looks related.
msg290618 - (view) Author: Barry A. Warsaw (barry) * (Python committer) Date: 2017-03-27 14:17
I'll take this one, and see if I can address 20314 also.
msg290717 - (view) Author: Barry A. Warsaw (barry) * (Python committer) Date: 2017-03-28 14:02
New changeset 9f74deba784fc8781d13ed564f69c02ed7c331bb by Barry Warsaw in branch 'master':
Improve the documentation for template strings (#856)
https://github.com/python/cpython/commit/9f74deba784fc8781d13ed564f69c02ed7c331bb
History
Date User Action Args
2017-03-28 14:04:19barrysetstatus: open -> closed
resolution: fixed
stage: needs patch -> resolved
2017-03-28 14:02:09barrysetmessages: + msg290717
2017-03-27 22:36:40barrysetpull_requests: + pull_request758
2017-03-27 14:17:15barrysetmessages: + msg290618
2017-03-27 14:16:39barrysetassignee: docs@python -> barry
2017-03-27 05:38:04serhiy.storchakasettype: enhancement
messages: + msg290563
stage: needs patch
2017-03-27 00:48:25r.david.murraysetnosy: + r.david.murray

messages: + msg290552
title: string.Template: Add PHP-style variable expansion example -> string.Template: Rewrite docs to emphasize i18n use case
2017-03-26 20:17:31barrysetstatus: pending -> open

messages: + msg290548
2017-03-26 19:17:24serhiy.storchakasetstatus: open -> pending
nosy: + serhiy.storchaka
messages: + msg290547

2013-11-28 21:12:59barrysetmessages: + msg204700
2013-11-28 20:00:36techtoniksetmessages: + msg204695
2013-11-28 18:00:02alexsetnosy: + alex
messages: + msg204687
2013-11-28 17:59:01techtoniksetmessages: + msg204686
2013-11-28 17:35:15barrysetmessages: + msg204682
2013-11-28 17:32:00barrysetnosy: + barry
2013-11-28 17:07:04techtonikcreate