pbr used in extension stops sphinx-build

[Matt Documatt]

Hello dear Sphinx fellow developers!

Recently, I release sphinxcontrib-constdata extension for showing external file data in docs as labels, links and tables. Sources are at https://gitlab.com/documatt/sphinxcontrib-constdata.

I started with sphinxcontrib template on GitHub that uses pbr (https://docs.openstack.org/pbr/latest/index.html). During the development, I had a number of problems with pbr. I dislike pbr and see that most other sphinxcontrib extensions don't use it. But I managed all problems. Now I have another one, a very serious blocker issue.

In the template and also in my extension I require pbr as setuptools install_requires dependency. I.e. all users of my extension will also have pbr installed. It is annoying itself, but okay.

If I add sphinxcontrib.constdata to conf.py's extensions list, and try to build the docs, it causes 

"pkg_resources.DistributionNotFound: The 'sphinxcontrib.constdata' distribution was not found and is required by the application"

and

Exception: Versioning for this project requires either an sdist tarball, or access to an upstream git repository. It's also possible that there is a mismatch between the package name in setup.cfg and the argument given to pbr.version.VersionInfo. Project name sphinxcontrib.constdata was given, but was not able to be found.

But sphinxcontrib.constdata is definitively in my venv... I also don't understand the meaning of these errors.

Can somebody help me explain proper usage of pbr for a libs?

Full traceback is:

Traceback (most recent call last):
  File "/Users/libor/tmp/sphinx-constdata-test/venv/lib/python3.9/site-packages/pbr/version.py", line 442, in _get_version_from_pkg_resources
    provider = pkg_resources.get_provider(requirement)
  File "/Users/libor/tmp/sphinx-constdata-test/venv/lib/python3.9/site-packages/pkg_resources/__init__.py", line 342, in get_provider
    return working_set.find(moduleOrReq) or require(str(moduleOrReq))[0]
  File "/Users/libor/tmp/sphinx-constdata-test/venv/lib/python3.9/site-packages/pkg_resources/__init__.py", line 886, in require
    needed = self.resolve(parse_requirements(requirements))
  File "/Users/libor/tmp/sphinx-constdata-test/venv/lib/python3.9/site-packages/pkg_resources/__init__.py", line 772, in resolve
    raise DistributionNotFound(req, requirers)
pkg_resources.DistributionNotFound: The 'sphinxcontrib.constdata' distribution was not found and is required by the application

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "/Users/libor/tmp/sphinx-constdata-test/venv/lib/python3.9/site-packages/sphinx/cmd/build.py", line 280, in build_main
    app = Sphinx(args.sourcedir, args.confdir, args.outputdir,
  File "/Users/libor/tmp/sphinx-constdata-test/venv/lib/python3.9/site-packages/sphinx/application.py", line 230, in __init__
    self.setup_extension(extension)
  File "/Users/libor/tmp/sphinx-constdata-test/venv/lib/python3.9/site-packages/sphinx/application.py", line 387, in setup_extension
    self.registry.load_extension(self, extname)
  File "/Users/libor/tmp/sphinx-constdata-test/venv/lib/python3.9/site-packages/sphinx/registry.py", line 433, in load_extension
    mod = import_module(extname)
  File "/opt/homebrew/Cellar/python@3.9/3.9.7_1/Frameworks/Python.framework/Versions/3.9/lib/python3.9/importlib/__init__.py", line 127, in import_module
    return _bootstrap._gcd_import(name[level:], package, level)
  File "<frozen importlib._bootstrap>", line 1030, in _gcd_import
  File "<frozen importlib._bootstrap>", line 1007, in _find_and_load
  File "<frozen importlib._bootstrap>", line 986, in _find_and_load_unlocked
  File "<frozen importlib._bootstrap>", line 680, in _load_unlocked
  File "<frozen importlib._bootstrap_external>", line 850, in exec_module
  File "<frozen importlib._bootstrap>", line 228, in _call_with_frames_removed
  File "/Users/libor/tmp/sphinx-constdata-test/venv/lib/python3.9/site-packages/sphinxcontrib/constdata/__init__.py", line 31, in <module>
    __version__ = pbr.version.VersionInfo("sphinxcontrib.constdata").version_string()
  File "/Users/libor/tmp/sphinx-constdata-test/venv/lib/python3.9/site-packages/pbr/version.py", line 467, in version_string
    return self.semantic_version().brief_string()
  File "/Users/libor/tmp/sphinx-constdata-test/venv/lib/python3.9/site-packages/pbr/version.py", line 462, in semantic_version
    self._semantic = self._get_version_from_pkg_resources()
  File "/Users/libor/tmp/sphinx-constdata-test/venv/lib/python3.9/site-packages/pbr/version.py", line 449, in _get_version_from_pkg_resources
    result_string = packaging.get_version(self.package)
  File "/Users/libor/tmp/sphinx-constdata-test/venv/lib/python3.9/site-packages/pbr/packaging.py", line 874, in get_version
    raise Exception("Versioning for this project requires either an sdist"
Exception: Versioning for this project requires either an sdist tarball, or access to an upstream git repository. It's also possible that there is a mismatch between the package name in setup.cfg and the argument given to pbr.version.VersionInfo. Project name sphinxcontrib.constdata was given, but was not able to be found.

Exception occurred:
  File "/Users/libor/tmp/sphinx-constdata-test/venv/lib/python3.9/site-packages/pbr/packaging.py", line 874, in get_version
    raise Exception("Versioning for this project requires either an sdist"
Exception: Versioning for this project requires either an sdist tarball, or access to an upstream git repository. It's also possible that there is a mismatch between the package name in setup.cfg and the argument given to pbr.version.VersionInfo. Project name sphinxcontrib.constdata was given, but was not able to be found.
The full traceback has been saved in /var/folders/wm/v70flf4d64s4k71brj16ldhm0000gn/T/sphinx-err-nh06onen.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
A bug report can be filed in the tracker at <https://github.com/sphinx-doc/sphinx/issues>. Thanks!
make: *** [html] Error 2

--
Matt
https://techwriter.documatt.com

[Matt Documatt]

I solved that my extension https://gitlab.com/documatt/sphinxcontrib-constdata based on pbr was causing during Sphinx build these errors

"pkg_resources.DistributionNotFound: The 'sphinxcontrib.constdata' distribution was not found and is required by the application"

and

Exception: Versioning for this project requires either an sdist tarball, or access to an upstream git repository. It's also possible that there is a mismatch between the package name in setup.cfg and the argument given to pbr.version.VersionInfo. Project name sphinxcontrib.constdata was given, but was not able to be found.

To fix it I

* changed "name" in setup.cfg from "sphinxcontrib-constdata" to "sphinxcontrib.constdata"
* removed sphinxcontrib/__init__.py

(see https://gitlab.com/documatt/sphinxcontrib-constdata/-/commit/1803a725ecf0ded209ef963f0929bb7c914b1a3b)

Python packaging is a jungle. I don't understand what was the problem. Is there anyone who can explain me why these two changes helped?

For example, many other Sphinx extensions based on pbr write its setup.py name with hyphen and works. According to https://packaging.python.org/en/latest/guides/distributing-packages-using-setuptools/#name "sphinxcontrib.constdata" and "sphinxcontrib-constdata" should be the same.

--
Matt
https://techwriter.documatt.com

> --
> You received this message because you are subscribed to the Google Groups "sphinx-dev" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to sphinx-dev+...@googlegroups.com.
> To view this discussion on the web, visit https://groups.google.com/d/msgid/sphinx-dev/3FB85CA3-A44E-4505-95F6-026A4195CFE2%40documatt.com.

[Juan Luis Cano Rodríguez]

I haven't looked into the issue in detail, but what you describe seems related to Namespace Packages https://www.python.org/dev/peps/pep-0420/

Cheers,

jua...@readthedocs.org

Read the Docs

To view this discussion on the web, visit https://groups.google.com/d/msgid/sphinx-dev/DB25606D-F40B-4A65-BA2A-F34C888EF47D%40documatt.com.