From a2c3455027f380460c274f314447c8671726e3a3 Mon Sep 17 00:00:00 2001
From: Emily Morehouse <emily@python.org>
Date: Fri, 27 Sep 2024 13:59:26 -0700
Subject: [PATCH] gh-81263: Add assignment expressions to `help` (#124641)

* Add assignment expression (:=) to `help`

* Update index for Assignment Expressions to include pair of `assignment; expression`
---
 Doc/reference/expressions.rst |  1 +
 Lib/pydoc.py                  |  2 ++
 Lib/pydoc_data/topics.py      | 28 ++++++++++++++++++++++++++++
 3 files changed, 31 insertions(+)

diff --git a/Doc/reference/expressions.rst b/Doc/reference/expressions.rst
index f734221a2cdec5..ab72ad49d041e1 100644
--- a/Doc/reference/expressions.rst
+++ b/Doc/reference/expressions.rst
@@ -1807,6 +1807,7 @@ returns a boolean value regardless of the type of its argument
    single: assignment expression
    single: walrus operator
    single: named expression
+   pair: assignment; expression
 
 Assignment expressions
 ======================
diff --git a/Lib/pydoc.py b/Lib/pydoc.py
index 40ec650b39d4e7..30cd0b3fa3cb4e 100755
--- a/Lib/pydoc.py
+++ b/Lib/pydoc.py
@@ -1861,6 +1861,7 @@ class Helper:
         ':': 'SLICINGS DICTIONARYLITERALS',
         '@': 'def class',
         '\\': 'STRINGS',
+        ':=': 'ASSIGNMENTEXPRESSIONS',
         '_': 'PRIVATENAMES',
         '__': 'PRIVATENAMES SPECIALMETHODS',
         '`': 'BACKQUOTES',
@@ -1954,6 +1955,7 @@ class Helper:
         'ASSERTION': 'assert',
         'ASSIGNMENT': ('assignment', 'AUGMENTEDASSIGNMENT'),
         'AUGMENTEDASSIGNMENT': ('augassign', 'NUMBERMETHODS'),
+        'ASSIGNMENTEXPRESSIONS': ('assignment-expressions', ''),
         'DELETION': 'del',
         'RETURNING': 'return',
         'IMPORTING': 'import',
diff --git a/Lib/pydoc_data/topics.py b/Lib/pydoc_data/topics.py
index 2b253dcbbc3a38..1d8c75df703798 100644
--- a/Lib/pydoc_data/topics.py
+++ b/Lib/pydoc_data/topics.py
@@ -421,6 +421,34 @@
                'some expressions (like un-parenthesized tuple expressions) '
                'caused a\n'
                'syntax error.\n',
+ 'assignment-expressions': 'Assignment expressions\n'
+          '**********************\n'
+          '\n'
+          'An assignment expression (sometimes also called a “named expression”'
+          '\nor “walrus”) assigns an expression to an identifier, while also\n'
+          'returning the value of the expression.\n'
+          '\n'
+          'One common use case is when handling matched regular expressions:\n'
+          '\n'
+          '   if matching := pattern.search(data):\n'
+          '      do_something(matching)\n'
+          '\n'
+          'Or, when processing a file stream in chunks:\n'
+          '\n'
+          '   while chunk := file.read(9000):\n'
+          '      process(chunk)\n'
+          '\n'
+          'Assignment expressions must be surrounded by parentheses when used as\n'
+          'expression statements and when used as sub-expressions in slicing,\n'
+          'conditional, lambda, keyword-argument, and comprehension-if\n'
+          'expressions and in assert, with, and assignment statements. In all\n'
+          'other places where they can be used, parentheses are not required,\n'
+          'including in if and while statements.\n'
+          '\n'
+          'Added in version 3.8.\n'
+          'See also:\n'
+          '\n'
+          '  **PEP 572** - Assignment Expressions\n',
  'async': 'Coroutines\n'
           '**********\n'
           '\n'