numpy / numpy/numpydoc

Parse error when attempting to document a type alias `MapType = dict[str, float]`

Open
#587 0 comments 0 reactions 0 assignees View on GitHub

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:

  1. Clone https://github.com/dagardner-nv/repro_1956
  2. 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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.