From fb77fc0b35a2f337627788cbe0b878796cc69444 Mon Sep 17 00:00:00 2001 From: Locked-chess-official <13140752715@163.com> Date: Thu, 7 Aug 2025 14:51:41 +0800 Subject: [PATCH 1/8] Create pep-0802.rst --- peps/pep-0802.rst | 140 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 140 insertions(+) create mode 100644 peps/pep-0802.rst diff --git a/peps/pep-0802.rst b/peps/pep-0802.rst new file mode 100644 index 00000000000..9fe59e12ce9 --- /dev/null +++ b/peps/pep-0802.rst @@ -0,0 +1,140 @@ +PEP: 802 +Title: Add `str.template()` Method to Dynamically Construct Template Objects +Author: Huang Hao Hua <13140752715@163.com> +Status: Draft +Type: Standards Track +Topic: String Formatting +Created: 2025-08-07 +Python-Version: 3.13 +Requires: 750 +Post-History: 2025-08-07 + +Abstract +======== + +This PEP proposes adding a new method ``str.template(*args, **kwargs) -> Template`` +to the built-in ``str`` type. This method allows dynamically creating template +objects using the template string syntax introduced in PEP 750. + +This complements PEP 750’s ``t""`` syntax by providing a runtime equivalent API +for dynamic string templating and deferred rendering. + +Motivation +========== + +PEP 750 introduces a structured template string syntax ``t""`` as an alternative +to ``f""`` and ``str.format()``. While ``t""`` allows compile-time template creation, +there is no standardized way to construct a ``Template`` object dynamically at runtime. + +Adding a ``str.template()`` method serves several needs: + +- Internationalization systems often generate format strings dynamically. +- Dynamic UIs or templates may assemble format strings based on user input or context. +- Reusable templates can be precompiled and stored as structured objects. +- The API would provide symmetry with ``str.format()``, making it easier to adopt. + +Specification +============= + +Method Signature +---------------- + +.. code:: python + + str.template(*args, **kwargs) -> Template + +Behavior +-------- + +- The method returns an instance of the ``Template`` class as defined by PEP 750. +- The string instance is treated as the template pattern. +- The passed arguments are used to bind values to the template at creation. +- Like ``str.format()``, both positional (``{0}``) and keyword (``{name}``) placeholders are supported. +- The returned ``Template`` object supports deferred rendering via ``__str__`` or explicit ``render()``. + +Example Usage +------------- + +.. code:: python + + tpl = "Hello, {name}!".template(name="Alice") + assert isinstance(tpl, Template) + print(str(tpl)) # Outputs: Hello, Alice! + + # Dynamic construction + fmt = "User {id} has status {status}." + tpl = fmt.template(id=42, status="active") + +Rationale +========= + +- Provides a runtime-compatible API for PEP 750’s static ``t""`` templates. +- Enables structured templates with delayed interpolation. +- Offers a migration path from ``.format()`` to structured templating. +- Useful for applications requiring dynamic template generation and reuse. +- Mirrors the mental model of ``str.format()``, reducing learning curve. + +Backwards Compatibility +======================= + +This is a fully additive proposal. ``str`` currently does not have a ``template()`` +method, so no code will be broken. + +This method has no effect on the legacy ``string.Template`` class or its behavior. + +Reference Implementation +======================== + +A sample implementation in pure Python could look like: + +.. code:: python + + class Template: + def __init__(self, pattern, *args, **kwargs): + self.pattern = pattern + self.args = args + self.kwargs = kwargs + + def __str__(self): + return self.pattern.format(*self.args, **self.kwargs) + + def str_template(self, *args, **kwargs): + return Template(self, *args, **kwargs) + + str.template = str_template + +In the CPython implementation, this would likely be implemented in C and integrated +into the ``str`` type’s method table. + +Alternatives +============ + +1. **Do nothing**: Continue using string concatenation or ``str.format()``. +2. **Use a standalone constructor**: Like ``Template.from_string(...)``. This is more verbose and less elegant. +3. **Inject into ``Template`` class only**: May reduce discoverability compared to a ``str`` method. + +Rejected Ideas +============== + +- Overloading ``str.format()`` to support structured templates. +- Adding new operators (e.g., ``@`` or ``%``) for template binding. +- Overloading ``t""`` to allow dynamic behavior (breaks simplicity and predictability). + +Open Issues +=========== + +- Whether the bound arguments are stored inside the ``Template`` object or applied at render time. +- Whether ``Template`` should expose a ``.render(...)`` method or rely solely on ``__str__``. + +References +========== + +- PEP 750: Structured Template Strings (`https://peps.python.org/pep-0750/`_) +- PEP 498: Formatted String Literals +- PEP 3101: Advanced String Formatting + +Copyright +========= + +This document has been placed in the public domain. + From bf8d2afd5d0ecaa8c76f0d5f13b1924faea28133 Mon Sep 17 00:00:00 2001 From: Locked-chess-official <13140752715@163.com> Date: Thu, 7 Aug 2025 14:58:20 +0800 Subject: [PATCH 2/8] Update pep-0802.rst --- peps/pep-0802.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/peps/pep-0802.rst b/peps/pep-0802.rst index 9fe59e12ce9..988254ee936 100644 --- a/peps/pep-0802.rst +++ b/peps/pep-0802.rst @@ -5,7 +5,7 @@ Status: Draft Type: Standards Track Topic: String Formatting Created: 2025-08-07 -Python-Version: 3.13 +Python-Version: 3.15 Requires: 750 Post-History: 2025-08-07 From 8bdaf05d7376f464d55484481e05b9093628f341 Mon Sep 17 00:00:00 2001 From: Locked-chess-official <13140752715@163.com> Date: Thu, 7 Aug 2025 15:07:12 +0800 Subject: [PATCH 3/8] Update pep-0802.rst --- peps/pep-0802.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/peps/pep-0802.rst b/peps/pep-0802.rst index 988254ee936..9d3438261ae 100644 --- a/peps/pep-0802.rst +++ b/peps/pep-0802.rst @@ -1,28 +1,28 @@ PEP: 802 -Title: Add `str.template()` Method to Dynamically Construct Template Objects +Title: Add str.template() Method to Dynamically Construct Template Objects Author: Huang Hao Hua <13140752715@163.com> Status: Draft Type: Standards Track Topic: String Formatting -Created: 2025-08-07 +Created: 07-Aug-2025 Python-Version: 3.15 Requires: 750 -Post-History: 2025-08-07 +Post-History: 07-Aug-2025 Abstract ======== This PEP proposes adding a new method ``str.template(*args, **kwargs) -> Template`` to the built-in ``str`` type. This method allows dynamically creating template -objects using the template string syntax introduced in PEP 750. +objects using the template string syntax introduced in :pep:`750`. -This complements PEP 750’s ``t""`` syntax by providing a runtime equivalent API +This complements :pep:`750`’s ``t""`` syntax by providing a runtime equivalent API for dynamic string templating and deferred rendering. Motivation ========== -PEP 750 introduces a structured template string syntax ``t""`` as an alternative +:pep:`750` introduces a structured template string syntax ``t""`` as an alternative to ``f""`` and ``str.format()``. While ``t""`` allows compile-time template creation, there is no standardized way to construct a ``Template`` object dynamically at runtime. @@ -46,7 +46,7 @@ Method Signature Behavior -------- -- The method returns an instance of the ``Template`` class as defined by PEP 750. +- The method returns an instance of the ``Template`` class as defined by :pep:`750`. - The string instance is treated as the template pattern. - The passed arguments are used to bind values to the template at creation. - Like ``str.format()``, both positional (``{0}``) and keyword (``{name}``) placeholders are supported. @@ -68,7 +68,7 @@ Example Usage Rationale ========= -- Provides a runtime-compatible API for PEP 750’s static ``t""`` templates. +- Provides a runtime-compatible API for :pep:`750`’s static ``t""`` templates. - Enables structured templates with delayed interpolation. - Offers a migration path from ``.format()`` to structured templating. - Useful for applications requiring dynamic template generation and reuse. From 772865b06b0b1e6c88996b7bf2fc49ca6f3e7d57 Mon Sep 17 00:00:00 2001 From: Locked-chess-official <13140752715@163.com> Date: Thu, 7 Aug 2025 15:11:08 +0800 Subject: [PATCH 4/8] Update pep-0802.rst --- peps/pep-0802.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/peps/pep-0802.rst b/peps/pep-0802.rst index 9d3438261ae..41ba5bc12dc 100644 --- a/peps/pep-0802.rst +++ b/peps/pep-0802.rst @@ -4,9 +4,9 @@ Author: Huang Hao Hua <13140752715@163.com> Status: Draft Type: Standards Track Topic: String Formatting +Requires: 750 Created: 07-Aug-2025 Python-Version: 3.15 -Requires: 750 Post-History: 07-Aug-2025 Abstract From a20561af8693393b7b4edd14cf30ec2cd26dcf64 Mon Sep 17 00:00:00 2001 From: Locked-chess-official <13140752715@163.com> Date: Thu, 7 Aug 2025 15:12:25 +0800 Subject: [PATCH 5/8] Update pep-0802.rst --- peps/pep-0802.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/peps/pep-0802.rst b/peps/pep-0802.rst index 41ba5bc12dc..85e499ac1f4 100644 --- a/peps/pep-0802.rst +++ b/peps/pep-0802.rst @@ -3,7 +3,7 @@ Title: Add str.template() Method to Dynamically Construct Template Objects Author: Huang Hao Hua <13140752715@163.com> Status: Draft Type: Standards Track -Topic: String Formatting +Topic: Standard Library Requires: 750 Created: 07-Aug-2025 Python-Version: 3.15 @@ -129,7 +129,7 @@ Open Issues References ========== -- PEP 750: Structured Template Strings (`https://peps.python.org/pep-0750/`_) +- :pep:`750`: Structured Template Strings (`https://peps.python.org/pep-0750/`_) - PEP 498: Formatted String Literals - PEP 3101: Advanced String Formatting From 0b43f72b06a23fdac5c0e8410fb1c170f32c918c Mon Sep 17 00:00:00 2001 From: Locked-chess-official <13140752715@163.com> Date: Thu, 7 Aug 2025 15:16:37 +0800 Subject: [PATCH 6/8] Update pep-0802.rst --- peps/pep-0802.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/peps/pep-0802.rst b/peps/pep-0802.rst index 85e499ac1f4..3f62f1fc4cc 100644 --- a/peps/pep-0802.rst +++ b/peps/pep-0802.rst @@ -3,7 +3,7 @@ Title: Add str.template() Method to Dynamically Construct Template Objects Author: Huang Hao Hua <13140752715@163.com> Status: Draft Type: Standards Track -Topic: Standard Library +Topic: Library Requires: 750 Created: 07-Aug-2025 Python-Version: 3.15 @@ -130,8 +130,8 @@ References ========== - :pep:`750`: Structured Template Strings (`https://peps.python.org/pep-0750/`_) -- PEP 498: Formatted String Literals -- PEP 3101: Advanced String Formatting +- :pep:`498`: Formatted String Literals +- :pep:`3101`: Advanced String Formatting Copyright ========= From 710dbeda570c664c0ac4f8307a56b6c5afb69184 Mon Sep 17 00:00:00 2001 From: Locked-chess-official <13140752715@163.com> Date: Thu, 7 Aug 2025 15:25:12 +0800 Subject: [PATCH 7/8] Update pep-0802.rst --- peps/pep-0802.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/peps/pep-0802.rst b/peps/pep-0802.rst index 3f62f1fc4cc..bb23a48dc2e 100644 --- a/peps/pep-0802.rst +++ b/peps/pep-0802.rst @@ -3,7 +3,7 @@ Title: Add str.template() Method to Dynamically Construct Template Objects Author: Huang Hao Hua <13140752715@163.com> Status: Draft Type: Standards Track -Topic: Library +Topic: Packaging Requires: 750 Created: 07-Aug-2025 Python-Version: 3.15 From ca83107a3f29a3bbf38e597554db6b088b17229e Mon Sep 17 00:00:00 2001 From: Locked-chess-official <13140752715@163.com> Date: Thu, 7 Aug 2025 15:28:13 +0800 Subject: [PATCH 8/8] Update pep-0802.rst --- peps/pep-0802.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/peps/pep-0802.rst b/peps/pep-0802.rst index bb23a48dc2e..136362a6e30 100644 --- a/peps/pep-0802.rst +++ b/peps/pep-0802.rst @@ -129,7 +129,7 @@ Open Issues References ========== -- :pep:`750`: Structured Template Strings (`https://peps.python.org/pep-0750/`_) +- :pep:`750`: Structured Template Strings - :pep:`498`: Formatted String Literals - :pep:`3101`: Advanced String Formatting