Add support for overloaded functions

.pre-commit-config.yaml

@@ -1,11 +1,15 @@
 repos:
--   repo: https://github.com/ambv/black
-    rev: 18.9b0
-    hooks:
-    - id: black
-      language_version: python3.6
+-   repo: https://github.com/psf/black
+    rev: 19.10b0
+    hooks:
+      - id: black
+        language_version: python3
+-   repo: https://github.com/PyCQA/pylint
+    rev: 'pylint-2.5.3'
+    hooks:
+      - id: pylint
 -   repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v1.2.3
+    rev: v3.1.0
     hooks:
-    -   id: trailing-whitespace
-    -   id: end-of-file-fixer
+      - id: trailing-whitespace
+      - id: end-of-file-fixer

autoapi/directives.py

@@ -20,9 +20,12 @@ def get_items(self, names):
         for name in names:
             obj = mapper.all_objects[name]
             if isinstance(obj, PythonFunction):
-                sig = "({})".format(obj.args)
-                if obj.return_annotation is not None:
-                    sig += " -> {}".format(obj.return_annotation)
+                if len(obj.signatures) > 1:
+                    sig = "(\u2026)"
+                else:
+                    sig = "({})".format(obj.args)
+                    if obj.return_annotation is not None:
+                        sig += " \u2192 {}".format(obj.return_annotation)
             else:
                 sig = ""
 

autoapi/mappers/python/astroid_utils.py

@@ -275,6 +275,42 @@ def is_decorated_with_property_setter(node):
     return False
 
 
+def is_decorated_with_overload(node):
+    """Check if the function is decorated as an overload definition.
+
+    :param node: The node to check.
+    :type node: astroid.nodes.FunctionDef
+
+    :returns: True if the function is an overload definition, False otherwise.
+    :rtype: bool
+    """
+    if not node.decorators:
+        return False
+
+    for decorator in node.decorators.nodes:
+        if not isinstance(decorator, (astroid.Name, astroid.Attribute)):
+            continue
+
+        try:
+            if _is_overload_decorator(decorator):
+                return True
+        except astroid.InferenceError:
+            pass
+
+    return False
+
+
+def _is_overload_decorator(decorator):
+    for inferred in decorator.infer():
+        if not isinstance(inferred, astroid.nodes.FunctionDef):
+            continue
+
+        if inferred.name == "overload" and inferred.root().name == "typing":
+            return True
+
+    return False
+
+
 def is_constructor(node):
     """Check if the function is a constructor.
 

autoapi/mappers/python/objects.py

@@ -183,6 +183,14 @@ def __init__(self, obj, **kwargs):
 
         :type: list(str)
         """
+        self.signatures = obj["signatures"]
+        """The list of all signatures ``[(args, return_annotation), ...]`` of this function.
+
+        When this function is not overloaded,
+        it must be the same as ``[(self.args, self.return_annotation)]``.
+
+        :type: list(tuple(str, str))
+        """
 
 
 class PythonMethod(PythonFunction):

autoapi/mappers/python/parser.py

@@ -98,7 +98,7 @@ def parse_assign(self, node):
 
         return [data]
 
-    def parse_classdef(self, node, data=None):
+    def parse_classdef(self, node, data=None):  # pylint: disable=too-many-branches
         type_ = "class"
         if astroid_utils.is_exception(node):
             type_ = "exception"
@@ -127,8 +127,11 @@ def parse_classdef(self, node, data=None):
         }
 
         self._name_stack.append(node.name)
-        seen = set()
+        overridden = set()
+        overloads = {}
+        # pylint: disable=too-many-nested-blocks
         for base in itertools.chain(iter((node,)), node.ancestors()):
+            seen = set()
             if base.qname() in ("__builtins__.object", "builtins.object"):
                 continue
             for child in base.get_children():
@@ -138,14 +141,42 @@ def parse_classdef(self, node, data=None):
                     if not assign_value:
                         continue
                     name = assign_value[0]
-                if not name or name in seen:
+
+                if not name or name in overridden:
                     continue
                 seen.add(name)
                 child_data = self.parse(child)
-                if child_data:
-                    for single_data in child_data:
-                        single_data["inherited"] = base is not node
-                    data["children"].extend(child_data)
+
+                for single_data in child_data:
+                    if single_data["type"] in ("method", "property"):
+                        if name in overloads:
+                            grouped = overloads[name]
+                            if single_data["doc"]:
+                                grouped["doc"] += "\n\n" + single_data["doc"]
+                            if single_data["is_overload"]:
+                                grouped["signatures"].append(
+                                    (
+                                        single_data["args"],
+                                        single_data["return_annotation"],
+                                    )
+                                )
+                            else:
+                                grouped["args"] = single_data["args"]
+                                grouped["return_annotation"] = single_data[
+                                    "return_annotation"
+                                ]
+                            continue
+                        if single_data["is_overload"] and name not in overloads:
+                            overloads[name] = single_data
+                        single_data["signatures"] = [
+                            (single_data["args"], single_data["return_annotation"])
+                        ]
+
+                    single_data["inherited"] = base is not node
+                    data["children"].append(single_data)
+
+            overridden.update(seen)
+
         self._name_stack.pop()
 
         return [data]
@@ -159,6 +190,7 @@ def parse_functiondef(self, node):  # pylint: disable=too-many-branches
 
         type_ = "method"
         properties = []
+
         if node.type == "function":
             type_ = "function"
         elif astroid_utils.is_decorated_with_property(node):
@@ -193,6 +225,7 @@ def parse_functiondef(self, node):  # pylint: disable=too-many-branches
             "to_line_no": node.tolineno,
             "return_annotation": return_annotation,
             "properties": properties,
+            "is_overload": astroid_utils.is_decorated_with_overload(node),
         }
 
         if type_ in ("method", "property"):
@@ -249,15 +282,38 @@ def parse_module(self, node):
             "all": astroid_utils.get_module_all(node),
         }
 
+        overloads = {}
         top_name = node.name.split(".", 1)[0]
         for child in node.get_children():
             if astroid_utils.is_local_import_from(child, top_name):
                 child_data = self._parse_local_import_from(child)
             else:
                 child_data = self.parse(child)
 
-            if child_data:
-                data["children"].extend(child_data)
+            for single_data in child_data:
+                if single_data["type"] == "function":
+                    name = single_data["name"]
+                    if name in overloads:
+                        grouped = overloads[name]
+                        if single_data["doc"]:
+                            grouped["doc"] += "\n\n" + single_data["doc"]
+                        if single_data["is_overload"]:
+                            grouped["signatures"].append(
+                                (single_data["args"], single_data["return_annotation"])
+                            )
+                        else:
+                            grouped["args"] = single_data["args"]
+                            grouped["return_annotation"] = single_data[
+                                "return_annotation"
+                            ]
+                        continue
+                    if single_data["is_overload"] and name not in overloads:
+                        overloads[name] = single_data
+                    single_data["signatures"] = [
+                        (single_data["args"], single_data["return_annotation"])
+                    ]
+
+                data["children"].append(single_data)
 
         return data
 
@@ -273,5 +329,4 @@ def parse(self, node):
                 data = self.parse(child)
                 if data:
                     break
-
         return data

autoapi/templates/python/function.rst

@@ -1,6 +1,13 @@
 {% if obj.display %}
-.. function:: {{ obj.short_name }}({{ obj.args }}){% if obj.return_annotation is not none %} -> {{ obj.return_annotation }}{% endif %}
+{% for (args, return_annotation) in obj.signatures %}
+{% if loop.index0 == 0 %}
+.. function:: {{ obj.short_name }}({{ args }}){% if return_annotation is not none %} -> {{ return_annotation }}{% endif %}
 
+{% else %}
+              {{ obj.short_name }}({{ args }}){% if return_annotation is not none %} -> {{ return_annotation }}{% endif %}
+
+{% endif %}
+{% endfor %}
    {% if sphinx_version >= (2, 1) %}
    {% for property in obj.properties %}
    :{{ property }}:

autoapi/templates/python/method.rst

@@ -1,19 +1,33 @@
 {%- if obj.display %}
 {% if sphinx_version >= (2, 1) %}
-.. method:: {{ obj.short_name }}({{ obj.args }}){% if obj.return_annotation is not none %} -> {{ obj.return_annotation }}{% endif %}
-   {% if obj.properties %}
+{% for (args, return_annotation) in obj.signatures %}
+{% if loop.index0 == 0 %}
+.. method:: {{ obj.short_name }}({{ args }}){% if return_annotation is not none %} -> {{ return_annotation }}{% endif %}
+
+{% else %}
+            {{ obj.short_name }}({{ args }}){% if return_annotation is not none %} -> {{ return_annotation }}{% endif %}
 
+{% endif %}
+{% endfor %}
+   {% if obj.properties %}
    {% for property in obj.properties %}
    :{{ property }}:
    {% endfor %}
+
    {% else %}
 
    {% endif %}
 {% else %}
-.. {{ obj.method_type }}:: {{ obj.short_name }}({{ obj.args }})
+{% for (args, return_annotation) in obj.signatures %}
+{% if loop.index0 == 0 %}
+.. {{ obj.method_type }}:: {{ obj.short_name }}({{ args }})
 
-{% endif %}
+{% else %}
+                        :: {{ obj.short_name }}({{ args }})
 
+{% endif %}
+{% endfor %}
+{% endif %}
    {% if obj.docstring %}
    {{ obj.docstring|prepare_docstring|indent(3) }}
    {% endif %}

tests/python/py3example/example/example.py

@@ -4,7 +4,8 @@
 This is a description
 """
 import asyncio
-from typing import ClassVar, Dict, Iterable, List, Union
+import typing
+from typing import ClassVar, Dict, Iterable, List, Union, overload
 
 max_rating: int = 10
 
@@ -35,7 +36,33 @@ def f2(not_yet_a: "A") -> int:
     ...
 
 
+@overload
+def overloaded_func(a: float) -> float:
+    ...
+
+
+@typing.overload
+def overloaded_func(a: str) -> str:
+    ...
+
+
+def overloaded_func(a: Union[float, str]) -> Union[float, str]:
+    """Overloaded function"""
+    return a * 2
+
+
+@overload
+def undoc_overloaded_func(a: str) -> str:
+    ...
+
+
+def undoc_overloaded_func(a: str) -> str:
+    return a * 2
+
+
 class A:
+    """class A"""
+
     is_an_a: ClassVar[bool] = True
     not_assigned_to: ClassVar[str]
 
@@ -57,6 +84,40 @@ def my_method(self) -> str:
         """My method."""
         return "method"
 
+    @overload
+    def overloaded_method(self, a: float) -> float:
+        ...
+
+    @typing.overload
+    def overloaded_method(self, a: str) -> str:
+        ...
+
+    def overloaded_method(self, a: Union[float, str]) -> Union[float, str]:
+        """Overloaded method"""
+        return a * 2
+
+    @overload
+    def undoc_overloaded_method(self, a: float) -> float:
+        ...
+
+    def undoc_overloaded_method(self, a: float) -> float:
+        return a * 2
+
+    @typing.overload
+    @classmethod
+    def overloaded_class_method(cls, a: float) -> float:
+        ...
+
+    @overload
+    @classmethod
+    def overloaded_class_method(cls, a: str) -> str:
+        ...
+
+    @classmethod
+    def overloaded_class_method(cls, a: Union[float, str]) -> Union[float, str]:
+        """Overloaded class method"""
+        return a * 2
+
 
 async def async_function(self, wait: bool) -> int:
     if wait: