Sphinx Build Error: ... can only concatenate str (not "__qualname__") to str

[askpatrickw]

This happen on main as well as in my PR branch.

sphinx.errors.SphinxWarning: error while formatting arguments for adafruit_azureiot.IoTCentralDevice: can only concatenate str (not "__qualname__") to str

No idea... searching the internet was no help.

verbose

sphinx-build -E -W -b html . _build/html -v
Running Sphinx v4.4.0
loading intersphinx inventory from https://docs.python.org/3.4/objects.inv...
loading intersphinx inventory from https://circuitpython.readthedocs.io/en/latest/objects.inv...
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 3 source files that are out of date
updating environment: [new config] 3 added, 0 changed, 0 removed
reading sources... [ 33%] api
reading sources... [ 66%] examples
reading sources... [100%] index

Traceback (most recent call last):
  File "/Users/menotyou/.pyenv/versions/3.9.7/envs/cp_base/lib/python3.9/site-packages/sphinx/cmd/build.py", line 284, in build_main
    app.build(args.force_all, filenames)
  File "/Users/menotyou/.pyenv/versions/3.9.7/envs/cp_base/lib/python3.9/site-packages/sphinx/application.py", line 337, in build
    self.builder.build_update()
  File "/Users/menotyou/.pyenv/versions/3.9.7/envs/cp_base/lib/python3.9/site-packages/sphinx/builders/__init__.py", line 294, in build_update
    self.build(to_build,
  File "/Users/menotyou/.pyenv/versions/3.9.7/envs/cp_base/lib/python3.9/site-packages/sphinx/builders/__init__.py", line 308, in build
    updated_docnames = set(self.read())
  File "/Users/menotyou/.pyenv/versions/3.9.7/lib/python3.9/contextlib.py", line 126, in __exit__
    next(self.gen)
  File "/Users/menotyou/.pyenv/versions/3.9.7/envs/cp_base/lib/python3.9/site-packages/sphinx/util/logging.py", line 225, in pending_warnings
    memhandler.flushTo(logger)
  File "/Users/menotyou/.pyenv/versions/3.9.7/envs/cp_base/lib/python3.9/site-packages/sphinx/util/logging.py", line 190, in flushTo
    logger.handle(record)
  File "/Users/menotyou/.pyenv/versions/3.9.7/lib/python3.9/logging/__init__.py", line 1599, in handle
    self.callHandlers(record)
  File "/Users/menotyou/.pyenv/versions/3.9.7/lib/python3.9/logging/__init__.py", line 1661, in callHandlers
    hdlr.handle(record)
  File "/Users/menotyou/.pyenv/versions/3.9.7/lib/python3.9/logging/__init__.py", line 948, in handle
    rv = self.filter(record)
  File "/Users/menotyou/.pyenv/versions/3.9.7/lib/python3.9/logging/__init__.py", line 806, in filter
    result = f.filter(record)
  File "/Users/menotyou/.pyenv/versions/3.9.7/envs/cp_base/lib/python3.9/site-packages/sphinx/util/logging.py", line 433, in filter
    raise exc
sphinx.errors.SphinxWarning: error while formatting arguments for adafruit_azureiot.IoTCentralDevice: can only concatenate str (not "__qualname__") to str

Warning, treated as error:
error while formatting arguments for adafruit_azureiot.IoTCentralDevice: can only concatenate str (not "__qualname__") to str

[askpatrickw]

If I remove__all__ from the adafruit_azureiot/__init__.py, the docs build fine.

__all__ = ["IoTHubDevice", "IoTCentralDevice", "IoTResponse", "IoTError"]

[askpatrickw]

It also builds if I change __all__ to use the full dot notation.

__all__ = [
    "adafruit_azureiot.IoTCentralDevice",
    "adafruit_azureiot.IoTHubDevice",
    "adafruit_azureiotIoTResponse",
    "adafruit_azureiot.IoTError",
]

But then pre-commit is angry.

************* Module adafruit_azureiot
adafruit_azureiot/__init__.py:43:4: E0603: Undefined variable name 'adafruit_azureiot.IoTCentralDevice' in __all__ (undefined-all-variable)
adafruit_azureiot/__init__.py:44:4: E0603: Undefined variable name 'adafruit_azureiot.IoTHubDevice' in __all__ (undefined-all-variable)
adafruit_azureiot/__init__.py:45:4: E0603: Undefined variable name 'adafruit_azureiotIoTResponse' in __all__ (undefined-all-variable)
adafruit_azureiot/__init__.py:46:4: E0603: Undefined variable name 'adafruit_azureiot.IoTError' in __all__ (undefined-all-variable)

[askpatrickw]

One final comment....

I also tried removing the __ALL__ and using automodule entries in api.rst for each module and then I got back to the same error as the beginning.

This leads me to believe there's something wrong with the docstrings.

[askpatrickw]

I worked around this by rolling Sphinx back to 4.3.2 in my branch. I opened a bug in the Sphinx repo https://github.com/sphinx-doc/sphinx/issues/10133

[FoamyGuy]

I think the logging type provided here: https://github.com/adafruit/Adafruit_CircuitPython_AzureIoT/blob/fe80aad45d74881cd26ece5ef0bd74dc78eeaaaf/adafruit_azureiot/iotcentral_device.py#L91

and here: https://github.com/adafruit/Adafruit_CircuitPython_AzureIoT/blob/fe80aad45d74881cd26ece5ef0bd74dc78eeaaaf/adafruit_azureiot/iothub_device.py#L138

are potentially leading to this issue. I noticed that I can build the docs successfully on sphinx 4.4.0 if I remove those type hints.

I think maybe those types should be Logger but it may be complicated a bit by the fact that adafruit_logging library is not published to PyPi, so the actions container is not going to be able to download it using the normal method atm.

[FoamyGuy]

As a short term fix I think it may be easiest to remove the type hint from those arguments for now. I think the actions container is going to need access to adafruit_logging library in order to fill in any sort of meaningful typing info from it and we'll need to get that published to PyPi in order for that to happen as far as I konw.

[FoamyGuy]

To test this theory I manually copied adafruit_logging to my site-packages directory and after doing that I am able to get a successful sphinx build on 4.4.0 also if I add this import:

from adafruit_logging import Logger

and change the type hint to be like this:

logger: Logger = None,

[askpatrickw]

I'll modify the logging in my PR as suggested. Thanks @FoamyGuy!

[askpatrickw]

Thanks @FoamyGuy that seems to have done the trick. They're also fixing this in Sphinx as well, the explanation was interesting.