Support for overloads

[chadrik]

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]"
    }
  }
]