diff --git a/pep-0501.txt b/pep-0501.txt index efd9e0adc..ce01a250a 100644 --- a/pep-0501.txt +++ b/pep-0501.txt @@ -243,6 +243,17 @@ to the following:: Conversion specifiers --------------------- +NOTE: + + Appropriate handling of conversion specifiers is currently an open question. + Exposing them more directly to custom renderers would increase the + complexity of the ``InterpolationTemplate`` definition without providing an + increase in expressiveness (since they're redundant with calling the builtins + directly). At the same time, they *are* made available as arbitary strings + when writing custom ``string.Formatter`` implementations, so it may be + desirable to offer similar levels of flexibility of interpretation in + interpolation templates. + The ``!a``, ``!r`` and ``!s`` conversion specifiers supported by ``str.format`` and hence PEP 498 are handled in interpolation templates as follows: @@ -277,6 +288,14 @@ For example, the following function would render a template using objects' return format(repr(value), specifier) return template.render(render_field=render_field) +When writing custom renderers, note that the return type of the overall +rendering operation is determined by the return type of the passed in ``render_template`` callable. While this is expected to be a string in most +cases, producing non-string objects *is* permitted. For example, a custom +template renderer could involve an ``sqlalchemy.sql.text`` call that produces +an `SQL Alchemy query object `__. + +Non-strings may also be returned from ``render_field``, as long as it is paired +with a ``render_template`` implementation that expects that behaviour. Expression evaluation --------------------- @@ -453,7 +472,7 @@ templates can still be prerendered with ``format``, rather than delegating the rendering to the called function. This reflects the key difference from PEP 498, which *always* eagerly applies -the default rendering, without any convenient way to delegate that choice to +the default rendering, without any way to delegate the choice of renderer to another section of the code. Preserving the raw template string @@ -503,7 +522,11 @@ Due to the original design of the ``str.format`` substitution syntax in PEP 3101 being inspired by C#'s string formatting syntax, the specific field substitution syntax used in PEP 498 is consistent not only with Python's own ``str.format`` syntax, but also with string formatting in C#, including the native "$-string" interpolation syntax introduced in C# 6.0 (released in July -2015). This means that while this particular substitution syntax may not +2015). The related ``IFormattable`` interface in C# forms the basis of a +`number of elements `__ of C#'s internationalization and localization +support. + +This means that while this particular substitution syntax may not currently be widely used for translation of *Python* applications (losing out to traditional %-formatting and the designed-specifically-for-i18n ``string.Template`` formatting), it *is* a popular translation format in the @@ -547,6 +570,9 @@ References .. [#] FormattableString and C# native string interpolation (https://msdn.microsoft.com/en-us/library/dn961160.aspx) +.. [#] IFormattable interface in C# (see remarks for globalization notes) + (https://msdn.microsoft.com/en-us/library/system.iformattable.aspx) + .. [#] Running external commands in Julia (http://julia.readthedocs.org/en/latest/manual/running-external-programs/)