gh-153568: Add fast paths for single-token atoms in the parser

A bare name or number followed by a token that cannot extend the
current construct is now built directly, avoiding a dozen rule
invocations per atom in expressions and skipping failing alternatives
for assignment targets and subscripts. Rules declare their hook with
the new (fastpath=function) flag next to (memo); the generator only
emits the hook call and knows nothing about tokens or expressions.

Author: pablogsal

Grammar/python.gram

@@ -761,7 +761,7 @@ named_expression[expr_ty]:
     | invalid_named_expression
     | expression !':='
 
-disjunction[expr_ty] (memo):
+disjunction[expr_ty] (memo, fastpath=_PyPegen_atom_fast_path):
     | a=conjunction b=('or' c=conjunction { c })+ { _PyAST_BoolOp(
         Or,
         CHECK(asdl_expr_seq*, _PyPegen_seq_insert_in_front(p, a, b)),
@@ -775,7 +775,7 @@ conjunction[expr_ty] (memo):
         EXTRA) }
     | inversion
 
-inversion[expr_ty] (memo):
+inversion[expr_ty] (memo, fastpath=_PyPegen_atom_fast_path):
     | 'not' a=inversion { _PyAST_UnaryOp(Not, a, EXTRA) }
     | comparison
 
@@ -889,7 +889,7 @@ slices[expr_ty]:
     | a=slice !',' { a }
     | a[asdl_expr_seq*]=','.(slice | starred_expression)+ [','] { _PyAST_Tuple(a, Load, EXTRA) }
 
-slice[expr_ty]:
+slice[expr_ty] (fastpath=_PyPegen_slice_fast_path):
     | a=[expression] ':' b=[expression] c=[':' d=[expression] { d }] { _PyAST_Slice(a, b, c, EXTRA) }
     | a=named_expression { a }
 
@@ -1133,7 +1133,7 @@ star_target[expr_ty] (memo):
         _PyAST_Starred(CHECK(expr_ty, _PyPegen_set_expr_context(p, a, Store)), Store, EXTRA) }
     | target_with_star_atom
 
-target_with_star_atom[expr_ty] (memo):
+target_with_star_atom[expr_ty] (memo, fastpath=_PyPegen_target_fast_path):
     | a=t_primary '.' b=NAME !t_lookahead { _PyAST_Attribute(a, b->v.Name.id, Store, EXTRA) }
     | a=t_primary '[' b=slices ']' !t_lookahead { _PyAST_Subscript(a, b, Store, EXTRA) }
     | star_atom

InternalDocs/parser.md

@@ -563,6 +563,51 @@ in the generated C parse code that allows to measure how much each rule uses
 memoization (check the [`Parser/pegen.c`](../Parser/pegen.c)
 file for more information) but it needs to be manually activated.
 
+Fast-path hooks
+---------------
+
+Some rules are entered so often that even the bookkeeping of trying their
+alternatives is expensive. Consider parsing the argument ``a`` in a call
+like ``f(a, b)``: the argument is a full expression, so the parser descends
+the whole operator precedence chain
+
+```
+expression -> disjunction -> conjunction -> inversion -> comparison
+    -> bitwise_or -> bitwise_xor -> bitwise_and -> shift_expr -> sum
+    -> term -> factor -> power -> await_primary -> primary -> atom
+```
+
+before it can produce the ``Name`` node for ``a``: around fourteen rule
+invocations, each paying its own C-stack check and memoization lookups, to
+consume a single token. But since the following token is ``,``, which
+cannot continue any binary or postfix expression, that outcome is already
+known after peeking at two tokens.
+
+For cases like this a rule can declare a hand-written C hook with the
+``fastpath`` flag, next to where ``memo`` goes:
+
+```
+disjunction[expr_ty] (memo, fastpath=_PyPegen_atom_fast_path):
+```
+
+The generator calls the hook on rule entry, before any alternative is tried:
+
+```c
+if (_PyPegen_atom_fast_path(p, &_res)) {
+    p->level--;
+    return _res;
+}
+```
+
+The hook receives the parser and a pointer to the rule's result variable and
+returns 1 if it handled the parse (storing its result, which can be ``NULL``
+to signal failure with ``p->error_indicator`` set) or 0 to fall through to
+the rule's normal alternatives. The generator knows nothing about what the
+hook does: all parsing logic lives in the hook itself, next to the other
+token helpers in [`Parser/pegen.c`](../Parser/pegen.c). A hook must behave
+exactly like the rule it accelerates, including which tokens it fills,
+because error reporting depends on the number of tokens read (``p->fill``).
+
 Automatic variables
 -------------------
 

Misc/NEWS.d/next/Core_and_Builtins/2026-07-11-15-00-13.gh-issue-153568.atomfp.rst

@@ -0,0 +1,2 @@
+Speed up parsing of simple expressions by recognizing single-token atoms
+without descending the full precedence rule chain.

Parser/parser.c

@@ -241,6 +241,135 @@ _resize_tokens_array(Parser *p) {
     return 0;
 }
 
+// Fast path attached to the expression precedence chain's entry rules via
+// the @fastpath meta in the grammar. A bare NAME/NUMBER atom followed by a
+// token that cannot start or continue a binary/postfix expression is a
+// complete expression, so it is built directly instead of descending the
+// whole chain. Returns 1 if it produced a result (stored in *result), 0 to
+// fall through to the rule's alternatives. The second token is only
+// examined when the first is NAME/NUMBER: the precedence chain fills it
+// too in that case, so error reporting (which keys off p->fill) observes
+// an identical token fill state.
+int
+_PyPegen_atom_fast_path(Parser *p, void *result)
+{
+    if (p->mark == p->fill && _PyPegen_fill_token(p) < 0) {
+        p->error_indicator = 1;
+        *(void **)result = NULL;
+        return 1;
+    }
+    Token *t = p->tokens[p->mark];
+    if (t->type != NAME && t->type != NUMBER) {
+        return 0;
+    }
+    if (p->mark + 1 == p->fill && _PyPegen_fill_token(p) < 0) {
+        p->error_indicator = 1;
+        *(void **)result = NULL;
+        return 1;
+    }
+    switch (p->tokens[p->mark + 1]->type) {
+        case COMMA:
+        case RPAR:
+        case RSQB:
+        case RBRACE:
+        case COLON:
+        case NEWLINE:
+        case SEMI:
+        case EQUAL:
+        case ENDMARKER:
+            break;
+        default:
+            return 0;
+    }
+    expr_ty res = (t->type == NAME)
+        ? _PyPegen_name_token(p) : _PyPegen_number_token(p);
+    *(void **)result = res;
+    return 1;
+}
+
+// Fast path for subscript elements, attached to the slice rule via the
+// (fastpath=function) grammar flag: a bare NAME/NUMBER atom followed by
+// ',' or ']' is a complete slice, so it is built directly instead of
+// trying the subscript alternative (which fails and backtracks) first.
+// Same contract and token-fill discipline as _PyPegen_atom_fast_path().
+int
+_PyPegen_slice_fast_path(Parser *p, void *result)
+{
+    if (p->mark == p->fill && _PyPegen_fill_token(p) < 0) {
+        p->error_indicator = 1;
+        *(void **)result = NULL;
+        return 1;
+    }
+    Token *t = p->tokens[p->mark];
+    if (t->type != NAME && t->type != NUMBER) {
+        return 0;
+    }
+    if (p->mark + 1 == p->fill && _PyPegen_fill_token(p) < 0) {
+        p->error_indicator = 1;
+        *(void **)result = NULL;
+        return 1;
+    }
+    switch (p->tokens[p->mark + 1]->type) {
+        case COMMA:
+        case RSQB:
+            break;
+        default:
+            return 0;
+    }
+    expr_ty res = (t->type == NAME)
+        ? _PyPegen_name_token(p) : _PyPegen_number_token(p);
+    *(void **)result = res;
+    return 1;
+}
+
+// Fast path for assignment targets, attached to target_with_star_atom via
+// the (fastpath=function) grammar flag: a bare NAME followed by a token
+// that cannot extend a target parses to that name in Store context,
+// skipping the t_primary attribute/subscript attempts. NAME only: literals
+// must keep failing through the normal path so "cannot assign to literal"
+// errors are unaffected. Same contract and token-fill discipline as
+// _PyPegen_atom_fast_path().
+int
+_PyPegen_target_fast_path(Parser *p, void *result)
+{
+    if (p->mark == p->fill && _PyPegen_fill_token(p) < 0) {
+        p->error_indicator = 1;
+        *(void **)result = NULL;
+        return 1;
+    }
+    Token *t = p->tokens[p->mark];
+    if (t->type != NAME) {
+        return 0;
+    }
+    if (p->mark + 1 == p->fill && _PyPegen_fill_token(p) < 0) {
+        p->error_indicator = 1;
+        *(void **)result = NULL;
+        return 1;
+    }
+    switch (p->tokens[p->mark + 1]->type) {
+        case EQUAL:
+        case COMMA:
+        case RPAR:
+        case RSQB:
+        case COLON:
+        case NEWLINE:
+            break;
+        default:
+            return 0;
+    }
+    expr_ty name = _PyPegen_name_token(p);
+    if (name == NULL) {
+        *(void **)result = NULL;
+        return 1;
+    }
+    expr_ty res = _PyPegen_set_expr_context(p, name, Store);
+    if (res == NULL) {
+        p->error_indicator = 1;
+    }
+    *(void **)result = res;
+    return 1;
+}
+
 int
 _PyPegen_fill_token(Parser *p)
 {

Parser/pegen.c

@@ -159,6 +159,9 @@ expr_ty _PyPegen_soft_keyword_token(Parser *p);
 expr_ty _PyPegen_fstring_middle_token(Parser* p);
 Token *_PyPegen_get_last_nonnwhitespace_token(Parser *);
 int _PyPegen_fill_token(Parser *p);
+int _PyPegen_atom_fast_path(Parser *p, void *result);
+int _PyPegen_slice_fast_path(Parser *p, void *result);
+int _PyPegen_target_fast_path(Parser *p, void *result);
 expr_ty _PyPegen_name_token(Parser *p);
 expr_ty _PyPegen_number_token(Parser *p);
 void *_PyPegen_string_token(Parser *p);

Parser/pegen.h

@@ -598,13 +598,47 @@ def _set_up_rule_memoization(self, node: Rule, result_type: str) -> None:
     def _should_memoize(self, node: Rule) -> bool:
         return "memo" in node.flags and not node.left_recursive
 
+    def _rule_fast_path(self, node: Rule) -> str | None:
+        """Return the C fast-path hook declared by a (fastpath=<function>) rule flag.
+
+        The hook is called on rule entry and returns 1 if it handled the
+        parse (storing its result), 0 to fall through to the rule's
+        alternatives. For example, given
+
+            disjunction[expr_ty] (memo, fastpath=_PyPegen_atom_fast_path):
+
+        the disjunction rule body starts with
+
+            if (_PyPegen_atom_fast_path(p, &_res)) {
+                p->level--;
+                return _res;
+            }
+
+        See "Fast-path hooks" in InternalDocs/parser.md.
+        """
+        for flag in node.flags:
+            name, _, func = flag.partition("=")
+            if name == "fastpath":
+                if not func:
+                    raise ValueError(
+                        f"rule {node.name!r}: fastpath flag needs a function"
+                    )
+                return func
+        return None
+
     def _handle_default_rule_body(self, node: Rule, rhs: Rhs, result_type: str) -> None:
         memoize = self._should_memoize(node)
 
         with self.indent():
             self.add_level()
             self._check_for_errors()
             self.print(f"{result_type} _res = NULL;")
+            fastpath = self._rule_fast_path(node)
+            if fastpath:
+                self.print(f"if ({fastpath}(p, &_res)) {{")
+                with self.indent():
+                    self.add_return("_res")
+                self.print("}")
             if memoize:
                 self.print(f"if (_PyPegen_is_memoized(p, {node.name}_type, &_res)) {{")
                 with self.indent():

Tools/peg_generator/pegen/c_generator.py

@@ -64,6 +64,7 @@ flags[frozenset[str]]:
     | '(' a=','.flag+ ')' { frozenset(a) }
 
 flag[str]:
+    | a=NAME '=' b=NAME { a.string + "=" + b.string }
     | NAME { name.string }
 
 alts[Rhs]: