Python APIView High-Pri Fixes (#6462)

* Add new token kinds.

* Update to use link token type.

* Fixes #6360.

* Revert overload fix.

* Fixes #6367.

* Update changelog

* Fix tests.

packages/python-packages/apiview-stub-generator/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Release History
 
+## Version 0.3.8 (2023-07-06)
+Display `--source-url` as an actual clickable link.
+Fix issue with line ids in diffs so that the entire signature doesn't turn red if something is changed. 
+
 ## Version 0.3.7 (2023-03-09)
 Fix incorrect type annotation.
 Update to follow best practices for accessing '__annotations__'.

packages/python-packages/apiview-stub-generator/apistub/_apiview.py

@@ -3,6 +3,7 @@
 import re
 import os
 import platform
+from typing import Optional
 
 from ._node_index import NodeIndex
 from ._token import Token
@@ -57,7 +58,8 @@ def __init__(self, *, pkg_name="", namespace = "", metadata_map=None, source_url
         self.add_line_marker("GLOBAL")
         if source_url:
             self.set_blank_lines(1)
-            self.add_literal(f"# Source URL: {source_url}")
+            self.add_literal("# Source URL: ")
+            self.add_link(source_url)
         self.add_token(Token("", TokenKind.SkipDiffRangeEnd))
         self.set_blank_lines(2)
 
@@ -73,10 +75,10 @@ def end_group(self):
         """End current group by moving indent to left
         """
         if not self.indent:
-            raise ValueError("Invalid intendation")
+            raise ValueError("Invalid indentation")
         self.indent -= 1
 
-    def add_whitespace(self, count: int = None):
+    def add_whitespace(self, count: Optional[int] = None):
         """ Inject appropriate whitespace for indentation,
             or inject a specific number of whitespace characters.
         """
@@ -86,7 +88,7 @@ def add_whitespace(self, count: int = None):
             self.add_token(Token(" " * (count)))
 
     def add_space(self):
-        """ Used to add a single space. Cannot add mutliple spaces.
+        """ Used to add a single space. Cannot add multiple spaces.
         """
         if self.tokens[-1].kind != TokenKind.Whitespace:
             self.add_token(Token(" ", TokenKind.Whitespace))
@@ -158,7 +160,7 @@ def add_type(self, type_name, line_id=None):
 
         type_name = type_name.replace(":class:", "")
         logging.debug("Processing type {}".format(type_name))
-        # Check if multiple types are listed with 'or' seperator
+        # Check if multiple types are listed with 'or' separator
         # Encode multiple types with or separator into Union
         if TYPE_OR_SEPARATOR in type_name:
             types = [t.strip() for t in type_name.split(TYPE_OR_SEPARATOR) if t != TYPE_OR_SEPARATOR]
@@ -167,6 +169,10 @@ def add_type(self, type_name, line_id=None):
 
         self._add_type_token(type_name, line_id)
 
+    def add_link(self, url):
+        self.add_token(Token(url, TokenKind.ExternalLinkStart))
+        self.add_token(Token(url))
+        self.add_token(Token(kind=TokenKind.ExternalLinkEnd))
 
     def _add_token_for_type_name(self, type_name, line_id = None):
         logging.debug("Generating tokens for type name {}".format(type_name))
@@ -213,7 +219,7 @@ def add_member(self, name, id):
         self.add_token(token)
 
 
-    def add_stringliteral(self, value):
+    def add_string_literal(self, value):
         self.add_token(Token("\u0022{}\u0022".format(value), TokenKind.StringLiteral))
 
 

packages/python-packages/apiview-stub-generator/apistub/_token_kind.py

@@ -19,3 +19,18 @@ class TokenKind(Enum):
     DeprecatedRangeEnd = 14
     SkipDiffRangeStart = 15
     SkipDiffRangeEnd = 16
+    FoldableSectionHeading = 17
+    FoldableSectionContentStart = 18
+    FoldableSectionContentEnd = 19
+    TableBegin = 20
+    TableEnd = 21
+    TableRowCount = 22
+    TableColumnCount = 23
+    TableColumnName = 24
+    TableCellBegin = 25
+    TableCellEnd = 26
+    LeafSectionPlaceholder = 27
+    ExternalLinkStart = 28
+    ExternalLinkEnd = 29
+    HiddenApiRangeStart = 30
+    HiddenApiRangeEnd = 31

packages/python-packages/apiview-stub-generator/apistub/_version.py

@@ -1,4 +1,4 @@
 # Copyright (c) Microsoft Corporation. All rights reserved.
 # Licensed under the MIT License.
 
-VERSION = "0.3.7"
+VERSION = "0.3.8"

packages/python-packages/apiview-stub-generator/apistub/nodes/_argtype.py

@@ -57,7 +57,7 @@ def generate_tokens(self, apiview, function_id, *, add_line_marker: bool, prefix
         if default is not None:
             apiview.add_punctuation("=", True, True)
             if isinstance(default, str) and default not in SPECIAL_DEFAULT_VALUES:
-                apiview.add_stringliteral(default)
+                apiview.add_string_literal(default)
             else:
                 if isinstance(default, astroid.node_classes.Name):
                     value = default.name

packages/python-packages/apiview-stub-generator/apistub/nodes/_class_node.py

@@ -211,7 +211,11 @@ def _inspect(self):
                 if not name.startswith("_") or name.startswith("__"):
                     func_node = FunctionNode(self.namespace, self, obj=child_obj)
                     func_overloads = [x for x in overloads if x.name == func_node.name]
-                    for overload in func_overloads:
+
+                    # Append a numeric tag to overloads to distinguish them from one another.
+                    # This will break down if overloads are moved around in the source file.
+                    for x, overload in enumerate(func_overloads):
+                        overload.namespace_id = overload.namespace_id + f"_{x+1}"
                         self.child_nodes.append(overload)
                     self.child_nodes.append(func_node)
             elif name == "__annotations__":

packages/python-packages/apiview-stub-generator/apistub/nodes/_enum_node.py

@@ -25,7 +25,7 @@ def generate_tokens(self, apiview):
         apiview.add_punctuation("=")
         apiview.add_space()
         if isinstance(self.value, str):
-            apiview.add_stringliteral(self.value)
+            apiview.add_string_literal(self.value)
         else:
             apiview.add_literal(str(self.value))
         for err in self.pylint_errors:

packages/python-packages/apiview-stub-generator/apistub/nodes/_function_node.py

@@ -58,22 +58,6 @@ def __init__(self, namespace, parent_node, *, obj=None, node: astroid.FunctionDe
             self.node = None
         self._inspect()
         self.kwargs = OrderedDict(sorted(self.kwargs.items()))
-        self.namespace_id = self._regenerate_function_id()
-
-    def _regenerate_function_id(self):
-        """
-        Regenerate the namespace_id for functions to account for overloads, which
-        have the same name.
-        """
-        lines = [f"{self.full_name}("]
-        for arg in self.args.values():
-            lines.append(f"{arg.argname}:{arg.argtype},")
-        for arg in self.kwargs.values():
-            lines.append(f"{arg.argname}:{arg.argtype},")
-        # FIXME: Need to include kwargs and args here?
-        lines.append(f")->{self.return_type}")
-        namespace_id = "".join(lines)
-        return namespace_id
 
     def _inspect(self):
         logging.debug("Processing function {0}".format(self.name))

packages/python-packages/apiview-stub-generator/apistub/nodes/_variable_node.py

@@ -35,7 +35,7 @@ def generate_tokens(self, apiview):
         apiview.add_punctuation("=", True, True)
         if not self.dataclass_properties:
             if self.type in ["str", "Optional[str]"]:
-                apiview.add_stringliteral(self.value)
+                apiview.add_string_literal(self.value)
             else:
                 apiview.add_literal(self.value)
         else: