readthedocs / readthedocs/sphinx-autoapi

First overload of functions with multiple overloads in .pyi files fail to appear in resultant .html

Open
#557 2 comments 0 reactions 0 assignees View on GitHub

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

  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

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.