Reload() description is unclear

[roysmith]

BPO	20769
Nosy	@brettcannon, @ericvsmith, @rbtcollins, @bitdancer, @wiggin15
Files	reload_importlib_doc_py_3_5_fix.patch: Python 3.5.0a patch for reload() documentation reload_builtin_functions_doc_py_2_7_fix.patch: Python 2.7.x patch for reload() documentation

^{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 = <Date 2015-08-04.20:33:15.256>
created_at = <Date 2014-02-25.16:23:55.529>
labels = ['docs']
title = 'Reload() description is unclear'
updated_at = <Date 2015-08-04.20:33:15.255>
user = 'https://bugs.python.org/roysmith'

bugs.python.org fields:

activity = <Date 2015-08-04.20:33:15.255>
actor = 'rbcollins'
assignee = 'docs@python'
closed = True
closed_date = <Date 2015-08-04.20:33:15.256>
closer = 'rbcollins'
components = ['Documentation']
creation = <Date 2014-02-25.16:23:55.529>
creator = 'roysmith'
dependencies = []
files = ['39019', '39020']
hgrepos = []
issue_num = 20769
keywords = ['patch']
message_count = 9.0
messages = ['212187', '212198', '241029', '241267', '247994', '247996', '247997', '247999', '248000']
nosy_count = 9.0
nosy_names = ['brett.cannon', 'roysmith', 'eric.smith', 'rbcollins', 'r.david.murray', 'docs@python', 'wiggin15', 'python-dev', 'dorianpula']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = None
url = 'https://bugs.python.org/issue20769'
versions = ['Python 2.7', 'Python 3.4', 'Python 3.5', 'Python 3.6']

[roysmith]

http://docs.python.org/2/library/functions.html#reload says:

It is legal though generally not very useful to reload built-in or dynamically loaded modules, except for sys, __main__ and __builtin__.

It is unclear what the "except for ..." part is referring to. Is it not legal to reload those modules? Or is it not very useful to reload them?

[bitdancer]

The python3 docs say:

"It is legal though generally not very useful to reload built-in or dynamically loaded modules (this is not true for e.g. sys, __main__, builtins and other key modules where reloading is frowned upon)."

So, it is the former...sort of. You don't get an error when you reload them, so implying that it is not "legal" is an odd phrasing. Probably that sentence should be clarified in both the python2 and python3 docs.

[dorianpula]

Attached patches with proposed change to the documentation to make the description clearer.

Please review and comment.

[brettcannon]

Patch LGTM.

[rbtcollins]

24081 invalidates half the patch, but the other half still applies.

[python-dev]

New changeset cfd768814ca3 by Robert Collins in branch '2.7':
Issue bpo-20769: Improve reload() docs. Patch by Dorian Pula.
https://hg.python.org/cpython/rev/cfd768814ca3

[rbtcollins]

2.7 side applied.

[python-dev]

New changeset 33dfbb293892 by Robert Collins in branch '3.4':
Issue bpo-20769: Improve reload() docs. Patch by Dorian Pula.
https://hg.python.org/cpython/rev/33dfbb293892

New changeset 9fe1a440e4b8 by Robert Collins in branch '3.5':
Issue bpo-20769: Improve reload() docs. Patch by Dorian Pula.
https://hg.python.org/cpython/rev/9fe1a440e4b8

New changeset 6778332f687a by Robert Collins in branch 'default':
Issue bpo-20769: Improve reload() docs. Patch by Dorian Pula.
https://hg.python.org/cpython/rev/6778332f687a

[rbtcollins]

Thanks for the patch. Applied to 3.4/3.5/3.6 as well.