__all__ lists are incomplete

[serhiy-storchaka]

BPO	23883
Nosy	@vstinner, @bitdancer, @berkerpeksag, @vadmium, @serhiy-storchaka, @maurorodrigues, @selik
Dependencies	bpo-10838: subprocess all is incomplete bpo-26676: Add missing XMLPullParser to ElementTree.all bpo-26782: subprocess.all incomplete on Windows bpo-27105: cgi.all is incomplete bpo-27106: configparser.all is incomplete bpo-27107: mailbox.all list is incomplete bpo-27108: mimetypes.all list is incomplete bpo-27109: plistlib.all list is incomplete bpo-27110: smtpd.all list is incomplete bpo-27112: tokenize.all list is incomplete
Files	Issue23883_tarfile_all.patch: Add documented items to tarfile.all Issue23883_calendar_all.patch: Add documented items to calendar.all Issue23883_csv_all.patch: Add documented items to csv.all issue23883_fileinput.patch: Add documented items to fileinput.all Issue23883_csv_all.v2.patch: Add documented items to csv.all Issue23883_support_check__all__.patch Issue23883_test_gettext.patch Issue23883_all.patch Issue23883_support_check__all__.v2.patch Issue23883_support_check__all__.v3.patch Issue23883_test_gettext.v2.patch Issue23883_all.v3.patch Issue23883_support_check__all__.v4.patch: test.support.check__all__ helper Issue23883_test_gettext.v3.patch: test.test_gettext update Issue23883_all.v4.patch: Add documented items to all in csv, enum, ftplib, logging, optparse, pickletools, threading and wave Issue23883_support_check__all__.v5.patch: test.support.check__all__ helper Issue23883_all.v5.patch: Add documented items to all in csv, enum, ftplib, logging, optparse, threading and wave Issue23883_all.v6.patch Issue23883_support_check__all__.v6.patch issue23883_fileinput.v2.patch: Add documented items to fileinput.all Issue23883_calendar_all.v2.patch Issue23883_tarfile_all.v2.patch Issue23883_pydoc_all.patch

^{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 2015-04-07.16:23:10.026>
labels = ['type-feature', 'library']
title = '__all__ lists are incomplete'
updated_at = <Date 2019-07-29.11:53:08.066>
user = 'https://github.com/serhiy-storchaka'

bugs.python.org fields:

activity = <Date 2019-07-29.11:53:08.066>
actor = 'vstinner'
assignee = 'none'
closed = False
closed_date = None
closer = None
components = ['Library (Lib)']
creation = <Date 2015-04-07.16:23:10.026>
creator = 'serhiy.storchaka'
dependencies = ['10838', '26676', '26782', '27105', '27106', '27107', '27108', '27109', '27110', '27112']
files = ['39065', '39067', '39717', '39718', '39721', '39733', '39734', '39735', '39760', '39807', '39808', '39809', '39867', '39868', '39869', '39976', '39977', '41012', '41013', '41052', '41117', '41118', '43002']
hgrepos = []
issue_num = 23883
keywords = ['patch']
message_count = 63.0
messages = ['240217', '240231', '240251', '240258', '240260', '240261', '240878', '240880', '241145', '241176', '241195', '241198', '241199', '241219', '241306', '241602', '245421', '245428', '245485', '245486', '245598', '245614', '245784', '245794', '245796', '245801', '245802', '246024', '246299', '246895', '247031', '247036', '247102', '247103', '247167', '251104', '254062', '254080', '254084', '254426', '254434', '254482', '254517', '254581', '254585', '254654', '254655', '254658', '254666', '254706', '254780', '255071', '258366', '258367', '258369', '258372', '258381', '258382', '266276', '266347', '266373', '267509', '348641']
nosy_count = 11.0
nosy_names = ['vstinner', 'r.david.murray', 'python-dev', 'berker.peksag', 'martin.panter', 'serhiy.storchaka', 'milap.py', 'maurosr', 'taddeimania', 'Unit03', 'selik']
pr_nums = []
priority = 'normal'
resolution = None
stage = 'needs patch'
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue23883'
versions = ['Python 3.6']

[serhiy-storchaka]

Here is a (perhaps incomplete) list of documented names absent in __all__ lists of respective modules. Perhaps some of them (but not all) are worth to be added to __all__ lists.

calendar.Calendar
calendar.HTMLCalendar
calendar.TextCalendar
cgi.test
configparser.Error
csv.unix_dialect
doctest.DocFileCase
doctest.DocTestCase
enum.EnumMeta
fileinput.fileno
ftplib.Error
ftplib.error_perm
ftplib.error_reply
gettext.bind_textdomain_codeset
gettext.lgettext
gettext.lngettext
http.client.HTTPMessage
http.cookies.Morsel
http.server.test
logging.shutdown
mailbox.Error
mailbox.ExternalClashError
mailbox.NoSuchMailboxError
mailbox.NotEmptyError
mimetypes.MimeTypes
optparse.check_choice
pickletools.OpcodeInfo
plistlib.InvalidFileException
pydoc.doc
smtpd.SMTPChannel
subprocess.SubprocessError
subprocess.TimeoutExpired
tarfile.CompressionError
tarfile.HeaderError
tarfile.ReadError
tarfile.open
threading.BrokenBarrierError
tkinter.ttk.Widget
tokenize.open
traceback.FrameSummary
traceback.StackSummary
traceback.TracebackException
traceback.walk_stack
traceback.walk_tb
wave.Wave_read
wave.Wave_write
xml.etree.ElementTree.XMLPullParser

[vadmium]

http.client.HTTPMessage: See bpo-23439. There was resistance to adding this (and the status code constants), though IMO they should be added, since they are documented public APIs.

http.server.test(): In bpo-23418, I consciously left this function out. It is only mentioned as a place to look for sample code, as far as I can tell.

[python-dev]

New changeset ebf3e6332a44 by Berker Peksag in branch 'default':
Issue bpo-23883: Add missing entries to traceback.__all__.
https://hg.python.org/cpython/rev/ebf3e6332a44

[serhiy-storchaka]

May be makes sense to add a helper in test.support that implements a test similar to the one in bpo-23411, and add tests for __all__ in multiple modules.

[milappy]

I working on these three.
calendar.Calendar
calendar.HTMLCalendar
calendar.TextCalendar

Changes would be the same as https://hg.python.org/cpython/rev/ebf3e6332a44/ for every module?

[vadmium]

Serhiy: Yes I was also thinking it might be time for a common helper function.

Milap: I think changes like you mentioned (originally by me) would be fine. Another variation was done for bpo-10838: revision 10b0a8076be8, which expects each object that is not a module object (e.g. not from “import sys”), rather than expecting each object that is a function or class defined in the module. It might depend on the particular circumstance which technique is superior.

[python-dev]

New changeset 86fbe140e395 by Andrew Kuchling in branch '2.7':
bpo-23883: add names missing from __all__ (l*gettext, bind_textdomain_codeset)
https://hg.python.org/cpython/rev/86fbe140e395

[python-dev]

New changeset 717d87c13f0d by Andrew Kuchling in branch '3.4':
bpo-23883: add names missing from __all__ (l*gettext, bind_textdomain_codeset)
https://hg.python.org/cpython/rev/717d87c13f0d

[taddeimania]

I took care of the tarfile module.

Added the following according to the first message:

tarfile.CompressionError
tarfile.HeaderError
tarfile.ReadError
tarfile.open

The following were included in __all__ that were not explicitly mentioned in the first message but were denoted as an exported function, exported class, or an exported error.

tarfile.main
tarfile.TarIter
tarfile.StreamError
tarfile.ExtractError
tarfile.SubsequentHeaderError
tarfile.InvalidHeaderError
tarfile.EmptyHeaderError
tarfile.EOFHeaderError
tarfile.TruncatedHeaderError

This is my first patch so feedback is highly appreciated.

[vadmium]

Regarding tarfile: Two of the extra errors are documented, so I agree they should be added:

• tarfile.StreamError
• tarfile.ExtractError

However I’m not so sure about main(), TarIter, and the HeaderError subclasses. They aren’t mentioned in the documentation. At least main() and TarIter are just implementation details I think.

There are other documented items that should be added in my opinion. These would not be picked up by the proposed test, although they would be picked up by making the test like in revision 10b0a8076be8.

• ENCODING
• USTAR/GNU/PAX/DEFAULT_FORMAT

[taddeimania]

Thanks for the feedback. I was unsure how to proceed with the undocumented items that seemed to be categorized as exported. Thanks for catching ENCODING & *_FORMAT.

[vadmium]

Oh I see, TarIter is listed underneath a comment saying “Exported Classes”, and main() is listed underneath “exported functions”. If they are indeed meant to be exported, they should probably also be documented. Otherwise, maybe we can just add another comment clarifying that they are internal.

In the latest patch, I think HeaderError should be added back to __all__; it is just its subclasses that are not documented. Also XHDTYPE is listed twice in the test case.

If it were up to me, I would add the TarInfo.type constants (REGTYPE, AREGTYPE, LNKTYPE, SYMTYPE, DIRTYPE, FIFOTYPE, CONTTYPE, CHRTYPE, BLKTYPE, GNUTYPE_SPARSE). But I’m not sure if others would agree.