Confusion running make coverage on macOS Sonoma

Documentation
1

Running make coverage inside folder /Doc failed with an error:

Warning, treated as error:
module encodings.mbcs could not be imported: cannot import name ‘mbcs_encode’ from ‘codecs’ (/opt/local/Library/Frameworks/Python.framework/Versions/3.12/lib/python3.12/codecs.py)
make: *** [build] Error 2

Both files exists: codecs.py, encodings/mbcs.py
Why is all loaded, also outside Windows ?
Can it be disabled in config.py ?

2

I can confirm this happens. It’s because of this module reference:

.. module:: encodings.mbcs
   :synopsis: Windows ANSI codepage

If I comment out those lines, the warning is about the next Windows-only module reference.

TBH, I’m not sure what “make coverage” is even supposed to do, or why these warnings don’t appear for “make html”.

3

Hi nedbat,

I agree.

We both know Sphinx builders and extensions, specific presentation format like epub, latex, html, text is one output, if a gap between code and documentation another.

4

It runs Sphinx with this coverage builder:

https://www.sphinx-doc.org/en/master/usage/extensions/coverage.html

I tried it once, it didn’t work, and then I moved on to something else. It was added 17 years ago in Merged revisions 61003-61033 via svnmerge from · python/cpython@d3eb5a1 · GitHub along with a lot of other stuff.

We could remove it from the Makefile if it’s not useful or fixable.

5

Hi hugovk,

not for me. Later perhaps, if it’s useless and unfixable. Documentation keeps stuff representative for Windows like winreg.rst, but it’s useless for MacOS.

6

Done!

Configuration for Debug in PyCharm:
--builder coverage --verbose --keep-going --conf-dir /Users/folkertmeeuw/cpython/Doc --doctree-dir /Users/folkertmeeuw/cpython/Doc/build/doctrees /Users/folkertmeeuw/cpython/Doc /Users/folkertmeeuw/cpython/Doc/build/coverage
creates c.txt, python.txt files.

Changes in conf.py for Terminal:

PYTHON       = python3
VENVDIR      = ./venv
SPHINXBUILD  = PATH=$(VENVDIR)/bin:$$PATH sphinx-build
BLURB        = PATH=$(VENVDIR)/bin:$$PATH blurb
JOBS         = auto
PAPER        =
SOURCES      = /Users/folkertmeeuw/cpython
DISTVERSION  = $(shell $(PYTHON) tools/extensions/patchlevel.py)
REQUIREMENTS = requirements.txt
SPHINXERRORHANDLING = -W

# Internal variables.
PAPEROPT_a4     = -D latex_elements.papersize=a4paper
PAPEROPT_letter = -D latex_elements.papersize=letterpaper

ALLSPHINXOPTS = --builder $(BUILDER) \
                --verbose \
                --keep-going \
                --jobs $(JOBS) \
                --conf-dir $(SOURCES)/Doc \
                --doctree-dir $(SOURCES)/Doc/build/doctrees \
                $(PAPEROPT_$(PAPER)) \
                $(SPHINXOPTS) $(SPHINXERRORHANDLING) \
                $(SOURCES)/Doc \
                $(SOURCES)/Doc/build/$(BUILDER)

creates c.txt, python.txt files, too.

Modules that failed to import:

 * _tkinter -- No module named '_tkinter'
 * dbm.sqlite3 -- No module named 'dbm.sqlite3'
 * encodings.mbcs -- cannot import name 'mbcs_encode' from 'codecs' (/opt/local/Library/Frameworks/Python.framework/Versions/3.12/lib/python3.12/codecs.py)
 * msvcrt -- No module named 'msvcrt'
 * sitecustomize -- No module named 'sitecustomize'
 * sys.monitoring -- No module named 'sys.monitoring'; 'sys' is not a package
 * turtle -- No module named '_tkinter'
 * usercustomize -- No module named 'usercustomize'
 * winreg -- No module named 'winreg'
 * winsound -- No module named 'winsound'

Possible is then

ALLSPHINXOPTS = --builder $(BUILDER) \
                --verbose \
                --jobs $(JOBS) \
                --conf-dir $(SOURCES)/Doc \
                --doctree-dir $(SOURCES)/Doc/build/doctrees \
                $(PAPEROPT_$(PAPER)) \
                $(SPHINXOPTS) $(SPHINXERRORHANDLING) \
                $(SOURCES)/Doc \
                $(SOURCES)/Doc/build/$(BUILDER)

in Makefile in combination with

coverage_ignore_modules = [
    r'[D|d][B|b][M|m]',
    r'[E|e][N|n]',
    r'[M|m][S|s][V|v]',
    r'[S|s][I|i][T|t][E|e]',
    r'[S|s][Y|y][S|s]',
    r'[T|t][K|k]',
    r'[_][T|t][K|k]',
    r'[T|t][U|u][R|r]',
    r'[U|u][S|s][E|e][R|r]',
    r'[W|w][I|i][N|n]',
]

in conf.py file.

Python 3.12 didn’t integrate the dbm.sqlite3, but it’s in 3.13.
Others are encoding, msvr, site, sys, turtle, and customizations. But that is probably too rough.

7

I’m sorry, I don’t understand what you have done or what you are trying to do.

8

Hi nedbat,

what do you think isn’t understandable what I do? I create the coverage for cpython documentation and use sphinx-build. I have had the described issue what confuses me and you too.

To get clear what sphinx-build is doing I debug it in PyCharm IDE, with the used parameters.
To get clear what sphinx-build is doing in terminal I change the used parameters in conf.py file in folder Doc/.

The python.txt file is one output and it showed among other things modules that failed to import.

And what are you doing ?

9

I see, thanks.