-
-
Notifications
You must be signed in to change notification settings - Fork 32.2k
gh-132661: Document t-strings and templatelib
#135229
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: main
Are you sure you want to change the base?
Conversation
…nce of `templatelib.Template`.
syntax and evaluation rules as `formatted string literals <f-strings>`_, with | ||
the following differences: | ||
|
||
- Rather than evaluating to a `str` object, t-strings evaluate to a |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Lint fix, either use double backticks (this is RST not MD):
- Rather than evaluating to a `str` object, t-strings evaluate to a | |
- Rather than evaluating to a ``str`` object, t-strings evaluate to a |
Or create link:
- Rather than evaluating to a `str` object, t-strings evaluate to a | |
- Rather than evaluating to a :class:`str` object, t-strings evaluate to a |
the expressions are evaluated and a new `Interpolation` object (also from the | ||
:mod:`string.templatelib` module) is created, which contains the evaluated | ||
value of the expression. That `Interpolation` object is found in the containing | ||
`Template`. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
the expressions are evaluated and a new `Interpolation` object (also from the | |
:mod:`string.templatelib` module) is created, which contains the evaluated | |
value of the expression. That `Interpolation` object is found in the containing | |
`Template`. | |
the expressions are evaluated and a new :class:`~string.templatelib.Interpolation` object (also from the | |
:mod:`string.templatelib` module) is created, which contains the evaluated | |
value of the expression. That :class:`~string.templatelib.Interpolation` object is found in the containing | |
:class:`~string.templatelib.Template`. |
the following differences: | ||
|
||
- Rather than evaluating to a `str` object, t-strings evaluate to a | ||
`Template` object from the :mod:`string.templatelib` module. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
`Template` object from the :mod:`string.templatelib` module. | |
:class:`~string.templatelib.Template` object from the :mod:`string.templatelib` module. |
Template | ||
-------- | ||
|
||
The :class:`Template` class describes the contents of a template string. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We try to avoid creating too many hyperlinks, see:
https://devguide.python.org/documentation/style-guide/#links
So we don't need to link this one back to this same section. We can prevent Sphinx from linking like this, but it still applies the other formatting:
The :class:`Template` class describes the contents of a template string. | |
The :class:`!Template` class describes the contents of a template string. |
|
||
The :class:`Template` class describes the contents of a template string. | ||
|
||
The most common way to create a new :class:`Template` instance is to use the t-string literal syntax. This syntax is identical to that of :ref:`f-strings`, except that the string is prefixed with a ``t`` instead of an ``f``. For example, the following code creates a :class:`Template` that can be used to format strings: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We try to avoid creating too many hyperlinks, see:
https://devguide.python.org/documentation/style-guide/#links
So we don't need to link this repeated mentions. We can prevent Sphinx from linking like this, but it still applies the other formatting:
The most common way to create a new :class:`Template` instance is to use the t-string literal syntax. This syntax is identical to that of :ref:`f-strings`, except that the string is prefixed with a ``t`` instead of an ``f``. For example, the following code creates a :class:`Template` that can be used to format strings: | |
The most common way to create a new :class:`!Template` instance is to use the t-string literal syntax. This syntax is identical to that of :ref:`f-strings`, except that the string is prefixed with a ``t`` instead of an ``f``. For example, the following code creates a :class:`!Template` that can be used to format strings: |
Also, please try and wrap at ~80 chars.
https://devguide.python.org/documentation/markup/#use-of-whitespace
>>> print(list(greeting)) | ||
['Hello ', Interpolation('World', 'name', None, ''), '!'] | ||
|
||
It is also possible to create a :class:`Template` directly, using its constructor. This takes an arbitrary collection of strings and :class:`Interpolation` instances: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It is also possible to create a :class:`Template` directly, using its constructor. This takes an arbitrary collection of strings and :class:`Interpolation` instances: | |
It is also possible to create a :class:`!Template` directly, using its constructor. This takes an arbitrary collection of strings and :class:`Interpolation` instances: |
Create a new :class:`Template` object. | ||
|
||
:param args: A mix of strings and :class:`Interpolation` instances in any order. | ||
:type args: str | Interpolation | ||
|
||
If two or more consecutive strings are passed, they will be concatenated into a single value in the :attr:`~Template.strings` attribute. For example, the following code creates a :class:`Template` with a single final string: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Similarly, we try and avoid linking back to the same unit.
Create a new :class:`Template` object. | |
:param args: A mix of strings and :class:`Interpolation` instances in any order. | |
:type args: str | Interpolation | |
If two or more consecutive strings are passed, they will be concatenated into a single value in the :attr:`~Template.strings` attribute. For example, the following code creates a :class:`Template` with a single final string: | |
Create a new :class:`!Template` object. | |
:param args: A mix of strings and :class:`Interpolation` instances in any order. | |
:type args: str | Interpolation | |
If two or more consecutive strings are passed, they will be concatenated into a single value in the :attr:`~Template.strings` attribute. For example, the following code creates a :class:`!Template` with a single final string: |
|
||
.. class:: Interpolation(*args) | ||
|
||
Create a new :class:`Interpolation` object. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Create a new :class:`Interpolation` object. | |
Create a new :class:`!Interpolation` object. |
:param format_spec: An optional, arbitrary string used as the :ref:`format specification <formatspec>` to present the value. | ||
:type expression: str = "" | ||
|
||
The :class:`Interpolation` type represents an expression inside a template string. It is shallow immutable -- its attributes cannot be reassigned. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The :class:`Interpolation` type represents an expression inside a template string. It is shallow immutable -- its attributes cannot be reassigned. | |
The :class:`!Interpolation` type represents an expression inside a template string. It is shallow immutable -- its attributes cannot be reassigned. |
@hugovk Thank you for the review and the helpful early feedback! Useful to know about linking. (FWIW this is very early stage still, so I expect plenty more linting and other issues that we'll eventually resolve.) |
[DRAFT] This has only just begun and is very much a work in progress; putting up a draft PR now for visibility.
We're keeping a TODO list of PEP 750 documentation tasks. There's lots to do.
📚 Documentation preview 📚: https://cpython-previews--135229.org.readthedocs.build/