imprv: Generator: Add deprecations

Author: matperc

pyproject.toml

@@ -14,6 +14,10 @@ authors = [
   {email = "[email protected]"},
   {name = "Christoph Reiter"}
 ]
+dependencies = [
+    # for @deprecated decorator
+    'typing_extensions>="4.5.0"; python_version<"3.13"',
+]
 classifiers = [
     "Programming Language :: Python :: 3",
     "Intended Audience :: Developers",

tools/generate.py

@@ -8,6 +8,7 @@
 
 from typing import Any
 from typing import Callable
+from typing import cast
 from typing import Optional
 from typing import Tuple
 from typing import Type
@@ -20,6 +21,7 @@
 import pprint
 import re
 import textwrap
+import xml.etree.ElementTree as ET
 from types import ModuleType
 
 import gi
@@ -34,6 +36,8 @@
 
 ObjectT = Union[ModuleType, Type[Any]]
 
+DEPRECATION_DOCS: dict[str, str] = {}
+
 
 def _object_get_props(
     obj: GI.ObjectInfo,
@@ -339,9 +343,16 @@ def _build(parent: ObjectT, namespace: str, overrides: dict[str, str]) -> str:
     typings = "from typing import Any, Callable, Literal, Optional, Tuple, Type, TypeVar, Sequence"
 
     typevars: list[str] = []
-    imports: list[str] = []
+    imports: list[str] = [
+        """
+try:
+    from warnings import deprecated
+except ImportError:
+    from typing_extensions import deprecated
+"""
+    ]
     if "cairo" in ns:
-        imports = ["import cairo"]
+        imports += ["import cairo"]
         typevars.append('_SomeSurface = TypeVar("_SomeSurface", bound=cairo.Surface)')
         ns.remove("cairo")
 
@@ -368,7 +379,7 @@ def _generate_full_name(prefix: str, name: str) -> str:
 def _build_function_info(
     current_namespace: str,
     name: str,
-    function: (GI.FunctionInfo | GI.VFuncInfo),
+    function: GI.FunctionInfo | GI.VFuncInfo,
     in_class: Optional[Any],
     needed_namespaces: set[str],
     return_signature: Optional[str] = None,
@@ -601,6 +612,21 @@ def _gi_build_stub(
 
     # Functions
     for name in sorted(functions):
+        if hasattr(functions[name], "is_deprecated"):
+            deprecated = functions[name].is_deprecated()
+            if deprecated:
+                full_name = _generate_full_name(prefix_name, name)
+                message = (
+                    functions[name].get_attribute("deprecated")
+                    or (
+                        DEPRECATION_DOCS[full_name]
+                        if full_name in DEPRECATION_DOCS
+                        else None
+                    )
+                    or f"This {'method' if in_class else 'function'} is deprecated"
+                )
+                ret += f'@deprecated("{message}")\n'
+
         override = _check_override(prefix_name, name, overrides)
         if override:
             ret += override + "\n"
@@ -615,13 +641,27 @@ def _gi_build_stub(
 
     # Classes
     for name, obj in sorted(classes.items()):
+        full_name = _generate_full_name(prefix_name, name)
+
+        if hasattr(obj, "__info__") and hasattr(obj.__info__, "is_deprecated"):
+            deprecated = obj.__info__.is_deprecated()
+            if deprecated:
+                message = (
+                    obj.__info__.get_attribute("deprecated")
+                    or (
+                        DEPRECATION_DOCS[full_name]
+                        if full_name in DEPRECATION_DOCS
+                        else None
+                    )
+                    or f"This class is deprecated"
+                )
+                ret += f'@deprecated("{message}")\n'
+
         override = _check_override(prefix_name, name, overrides)
         if override:
             ret += override + "\n\n"
             continue
 
-        full_name = _generate_full_name(prefix_name, name)
-
         classret = _gi_build_stub(
             obj,
             current_namespace,
@@ -940,6 +980,27 @@ def start(module: str, version: str, overrides: dict[str, str]) -> str:
 
     args = parser.parse_args()
 
+    ns = {
+        "core": "http://www.gtk.org/introspection/core/1.0",
+        "c": "http://www.gtk.org/introspection/c/1.0",
+        "glib": "http://www.gtk.org/introspection/glib/1.0",
+    }
+    gir_tree = ET.parse(f"/usr/share/gir-1.0/{args.module}-{args.version}.gir")
+    gir_root = gir_tree.getroot()
+    gir_parent_map = {c: p for p in gir_tree.iter() for c in p}
+    for child in gir_root.iterfind(".//core:doc-deprecated", ns):
+        parents: list[str] = []
+        parent = gir_parent_map[child]
+        while True:
+            try:
+                parents.insert(0, parent.attrib["name"])
+            except KeyError:
+                break
+            parent = gir_parent_map[parent]
+        DEPRECATION_DOCS[".".join(parents[1:])] = (
+            cast(str, child.text).replace("\n", "").replace('"', '\\"')
+        )
+
     if args.output:
         overrides: dict[str, str] = {}
         try: