PEP 822: cleanup and clalification (#4855)

methane · web-flow · commit 4eaa0841c1bc · 2026-03-09T10:19:30.000+09:00
PEP 822: cleanup
diff --git a/peps/pep-0822.rst b/peps/pep-0822.rst
@@ -59,7 +59,8 @@ maintainability.
   methods.
 * Concatenated single-line string literals are more verbose and harder to
   maintain. Writing ``"\n"`` at the end of each line is tedious.
-  It's easy to miss the semicolons between many string concatenations.
+  In argument lists or collection literals, separating commas between
+  multi-line string literals are easy to miss.
 * ``textwrap.dedent()`` is implemented in Python so it requires some runtime
   overhead. Moreover, it cannot be used to dedent t-strings.
 
@@ -82,8 +83,8 @@ However, this approach has several drawbacks:
   the ``dedent()`` method would need to accept an argument specifying
   the amount of indentation to remove.
   This would be cumbersome and error-prone for users.
-* When continuation lines (lines after line ends with a backslash) are used,
-  they cannot be dedented.
+* When continuation lines (lines following a line that ends with a backslash)
+  are used, 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
@@ -93,8 +94,8 @@ However, this approach has several drawbacks:
   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.
-However, for ease of use with multiline string literals, providing dedicated
+so this PEP does not reject that idea.
+However, for dedenting multiline strings, especially t-strings, using dedicated
 syntax is superior.
 
 
@@ -103,11 +104,13 @@ Specification
 
 Add a new string literal prefix "d" for dedented multiline strings.
 This prefix can be combined with "f", "t", "r", and "b" prefixes.
+As with existing string prefixes, uppercase and lowercase forms have the same
+meaning, and any order is allowed.
 
 This prefix is only for multiline string literals.
-So it can only be used with triple quotes (``"""`` or ``'''``).
+It can only be used with triple quotes (``"""`` or ``'''``).
 
-Opening triple quotes needs to be followed by a newline character.
+The opening triple quotes must be followed by a newline character.
 This newline is not included in the resulting string.
 The content of the d-string starts from the next line.
 
@@ -127,7 +130,7 @@ the string.
 
 * Lines that are longer than or equal in length to the determined indentation
   must start with the determined indentation.
-  Othrerwise, Python raises an ``IndentationError``.
+  Otherwise, Python raises an ``IndentationError``.
   The determined indentation is removed from these lines.
 * Lines that are shorter than the determined indentation (including
   empty lines) must be a prefix of the determined indentation.
@@ -140,11 +143,13 @@ So you cannot use ``\\t`` in indentations.
 And you can use line continuation (backslash at the end of line) and remove
 indentation from the continued line.
 
-Examples:
+
+Examples
+--------
 
 .. code-block:: python
 
-   # d-string must starts with a newline.
+   # d-string must start with a newline.
    s = d""           # SyntaxError: d-string must be triple-quoted
    s = d""""""       # SyntaxError: d-string must start with a newline
    s = d"""Hello"""  # SyntaxError: d-string must start with a newline
@@ -180,7 +185,7 @@ Examples:
    ..."""  # Longest common indentation is '..'.
    print(repr(s))  # 'Hello\n\n\nWorld!\n.'
 
-   # Closing qutotes can be on the same line as the last content line.
+   # Closing quotes can be on the same line as the last content line.
    # In this case, the string does not end with a newline.
    s = d"""
    ..Hello
@@ -204,15 +209,15 @@ Examples:
    # Line continuation with backslash works as usual.
    # But you cannot put a backslash right after the opening quotes.
    s = d"""
-   ..Hello \
+   ..Hello.\
    ..World!\
    .."""
-   print(repr(s))  # 'Hello World!'
+   print(repr(s))  # 'Hello.World!'
 
    s = d"""\
    ..Hello
    ..World
-   .."""  # SyntaxError: d-string must starts with a newline.
+   .."""  # SyntaxError: d-string must start with a newline.
 
    # d-string can be combined with r-string, b-string, f-string, and t-string.
    s = dr"""
@@ -228,15 +233,15 @@ Examples:
    print(repr(s))  # b'Hello\nWorld!\n'
 
    s = df"""
-   ....Hello, {"world".title()}!
+   ....Hello,.{"world".title()}!
    ...."""
    print(repr(s))  # 'Hello,.World!\n'
 
    s = dt"""
-   ....Hello, {"world".title()}!
+   ....Hello,.{"world".title()}!
    ...."""
    print(type(s))   # <class 'string.templatelib.Template'>
-   print(s.strings) # ('Hello, ', '!\n')
+   print(s.strings) # ('Hello,.', '!\n')
    print(s.values)  # ('World',)
 
 
@@ -248,7 +253,7 @@ explained as follows:
 
 * ``textwrap.dedent()`` is a regular function, but d-string is part of the
   language syntax. d-string has no runtime overhead, and it can remove
-  indentation from t-strings.
+  indentation even from t-strings.
 
 * When using ``textwrap.dedent()``, you need to start with ``"""\`` to avoid
   including the first newline character, but with d-string, the string content
@@ -312,12 +317,11 @@ explained as follows:
      assert s1 == s2
 
 
-
 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
+Since Java had not used triple quotes before, they introduced triple quotes for
 multiline string literals with automatic indent removal.
 
 C# 11 also introduced a similar feature called
@@ -337,7 +341,7 @@ that removes indent from lines in heredoc.
 Perl has `"Indented Here-documents <https://perldoc.perl.org/perl5260delta#Indented-Here-documents>`__
 since Perl 5.26 as well.
 
-Java, Julia, and Ruby uses the least-indented line to determine the amount of
+Java, Julia, and Ruby use the least-indented line to determine the amount of
 indentation to be removed.
 Swift, C#, PHP, and Perl use the indentation of the closing triple quotes or
 closing marker.
@@ -408,10 +412,10 @@ Removing newline in the last line
 ---------------------------------
 
 Another idea considered was to remove the newline character from the last line.
-This idea is same to Swift's multiline string literals.
+This idea is similar to Swift's multiline string literals.
 
-With this idea, user can write multiline string having indent without trailing
-newline like below:
+With this idea, users can write multiline strings with indentation without
+a trailing newline like below:
 
 .. code-block:: python
 
