reflow

Author: methane

peps/pep-0822.rst

@@ -12,9 +12,11 @@ Post-History: `05-Jan-2026 <https://discuss.python.org/t/105519>`__,
 Abstract
 ========
 
-This PEP proposes to add a feature that automatically removes indentation from multiline string literals.
+This PEP proposes to add a feature that automatically removes indentation from
+multiline string literals.
 
-Dedented multiline strings use a new prefix "d" (shorthand for "dedent") before the opening quote of a multiline string literal.
+Dedented multiline strings use a new prefix "d" (shorthand for "dedent") before
+the opening quote of a multiline string literal.
 
 Example (spaces are visualized as ``_``):
 
@@ -42,15 +44,20 @@ When writing multiline string literals within deeply indented Python code,
 users are faced with the following choices:
 
 * Accept that the content of the string literal will be left-aligned.
-* Use multiple single-line string literals concatenated together instead of a multiline string literal.
+* Use multiple single-line string literals concatenated together instead of
+  a multiline string literal.
 * Use ``textwrap.dedent()`` to remove indentation.
 
-All of these options have drawbacks in terms of code readability and maintainability.
+All of these options have drawbacks in terms of code readability and
+maintainability.
 
 * Left-aligned multiline strings look awkward and tend to be avoided.
-  In practice, many places including Python's own test code choose other methods.
-* Concatenated single-line string literals are more verbose and harder to maintain.
-* ``textwrap.dedent()`` is implemented in Python so it requires some runtime overhead.
+  In practice, many places including Python's own test code choose other
+  methods.
+* Concatenated single-line string literals are more verbose and harder to
+  maintain.
+* ``textwrap.dedent()`` is implemented in Python so it requires some runtime
+  overhead.
   It cannot be used in hot paths where performance is critical.
 
 This PEP aims to provide a built-in syntax for dedented multiline strings that
@@ -76,10 +83,11 @@ However, this approach has several drawbacks:
   they cannot be dedented.
 * f-strings may interpolate expressions as multiline string without indent.
   In such case, f-string + ``str.dedent()`` cannot dedent the whole string.
-* t-strings do not create ``str`` objects, so they cannot use the ``str.dedent()`` method.
-  While adding a ``dedent()`` method to ``string.templatelib.Template`` is an option,
-  it would lead to inconsistency since t-strings and f-strings are very similar but
-  would have different behaviors regarding dedentation.
+* t-strings do not create ``str`` objects, so they cannot use the
+  ``str.dedent()`` method.
+  While adding a ``dedent()`` method to ``string.templatelib.Template`` is an
+  option, it would lead to inconsistency since t-strings and f-strings are very
+  similar but would have different behaviors regarding dedentation.
 
 The ``str.dedent()`` method can still be useful for non-literal strings,
 so this PEP does not preclude that idea.
@@ -102,17 +110,21 @@ This newline is not included in the resulting string.
 
 The amount of indentation to be removed is determined by the whitespace
 (``' '`` or ``'\t'``) preceding the closing triple quotes.
-Mixing spaces and tabs in indentation raises a ``TabError``, similar to Python's
-own indentation rules.
+Mixing spaces and tabs in indentation raises a ``TabError``, similar to
+Python's own indentation rules.
 
-The dedentation process removes the determined amount of leading whitespace from every line in the string.
-Lines that are shorter than the determined indentation become just an empty line (e.g. ``"\n"``).
+The dedentation process removes the determined amount of leading whitespace
+from every line in the string.
+Lines that are shorter than the determined indentation become just an empty
+line (e.g. ``"\n"``).
 Otherwise, if the line does not start with the determined indentation,
 Python raises an ``IndentationError``.
 
-Unless combined with the "r" prefix, backslash escapes are processed after removing indentation.
+Unless combined with the "r" prefix, backslash escapes are processed after
+removing indentation.
 So you cannot use ``\\t`` to create indentation.
-And you can use line continuation (backslash at the end of line) and remove indentation from the continued line.
+And you can use line continuation (backslash at the end of line) and remove
+indentation from the continued line.
 
 Examples:
 
@@ -199,37 +211,44 @@ Examples:
     print(type(s))  # <class 'string.templatelib.Template'>
     print(s.strings)  # ('Hello, ', '!\n')
     print(s.values)  # ('World',)
-    print(s.interpolations)  # (Interpolation('World', '"world".title()', None, ''),)
+    print(s.interpolations)
+    # (Interpolation('World', '"world".title()', None, ''),)
 
 
 How to Teach This
 =================
 
 In the tutorial, we can introduce d-string with triple quote string literals.
 Additionally, we can add a note in the ``textwrap.dedent()`` documentation,
-providing a link to the d-string section in the language reference or the relevant part of the tutorial.
+providing a link to the d-string section in the language reference or
+the relevant part of the tutorial.
 
 
 Other Languages having Similar Features
 ========================================
 
 Java 15 introduced a feature called `text blocks <https://openjdk.org/jeps/378>`__.
-Since Java had not used triple qutes before, they introduced triple quotes for multiline string literals with automatic indent removal.
+Since Java had not used triple qutes before, they introduced triple quotes for
+multiline string literals with automatic indent removal.
 
-C# 11 also introduced a similar feature called `raw string literals <https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/proposals/csharp-11.0/raw-string-literal>`__.
+C# 11 also introduced a similar feature called
+`raw string literals <https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/proposals/csharp-11.0/raw-string-literal>`__.
 
 `Julia <https://docs.julialang.org/en/v1/manual/strings/#Triple-Quoted-String-Literals>`__ and
 `Swift <https://docs.swift.org/swift-book/documentation/the-swift-programming-language/stringsandcharacters/#Multiline-String-Literals>`__
 also support triple-quoted string literals that automatically remove indentation.
 
 PHP 7.3 introduced `Flexible Heredoc and Nowdoc Syntaxes <https://wiki.php.net/rfc/flexible_heredoc_nowdoc_syntaxes>`__
-Although it uses closing marker (e.g. ``<<<END ... END``) instead of triple quote,
-it removes indent from text too.
+Although it uses closing marker (e.g. ``<<<END ... END``) instead of
+triple quote, it removes indent from text too.
 
-Java and Julia uses the least-indented line to determine the amount of indentation to be removed.
-Swift, C#, and PHP uses the indentation of the closing triple quotes or closing marker.
+Java and Julia uses the least-indented line to determine the amount of
+indentation to be removed.
+Swift, C#, and PHP uses the indentation of the closing triple quotes or
+closing marker.
 
-This PEP chose the Swift and C# approach because it is simpler and easier to explain.
+This PEP chose the Swift and C# approach because it is simpler and easier to
+explain.
 
 
 Reference Implementation
@@ -245,8 +264,10 @@ Rejected Ideas
 ``str.dedent()`` method
 -----------------------
 
-As mentioned in the Rationale section, this PEP doesn't reject the idea of a ``str.dedent()`` method.
-A faster version of ``textwrap.dedent()`` implemented in C would be useful for runtime dedentation.
+As mentioned in the Rationale section, this PEP doesn't reject the idea of a
+``str.dedent()`` method.
+A faster version of ``textwrap.dedent()`` implemented in C would be useful for
+runtime dedentation.
 
 However, d-string is more suitable for multiline string literals because:
 
@@ -258,28 +279,37 @@ However, d-string is more suitable for multiline string literals because:
 Triple-backtick
 ---------------
 
-It is considered that `using triple backticks <https://discuss.python.org/t/40679>`__
+It is considered that
+`using triple backticks <https://discuss.python.org/t/40679>`__
 for dedented multiline strings could be an alternative syntax.
-This notation is familiar to us from Markdown. While there were past concerns about certain keyboard layouts,
+This notation is familiar to us from Markdown. While there were past concerns
+about certain keyboard layouts,
 nowadays many people are accustomed to typing this notation.
 
-However, this notation conflicts when embedding Python code within Markdown or vice versa.
+However, this notation conflicts when embedding Python code within Markdown or
+vice versa.
 Therefore, considering these drawbacks, increasing the variety of quote
-characters is not seen as a superior idea compared to adding a prefix to string literals.
+characters is not seen as a superior idea compared to adding a prefix to
+string literals.
 
 
 ``__future__`` import
 ---------------------
 
-Instead of adding a prefix to string literals, the idea of using a ``__future__``
-import to change the default behavior of multiline string literals was also considered.
+Instead of adding a prefix to string literals, the idea of using a
+``__future__`` import to change the default behavior of multiline
+string literals was also considered.
 This could help simplify Python's grammar in the future.
 
-But rewriting all existing complex codebases to the new notation may not be straightforward.
-Until all multiline strings in that source code are rewritten to the new notation, automatic dedentation cannot be utilized.
+But rewriting all existing complex codebases to the new notation may not be
+straightforward.
+Until all multiline strings in that source code are rewritten to
+the new notation, automatic dedentation cannot be utilized.
 
-Until all users can rewrite existing codebases to the new notation, two types of Python syntax will coexist indefinitely.
-Therefore, `many people preferred the new string prefix <https://discuss.python.org/t/90988/54>`__ over the ``__future__`` import.
+Until all users can rewrite existing codebases to the new notation,
+two types of Python syntax will coexist indefinitely.
+Therefore, `many people preferred the new string prefix <https://discuss.python.org/t/90988/54>`__
+over the ``__future__`` import.
 
 
 Copyright