Building docs on Linux gives errors about ctypes.WINFUNCTYPE

[EdwardBetts]

• bleak version: 0.22.2
• Python version: 3.12
• Operating System: Debian GNU/Linux
• BlueZ version (bluetoothctl -v) in case of Linux: 5.73

Description

Building documentation on Linux produces errors when sphinx autodoc looks at bleak.backends.winrt.

I get this error.

AttributeError: module 'ctypes' has no attribute 'WINFUNCTYPE'. Did you mean: 'CFUNCTYPE'?

I suggest that sphinx autodoc be made to ignore bleak.backends.winrt when run on Linux to silence this error.

Logs

cd docs && LC_ALL=C.UTF-8 LANGUAGE=C.UTF-8 sphinx-build -b html -d _build/doctrees   . _build/html
Running Sphinx v7.4.7
loading translations [en]... done
making output directory... done
Converting `source_suffix = '.rst'` to `source_suffix = {'.rst': 'restructuredtext'}`.
building [mo]: targets for 0 po files that are out of date
writing output... 
building [html]: targets for 22 source files that are out of date
updating environment: [new config] 22 added, 0 changed, 0 removed
reading sources... [  5%] api/client
reading sources... [  9%] api/index
reading sources... [ 14%] api/scanner
reading sources... [ 18%] authors
reading sources... [ 23%] backends/android
reading sources... [ 27%] backends/index
reading sources... [ 32%] backends/linux
reading sources... [ 36%] backends/macos
reading sources... [ 41%] backends/windows
reading sources... [ 45%] bleak
reading sources... [ 50%] bleak.backends
reading sources... [ 55%] bleak.backends.bluezdbus
reading sources... [ 59%] bleak.backends.corebluetooth
reading sources... [ 64%] bleak.backends.p4android
reading sources... [ 68%] bleak.backends.winrt
reading sources... [ 73%] contributing
reading sources... [ 77%] history
reading sources... [ 82%] index
reading sources... [ 86%] installation
reading sources... [ 91%] modules
reading sources... [ 95%] troubleshooting
reading sources... [100%] usage

WARNING: autodoc: failed to import module 'util' from module 'bleak.backends.winrt'; the following exception was raised:
Traceback (most recent call last):
  File "/usr/lib/python3/dist-packages/sphinx/ext/autodoc/importer.py", line 143, in import_module
    return importlib.import_module(modname)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3.12/importlib/__init__.py", line 90, in import_module
    return _bootstrap._gcd_import(name[level:], package, level)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "<frozen importlib._bootstrap>", line 1387, in _gcd_import
  File "<frozen importlib._bootstrap>", line 1360, in _find_and_load
  File "<frozen importlib._bootstrap>", line 1331, in _find_and_load_unlocked
  File "<frozen importlib._bootstrap>", line 935, in _load_unlocked
  File "<frozen importlib._bootstrap_external>", line 995, in exec_module
  File "<frozen importlib._bootstrap>", line 488, in _call_with_frames_removed
  File "/home/edward/src/debian/python-modules/bleak/bleak/bleak/backends/winrt/util.py", line 34, in <module>
    _TIMERPROC = ctypes.WINFUNCTYPE(
                 ^^^^^^^^^^^^^^^^^^
AttributeError: module 'ctypes' has no attribute 'WINFUNCTYPE'. Did you mean: 'CFUNCTYPE'?

WARNING: autodoc: failed to import module 'scanner' from module 'bleak.backends.winrt'; the following exception was raised:
Traceback (most recent call last):
  File "/usr/lib/python3/dist-packages/sphinx/ext/autodoc/importer.py", line 143, in import_module
    return importlib.import_module(modname)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3.12/importlib/__init__.py", line 90, in import_module
    return _bootstrap._gcd_import(name[level:], package, level)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "<frozen importlib._bootstrap>", line 1387, in _gcd_import
  File "<frozen importlib._bootstrap>", line 1360, in _find_and_load
  File "<frozen importlib._bootstrap>", line 1331, in _find_and_load_unlocked
  File "<frozen importlib._bootstrap>", line 935, in _load_unlocked
  File "<frozen importlib._bootstrap_external>", line 995, in exec_module
  File "<frozen importlib._bootstrap>", line 488, in _call_with_frames_removed
  File "/home/edward/src/debian/python-modules/bleak/bleak/bleak/backends/winrt/scanner.py", line 7, in <module>
    from .util import assert_mta
  File "/home/edward/src/debian/python-modules/bleak/bleak/bleak/backends/winrt/util.py", line 34, in <module>
    _TIMERPROC = ctypes.WINFUNCTYPE(
                 ^^^^^^^^^^^^^^^^^^
AttributeError: module 'ctypes' has no attribute 'WINFUNCTYPE'. Did you mean: 'CFUNCTYPE'?

WARNING: autodoc: failed to import module 'client' from module 'bleak.backends.winrt'; the following exception was raised:
Traceback (most recent call last):
  File "/usr/lib/python3/dist-packages/sphinx/ext/autodoc/importer.py", line 143, in import_module
    return importlib.import_module(modname)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3.12/importlib/__init__.py", line 90, in import_module
    return _bootstrap._gcd_import(name[level:], package, level)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "<frozen importlib._bootstrap>", line 1387, in _gcd_import
  File "<frozen importlib._bootstrap>", line 1360, in _find_and_load
  File "<frozen importlib._bootstrap>", line 1331, in _find_and_load_unlocked
  File "<frozen importlib._bootstrap>", line 935, in _load_unlocked
  File "<frozen importlib._bootstrap_external>", line 995, in exec_module
  File "<frozen importlib._bootstrap>", line 488, in _call_with_frames_removed
  File "/home/edward/src/debian/python-modules/bleak/bleak/bleak/backends/winrt/client.py", line 116, in <module>
    from .scanner import BleakScannerWinRT
  File "/home/edward/src/debian/python-modules/bleak/bleak/bleak/backends/winrt/scanner.py", line 7, in <module>
    from .util import assert_mta
  File "/home/edward/src/debian/python-modules/bleak/bleak/bleak/backends/winrt/util.py", line 34, in <module>
    _TIMERPROC = ctypes.WINFUNCTYPE(
                 ^^^^^^^^^^^^^^^^^^
AttributeError: module 'ctypes' has no attribute 'WINFUNCTYPE'. Did you mean: 'CFUNCTYPE'?

[dlech]

I suggest that sphinx autodoc be made to ignore bleak.backends.winrt when run on Linux to silence this error.

It is set up like this already here and was working fine for years. So I suspect a bug in Sphinx. Also the readthedocs.org builds are passing and they run on Linux. So if we can find the difference between a setup that is failing and one that is passing, then we can find the source of the bug.

[EdwardBetts]

Thanks for looking into this. I missed the autodoc_mock_imports in docs/conf.py.

Maybe I'm passing the wrong arguments to sphinx. I'll investigate.

[dlech]

I've seen this error occasionally too, so I don't think it is just you. I just haven't had time to dig into it.

[dlech]

Maybe it is something that has changed in Python itself? readthedocs is using Python 3.9.19, so maybe the bug only happens with newer Python runtimes?