Warning (and mildly inelegant output) from pdoc when using a type defined using a type alias
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 2.5k
- Forks
- 228
- PR merge metrics
- No merged PRs in 30d
Description
Problem Description
Using a type defined using a type alias produces a warning message and uses ForwardRef('TheType') in documentation output instead of the correct TheType.
Sample code:
from __future__ import annotations
from typing import NamedTuple
import numpy
from numpy.typing import NDArray
type Array = NDArray[numpy.float64]
class ArrayThing(NamedTuple):
data: Array
This triggers the following warning when running pdoc:
$ PDOC_ALLOW_EXEC=1 uv run --quiet --locked pdoc -d google -o docs --math foo
Warn: Error parsing type annotation ForwardRef('Array') for foo.foo.ArrayThing.__init__. Import of Array failed: name 'Array' is not defined (/home/me/pdoc_test/.venv/lib/python3.13/site-packages/pdoc/doc_types.py:148)
The output is usable but slightly verbose (it includes the ForwardRef instead of directly naming the type which has been defined:
Steps to reproduce the behavior:
- Run pdoc on the python source defined above!
System Information
$ PDOC_ALLOW_EXEC=1 uv run --quiet --locked pdoc -d google -o docs --math --version
pdoc: 15.0.4
Python: 3.13.1
Platform: Linux-5.15.167.4-microsoft-standard-WSL2-x86_64-with-glibc2.36
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
Reproduce the report with the supplied Python 3.13 type-alias example and the documented pdoc command. Then inspect pdoc/doc_types.py around the reported annotation-parsing location; the work is done when the warning is gone and the generated documentation names Array directly instead of showing ForwardRef('Array').
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
- 48/100