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: "This module is always available" is confusing
Type: Stage: resolved
Components: Documentation Versions: Python 3.9, Python 3.8, Python 3.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Mariatta, docs@python, eamanu, kushal.das, miss-islington, nedbat
Priority: normal Keywords: patch

Created on 2019-05-13 21:15 by nedbat, last changed 2022-04-11 14:59 by admin. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 13297 merged nedbat, 2019-05-13 21:24
PR 13394 merged miss-islington, 2019-05-17 20:51
Messages (11)
msg342386 - (view) Author: Ned Batchelder (nedbat) * (Python triager) Date: 2019-05-13 21:15
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.)
msg342390 - (view) Author: Mariatta (Mariatta) * (Python committer) Date: 2019-05-13 21:51
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"?
msg342392 - (view) Author: Ned Batchelder (nedbat) * (Python triager) Date: 2019-05-13 22:09
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?
msg342394 - (view) Author: Ned Batchelder (nedbat) * (Python triager) Date: 2019-05-13 22:17
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).
msg342402 - (view) Author: Emmanuel Arias (eamanu) * Date: 2019-05-14 00:13
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 ...
```

?
msg342403 - (view) Author: Ned Batchelder (nedbat) * (Python triager) Date: 2019-05-14 00:16
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.
msg342404 - (view) Author: Emmanuel Arias (eamanu) * Date: 2019-05-14 00:20
> More useful would be to annotate those modules that might not be importable, with a reason why.

yes, that is more reasonable. :-D
msg342700 - (view) Author: Kushal Das (kushal.das) * (Python committer) Date: 2019-05-17 09:50
In future we should do the similar change for any module. This will be helpful for new beginners.
msg342704 - (view) Author: Kushal Das (kushal.das) * (Python committer) Date: 2019-05-17 09:59
New changeset 6faad355db6c2bd4a0ade7868f245b42c04f5337 by Kushal Das (Ned Batchelder) in branch 'master':
bpo-36908: 'This module is always available' isn't helpful. (#13297)
https://github.com/python/cpython/commit/6faad355db6c2bd4a0ade7868f245b42c04f5337
msg342767 - (view) Author: miss-islington (miss-islington) Date: 2019-05-17 21:08
New changeset 740a7cde9c0af5a237a7f6525b38d65a83f4fbf1 by Miss Islington (bot) in branch '3.7':
bpo-36908: 'This module is always available' isn't helpful. (GH-13297)
https://github.com/python/cpython/commit/740a7cde9c0af5a237a7f6525b38d65a83f4fbf1
msg342768 - (view) Author: Mariatta (Mariatta) * (Python committer) Date: 2019-05-17 21:10
Thanks all. I've backported the change to 3.7. I think this is good to be closed.
History
Date User Action Args
2022-04-11 14:59:15adminsetgithub: 81089
2019-05-17 21:10:25Mariattasetstatus: open -> closed
versions: + Python 3.7, Python 3.8, Python 3.9
messages: + msg342768

resolution: fixed
stage: patch review -> resolved
2019-05-17 21:08:24miss-islingtonsetnosy: + miss-islington
messages: + msg342767
2019-05-17 20:51:33miss-islingtonsetpull_requests: + pull_request13304
2019-05-17 09:59:17kushal.dassetmessages: + msg342704
2019-05-17 09:50:26kushal.dassetnosy: + kushal.das
messages: + msg342700
2019-05-14 00:20:02eamanusetmessages: + msg342404
2019-05-14 00:16:01nedbatsetmessages: + msg342403
2019-05-14 00:13:33eamanusetnosy: + eamanu
messages: + msg342402
2019-05-13 22:17:02nedbatsetmessages: + msg342394
2019-05-13 22:09:44nedbatsetmessages: + msg342392
2019-05-13 21:51:40Mariattasetnosy: + Mariatta
messages: + msg342390
2019-05-13 21:24:41nedbatsetkeywords: + patch
stage: patch review
pull_requests: + pull_request13207
2019-05-13 21:15:22nedbatcreate