"No module named 'pkg_resources'" error when installing against Python 3.12

[gasman]

On a fairly new* Python 3.12 virtualenv, running the following from the root of the Wagtail codebase

pip install -e .[docs]
cd docs
make html

results in the error:

sphinx-build -b html -d _build/doctrees   . _build/html
Running Sphinx v5.3.0

Configuration error:
There is a programmable error in your configuration file:

Traceback (most recent call last):
  File "/Users/matthew/.virtualenvs/wagtailpy312/lib/python3.12/site-packages/sphinx/config.py", line 350, in eval_config_file
    exec(code, namespace)
  File "/Users/matthew/Development/tbx/wagtail/devscript/wagtail/docs/conf.py", line 19, in <module>
    import sphinx_wagtail_theme
  File "/Users/matthew/.virtualenvs/wagtailpy312/lib/python3.12/site-packages/sphinx_wagtail_theme/__init__.py", line 4, in <module>
    import pkg_resources
ModuleNotFoundError: No module named 'pkg_resources'

make: *** [html] Error 2

This is with Python 3.12.0, pip 23.2.1.

* created about a week ago - haven't tried replicating this from scratch yet

[thibaudcolas]

Ran into this too :)

I assume this is because setuptools is no longer installed by default. According to the pkg_resources docs, that module is now deprecated. Looks like we could replace it with importlib.metadata, introduced in Python 3.7:

from importlib.metadata import version  
version("sphinx_wagtail_theme")  

Or hard-code the version number, it’s not like this package is updated often.

---

If anyone wants to take this on please go for it. This would involve setting up this package locally with Python 3.12, reproducing the issue currently discussed, and then changing the init.py file to use either the importlib.metadata approach I mentioned above, or hard-coding the version number.

[kituuu]

Hey, can I work on this? @thibaudcolas

[thibaudcolas]

Yes, go for it.

[kituuu]

Hey, do we have to follow the setup instructions (given in README) before running these command. Because without that I am getting this...

macOS - Sonoma virtenv - python 3.12.1 @thibaudcolas

[gasman]

@kituuu See https://docs.wagtail.org/en/stable/contributing/developing.html#compiling-the-documentation - there's an alternative command to run here if you're using zsh.

[kituuu]

Thanks @gasman

[kituuu]

Hmm, any idea if this error is OS specific or not? Because for me it is working fine.

first installed pyenv -> installed python 3.12.0 -> set it as my global python version ran pipenv install to make a virtual environment in the root folder then pipenv shell to activate the environment.

[thibaudcolas]

@kituuu interesting! Could you try with a vanilla virtual environment rather than pipenv perhaps? Also I don’t expect this would make a difference but just in case, the command that caused this for me is make spelling / sphinx-build -b spelling -d _build/doctrees . _build/spelling.

After you’ve created your virtual environment (or with your current pipenv one), you can share the output of pip list or equivalent with us so we can double check whether setuptools is there or not.

[kituuu]

@thibaudcolas Pip list has setuptools in it.

I tried creating a virtual env with conda instead of pipenv, but again, setuptools will install.

Ig with standard venv setup, we don't have setup tools

I can reproduce the error, now. Working on the fix : D