"This module is always available" is confusing

[nedbat]

BPO	36908
Nosy	@nedbat, @kushaldas, @Mariatta, @eamanu, @miss-islington
PRs	bpo-36908: 'This module is always available' isn't helpful. #13297 [3.7] bpo-36908: 'This module is always available' isn't helpful. (GH-13297) #13394

^{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 2019-05-17.21:10:25.415>
created_at = <Date 2019-05-13.21:15:22.710>
labels = ['3.7', '3.8', '3.9', 'docs']
title = '"This module is always available" is confusing'
updated_at = <Date 2019-05-17.21:10:25.336>
user = 'https://github.com/nedbat'

bugs.python.org fields:

activity = <Date 2019-05-17.21:10:25.336>
actor = 'Mariatta'
assignee = 'docs@python'
closed = True
closed_date = <Date 2019-05-17.21:10:25.415>
closer = 'Mariatta'
components = ['Documentation']
creation = <Date 2019-05-13.21:15:22.710>
creator = 'nedbat'
dependencies = []
files = []
hgrepos = []
issue_num = 36908
keywords = ['patch']
message_count = 11.0
messages = ['342386', '342390', '342392', '342394', '342402', '342403', '342404', '342700', '342704', '342767', '342768']
nosy_count = 6.0
nosy_names = ['nedbat', 'docs@python', 'kushal.das', 'Mariatta', 'eamanu', 'miss-islington']
pr_nums = ['13297', '13394']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = None
url = 'https://bugs.python.org/issue36908'
versions = ['Python 3.7', 'Python 3.8', 'Python 3.9']

[nedbat]

The math and cmath modules say this in their docs: "This module is always available." This lead a beginner to believe they didn't need to be imported.

Nearly the entire standard library is always available in this sense (they can be imported). This sentence isn't useful.

Can we change the first paragraph of the math module to be:

"This module provides access to the mathematical functions defined by the C standard."

(and similarly for the cmath module.)

[Mariatta]

I agree the wording "is always available" is quite ambiguous. It's just that we use this phrase pretty much everywhere...

Example:
First paragraph of https://docs.python.org/3/library/sys.html
"It is always available."

https://docs.python.org/3/library/threading.html?highlight=threading#module-threading "This module used to be optional, it is now always available."

I wonder if it will be clearer if it says "is available across all platforms"?

[nedbat]

If we want to keep it, how about "it can always be imported."? Though I still wonder whether this is worth it. Are we going to annotate all of the always-available modules with this notation?

[nedbat]

Looks like these modules describe themselves as always available: _thread, sys, threading, time.

Notice that the built-ins are also described as "always available", which is the meaning we're trying to move math away from (you can use them without importing anything).

[eamanu]

I agree. What about create a section (or subsection?) or note with
the text:

The next modules: sys, math ...  are always available. This
mean that ...

?

[nedbat]

There are hundreds of modules that are always importable. The majority of the standard library is always importable. More useful would be to annotate those modules that might not be importable, with a reason why.

[eamanu]

More useful would be to annotate those modules that might not be importable, with a reason why.

yes, that is more reasonable. :-D

[kushaldas]

In future we should do the similar change for any module. This will be helpful for new beginners.

[kushaldas]

New changeset 6faad35 by Kushal Das (Ned Batchelder) in branch 'master':
bpo-36908: 'This module is always available' isn't helpful. (bpo-13297)
6faad35

[miss-islington]

New changeset 740a7cd by Miss Islington (bot) in branch '3.7':
bpo-36908: 'This module is always available' isn't helpful. (GH-13297)
740a7cd

[Mariatta]

Thanks all. I've backported the change to 3.7. I think this is good to be closed.