diff --git a/peps/pep-0791.rst b/peps/pep-0791.rst new file mode 100644 index 00000000000..7369a995009 --- /dev/null +++ b/peps/pep-0791.rst @@ -0,0 +1,153 @@ +PEP: 791 +Title: Dedented Multiline Strings with Optional Language Hinting +Author: Guillaume Gauvrit +Discussions-To: Pending +Status: Draft +Type: Standards Track +Created: 06-May-2025 +Python-Version: 3.15 + + + +Abstract +======== + +This PEP proposes a new string prefix ``d`` for Python that enables automatic +dedenting of multiline strings. +Optionally, a language hint may be included immediately after the opening +triple quotes to assist editors and tooling with syntax highlighting. + + +Motivation +========== + +Writing readable, properly formatted multiline strings currently requires +the use of ``textwrap.dedent``, adding verbosity and cognitive overhead. +Developers often embed structured content (SQL, HTML, ...) within strings, +but Python does not natively support lightweight language hinting. + +Combining dedenting with an optional language hint improves both code +readability and tooling support without impacting runtime behavior. + +Additionally, this proposal complements the upcoming t-string +feature (PEP 750), which would allow template strings with placeholders. +By combining the d-string with t-strings, developers can easily format and +manage indented content (like SQL queries or template code) while keeping +everything neat and readable. + +The d-string's dedenting behavior would work seamlessly with t-strings, +enabling both automatic formatting and interpolation in a single workflow, +streamlining code maintenance and readability. + + +Rationale +========= + +- **Dedenting** greatly improves the usability of multiline strings. +- **Language hinting** helps modern editors provide syntax highlighting, + linting, and formatting. +- Keeping these two features together makes sense, as language-specific blocks + are often multi-line. +- There is **no runtime penalty**: the hint is ignored after parsing. + + +Specification +============= + +- ``d`` prefix can only be used with triple-quoted strings (``"""`` or + ``'''``). +- Content inside is **automatically dedented** based on the smallest common + leading whitespace. +- Optionally, the first non-whitespace token immediately after the opening + triple quotes will be treated as a **language hint** for editors/tooling. + This is comparable to markdown code fence info string [1]_ in order to + speficy a media, or Gherkin doc strings content type [2]_. +- At runtime, the resulting value is a normal ``str`` object, identical + to any regular string. + +Syntax examples +--------------- + +Dedented string without hint: + +.. code-block:: python + + d""" + Some plain text + across multiple lines + """ + +Dedented string with language hint: + +.. code-block:: python + + d"""sql + SELECT * + FROM users + """ + +Additional example with another language hint: + +.. code-block:: python + + d"""jinja2 +