Doc: update term "namespace package"

[methane]

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/

[methane]

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

[StanFromIreland]

Suggested change

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

[methane]

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.

[merwok]

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

[merwok]

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!

[StanFromIreland]

I agree, it is friendlier

[merwok]

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

[willingc]

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.

[merwok]

oops message didn’t post earlier

[merwok]

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]

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.

[willingc]

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

[willingc]

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]

@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.