Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

Support for overloads

Open
  • Is something wrong?
#102 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
42/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Stale
Tech stack
python
Domain
tooling

Research direction

No source files, tests, or entry points are named in the issue. Start by tracing how pyannotate currently consumes signature data and writes .py versus .pyi files; implement the proposed overloads behavior for both formats and verify generated output against the JSON example.

Written by the indexing model from the issue text.

Description

I've written a tool that extracts signature data for a C extension from doxygen xml files, and I have stubs that I created using mypy's stubgen, and I'd like to use pyannotate to combine the two. In order to do that I need pyannotate to support @overloads.

I'm happy to make the PR for this.

I was thinking that we can add support for a "overloads" key that contains a list of signature data. The behavior will be slightly different depending on whether the target file is a .py or .pyi

  • For .py files: If the "overloads" key is present, a new @overload function will be created for each entry. If the "signature" key is present, it will be applied to the target function (this means in the presence of "overloads", "signature" is optional)
  • For .pyi files: If the "overloads" key is present, a new @overload function will be created for each entry, and the target function will be deleted (we assume the target function represents the "real" function, which is superseded by overloads, and may have a completely different arg signature than the overloads. This means we assume the list of overloads is complete, not sparse). The "signature" key will always be ignored.

Here's an example json file:

[
  {
    "func_name": "my_command",
    "line": 16,
    "path": "/Users/chad/dev/mymodule.py",
    "samples": 0,
    "overloads": [
      {
        "arg_types": [
          "str"
        ],
        "return_type": "str"
      },
      {
        "arg_types": [
          "int"
        ],
        "return_type": "None"
      }
    ],
    "signature": {
      "arg_types": [
        "Union[str, int]"
      ],
      "return_type": "Optional[str]"
    }
  }
]
Dominant language
Python
Stars
1.4k
Forks
59
No merged PRs in 30d

Getting set up

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.

More from dropbox/pyannotate

All issues in dropbox/pyannotate

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.