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: "Modules" section in Tutorial contains incorrect description about __init__.py
Type: enhancement Stage:
Components: Documentation Versions: 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: docs@python, ezio.melotti, methane, musou1500, steven.daprano
Priority: normal Keywords:

Created on 2019-05-11 23:00 by musou1500, last changed 2022-04-11 14:59 by admin.

Messages (4)
msg342228 - (view) Author: musou1500 (musou1500) Date: 2019-05-11 23:00
"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/
msg342230 - (view) Author: Steven D'Aprano (steven.daprano) * (Python committer) Date: 2019-05-12 00:03
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.
msg342233 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2019-05-12 01:30
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.
msg360304 - (view) Author: Inada Naoki (methane) * (Python committer) Date: 2020-01-20 09:14
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.
History
Date User Action Args
2022-04-11 14:59:15adminsetgithub: 81073
2020-01-20 09:14:32methanesetnosy: + methane
messages: + msg360304
2019-05-12 01:30:23ezio.melottisetnosy: + ezio.melotti
messages: + msg342233
2019-05-12 00:03:13steven.dapranosetnosy: + steven.daprano
messages: + msg342230
2019-05-11 23:00:01musou1500create