python · serhiy-storchaka · Jan 8, 2025 · Dec 2, 2024 · Dec 2, 2024 · Dec 2, 2024
diff --git a/Lib/pydoc.py b/Lib/pydoc.py
@@ -53,6 +53,7 @@ class or function within a module or module in a package.  If the
 #     the current directory is changed with os.chdir(), an incorrect
 #     path will be displayed.
 
+import ast
 import __future__
 import builtins
 import importlib._bootstrap
@@ -384,21 +385,20 @@ def ispackage(path):
     return False
 
 def source_synopsis(file):
-    line = file.readline()
-    while line[:1] == '#' or not line.strip():
-        line = file.readline()
-        if not line: break
-    line = line.strip()
-    if line[:4] == 'r"""': line = line[1:]
-    if line[:3] == '"""':
-        line = line[3:]
-        if line[-1:] == '\\': line = line[:-1]
-        while not line.strip():
-            line = file.readline()
-            if not line: break
-        result = line.split('"""')[0].strip()
-    else: result = None
-    return result
+    """Return the one-line summary of a file object, if present"""
+
+    try:
+        tokens = tokenize.generate_tokens(file.readline)
+        for tok_type, tok_string, _, _, _ in tokens:
+            if tok_type == tokenize.STRING:
+                docstring = ast.literal_eval(tok_string)
+                if isinstance(docstring, str):
+                    return docstring.strip().split('\n')[0].strip()
+                return None
+            elif tok_type not in (tokenize.COMMENT, tokenize.NL, tokenize.ENCODING):
+                return None
+    except (tokenize.TokenError, UnicodeDecodeError, SyntaxError, ValueError) as e:
+        return None
 
 def synopsis(filename, cache={}):
     """Get the one-line summary out of a module file."""

diff --git a/Lib/test/test_pydoc/test_pydoc.py b/Lib/test/test_pydoc/test_pydoc.py
@@ -899,6 +899,57 @@ def test_synopsis(self):
             synopsis = pydoc.synopsis(TESTFN, {})
             self.assertEqual(synopsis, 'line 1: h\xe9')
 
+    def test_source_synopsis(self):
+        test_cases = [
+            ('"""Single line docstring."""',
+            "Single line docstring."),
+
+            ('"""First line of docstring.\nSecond line.\nThird line."""',
+            "First line of docstring."),
+
+            ('"""  Whitespace around docstring.  """',
+            "Whitespace around docstring."),
+
+            # No docstring
+            ('x = 1\ny = 2',
+            None),
+
+            ('# Comment\n"""Docstring after comment."""',
+            "Docstring after comment."),
+
+            # Empty docstring
+            ('""""""',
+            ""),
+
+            ('"""Café and résumé."""',
+            "Café and résumé."),
+
+            ("'''Triple single quotes'''",
+            "Triple single quotes"),
+
+            ('"Single double quotes"',
+            "Single double quotes"),
+
+            ("'Single single quotes'",
+            'Single single quotes'),
+
+            ('"""Concatenated""" \\\n"string" \'literals\'',
+            "Concatenatedstringliterals")
+        ]
+
+        for source, expected in test_cases:
+            with self.subTest(source=source):
+                source_file = StringIO(source)
+                result = pydoc.source_synopsis(source_file)
+                self.assertEqual(result, expected)
+
+        with tempfile.NamedTemporaryFile(mode='w+', encoding='utf-8') as temp_file:
+            temp_file.write('"""Real file test."""\n')
+            temp_file.flush()
+            temp_file.seek(0)
+            result = pydoc.source_synopsis(temp_file)
+            self.assertEqual(result, "Real file test.")
+
     @requires_docstrings
     def test_synopsis_sourceless(self):
         os = import_helper.import_fresh_module('os')

diff --git a/Misc/NEWS.d/next/Library/2024-12-17-15-23-40.gh-issue-41872.31LjKY.rst b/Misc/NEWS.d/next/Library/2024-12-17-15-23-40.gh-issue-41872.31LjKY.rst
@@ -0,0 +1 @@
+Parse docstrings with ast instead of string manipulation
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		Parse docstrings with ast instead of string manipulation