This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

classification
Title: Mark optional stdlib modules in documentation
Type: enhancement Stage:
Components: Documentation Versions: Python 3.8
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, of4tvziy, terry.reedy
Priority: normal Keywords:

Created on 2018-10-04 16:33 by of4tvziy, last changed 2022-04-11 14:59 by admin.

Messages (3)
msg327065 - (view) Author: Marcus (of4tvziy) Date: 2018-10-04 16:33
Some stdlib modules have external build time dependencies and will be automatically disabled if the dependencies can't be met (cf. detect_modules() in setup.py).
From a user's perspective there is no reason to assume that the presence of a stdlib module may not be relied upon. See also the discussion on python-ideas (https://mail.python.org/pipermail/python-ideas/2018-October/054008.html).
A rather simple to implement debugging aid would be to add a note to the affected modules' documentation, stating that these modules may not be available on all systems.
msg327187 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2018-10-05 21:00
Some modules are marked 'unix-only' or 'windows-only'.  The Windows installer includes all dependencies unless one asks that tcl/tk, tkinter, IDLE, (and turtle?) not be installed.  I believe the situation is now similar on Mac.  Please give specific examples of doc you think is deficient.
msg328377 - (view) Author: Marcus (of4tvziy) Date: 2018-10-24 16:31
My concern is that certain missing build-time dependencies do not stop the build but trigger an easy to miss message at the end of the build stage (only). Also the end user doesn't get to see this. At the same time these modules are sort of expected to be part of a complete Python distribution.

Two issues I see with this: 1. By omission, the distributor might inadvertently create an incomplete distribution. 2. The enduser, running a script (possibly created elsewhere) receives a standard “ModuleNotFoundError” and is left in the dark about its origin as the documentation seems to confirm that the affected module ought to be available.

$ grep -F missing.append setup.py
             missing.append('spwd')
             missing.append('readline')
             missing.append('_ssl')
             missing.append('_hashlib')
             missing.append('_sqlite3')
                 missing.append('_dbm')
             missing.append('_gdbm')
             missing.append('nis')
             missing.append('_curses')
             missing.append('_curses_panel')
                     missing.append('zlib')
                 missing.append('zlib')
             missing.append('zlib')
             missing.append('_bz2')
             missing.append('_lzma')
             missing.append('_elementtree')
             missing.append('ossaudiodev')
             missing.append('_tkinter')
             missing.append('_uuid')

All modules in the above list are potentially affected, although some (ossaudiodev, nis) might be considered platform specific. Arguably availablility some of these modules could be perhaps turned into build-time requirements with opt-out mechanics.

In any case a hint to the end user debugging such issues would be rather helpful and a big timesaver (see initial report).
History
Date User Action Args
2022-04-11 14:59:06adminsetgithub: 79076
2018-10-24 16:31:13of4tvziysetmessages: + msg328377
2018-10-05 21:00:13terry.reedysetnosy: + terry.reedy
messages: + msg327187
2018-10-04 16:33:38of4tvziycreate