🐛 Error when building documentation with Python 3.13+ (No module named 'imghdr')

[ebouchut]

Description

❌ Since Feb 17, the documentation.yaml workflow has been failing repeatedly with this error:

Could not import extension sphinx.builders.epub3 (exception: No module named 'imghdr'

Run sphinx-build -b dirhtml docs _build
sphinx-build -b dirhtml docs _build
shell: /usr/bin/bash -e {0}
env:
  pythonLocation: /opt/hostedtoolcache/Python/3.13.2/x64
  LD_LIBRARY_PATH: /opt/hostedtoolcache/Python/3.13.2/x64/lib
Running Sphinx v5.3.0

Extension error:
Could not import extension sphinx.builders.epub3 (exception: No module named 'imghdr')
Error: Process completed with exit code 2.

Cause

The imghdr module has been removed from the Python Standard Library as of Python 3.13, following its deprecation in Python 3.11.

The documentation.yaml GitHub workflow highlighted this bug as it uses Python v3.13+.
I reproduced the bug locally after upgrading Python to version 3.13 and attempting to build the documentation.
Therefore, this is not a CI/CD bug.

➡️ The cause is the outdated package(s) using the ìmghdr` module that no longer exists as of Python 3.13+.

cd nighscout.github.io

pyenv install 3.13.2
pyenv local 3.13.2

python  -m venv venv
pip install -r requirements.txt

rm -rf _build
sphinx-build -M dirhtml docs/ _build/

#=> Running Sphinx v5.3.0
#=>
#=> Extension error:
#=> Could not import extension sphinx.builders.epub3 (exception: No module named 'imghdr')

Solution

A quick search led me to conclude that sphinx version 5.3 is the only package that uses it.

grep -r imghdr venv/lib/python3.13/site-packages/

Binary file venv/lib/python3.13/site-packages//sphinx/util/__pycache__/images.cpython-313.pyc matches
venv/lib/python3.13/site-packages//sphinx/util/images.py:import imghdr
venv/lib/python3.13/site-packages//sphinx/util/images.py:    imgtype = imghdr.what(stream)
venv/lib/python3.13/site-packages//sphinx/util/images.py:    """An additional imghdr library helper; test the header is SVG's or not."""
venv/lib/python3.13/site-packages//sphinx/util/images.py:# install test_svg() to imghdr
venv/lib/python3.13/site-packages//sphinx/util/images.py:# refs: https://docs.python.org/3.6/library/imghdr.html#imghdr.tests
venv/lib/python3.13/site-packages//sphinx/util/images.py:imghdr.tests.append(test_svg)

🎯 So, I suggest updating the project packages/dependencies:

• using imghdr, i.e. sphinx
• but also all the other direct dependencies/packages in one go.