Local environment setup failed with Python 3.13.1 due to `No module named 'imghdr'`

[codersjj]

Page

Abstract

After downloading the latest version of Python (currently 3.13.1) for Windows:

I attempted to run ./docs.sh, but encountered the following error:

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

Upon investigating the issue, I found a related discussion in the Sphinx repository: sphinx-doc/sphinx#10440. Based on the information there, it appears that the problem might be related to compatibility issues with Python 3.13.1.

To resolve the issue, I decided to switch to Python 3.11. After installing Python 3.11 and re-running ./docs.sh, the script executed successfully without any errors:

I would appreciate it if the maintainers could investigate and address this issue to ensure compatibility with Python 3.13. 😃

Pull request

[nikola-matic]

I encountered this issue when installing in a virtual environment (not default). I then tried using --break-system-packages and encountered the following:

      File "/opt/homebrew/lib/python3.13/site-packages/antlr4/Lexer.py", line 12, in <module>
        from typing.io import TextIO
    ModuleNotFoundError: No module named 'typing.io'; 'typing' is not a package

The above also occurs because the typing.io package was deprecated in 3.8 and removed in 3.12.

[r0qs]

I investigated this issue further, and to properly fix it and support Python 3.13+, we need to wait for a release of sphinx-a4doc.

To summarize the issues, as pointed out by @codersjj, imghdr was removed in Python 3.13, and Sphinx 6.2.0 (sphinx-doc/sphinx#10440 (comment)). However, sphinx-a4doc 1.6.0 (the latest release we rely on for our documentation) still uses an outdated antlr4-python3-runtime version that depends on typing.io (antlr/antlr4#4767), which, as @nikola-matic pointed out, was also removed in Python 3.12.

The issue was actually reported upstream in taminomara/sphinx-a4doc#20 and fixed in taminomara/sphinx-a4doc#22 but has not been released yet. I will open an issue there.

Currently, our documentation requires Sphinx >=2.1.0 and <6.0, and this will continue to work as long as we don't update the Python version. However, I suggest updating it to >=6.2.0 <9.0 as soon as sphinx-a4doc releases its next version.

For instance, changing our requirements.txt to the following fix the issue:

sphinx_rtd_theme>=0.5.2
pygments-lexer-solidity>=0.7.0

git+https://github.com/taminomara/sphinx-a4doc.git@f63d3b276d201f044dd3f2fac0380f53fdce978f#egg=sphinx-a4doc

sphinx>=6.2.0, <9.0