gh-64020: Deprecate pydoc.ispackage() (GH-20908)

Co-authored-by: Serhiy Storchaka <storchaka@gmail.com>

diff --git a/Doc/whatsnew/3.13.rst b/Doc/whatsnew/3.13.rst
index c905cddc6cba628490dbf9b84f232fefd3822f40..4b02ecddd63b271b288edc3de875c756fb6349ae 100644 (file)
--- a/Doc/whatsnew/3.13.rst
+++ b/Doc/whatsnew/3.13.rst
@@ -556,6 +556,9 @@ Deprecated
   coroutine.
   (Contributed by Irit Katriel in :gh:`81137`.)
 
+* Deprecate undocumented :func:`!pydoc.ispackage` function.
+  (Contributed by Zackery Spytz in :gh:`64020`.)
+
 
 Pending Removal in Python 3.14
 ------------------------------

diff --git a/Lib/pydoc.py b/Lib/pydoc.py
index 83c74a75cd1c004067d21a7cd5b070923ededd80..96aa1dfc1aacf648cceb363dbeb89122eb7288d4 100755 (executable)
--- a/Lib/pydoc.py
+++ b/Lib/pydoc.py
@@ -345,6 +345,8 @@ def sort_attributes(attrs, object):
 
 def ispackage(path):
     """Guess whether a path refers to a package directory."""
+    warnings.warn('The pydoc.ispackage() function is deprecated',
+                  DeprecationWarning, stacklevel=2)
     if os.path.isdir(path):
         for ext in ('.py', '.pyc'):
             if os.path.isfile(os.path.join(path, '__init__' + ext)):

diff --git a/Lib/test/test_pydoc.py b/Lib/test/test_pydoc.py
index 982ee60c0be4f73b15ab84b87f542d7feb13ed5b..99b19d01783a10f87a401fe418d7bf6a779b2458 100644 (file)
--- a/Lib/test/test_pydoc.py
+++ b/Lib/test/test_pydoc.py
@@ -745,14 +745,18 @@ class PydocDocTest(unittest.TestCase):
 
     def test_is_package_when_not_package(self):
         with os_helper.temp_cwd() as test_dir:
-            self.assertFalse(pydoc.ispackage(test_dir))
+            with self.assertWarns(DeprecationWarning) as cm:
+                self.assertFalse(pydoc.ispackage(test_dir))
+            self.assertEqual(cm.filename, __file__)
 
     def test_is_package_when_is_package(self):
         with os_helper.temp_cwd() as test_dir:
             init_path = os.path.join(test_dir, '__init__.py')
             open(init_path, 'w').close()
-            self.assertTrue(pydoc.ispackage(test_dir))
+            with self.assertWarns(DeprecationWarning) as cm:
+                self.assertTrue(pydoc.ispackage(test_dir))
             os.remove(init_path)
+            self.assertEqual(cm.filename, __file__)
 
     def test_allmethods(self):
         # issue 17476: allmethods was no longer returning unbound methods.

diff --git a/Misc/NEWS.d/next/Library/2020-06-15-23-44-53.bpo-19821.ihBk39.rst b/Misc/NEWS.d/next/Library/2020-06-15-23-44-53.bpo-19821.ihBk39.rst
new file mode 100644 (file)
index 0000000..ede6810
--- /dev/null
+++ b/Misc/NEWS.d/next/Library/2020-06-15-23-44-53.bpo-19821.ihBk39.rst
@@ -0,0 +1 @@
+The :func:`!pydoc.ispackage` function has been deprecated.