Parse error when attempting to document a type alias `MapType = dict[str, float]`
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 355
- Forks
- 181
- Avg merge
- 1d 9h
- Merged PRs (30d)
- 3
Description
When documenting with sphinx, sphinx.ext.autodoc and numpydoc the following type alias:
MapType = dict[str, float]
"""Alias for a dictionary of strings to floats"""
yields this error (truncated full below):
type_aliases.py:docstring of builtins.dict:9: WARNING: autosummary: failed to import clear.
Possible hints:
* ModuleNotFoundError: No module named 'repro_1956.type_aliases.clear'; 'repro_1956.type_aliases' is not a package
* ModuleNotFoundError: No module named 'clear'
* KeyError: 'clear'
* ValueError: not enough values to unpack (expected 2, got 1)
* AttributeError: module 'repro_1956.type_aliases' has no attribute 'clear'
However changing the alias to typing.Dict[str, float] avoids the error, as does disabling the numpydoc extension for sphinx. The problem appears to be that when the alias is dict[str, float] it attempts to document the dict class, as the partial documentation generated documents the dict.copy method.
Issue was originally observed with the following versions:
- Python 3.10
- numpydoc 1.5.0
- sphinx 4.5.0
And reproduced with versions:
- Python 3.10
- numpydoc 1.8.0
- sphinx==8.1.0
Full repro at https://github.com/dagardner-nv/repro_1956
Repro:
- Clone https://github.com/dagardner-nv/repro_1956
- Run the following commands:
cd repro_1956
pip install -r requirements.txt
make html
Full output:
$ make html
Running Sphinx v8.1.0
loading translations [en]... done
making output directory... done
[autosummary] generating autosummary for: index.rst
building [mo]: targets for 0 po files that are out of date
writing output...
building [html]: targets for 1 source files that are out of date
updating environment: [new config] 1 added, 0 changed, 0 removed
reading sources... [100%] index
/home/dagardner/work/repro_1956/src/repro_1956/type_aliases.py:docstring of builtins.dict:9: WARNING: autosummary: failed to import clear.
Possible hints:
* ModuleNotFoundError: No module named 'repro_1956.type_aliases.clear'; 'repro_1956.type_aliases' is not a package
* ModuleNotFoundError: No module named 'clear'
* KeyError: 'clear'
* ValueError: not enough values to unpack (expected 2, got 1)
* AttributeError: module 'repro_1956.type_aliases' has no attribute 'clear'
/home/dagardner/work/repro_1956/src/repro_1956/type_aliases.py:docstring of builtins.dict:9: WARNING: autosummary: failed to import fromkeys.
Possible hints:
* KeyError: 'fromkeys'
* AttributeError: module 'repro_1956.type_aliases' has no attribute 'fromkeys'
* ModuleNotFoundError: No module named 'fromkeys'
* ValueError: not enough values to unpack (expected 2, got 1)
* ModuleNotFoundError: No module named 'repro_1956.type_aliases.fromkeys'; 'repro_1956.type_aliases' is not a package
/home/dagardner/work/repro_1956/src/repro_1956/type_aliases.py:docstring of builtins.dict:9: WARNING: autosummary: failed to import get.
Possible hints:
* ModuleNotFoundError: No module named 'repro_1956.type_aliases.get'; 'repro_1956.type_aliases' is not a package
* ValueError: not enough values to unpack (expected 2, got 1)
* ModuleNotFoundError: No module named 'get'
* KeyError: 'get'
* AttributeError: module 'repro_1956.type_aliases' has no attribute 'get'
/home/dagardner/work/repro_1956/src/repro_1956/type_aliases.py:docstring of builtins.dict:9: WARNING: autosummary: failed to import items.
Possible hints:
* KeyError: 'items'
* ModuleNotFoundError: No module named 'items'
* ModuleNotFoundError: No module named 'repro_1956.type_aliases.items'; 'repro_1956.type_aliases' is not a package
* ValueError: not enough values to unpack (expected 2, got 1)
* AttributeError: module 'repro_1956.type_aliases' has no attribute 'items'
/home/dagardner/work/repro_1956/src/repro_1956/type_aliases.py:docstring of builtins.dict:9: WARNING: autosummary: failed to import keys.
Possible hints:
* ModuleNotFoundError: No module named 'keys'
* AttributeError: module 'repro_1956.type_aliases' has no attribute 'keys'
* ModuleNotFoundError: No module named 'repro_1956.type_aliases.keys'; 'repro_1956.type_aliases' is not a package
* KeyError: 'keys'
* ValueError: not enough values to unpack (expected 2, got 1)
/home/dagardner/work/repro_1956/src/repro_1956/type_aliases.py:docstring of builtins.dict:9: WARNING: autosummary: failed to import pop.
Possible hints:
* ModuleNotFoundError: No module named 'pop'
* KeyError: 'pop'
* ValueError: not enough values to unpack (expected 2, got 1)
* AttributeError: module 'repro_1956.type_aliases' has no attribute 'pop'
* ModuleNotFoundError: No module named 'repro_1956.type_aliases.pop'; 'repro_1956.type_aliases' is not a package
/home/dagardner/work/repro_1956/src/repro_1956/type_aliases.py:docstring of builtins.dict:9: WARNING: autosummary: failed to import popitem.
Possible hints:
* AttributeError: module 'repro_1956.type_aliases' has no attribute 'popitem'
* ModuleNotFoundError: No module named 'popitem'
* ModuleNotFoundError: No module named 'repro_1956.type_aliases.popitem'; 'repro_1956.type_aliases' is not a package
* ValueError: not enough values to unpack (expected 2, got 1)
* KeyError: 'popitem'
/home/dagardner/work/repro_1956/src/repro_1956/type_aliases.py:docstring of builtins.dict:9: WARNING: autosummary: failed to import setdefault.
Possible hints:
* AttributeError: module 'repro_1956.type_aliases' has no attribute 'setdefault'
* ValueError: not enough values to unpack (expected 2, got 1)
* ModuleNotFoundError: No module named 'setdefault'
* KeyError: 'setdefault'
* ModuleNotFoundError: No module named 'repro_1956.type_aliases.setdefault'; 'repro_1956.type_aliases' is not a package
/home/dagardner/work/repro_1956/src/repro_1956/type_aliases.py:docstring of builtins.dict:9: WARNING: autosummary: failed to import update.
Possible hints:
* KeyError: 'update'
* ModuleNotFoundError: No module named 'repro_1956.type_aliases.update'; 'repro_1956.type_aliases' is not a package
* ModuleNotFoundError: No module named 'update'
* ValueError: not enough values to unpack (expected 2, got 1)
* AttributeError: module 'repro_1956.type_aliases' has no attribute 'update'
/home/dagardner/work/repro_1956/src/repro_1956/type_aliases.py:docstring of builtins.dict:9: WARNING: autosummary: failed to import values.
Possible hints:
* ModuleNotFoundError: No module named 'repro_1956.type_aliases.values'; 'repro_1956.type_aliases' is not a package
* ValueError: not enough values to unpack (expected 2, got 1)
* AttributeError: module 'repro_1956.type_aliases' has no attribute 'values'
* ModuleNotFoundError: No module named 'values'
* KeyError: 'values'
/home/dagardner/work/repro_1956/src/repro_1956/type_aliases.py:docstring of builtins.dict:9: WARNING: autosummary: stub file not found 'copy'. Check your autosummary_generate setting.
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
copying assets...
copying static files...
Writing evaluated template result to /home/dagardner/work/repro_1956/build/html/_static/basic.css
Writing evaluated template result to /home/dagardner/work/repro_1956/build/html/_static/language_data.js
Writing evaluated template result to /home/dagardner/work/repro_1956/build/html/_static/documentation_options.js
Writing evaluated template result to /home/dagardner/work/repro_1956/build/html/_static/js/versions.js
copying static files: done
copying extra files...
copying extra files: done
copying assets: done
writing output... [100%] index
generating indices... genindex py-modindex done
writing additional pages... search done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded, 11 warnings.
The HTML pages are in build/html.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Use the linked repro repository, starting with src/repro_1956/type_aliases.py and the Sphinx configuration referenced by its make html build. Install requirements.txt and run make html to reproduce the autosummary warnings for the built-in dict methods. Done means the documented dict[str, float] alias no longer triggers those warnings while the documentation build completes correctly.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 52/100