PEP 813: Implement !p pretty-print conversion for f-strings

Add the !p conversion flag for f-strings that calls sys.__prettyhook__
(defaulting to pprint.pformat) on the value. When a callable is provided
as a format spec (e.g. f"{obj!p:my_formatter}"), the format spec is
evaluated as a Python expression and called on the value instead.

Key changes:
- Tokenizer: When !p: is detected inside an f-string expression, keep
  expression tokenization mode instead of switching to format-spec mode,
  allowing the format spec to be parsed as a Python expression.
- Grammar: Add fstring_pretty_conversion rule and two new alternatives
  in fstring_replacement_field for !p with and without callable.
- Parser: Add _PyPegen_check_pretty_conversion() to validate the !p
  conversion, and _PyPegen_pretty_formatted_value() to build the AST.
- Codegen: Handle 'p' conversion - without callable uses CONVERT_VALUE
  with new FVC_PRETTY opcode arg; with callable emits CALL bytecode.
- Runtime: Add _PyObject_Pretty() conversion function that looks up
  sys.__prettyhook__ and calls it on the object.
- sys module: Add sys.prettyhook (default: pprint.pformat) and
  sys.__prettyhook__ backup copy following the existing hook pattern.

https://claude.ai/code/session_01M64NyGDjnkVvSmDRmJFF64

Author: claude

Grammar/python.gram

@@ -953,9 +953,15 @@ fstring_middle[expr_ty]:
     | fstring_replacement_field
     | t=FSTRING_MIDDLE { _PyPegen_constant_from_token(p, t) }
 fstring_replacement_field[expr_ty]:
+    | '{' a=annotated_rhs debug_expr='='? conv=fstring_pretty_conversion ':' pretty_func=annotated_rhs rbrace='}' {
+        _PyPegen_pretty_formatted_value(p, a, debug_expr, conv, pretty_func, rbrace, EXTRA) }
+    | '{' a=annotated_rhs debug_expr='='? conv=fstring_pretty_conversion rbrace='}' {
+        _PyPegen_pretty_formatted_value(p, a, debug_expr, conv, NULL, rbrace, EXTRA) }
     | '{' a=annotated_rhs debug_expr='='? conversion=[fstring_conversion] format=[fstring_full_format_spec] rbrace='}' {
         _PyPegen_formatted_value(p, a, debug_expr, conversion, format, rbrace, EXTRA) }
     | invalid_fstring_replacement_field
+fstring_pretty_conversion[Token*]:
+    | conv_token="!" conv=NAME { _PyPegen_check_pretty_conversion(p, conv_token, conv) }
 fstring_conversion[ResultTokenWithMetadata*]:
     | conv_token="!" conv=NAME { _PyPegen_check_fstring_conversion(p, conv_token, conv) }
 fstring_full_format_spec[ResultTokenWithMetadata*]:

Include/ceval.h

@@ -125,13 +125,14 @@ PyAPI_FUNC(void) PyEval_ReleaseThread(PyThreadState *tstate);
                  }
 
 /* Masks and values used by FORMAT_VALUE opcode. */
-#define FVC_MASK      0x3
+#define FVC_MASK      0x7
 #define FVC_NONE      0x0
 #define FVC_STR       0x1
 #define FVC_REPR      0x2
 #define FVC_ASCII     0x3
-#define FVS_MASK      0x4
-#define FVS_HAVE_SPEC 0x4
+#define FVC_PRETTY    0x4
+#define FVS_MASK      0x8
+#define FVS_HAVE_SPEC 0x8
 
 #ifndef Py_LIMITED_API
 #  define Py_CPYTHON_CEVAL_H

Lib/test/test_fstring.py

@@ -1866,6 +1866,104 @@ def test_gh139516(self):
                 f.write('''def f(a): pass\nf"{f(a=lambda: 'à'\n)}"'''.encode())
             assert_python_ok(script)
 
+    def test_pretty_conversion_basic(self):
+        """PEP 813: Test !p conversion calls sys.__prettyhook__"""
+        import pprint
+        x = [1, 2, 3]
+        self.assertEqual(f'{x!p}', pprint.pformat(x))
+
+        d = {'hello': 'world', 'foo': 'bar'}
+        self.assertEqual(f'{d!p}', pprint.pformat(d))
+
+        # Simple values
+        self.assertEqual(f'{42!p}', pprint.pformat(42))
+        self.assertEqual(f'{"hello"!p}', pprint.pformat("hello"))
+
+    def test_pretty_conversion_with_callable(self):
+        """PEP 813: Test !p with callable format spec"""
+        x = [1, 2, 3]
+
+        # Use repr as the callable
+        self.assertEqual(f'{x!p:repr}', repr(x))
+
+        # Use str as the callable
+        self.assertEqual(f'{x!p:str}', str(x))
+
+        # Use a custom function
+        def my_format(obj):
+            return f'custom({obj!r})'
+        self.assertEqual(f'{x!p:my_format}', 'custom([1, 2, 3])')
+
+    def test_pretty_conversion_with_expression_callable(self):
+        """PEP 813: Test !p with expression as callable"""
+        import pprint
+
+        d = {'key1': 'value1', 'key2': 'value2'}
+
+        # Attribute access
+        pp = pprint.PrettyPrinter(width=20)
+        result = f'{d!p:pp.pformat}'
+        self.assertEqual(result, pp.pformat(d))
+
+        # Method call in callable expression
+        result = f'{d!p:pprint.PrettyPrinter(width=20).pformat}'
+        self.assertEqual(result, pprint.PrettyPrinter(width=20).pformat(d))
+
+    def test_pretty_conversion_debug(self):
+        """PEP 813: Test !p with debug (=) syntax"""
+        import pprint
+        x = [1, 2, 3]
+        result = f'{x=!p}'
+        self.assertEqual(result, f'x={pprint.pformat(x)}')
+
+    def test_pretty_conversion_custom_hook(self):
+        """PEP 813: Test overriding sys.__prettyhook__"""
+        import sys
+        original = sys.__prettyhook__
+
+        def custom_hook(obj):
+            return f'CUSTOM({obj!r})'
+
+        try:
+            sys.__prettyhook__ = custom_hook
+            x = [1, 2, 3]
+            self.assertEqual(f'{x!p}', 'CUSTOM([1, 2, 3])')
+        finally:
+            sys.__prettyhook__ = original
+
+    def test_pretty_hook_exists(self):
+        """PEP 813: Test sys.prettyhook and sys.__prettyhook__ exist"""
+        import sys
+        self.assertTrue(hasattr(sys, 'prettyhook'))
+        self.assertTrue(hasattr(sys, '__prettyhook__'))
+        self.assertTrue(callable(sys.prettyhook))
+        self.assertTrue(callable(sys.__prettyhook__))
+
+    def test_pretty_conversion_p_as_variable(self):
+        """PEP 813: Test that 'p' can still be used as a variable name"""
+        p = 42
+        self.assertEqual(f'{p}', '42')
+        self.assertEqual(f'{p!r}', '42')
+        self.assertEqual(f'{p!s}', '42')
+
+        # And as part of expressions
+        p = [1, 2, 3]
+        self.assertEqual(f'{p[0]}', '1')
+
+    def test_pretty_conversion_not_callable_error(self):
+        """PEP 813: Test error when format spec is not callable"""
+        x = 42
+        with self.assertRaises(TypeError):
+            f'{x!p:42}'
+
+    def test_pretty_conversion_combined(self):
+        """PEP 813: Test !p in combined f-strings"""
+        x = {'a': 1}
+        y = [1, 2]
+        result = f'{x!p} and {y!r}'
+        import pprint
+        self.assertEqual(result, f'{pprint.pformat(x)} and {y!r}')
+
 
 if __name__ == '__main__':
     unittest.main()

Objects/interpolationobject.c

@@ -212,9 +212,12 @@ _PyInterpolation_Build(PyObject *value, PyObject *str, int conversion, PyObject
             case FVC_STR:
                 interpolation->conversion = _Py_LATIN1_CHR('s');
                 break;
+            case FVC_PRETTY:
+                interpolation->conversion = _Py_LATIN1_CHR('p');
+                break;
             default:
                 PyErr_SetString(PyExc_SystemError,
-                    "Interpolation() argument 'conversion' must be one of 's', 'a' or 'r'");
+                    "Interpolation() argument 'conversion' must be one of 's', 'a', 'r', or 'p'");
                 Py_DECREF(interpolation);
                 return NULL;
         }

Parser/action_helpers.c

@@ -983,6 +983,25 @@ _PyPegen_check_fstring_conversion(Parser *p, Token* conv_token, expr_ty conv)
     return result_token_with_metadata(p, conv, conv_token->metadata);
 }
 
+/* PEP 813: Check for !p pretty-print conversion.
+ * Returns the conv_token on success, NULL without error on failure
+ * (causing the PEG parser to backtrack). */
+Token *
+_PyPegen_check_pretty_conversion(Parser *p, Token *conv_token, expr_ty conv)
+{
+    if (conv_token->lineno != conv->lineno || conv_token->end_col_offset != conv->col_offset) {
+        return NULL;  /* Not adjacent - let other rules handle it */
+    }
+    if (PyUnicode_GET_LENGTH(conv->v.Name.id) != 1) {
+        return NULL;
+    }
+    Py_UCS4 first = PyUnicode_READ_CHAR(conv->v.Name.id, 0);
+    if (first != 'p') {
+        return NULL;  /* Not !p - backtrack */
+    }
+    return conv_token;
+}
+
 ResultTokenWithMetadata *
 _PyPegen_setup_full_format_spec(Parser *p, Token *colon, asdl_expr_seq *spec, int lineno, int col_offset,
                                 int end_lineno, int end_col_offset, PyArena *arena)
@@ -1604,6 +1623,43 @@ expr_ty _PyPegen_formatted_value(Parser *p, expr_ty expression, Token *debug, Re
     return _PyAST_JoinedStr(values, lineno, col_offset, debug_end_line, debug_end_offset, p->arena);
 }
 
+expr_ty _PyPegen_pretty_formatted_value(Parser *p, expr_ty expression, Token *debug,
+                                        Token *conv_token, expr_ty pretty_func,
+                                        Token *closing_brace, int lineno, int col_offset,
+                                        int end_lineno, int end_col_offset, PyArena *arena) {
+    /* PEP 813: !p conversion.
+     * conversion = 'p' (112).
+     * format_spec holds the callable expression, or NULL for default
+     * (sys.__prettyhook__). */
+    int conversion_val = (int)'p';
+
+    expr_ty formatted_value = _PyAST_FormattedValue(
+        expression, conversion_val, pretty_func,
+        lineno, col_offset, end_lineno,
+        end_col_offset, arena
+    );
+
+    if (!debug) {
+        return formatted_value;
+    }
+
+    /* Handle debug expression (f"{foo=!p:callable}") */
+    int debug_end_line = conv_token->lineno;
+    int debug_end_offset = conv_token->col_offset;
+    PyObject *debug_metadata = conv_token->metadata;
+
+    expr_ty debug_text = _PyAST_Constant(debug_metadata, NULL, lineno, col_offset + 1, debug_end_line,
+                                            debug_end_offset - 1, p->arena);
+    if (!debug_text) {
+        return NULL;
+    }
+
+    asdl_expr_seq *values = _Py_asdl_expr_seq_new(2, arena);
+    asdl_seq_SET(values, 0, debug_text);
+    asdl_seq_SET(values, 1, formatted_value);
+    return _PyAST_JoinedStr(values, lineno, col_offset, debug_end_line, debug_end_offset, p->arena);
+}
+
 static expr_ty
 _build_concatenated_bytes(Parser *p, asdl_expr_seq *strings, int lineno,
                         int col_offset, int end_lineno, int end_col_offset,

Parser/lexer/lexer.c

@@ -1096,6 +1096,7 @@ tok_get_normal_mode(struct tok_state *tok, tokenizer_mode* current_tok, struct t
         the_current_tok->last_expr_end = -1;
         the_current_tok->in_format_spec = 0;
         the_current_tok->in_debug = 0;
+        the_current_tok->in_pretty_conversion = 0;
 
         enum string_kind_t string_kind = FSTRING;
         switch (*tok->start) {
@@ -1265,7 +1266,25 @@ tok_get_normal_mode(struct tok_state *tok, tokenizer_mode* current_tok, struct t
             return MAKE_TOKEN(ERRORTOKEN);
         }
 
-        if (c == ':' && cursor == current_tok->curly_bracket_expr_start_depth) {
+        /* When we see '!' at the top level of an f-string expression,
+         * peek ahead for 'p' followed by ':'. If found, set the
+         * in_pretty_conversion flag so that ':' does NOT trigger
+         * format-spec mode. This allows the text after ':' to be
+         * tokenized as a regular Python expression (PEP 813). */
+        if (c == '!' && cursor == current_tok->curly_bracket_expr_start_depth) {
+            int peek1 = tok_nextc(tok);
+            if (peek1 == 'p') {
+                int peek2 = tok_nextc(tok);
+                if (peek2 == ':') {
+                    current_tok->in_pretty_conversion = 1;
+                }
+                tok_backup(tok, peek2);
+            }
+            tok_backup(tok, peek1);
+        }
+
+        if (c == ':' && cursor == current_tok->curly_bracket_expr_start_depth
+                && !current_tok->in_pretty_conversion) {
             current_tok->kind = TOK_FSTRING_MODE;
             current_tok->in_format_spec = 1;
             p_start = tok->start;
@@ -1365,6 +1384,7 @@ tok_get_normal_mode(struct tok_state *tok, tokenizer_mode* current_tok, struct t
                 current_tok->kind = TOK_FSTRING_MODE;
                 current_tok->in_format_spec = 0;
                 current_tok->in_debug = 0;
+                current_tok->in_pretty_conversion = 0;
             }
         }
         break;

Parser/lexer/state.h

@@ -66,6 +66,7 @@ typedef struct _tokenizer_mode {
     char* last_expr_buffer;
     int in_debug;
     int in_format_spec;
+    int in_pretty_conversion;
 
     enum string_kind_t string_kind;
 } tokenizer_mode;