deprecate pydoc.ispackage()

[ericsnowcurrently]

BPO	19821
Nosy	@PCManticore, @ericsnowcurrently, @wm75, @ZackerySpytz
PRs	gh-64020: Deprecate pydoc.ispackage() #20908

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2013-11-28.07:55:30.790>
labels = ['type-feature', 'library', '3.11']
title = 'deprecate pydoc.ispackage()'
updated_at = <Date 2021-05-21.20:20:33.155>
user = 'https://github.com/ericsnowcurrently'

bugs.python.org fields:

activity = <Date 2021-05-21.20:20:33.155>
actor = 'iritkatriel'
assignee = 'none'
closed = False
closed_date = None
closer = None
components = ['Library (Lib)']
creation = <Date 2013-11-28.07:55:30.790>
creator = 'eric.snow'
dependencies = []
files = []
hgrepos = []
issue_num = 19821
keywords = ['patch']
message_count = 3.0
messages = ['204646', '204697', '221548']
nosy_count = 4.0
nosy_names = ['Claudiu.Popa', 'eric.snow', 'wolma', 'ZackerySpytz']
pr_nums = ['20908']
priority = 'low'
resolution = None
stage = 'patch review'
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue19821'
versions = ['Python 3.11']

[ericsnowcurrently]

pydoc.ispackage() is a best-effort guess at whether or not a path is the location of a package. However, it uses hard-coded suffixes when matching file names, which can miss files (e.g. extension modules and sourceless packages on Windows). It should probably use suffixes defined in importlib.util, as they're used elsewhere in pydoc. The function also does not comprehend namespace packages, but I'm not sure that's worth worrying about.

FWIW, it isn't clear to me what is using pydoc.ispackage(). It may not be used in the stdlib at all.

[PCManticore]

It was used by pydoc.py until 2006, when it was removed with this commit:

Changeset:
37821 (3135648026c4) Second phase of refactoring for runpy, pkgutil, pydoc, and setuptools.

Is it worth to fix this?

[PCManticore]

I would go on the deprecation route with this and removing it in 3.6, just like the formatter module.

[hugovk]

Searching the top 5k PyPI packages shows only a single use:

❯ python3 ~/github/misc/cpython/search_pypi_top.py -q . "pydoc.*ispackage"
./PyDispatcher-2.0.7.tar.gz: PyDispatcher-2.0.7/docs/pydoc/pydoc2.py: elif pydoc.ispackage(path):
./PyDispatcher-2.0.7.tar.gz: PyDispatcher-2.0.7/docs/pydoc/pydoc2.py: elif pydoc.ispackage(path):