adafruit / adafruit/Adafruit_CircuitPython_BLE_File_Transfer

Docs build broken

Open
#29 1 comment 0 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
28
Forks
5
PR merge metrics
No merged PRs in 30d

Description

When I build the docs locally I first got a failure due to `_bleio` module not found.

I added that to the mock list which got me past that error.

But now the build is failing with this error:
```
WARNING: autodoc: failed to import module 'adafruit_ble_file_transfer'; the following exception was raised:
Traceback (most recent call last):
File ".cpy_venv/lib/python3.12/site-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 "", line 1387, in _gcd_import
File "", line 1360, in _find_and_load
File "", line 1331, in _find_and_load_unlocked
File "", line 935, in _load_unlocked
File "", line 995, in exec_module
File "", line 488, in _call_with_frames_removed
File "Adafruit_CircuitPython_BLE_File_Transfer/adafruit_ble_file_transfer.py", line 76, in
class FileTransferService(Service):
File "Adafruit_CircuitPython_BLE_File_Transfer/adafruit_ble_file_transfer.py", line 86, in FileTransferService
raw = _TransferCharacteristic()
^^^^^^^^^^^^^^^^^^^^^^^^^
File "Adafruit_CircuitPython_BLE_File_Transfer/adafruit_ble_file_transfer.py", line 59, in __init__
properties=Characteristic.WRITE_NO_RESPONSE
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
TypeError: unsupported operand type(s) for |: 'WRITE_NO_RESPONSE' and 'READ'
[autodoc.import_object]
```

Which appears to take issue with these lines: https://github.com/adafruit/Adafruit_CircuitPython_BLE_File_Transfer/blob/df30c3c42464bb961b3484a203352af4d6d64edd/adafruit_ble_file_transfer.py#L59-L61

`Characteristic.WRITE_NO_RESPONSE`, `Characteristic.READ` and `Characteristic.NOTIFY` are all ints if you follow them to their value, though they do go through some intermediary classes.

In a python 3.12 REPL I am able to bitwise OR the values wtihout issue:
```
Characteristic.NOTIFY | Characteristic.READ | Characteristic.WRITE_NO_RESPONSE
44
```
I'm not sure why sphinx / autodoc import is failing to do so.

Contributor guide

No contributing guide indexed for this repository

Research direction

Reproduce the local documentation build with Python 3.12 and inspect the Sphinx autodoc import failure for adafruit_ble_file_transfer. Start with adafruit_ble_file_transfer.py lines 59–61, especially the Characteristic flag values, and trace the intermediary classes mentioned in the report. Done means the documentation build imports the module without this TypeError or autodoc warning.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.