readthedocs / readthedocs/sphinx-autoapi
First overload of functions with multiple overloads in .pyi files fail to appear in resultant .html
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 494
- Forks
- 147
- Avg merge
- 9m
- Merged PRs (30d)
- 1
Description
When I set the following in conf.py:
autoapi_file_patterns = ['*.pyi']
autoapi correctly reads the annotations and documentation from stubs only. However, for many of my function signatures which make use of typing.overload, I notice that the signature overload that comes first, which originally had type annotations:
@overload
def foo[T=int](bar: str, /, *, baz: T=...) -> list[T]: ...
@overload
def foo[T](quux: int, /, *, baz: T) -> set[T]: ...
renders to the following:
foo[T=int](bar, /, *, baz) [source]
foo(quux: int, /, *, baz: T) -> set[T]
Real example from my own library, with html output
Input:
# asyncutils/iters.pyi
from ._internal.protocols import SupportsIteration
from _collections_abc import AsyncGenerator
@overload
def agroupby[T](it: SupportsIteration[T], key: Callable[[T], T]=...) -> AsyncGenerator[tuple[T, AsyncGenerator[T, None]], None]: ...
@overload
def agroupby[T, R](it: SupportsIteration[T], key: Callable[[T], R]) -> AsyncGenerator[tuple[R, AsyncGenerator[T, None]], None]: ...
Output:
- asyncutils.iters.agroupby[T](it, key=...)[source]
- asyncutils.iters.agroupby(it: asyncutils._internal.protocols.SupportsIteration[T], key: _collections_abc.Callable[[T], R]) → _collections_abc.AsyncGenerator[tuple[R, _collections_abc.AsyncGenerator[T, None]], None]
Contributor guide
No contributing guide indexed for this repository
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
Start by reproducing the issue with autoapi_file_patterns in conf.py and the overloads from asyncutils/iters.pyi. Trace how .pyi overload signatures are collected and rendered, focusing on why the first overload loses annotations. Done means the first overload appears in the generated HTML with its type parameters, annotations, defaults, and return type preserved.
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
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100