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: Error in Python Datamodel Documentation
Type: enhancement Stage:
Components: Documentation Versions: Python 3.10, Python 3.9, Python 3.8, Python 3.7, Python 3.6, Python 3.5
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: chrisyeh96, docs@python, rhettinger
Priority: normal Keywords:

Created on 2020-06-13 23:37 by chrisyeh96, last changed 2022-04-11 14:59 by admin.

Pull Requests
URL Status Linked Edit
PR 20864 open chrisyeh96, 2020-06-13 23:37
Messages (5)
msg371473 - (view) Author: Christopher Yeh (chrisyeh96) * Date: 2020-06-13 23:37
The documentation says the following:

> A built-in function object is a wrapper around a C function.  Examples of built-in functions are `len` and `math.sin` (`math` is a standard built-in module).

However, `math` is not always a built-in module, as can be seen in on my own Python installation (Windows 10, WSL 1, Python 3.7.7 installed via conda).

>>> import sys
>>> sys.builtin_module_names
('_abc', '_ast', '_codecs', '_collections', '_functools', '_imp', '_io', '_locale', '_operator', '_signal', '_sre', '_stat', '_string', '_symtable', '_thread', '_tracemalloc', '_warnings', '_weakref', 'atexit', 'builtins', 'errno', 'faulthandler', 'gc', 'itertools', 'marshal', 'posix', 'pwd', 'sys', 'time', 'xxsubtype', 'zipimport')

Therefore, I have submitted a pull request to remove the statement "(`math` is a standard built-in module)" from the documentation.
msg371480 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2020-06-14 03:14
What happens when you type, "import math" and "print(type(math))"?
msg371481 - (view) Author: Christopher Yeh (chrisyeh96) * Date: 2020-06-14 03:34
Here's the output from my terminal comparing the `math` standard library module (not always built-in) against the `sys` standard library module (always built-in).

On Windows 10 x64, WSL 1, Ubuntu 18.04.02 LTS, Python 3.7.7 installed via conda: math is not a built-in module.

$ python
Python 3.7.7 (default, Mar 26 2020, 15:48:22)
[GCC 7.3.0] :: Anaconda, Inc. on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import math
>>> print(math)
<module 'math' from '/home/chris/miniconda3/envs/py37/lib/python3.7/lib-dynload/math.cpython-37m-x86_64-linux-gnu.so'>
>>> print(type(math))
<class 'module'>
>>> import sys
>>> print(sys)
<module 'sys' (built-in)>
>>> print(type(sys))
<class 'module'>


On Windows 10 x64, Python installed directly from Python.org: math is a built-in module.

C:\>python
Python 3.7.3 (v3.7.3:ef4ec6ed12, Mar 25 2019, 22:22:05) [MSC v.1916 64 bit (AMD64)] on win32
Type "help", "copyright", "credits" or "license" for more information.
>>> import math
>>> print(math)
<module 'math' (built-in)>
>>> print(type(math))
<class 'module'>
>>> import sys
>>> print(sys)
<module 'sys' (built-in)>
>>> print(type(sys))
<class 'module'>
msg371482 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2020-06-14 03:48
FWIW, the word "built-in" is being used in two different ways here.  It is used in a strict sense for sys.builtin_module_names and in a general sense in the datamodel docs.

The former only includes modules compiled into the core exe or dll file.  The latter includes anything in compiled extension such as the math module.  The latter is part of the standard build in the sense that it is included in setup.py and parts of the library depend on it being present:

    ~ $ python3.8
    Python 3.8.3 (v3.8.3:6f8c8320e9, May 13 2020, 16:29:34)
    [Clang 6.0 (clang-600.0.57)] on darwin
    Type "help", "copyright", "credits" or "license" for more information.
    >>> import sys
    >>> 'math' in sys.builtin_module_names     
    >>> False
    >>> import math
    >>> type(math.sin)
    <class 'builtin_function_or_method'>
msg371493 - (view) Author: Christopher Yeh (chrisyeh96) * Date: 2020-06-14 06:50
I understand the two uses of the phrase "built-in":

1) to refer to things included with the Python interpreter (e.g. modules in sys.builtin_module_names, and built-in functions like len() and ord())
2) to refer to things included with Python that are written in C

However, I find it fairly difficult to distinguish between the two uses in the context presented:

> A built-in function object is a wrapper around a C function.  Examples of built-in functions are `len` and `math.sin` (`math` is a standard built-in module).

Within the Python Language Reference (docs.python.org/3/reference), this is actually the only case where definition (2) applies, as far as I can tell: https://www.google.com/search?q="built-in+module"+site%3Ahttps%3A%2F%2Fdocs.python.org%2F3%2Freference%2F

Also, I am not sure that the parenthetical about `math` being a module written in C adds any additional clarity.
History
Date User Action Args
2022-04-11 14:59:32adminsetgithub: 85142
2020-06-14 06:50:46chrisyeh96setmessages: + msg371493
2020-06-14 03:48:13rhettingersetmessages: + msg371482
2020-06-14 03:34:54chrisyeh96setmessages: + msg371481
2020-06-14 03:14:46rhettingersetnosy: + rhettinger
messages: + msg371480
2020-06-13 23:37:57chrisyeh96create