gh-148672: Document namespace subpackages inside regular packages

[Taeknology]

This documents the long-standing behaviour where a subdirectory of a
regular package that does not contain an __init__.py file is imported
as a namespace subpackage of that regular package, per
PEP 420.

The reference docs (Doc/reference/import.rst) currently describe
"Regular packages" and "Namespace packages" as two disjoint categories,
and do not mention that a namespace package can also be nested inside a
regular package. The behaviour is intentional (PEP 420 Specification;
implemented in Lib/importlib/_bootstrap_external.py
FileFinder.find_spec), but is undocumented.

This PR adds:

1. A short cross-reference paragraph at the end of the "Regular packages"
   section pointing to the namespace package definition.
2. A paragraph in the "Namespace packages" section explicitly stating
   that namespace packages may also be nested inside a regular package.

Verified locally (Python 3.12.11)

I reproduced the documented behaviour against a CPython interpreter to
make sure the new wording matches what the import system actually does:

$ tree /tmp/test/
/tmp/test/
└── myreg/
    ├── __init__.py        # regular package
    └── empty_sub/         # no __init__.py
        └── deeper/        # no __init__.py

$ python3 -c "
import sys; sys.path.insert(0, '/tmp/test')
import myreg
import myreg.empty_sub
import myreg.empty_sub.deeper
print(repr(myreg))
print(repr(myreg.empty_sub))
print(repr(myreg.empty_sub.deeper))
"
<module 'myreg' from '/tmp/test/myreg/__init__.py'>
<module 'myreg.empty_sub' (namespace) from ['/tmp/test/myreg/empty_sub']>
<module 'myreg.empty_sub.deeper' (namespace) from ['/tmp/test/myreg/empty_sub/deeper']>

The interpreter's own repr labels myreg.empty_sub and
myreg.empty_sub.deeper as (namespace), confirming this is the
intended behaviour and not a bug, which is what the new paragraphs
document.

No code change. No Misc/NEWS.d entry (docs-only).

Fixes #148672

• Issue: Document the unexpected importing of sub-namespaces inside normal python packages/namespaces #148672

[read-the-docs-community]

Documentation build overview

📚 cpython-previews | 🛠️ Build #32910206 | 📁 Comparing ef2131a against main (517d3d2)

  🔍 Preview build  

41 files changed · ± 41 modified

± Modified

• glossary.html
• index.html
• c-api/import.html
• c-api/sentinel.html
• c-api/threads.html
• library/audit_events.html
• library/ctypes.html
• library/datatypes.html
• library/difflib.html
• library/enum.html
• and 31 more...

[miss-islington-app]

Thanks @Taeknology for the PR, and @brettcannon for merging it 🌮🎉.. I'm working now to backport this PR to: 3.13, 3.14, 3.15.
🐍🍒⛏🤖

[bedevere-app]

GH-150729 is a backport of this pull request to the 3.15 branch.

[bedevere-app]

GH-150730 is a backport of this pull request to the 3.14 branch.

[bedevere-app]

GH-150731 is a backport of this pull request to the 3.13 branch.