Doc: update term "namespace package" #129251

methane · 2025-01-24T05:43:59Z

Recommend using regular package officially to avoid people just think __init__.py is not necessary.

For example: https://stackoverflow.com/questions/448271/what-is-init-py-for

📚 Documentation preview 📚: https://cpython-previews--129251.org.readthedocs.build/

Recommend using regular package officially to avoid people just think `__init__.py` is not necessary.

methane · 2025-01-24T06:01:57Z

Another example of namespace pacakge being misunderstood.
#81073 (comment)

Doc/glossary.rst

StanFromIreland · 2025-01-24T08:15:37Z

Doc/glossary.rst

      and specifically are not like a :term:`regular package` because they
      have no ``__init__.py`` file.

+      Namespace packages allow you to split single package across multiple directories or distributions.
+      On the other hand, namespace packages have some drawbacks and pitfalls.
+      Use :term:`regular package` always when it fits your needs.


Suggested change

Use :term:`regular package` always when it fits your needs.

It is recommended to use a :term:`regular package` when possible.

Does "When possible" and "fits your needs" have same nuance?

For example, user who are thinking splitting their packages to two distribution, but it is "possible" to keep releasing one distribution.

In this case, regular package is not fits their need, but it is possible to use regular package.

The suggested edit makes text less direct, which is the style wanted for our docs.

But I think the wording should be improved. «always» seems strong but is weakened by «when it fits your needs» – people may not now if they do need to split a project!

Also, «across multiple directories» is talking about source trees but «across multiple distributions» is a concern for packaging and installation, so they’re not on the same level.

I’ll think on this and suggest edits!

I agree, it is friendlier

You misunderstand – I meant that the previous wording was more direct, which is what we want. «It is recommended» is not an improvement.

For context, @StanFromIreland, Open telemetry is an example of a namespace package.

I recommend removing "On the other hand ... your needs." This is a glossary entry so the prose should be brief and direct. I think if you add @methane's suggestion Namespace packages allow several individually installable packages to have a common parent package., then there is no need for the two sentences and they can be removed.

Co-authored-by: Stan Ulbrych <[email protected]>

merwok

oops message didn’t post earlier

merwok · 2025-01-24T14:23:23Z

Doc/glossary.rst

      and specifically are not like a :term:`regular package` because they
      have no ``__init__.py`` file.

+      Namespace packages allow you to split single package across multiple directories or distributions.
+      On the other hand, namespace packages have some drawbacks and pitfalls.
+      Use :term:`regular package` always when it fits your needs.


But I think the wording should be improved. «always» seems strong but is weakened by «when it fits your needs» – people may not now if they do need to split a project!

Also, «across multiple directories» is talking about source trees but «across multiple distributions» is a concern for packaging and installation, so they’re not on the same level.

I’ll think on this and suggest edits!

methane · 2025-01-24T23:28:44Z

Also, «across multiple directories» is talking about source trees but «across multiple distributions» is a concern for packaging and installation, so they’re not on the same level.

How about this?

Namespace packages allow several individually installable packages to have a common parent package.

Both of pip install and "setting multiple import paths" are "install".

In case of pip install, namespace package would be a single directory. But that is certainly a situation where implicit namespace packages can be used.

Doc/glossary.rst

willingc

Thanks @methane. I recommend removing the awkward sentences at the end.

willingc · 2025-01-25T01:27:12Z

Doc/glossary.rst

      and specifically are not like a :term:`regular package` because they
      have no ``__init__.py`` file.

+      Namespace packages allow you to split single package across multiple directories or distributions.
+      On the other hand, namespace packages have some drawbacks and pitfalls.
+      Use :term:`regular package` always when it fits your needs.


For context, @StanFromIreland, Open telemetry is an example of a namespace package.

I recommend removing "On the other hand ... your needs." This is a glossary entry so the prose should be brief and direct. I think if you add @methane's suggestion Namespace packages allow several individually installable packages to have a common parent package., then there is no need for the two sentences and they can be removed.

methane · 2025-01-25T07:42:48Z

@willingc I would like to add a sentence to the official documentation to debunk the misconception that __init__.py is no longer needed from Python 3.3.

#113209 added unless using a :term:`namespace package`, a relatively advanced feature in the tutorial. But "relatively advanced feature" is not enough to prevent omitting __init__.py without knowing its risk.

We have namespace packages section in the reference. But tutorial refers to glossary, not reference. That is why I added the awkward sentences at the end.

ericvsmith

This looks good to me.

Doc/glossary.rst

merwok · 2025-02-14T18:48:17Z

Thanks all!

I think we should backport

miss-islington-app · 2025-02-14T18:48:47Z

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

miss-islington-app · 2025-02-14T18:48:47Z

Thanks @methane for the PR, and @merwok for merging it 🌮🎉.. I'm working now to backport this PR to: 3.12.
🐍🍒⛏🤖

(cherry picked from commit e65e9f9) Co-authored-by: Inada Naoki <[email protected]>

bedevere-app · 2025-02-14T18:48:55Z

GH-130128 is a backport of this pull request to the 3.12 branch.

(cherry picked from commit e65e9f9) Co-authored-by: Inada Naoki <[email protected]>

bedevere-app · 2025-02-14T18:49:00Z

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

bedevere-bot · 2025-02-14T20:38:43Z

⚠️⚠️⚠️ Buildbot failure ⚠️⚠️⚠️

Hi! The buildbot AMD64 CentOS9 NoGIL Refleaks 3.x has failed when building commit e65e9f9.

What do you need to do:

Don't panic.
Check the buildbot page in the devguide if you don't know what the buildbots are or how they work.
Go to the page of the buildbot that failed (https://buildbot.python.org/#/builders/1610/builds/858) and take a look at the build logs.
Check if the failure is related to this commit (e65e9f9) or if it is a false positive.
If the failure is related to this commit, please, reflect that on the issue and make a new Pull Request with a fix.

You can take a look at the buildbot page here:

https://buildbot.python.org/#/builders/1610/builds/858

Failed tests:

test_free_threading

Summary of the results of the build (if available):

==

Click to see traceback logs

remote: Enumerating objects: 6, done.        
remote: Counting objects:  16% (1/6)        
remote: Counting objects:  33% (2/6)        
remote: Counting objects:  50% (3/6)        
remote: Counting objects:  66% (4/6)        
remote: Counting objects:  83% (5/6)        
remote: Counting objects: 100% (6/6)        
remote: Counting objects: 100% (6/6), done.        
remote: Compressing objects:  20% (1/5)        
remote: Compressing objects:  40% (2/5)        
remote: Compressing objects:  60% (3/5)        
remote: Compressing objects:  80% (4/5)        
remote: Compressing objects: 100% (5/5)        
remote: Compressing objects: 100% (5/5), done.        
remote: Total 6 (delta 1), reused 2 (delta 1), pack-reused 0 (from 0)        
From https://github.com/python/cpython
 * branch                    main       -> FETCH_HEAD
Note: switching to 'e65e9f90626a4c62da4d3500044f354b51e51dbb'.

You are in 'detached HEAD' state. You can look around, make experimental
changes and commit them, and you can discard any commits you make in this
state without impacting any branches by switching back to a branch.

If you want to create a new branch to retain commits you create, you may
do so (now or later) by using -c with the switch command. Example:

  git switch -c <new-branch-name>

Or undo this operation with:

  git switch -

Turn off this advice by setting config variable advice.detachedHead to false

HEAD is now at e65e9f90626 Doc: update term "namespace package" (#129251)
Switched to and reset branch 'main'

configure: WARNING: no system libmpdecimal found; falling back to bundled libmpdecimal (deprecated and scheduled for removal in Python 3.15)

make: *** [Makefile:2325: buildbottest] Error 2

(cherry picked from commit e65e9f9)

(cherry picked from commit e65e9f9) Co-authored-by: Inada Naoki <[email protected]>

Doc: update term "namespace package"

5215bae

Recommend using regular package officially to avoid people just think `__init__.py` is not necessary.

methane added the docs Documentation in the Doc dir label Jan 24, 2025

methane requested review from willingc and AA-Turner as code owners January 24, 2025 05:44

bedevere-app bot added awaiting core review skip news labels Jan 24, 2025

methane added the skip issue label Jan 24, 2025

methane requested a review from ericvsmith January 24, 2025 06:02

StanFromIreland reviewed Jan 24, 2025

View reviewed changes

Apply suggestions from code review

16d5407

Co-authored-by: Stan Ulbrych <[email protected]>

merwok reviewed Jan 24, 2025

View reviewed changes

merwok requested review from ncoghlan and merwok January 24, 2025 17:53

methane force-pushed the doc-namespace-package branch from 5002745 to 16d5407 Compare January 24, 2025 23:13

methane commented Jan 24, 2025

View reviewed changes

Doc/glossary.rst Outdated Show resolved Hide resolved

willingc reviewed Jan 25, 2025

View reviewed changes

methane added 3 commits January 25, 2025 17:05

Update Doc/glossary.rst

64f6e73

simplify

c33cc85

Merge remote-tracking branch 'upstream/main' into doc-namespace-package

b6b4c09

ericvsmith approved these changes Feb 14, 2025

View reviewed changes

bedevere-app bot added awaiting merge and removed awaiting core review labels Feb 14, 2025

merwok requested a review from brettcannon February 14, 2025 17:25

merwok reviewed Feb 14, 2025

View reviewed changes

Doc/glossary.rst Show resolved Hide resolved

merwok approved these changes Feb 14, 2025

View reviewed changes

Merge branch 'main' into doc-namespace-package

4e47450

merwok merged commit e65e9f9 into python:main Feb 14, 2025
24 checks passed

bedevere-app bot removed the awaiting merge label Feb 14, 2025

merwok added needs backport to 3.12 only security fixes needs backport to 3.13 bugs and security fixes labels Feb 14, 2025

miss-islington pushed a commit to miss-islington/cpython that referenced this pull request Feb 14, 2025

Doc: update term "namespace package" (pythonGH-129251)

d287ff5

(cherry picked from commit e65e9f9) Co-authored-by: Inada Naoki <[email protected]>

bedevere-app bot removed the needs backport to 3.12 only security fixes label Feb 14, 2025

miss-islington pushed a commit to miss-islington/cpython that referenced this pull request Feb 14, 2025

Doc: update term "namespace package" (pythonGH-129251)

7c3702b

(cherry picked from commit e65e9f9) Co-authored-by: Inada Naoki <[email protected]>

bedevere-app bot removed the needs backport to 3.13 bugs and security fixes label Feb 14, 2025

methane deleted the doc-namespace-package branch February 15, 2025 05:07

methane pushed a commit that referenced this pull request Feb 15, 2025

Doc: update term "namespace package" (GH-129251)

692d36f

(cherry picked from commit e65e9f9)

methane added a commit that referenced this pull request Feb 15, 2025

Doc: update term "namespace package" (GH-129251)

de1279a

(cherry picked from commit e65e9f9) Co-authored-by: Inada Naoki <[email protected]>

	Use :term:`regular package` always when it fits your needs.
	It is recommended to use a :term:`regular package` when possible.

Uh oh!

Doc: update term "namespace package" #129251

Doc: update term "namespace package" #129251

Uh oh!

Conversation

methane commented Jan 24, 2025 • edited by github-actions bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

methane commented Jan 24, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

merwok left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

methane commented Jan 24, 2025

Uh oh!

Uh oh!

willingc left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

methane commented Jan 25, 2025

Uh oh!

ericvsmith left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

merwok commented Feb 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

miss-islington-app bot commented Feb 14, 2025

Uh oh!

miss-islington-app bot commented Feb 14, 2025

Uh oh!

bedevere-app bot commented Feb 14, 2025

Uh oh!

bedevere-app bot commented Feb 14, 2025

Uh oh!

bedevere-bot commented Feb 14, 2025

⚠️⚠️⚠️ Buildbot failure ⚠️⚠️⚠️

Uh oh!

Uh oh!

methane commented Jan 24, 2025 •

edited by github-actions bot

Loading

merwok commented Feb 14, 2025 •

edited

Loading