gh-117618: Make package.module searchable for breakpoints and clean up docs (#117619)

Lib/pdb.py

@@ -2007,17 +2007,23 @@ class Pdb(bdb.Bdb, cmd.Cmd):
 
         lookupmodule() translates (possibly incomplete) file or module name
         into an absolute file name.
+
+        filename could be in format of:
+            * an absolute path like '/path/to/file.py'
+            * a relative path like 'file.py' or 'dir/file.py'
+            * a module name like 'module' or 'package.module'
+
+        files and modules will be searched in sys.path.
         """
-        if os.path.isabs(filename) and  os.path.exists(filename):
-            return filename
-        f = os.path.join(sys.path[0], filename)
-        if  os.path.exists(f) and self.canonic(f) == self.mainpyfile:
-            return f
-        root, ext = os.path.splitext(filename)
-        if ext == '':
-            filename = filename + '.py'
+        if not filename.endswith('.py'):
+            # A module is passed in so convert it to equivalent file
+            filename = filename.replace('.', os.sep) + '.py'
+
         if os.path.isabs(filename):
-            return filename
+            if os.path.exists(filename):
+                return filename
+            return None
+
         for dirname in sys.path:
             while os.path.islink(dirname):
                 dirname = os.readlink(dirname)

Lib/test/test_pdb.py

@@ -354,6 +354,46 @@ def test_pdb_breakpoint_commands():
     4
     """
 
+def test_pdb_breakpoint_with_filename():
+    """Breakpoints with filename:lineno
+
+    >>> def test_function():
+    ...     # inspect_fodder2 is a great module as the line number is stable
+    ...     from test.test_inspect import inspect_fodder2 as mod2
+    ...     import pdb; pdb.Pdb(nosigint=True, readrc=False).set_trace()
+    ...     mod2.func88()
+    ...     mod2.func114()
+    ...     # Be a good citizen and clean up the mess
+    ...     reset_Breakpoint()
+
+    First, need to clear bdb state that might be left over from previous tests.
+    Otherwise, the new breakpoints might get assigned different numbers.
+
+    >>> reset_Breakpoint()
+
+    >>> with PdbTestInput([  # doctest: +NORMALIZE_WHITESPACE +ELLIPSIS
+    ...     'break test.test_inspect.inspect_fodder2:90',
+    ...     'continue', # will stop at func88
+    ...     'break test/test_inspect/inspect_fodder2.py:115',
+    ...     'continue', # will stop at func114
+    ...     'continue',
+    ... ]):
+    ...    test_function()
+    > <doctest test.test_pdb.test_pdb_breakpoint_with_filename[0]>(5)test_function()
+    -> mod2.func88()
+    (Pdb) break test.test_inspect.inspect_fodder2:90
+    Breakpoint 1 at ...inspect_fodder2.py:90
+    (Pdb) continue
+    > ...inspect_fodder2.py(90)func88()
+    -> return 90
+    (Pdb) break test/test_inspect/inspect_fodder2.py:115
+    Breakpoint 2 at ...inspect_fodder2.py:115
+    (Pdb) continue
+    > ...inspect_fodder2.py(115)func114()
+    -> return 115
+    (Pdb) continue
+    """
+
 def test_pdb_breakpoints_preserved_across_interactive_sessions():
     """Breakpoints are remembered between interactive sessions