From 1ff6afe6845c47dfc58bd563c61752535c4eaac4 Mon Sep 17 00:00:00 2001
From: Guillaume Gauvrit <guillaume@gauvr.it>
Date: Mon, 28 Apr 2025 12:56:44 +0200
Subject: [PATCH] Add a pep for d-string

---
 peps/pep-0791.rst | 153 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 153 insertions(+)
 create mode 100644 peps/pep-0791.rst

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
+      <div>
+         <h1>{{ title }}</h1>
+      </div>
+   """
+
+In both cases, the hint ("sql", "jinja2") is purely for tooling and has
+no impact at runtime.
+It allows syntax highlighting, linting to improves the developer experience.
+
+Invalid usage examples
+----------------------
+
+.. code-block:: python
+
+   d"Just a single-line string"   # Error: must use triple quotes
+
+
+Backwards Compatibility
+=======================
+
+This proposal introduces a new string prefix ``d``.
+It does not affect any existing code.
+
+
+Security Implications
+=====================
+
+Security considerations for this feature would mostly involve data injection,
+especially since we're dealing with string manipulation and possibly embedding
+SQL, HTML, or any templating languages.
+
+Mitigation: While the d-string itself doesn't execute the content, users
+should be aware of security concerns when the content is later executed or
+rendered.
+
+How to Teach This
+=================
+
+The ``d`` prefix will be documented as part of the language standard.
+Code editors should update their syntax highlighting for d-string embeded
+language hinting.
+
+
+Reference Implementation
+========================
+
+A reference implementation may be found at:
+https://github.com/mardiros/cpython/tree/features/d-string
+
+Footnotes
+=========
+
+.. [1] https://spec.commonmark.org/0.31.2/#example-142
+.. [2] https://cucumber.io/docs/gherkin/reference/#doc-strings
+
+Copyright
+=========
+
+This document is placed in the public domain or under the
+CC0-1.0-Universal license, whichever is more permissive.