Ownership of `sphinxcontrib/__init__.py`

[jamesjer]

This project installs a file to the parent namespace, sphinxcontrib/__init__.py. In Fedora, this has caused a problem for us, because sphinxcontrib-zopeext does likewise, and the two files differ. I brought this up on the Fedora developer's mailing list, and Elliott Sales de Andrade has this to say:

I think these packages are wrong upstream. The `sphinxcontrib` directory is provided by python3-sphinx, and it specifically doesn't have `__init__.py` there. Those extensions should not be adding one, so as to keep the implicit namespace package nature of that directory: https://packaging.python.org/en/latest/guides/packaging-namespace-packages/#native-namespace-packages

By the contents of the files, it appears they are trying to force it to be a pkg_resources-style namespace package: https://packaging.python.org/en/latest/guides/packaging-namespace-packages/#pkg-resources-style-namespace-packages

But since Sphinx didn't do that in the first place, there's no guarantee that other packages will contain `__init__.py` (and indeed most do not).

Does sphinxcontrib-asyncio need that __init__.py file for some reason?

[jamesjer]

Here is the same issue reported to sphinxcontrib-zopeext: https://github.com/sphinx-contrib/zopeext/issues/5

[asvetlov]

I guess the library uses the recommended (well, the old-style recommendation) way to create namespace packages.

Please take a look at other sphinconrib packages, e.g. https://github.com/sphinx-contrib/napoleon/blob/master/sphinxcontrib/init.py

[webknjaz]

The deprecated setuptools-provided namespace packages used to be needed for Python 2 which is when said namespace was first claimed. Migrating to the modern implicit namespaces is not a straightforward task. These two approaches are incompatible and if some of the projects in the namespaces switch the implementation, it'll cause problems with package management. Even if all of the projects change this, it's mean that the end-users would be unable to keep some of the extensions on their older versions. Also, the end-users would have to know upfront to uninstall any of the old packages before installing the new ones into the existing envs.

In general, it's good to start with the modern namespacing approach today.