0.18: Issues running tests, and use of sphinxcontrib/__init__.py

[dvzrv]

Hi! 👋

I package this project for Arch Linux.

With 0.18 I noticed that I was unable to run tests as before, because none of the test tools I tried (zope-testrunner, unittest, pytest) were able to import the package anymore. I have only now had the time for an investigation, as it took some time to understand what went wrong.

(Here is the relevant check function for 0.17 in our build script).

TL;DR:

• The dependency on zope-testrunner is not needed and can be replaced with python's internal unittest module (or pytest).
• src/sphinxcontrib/__init__.py should be deleted (at least definitely not be shipped in the wheel AFAICT).

Looking at the wheels created for 0.17 and 0.18 I also notice one significant difference:

unzip -l sphinxcontrib_programoutput-0.17-py2.py3-none-any.whl
Archive:  sphinxcontrib_programoutput-0.17-py2.py3-none-any.whl
  Length      Date    Time    Name
---------  ---------- -----   ----
      574  2021-03-31 14:59   sphinxcontrib_programoutput-0.17-py3.8-nspkg.pth
    12911  2021-03-31 14:59   sphinxcontrib/programoutput/__init__.py
     5243  2021-03-31 14:59   sphinxcontrib/programoutput/tests/__init__.py
     4159  2021-03-31 14:59   sphinxcontrib/programoutput/tests/test_cache.py
     5546  2021-03-31 14:59   sphinxcontrib/programoutput/tests/test_command.py
    17122  2021-03-31 14:59   sphinxcontrib/programoutput/tests/test_directive.py
     1964  2021-03-31 14:59   sphinxcontrib/programoutput/tests/test_setup.py
     2462  2021-03-31 14:59   sphinxcontrib/programoutput/tests/test_util.py
     1337  2021-03-31 14:59   sphinxcontrib_programoutput-0.17.dist-info/LICENSE
     7169  2021-03-31 14:59   sphinxcontrib_programoutput-0.17.dist-info/METADATA
      110  2021-03-31 14:59   sphinxcontrib_programoutput-0.17.dist-info/WHEEL
       14  2021-03-31 14:59   sphinxcontrib_programoutput-0.17.dist-info/namespace_packages.txt
       14  2021-03-31 14:59   sphinxcontrib_programoutput-0.17.dist-info/top_level.txt
     1431  2021-03-31 14:59   sphinxcontrib_programoutput-0.17.dist-info/RECORD
---------                     -------
    60056                     14 files

unzip -l sphinxcontrib_programoutput-0.18-py3-none-any.whl
Archive:  sphinxcontrib_programoutput-0.18-py3-none-any.whl
  Length      Date    Time    Name
---------  ---------- -----   ----
       65  2024-12-06 20:36   sphinxcontrib/__init__.py
    13267  2024-12-06 20:36   sphinxcontrib/programoutput/__init__.py
     5267  2024-12-06 20:36   sphinxcontrib/programoutput/tests/__init__.py
     4087  2024-12-06 20:36   sphinxcontrib/programoutput/tests/test_cache.py
     5546  2024-12-06 20:36   sphinxcontrib/programoutput/tests/test_command.py
    17650  2024-12-06 20:36   sphinxcontrib/programoutput/tests/test_directive.py
     1964  2024-12-06 20:36   sphinxcontrib/programoutput/tests/test_setup.py
     2462  2024-12-06 20:36   sphinxcontrib/programoutput/tests/test_util.py
     1432  2024-12-06 20:38   sphinxcontrib_programoutput-0.18.dist-info/LICENSE
     3217  2024-12-06 20:38   sphinxcontrib_programoutput-0.18.dist-info/METADATA
       91  2024-12-06 20:38   sphinxcontrib_programoutput-0.18.dist-info/WHEEL
       14  2024-12-06 20:38   sphinxcontrib_programoutput-0.18.dist-info/top_level.txt
     1286  2024-12-06 20:38   sphinxcontrib_programoutput-0.18.dist-info/RECORD
---------                     -------
    56348                     13 files

In 0.18 the wheel now ships sphinxcontrib/__init__.py. This prevents all test tools I tried to use (in all permutations of trying directly on the code base vs. building the wheel, then installing it to a temporary location and testing against that). Further, I believe shipping that file is additionally problematic for other sphinxcontrib namespaced packages (e.g. sphinxcontrib-spelling, sphinxcontrib-towncrier, etc. etc.). The file should not exist in site-packages!

That said: I am only able to run tests successfully if I remove that file before building and testing.

Afterwards, the following is possible:

PYTHONPATH=src python -m unittest discover -v src/sphinxcontrib/programoutput

or

PYTHONPATH=src pytest -vv src/sphinxcontrib/programoutput

(Personally, I prefer the latter as it allows disabling broken tests more easily).