"Modules" section in Tutorial contains incorrect description about __init__.py

[musou1500]

BPO	36892
Nosy	@ezio-melotti, @stevendaprano, @methane, @musou1500

^{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 2019-05-11.23:00:01.107>
labels = ['3.8', 'type-feature', '3.7', '3.9', 'docs']
title = '"Modules" section in Tutorial contains incorrect description about __init__.py'
updated_at = <Date 2020-01-20.09:14:32.711>
user = 'https://github.com/musou1500'

bugs.python.org fields:

activity = <Date 2020-01-20.09:14:32.711>
actor = 'methane'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2019-05-11.23:00:01.107>
creator = 'musou1500'
dependencies = []
files = []
hgrepos = []
issue_num = 36892
keywords = []
message_count = 4.0
messages = ['342228', '342230', '342233', '360304']
nosy_count = 5.0
nosy_names = ['ezio.melotti', 'steven.daprano', 'methane', 'docs@python', 'musou1500']
pr_nums = []
priority = 'normal'
resolution = None
stage = None
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue36892'
versions = ['Python 3.5', 'Python 3.6', 'Python 3.7', 'Python 3.8', 'Python 3.9']

[musou1500]

"Modules" section in the tutorial says that
https://docs.python.org/3/tutorial/modules.html
"The __init__.py files are required to make Python treat directories containing the file as packages. "

But, thanks to PEP-420, __init__.py is not required after Python 3.3.
https://www.python.org/dev/peps/pep-0420/

[stevendaprano]

In my experience, beginners have enough trouble getting packages right without complicating the tutorial with a rarely-used advanced feature like namespace packages.

I don't think this needs more than perhaps a footnote, if that.

[ezio-melotti]

I agree that implicit namespace packages don't deserve more than a footnote in that page.

However, since I often have to answer questions about packages, I'm thinking that perhaps it would be better to expand that page and maybe have a page dedicated to modules and one to packages, where PEP-420 and other common issues could be covered in more details.

[methane]

I think it is just a noise for the tutorial readers.

I created a post about misunderstanding of PEP-420.
https://dev.to/methane/don-t-omit-init-py-3hga

How about adding note in top of the PEP-420 instead?

.. note::
Namespace packages are not regular packages. It
is a feature for very special use case.
Don't omit __init__.py in regular packages.

[zahlman]

Rather than discussing namespace packages separately, how about just accurately stating the purpose and effects of __init__.py in the example? Something like:

When importing the package, Python searches through the directories on sys.path looking for the package subdirectory.

The __init__.py files are required to make Python treat directories containing the file as packages. This prevents directories with a common name, such as string, from unintentionally hiding valid modules that occur later on the module search path. In the simplest case, __init__.py can just be an empty file, but it can also execute initialization code for the package or set the __all__ variable, described later.

Python will create a module object for each directory as well, representing the sound package and its subpackages. The __init__.py files in these directories tell Python explicitly that they represent packages. They also allow you to customize the corresponding module objects. For example, classes and functions can be defined directly inside the package (since it is a module), rather than within a module within that package. __init__.py can also contain initialization code for a package; in particular, it can set the special __all__ attribute (described later).

When importing the package, Python searches through the directories on sys.path looking for the package subdirectory. If Python finds a subdirectory that does not contain __init__.py, it will defer loading a package from that subdirectory, and check the rest of sys.path first. This is a special rule, intended to avoid accidentally hiding a valid module (for example, string in the standard library) with a folder which was found first, but which was not intended to represent a package. If this causes a problem, add a blank __init__.py to the subdirectory.

[methane]

Rather than discussing namespace packages separately, how about just accurately stating the purpose and effects of __init__.py in the example? Something like:

I don't think accuracy is not important for tutorial.
Tutorial should be optimized for speed to learn Python.

[methane]

fixed in #113209.