Update stubs after deprecation

Author: jtojnar

src/gi-stubs/repository/Adw.pyi

@@ -7,6 +7,11 @@ from typing import Tuple
 from typing import Type
 from typing import TypeVar
 
+try:
+    from warnings import deprecated
+except ImportError:
+    from typing_extensions import deprecated
+
 from gi.repository import Gdk
 from gi.repository import GObject
 from gi.repository import Gtk
@@ -142,8 +147,10 @@ class Indicator(GObject.Object):
     def new_with_path(
         cls, id: str, icon_name: str, category: IndicatorCategory, icon_theme_path: str
     ) -> Indicator: ...
+    @deprecated("Use app_indicator_set_attention_icon_full() instead.")
     def set_attention_icon(self, icon_name: str) -> None: ...
     def set_attention_icon_full(self, icon_name: str, icon_desc: str) -> None: ...
+    @deprecated("Use app_indicator_set_icon_full()")
     def set_icon(self, icon_name: str) -> None: ...
     def set_icon_full(self, icon_name: str, icon_desc: str) -> None: ...
     def set_icon_theme_path(self, icon_theme_path: str) -> None: ...

src/gi-stubs/repository/AppIndicator3.pyi

@@ -7,6 +7,11 @@ from typing import Tuple
 from typing import Type
 from typing import TypeVar
 
+try:
+    from warnings import deprecated
+except ImportError:
+    from typing_extensions import deprecated
+
 from gi.repository import Gio
 from gi.repository import GLib
 from gi.repository import GObject

src/gi-stubs/repository/AppStream.pyi

@@ -7,6 +7,11 @@ from typing import Tuple
 from typing import Type
 from typing import TypeVar
 
+try:
+    from warnings import deprecated
+except ImportError:
+    from typing_extensions import deprecated
+
 from gi.repository import GLib
 from gi.repository import GObject
 
@@ -21,6 +26,9 @@ _namespace: str = "Atk"
 _version: str = "1.0"
 
 def attribute_set_free(attrib_set: list[None]) -> None: ...
+@deprecated(
+    "Focus tracking has been dropped as a feature to be implemented by ATK itself. As #AtkObject::focus-event was deprecated in favor of a #AtkObject::state-change signal, in order to notify a focus change on your implementation, you can use atk_object_notify_state_change() instead."
+)
 def focus_tracker_notify(object: Object) -> None: ...
 def get_binary_age() -> int: ...
 def get_default_registry() -> Registry: ...
@@ -36,12 +44,18 @@ def get_version() -> str: ...
 def relation_type_for_name(name: str) -> RelationType: ...
 def relation_type_get_name(type: RelationType) -> str: ...
 def relation_type_register(name: str) -> RelationType: ...
+@deprecated(
+    'Focus tracking has been dropped as a feature to be implemented by ATK itself. If you need focus tracking on your implementation, subscribe to the #AtkObject::state-change "focused" signal.'
+)
 def remove_focus_tracker(tracker_id: int) -> None: ...
 def remove_global_event_listener(listener_id: int) -> None: ...
 def remove_key_event_listener(listener_id: int) -> None: ...
 def role_for_name(name: str) -> Role: ...
 def role_get_localized_name(role: Role) -> str: ...
 def role_get_name(role: Role) -> str: ...
+@deprecated(
+    "Since 2.12. If your application/toolkit doesn't find a suitable role for a specific object defined at #AtkRole, please submit a bug in order to add a new role to the specification."
+)
 def role_register(name: str) -> Role: ...
 def state_type_for_name(name: str) -> StateType: ...
 def state_type_get_name(type: StateType) -> str: ...
@@ -109,12 +123,17 @@ class Component(GObject.GInterface):
     def get_extents(self, coord_type: CoordType) -> Tuple[int, int, int, int]: ...
     def get_layer(self) -> Layer: ...
     def get_mdi_zorder(self) -> int: ...
+    @deprecated("Since 2.12. Use atk_component_get_extents() instead.")
     def get_position(self, coord_type: CoordType) -> Tuple[int, int]: ...
+    @deprecated("Since 2.12. Use atk_component_get_extents() instead.")
     def get_size(self) -> Tuple[int, int]: ...
     def grab_focus(self) -> bool: ...
     def ref_accessible_at_point(
         self, x: int, y: int, coord_type: CoordType
     ) -> Optional[Object]: ...
+    @deprecated(
+        'If you need to track when an object gains or lose the focus, use the #AtkObject::state-change "focused" notification instead.'
+    )
     def remove_focus_handler(self, handler_id: int) -> None: ...
     def scroll_to(self, type: ScrollType) -> bool: ...
     def scroll_to_point(self, coords: CoordType, x: int, y: int) -> bool: ...
@@ -162,8 +181,15 @@ class Document(GObject.GInterface):
     def get_attribute_value(self, attribute_name: str) -> Optional[str]: ...
     def get_attributes(self) -> list[None]: ...
     def get_current_page_number(self) -> int: ...
+    @deprecated(
+        "Since 2.12. @document is already a representation of the document. Use it directly, or one of its children, as an instance of the DOM."
+    )
     def get_document(self) -> None: ...
+    @deprecated(
+        "Since 2.12. Please use atk_document_get_attributes() to ask for the document type if it applies."
+    )
     def get_document_type(self) -> str: ...
+    @deprecated("Please use atk_object_get_object_locale() instead.")
     def get_locale(self) -> str: ...
     def get_page_count(self) -> int: ...
     def set_attribute_value(
@@ -377,6 +403,9 @@ class Hyperlink(GObject.Object, Action):
     def get_start_index(self) -> int: ...
     def get_uri(self, i: int) -> str: ...
     def is_inline(self) -> bool: ...
+    @deprecated(
+        "Please use ATK_STATE_FOCUSABLE for all links, and ATK_STATE_FOCUSED for focused links."
+    )
     def is_selected_link(self) -> bool: ...
     def is_valid(self) -> bool: ...
 
@@ -510,9 +539,12 @@ class Misc(GObject.Object):
     parent: GObject.Object = ...
     def do_threads_enter(self) -> None: ...
     def do_threads_leave(self) -> None: ...
+    @deprecated("Since 2.12.")
     @staticmethod
     def get_instance() -> Misc: ...
+    @deprecated("Since 2.12.")
     def threads_enter(self) -> None: ...
+    @deprecated("Since 2.12.")
     def threads_leave(self) -> None: ...
 
 class MiscClass(GObject.GPointer):
@@ -847,7 +879,9 @@ class Object(GObject.Object):
     def get_attributes(self) -> list[None]: ...
     def get_description(self) -> str: ...
     def get_index_in_parent(self) -> int: ...
+    @deprecated("Use atk_component_get_layer instead.")
     def get_layer(self) -> Layer: ...
+    @deprecated("Use atk_component_get_mdi_zorder instead.")
     def get_mdi_zorder(self) -> int: ...
     def get_n_accessible_children(self) -> int: ...
     def get_name(self) -> str: ...
@@ -860,6 +894,7 @@ class Object(GObject.Object):
     def ref_accessible_child(self, i: int) -> Object: ...
     def ref_relation_set(self) -> RelationSet: ...
     def ref_state_set(self) -> StateSet: ...
+    @deprecated("See atk_object_connect_property_change_handler()")
     def remove_property_change_handler(self, handler_id: int) -> None: ...
     def remove_relationship(
         self, relationship: RelationType, target: Object
@@ -1443,13 +1478,18 @@ class Table(GObject.GInterface):
     def add_column_selection(self, column: int) -> bool: ...
     def add_row_selection(self, row: int) -> bool: ...
     def get_caption(self) -> Optional[Object]: ...
+    @deprecated("Since 2.12.")
     def get_column_at_index(self, index_: int) -> int: ...
     def get_column_description(self, column: int) -> str: ...
     def get_column_extent_at(self, row: int, column: int) -> int: ...
     def get_column_header(self, column: int) -> Optional[Object]: ...
+    @deprecated(
+        "Since 2.12. Use atk_table_ref_at() in order to get the accessible that represents the cell at (@row, @column)"
+    )
     def get_index_at(self, row: int, column: int) -> int: ...
     def get_n_columns(self) -> int: ...
     def get_n_rows(self) -> int: ...
+    @deprecated("since 2.12.")
     def get_row_at_index(self, index_: int) -> int: ...
     def get_row_description(self, row: int) -> Optional[str]: ...
     def get_row_extent_at(self, row: int, column: int) -> int: ...
@@ -1584,12 +1624,17 @@ class Text(GObject.GInterface):
         self, offset: int, granularity: TextGranularity
     ) -> Tuple[Optional[str], int, int]: ...
     def get_text(self, start_offset: int, end_offset: int) -> str: ...
+    @deprecated("Please use atk_text_get_string_at_offset() instead.")
     def get_text_after_offset(
         self, offset: int, boundary_type: TextBoundary
     ) -> Tuple[str, int, int]: ...
+    @deprecated(
+        "This method is deprecated since ATK version 2.9.4. Please use atk_text_get_string_at_offset() instead."
+    )
     def get_text_at_offset(
         self, offset: int, boundary_type: TextBoundary
     ) -> Tuple[str, int, int]: ...
+    @deprecated("Please use atk_text_get_string_at_offset() instead.")
     def get_text_before_offset(
         self, offset: int, boundary_type: TextBoundary
     ) -> Tuple[str, int, int]: ...
@@ -1721,14 +1766,19 @@ class Value(GObject.GInterface):
     Interface AtkValue
     """
 
+    @deprecated("Since 2.12. Use atk_value_get_value_and_text() instead.")
     def get_current_value(self) -> Any: ...
     def get_increment(self) -> float: ...
+    @deprecated("Since 2.12. Use atk_value_get_range() instead.")
     def get_maximum_value(self) -> Any: ...
+    @deprecated("Since 2.12. Use atk_value_get_increment() instead.")
     def get_minimum_increment(self) -> Any: ...
+    @deprecated("Since 2.12. Use atk_value_get_range() instead.")
     def get_minimum_value(self) -> Any: ...
     def get_range(self) -> Optional[Range]: ...
     def get_sub_ranges(self) -> list[Range]: ...
     def get_value_and_text(self) -> Tuple[float, str]: ...
+    @deprecated("Since 2.12. Use atk_value_set_value() instead.")
     def set_current_value(self, value: Any) -> bool: ...
     def set_value(self, new_value: float) -> None: ...
 

src/gi-stubs/repository/Atk.pyi

@@ -7,6 +7,11 @@ from typing import Tuple
 from typing import Type
 from typing import TypeVar
 
+try:
+    from warnings import deprecated
+except ImportError:
+    from typing_extensions import deprecated
+
 from gi.repository import Gdk
 from gi.repository import GObject
 from gi.repository import Gtk
@@ -141,10 +146,12 @@ class Indicator(GObject.Object):
     def new_with_path(
         cls, id: str, icon_name: str, category: IndicatorCategory, icon_theme_path: str
     ) -> Indicator: ...
+    @deprecated("Use app_indicator_set_attention_icon_full() instead.")
     def set_attention_icon(self, icon_name: str) -> None: ...
     def set_attention_icon_full(
         self, icon_name: str, icon_desc: Optional[str] = None
     ) -> None: ...
+    @deprecated("Use app_indicator_set_icon_full()")
     def set_icon(self, icon_name: str) -> None: ...
     def set_icon_full(
         self, icon_name: str, icon_desc: Optional[str] = None

src/gi-stubs/repository/AyatanaAppIndicator3.pyi

@@ -7,6 +7,11 @@ from typing import Tuple
 from typing import Type
 from typing import TypeVar
 
+try:
+    from warnings import deprecated
+except ImportError:
+    from typing_extensions import deprecated
+
 from gi.repository import GLib
 from gi.repository import GObject
 from gi.repository import Gst

src/gi-stubs/repository/Farstream.pyi

@@ -7,6 +7,11 @@ from typing import Tuple
 from typing import Type
 from typing import TypeVar
 
+try:
+    from warnings import deprecated
+except ImportError:
+    from typing_extensions import deprecated
+
 from gi.repository import Gio
 from gi.repository import GLib
 from gi.repository import GObject
@@ -185,6 +190,7 @@ class Installation(GObject.Object):
         self, name: str, cancellable: Optional[Gio.Cancellable] = None
     ) -> Remote: ...
     def get_storage_type(self) -> StorageType: ...
+    @deprecated("Use flatpak_transaction_add_install() instead.")
     def install(
         self,
         remote_name: str,
@@ -196,13 +202,15 @@ class Installation(GObject.Object):
         cancellable: Optional[Gio.Cancellable] = None,
         *progress_data: Any,
     ) -> InstalledRef: ...
+    @deprecated("Use flatpak_transaction_add_install_bundle() instead.")
     def install_bundle(
         self,
         file: Gio.File,
         progress: Optional[Callable[..., None]] = None,
         cancellable: Optional[Gio.Cancellable] = None,
         *progress_data: Any,
     ) -> InstalledRef: ...
+    @deprecated("Use flatpak_transaction_add_install() instead.")
     def install_full(
         self,
         flags: InstallFlags,
@@ -216,6 +224,7 @@ class Installation(GObject.Object):
         cancellable: Optional[Gio.Cancellable] = None,
         *progress_data: Any,
     ) -> InstalledRef: ...
+    @deprecated("Use flatpak_transaction_add_install_flatpakref() instead.")
     def install_ref_file(
         self, ref_file_data: GLib.Bytes, cancellable: Optional[Gio.Cancellable] = None
     ) -> RemoteRef: ...
@@ -319,6 +328,7 @@ class Installation(GObject.Object):
         self, key: str, value: str, cancellable: Optional[Gio.Cancellable] = None
     ) -> bool: ...
     def set_no_interaction(self, no_interaction: bool) -> None: ...
+    @deprecated("Use flatpak_transaction_add_uninstall() instead.")
     def uninstall(
         self,
         kind: RefKind,
@@ -329,6 +339,7 @@ class Installation(GObject.Object):
         cancellable: Optional[Gio.Cancellable] = None,
         *progress_data: Any,
     ) -> bool: ...
+    @deprecated("Use flatpak_transaction_add_uninstall() instead.")
     def uninstall_full(
         self,
         flags: UninstallFlags,
@@ -340,6 +351,7 @@ class Installation(GObject.Object):
         cancellable: Optional[Gio.Cancellable] = None,
         *progress_data: Any,
     ) -> bool: ...
+    @deprecated("Use flatpak_transaction_add_update() instead.")
     def update(
         self,
         flags: UpdateFlags,
@@ -367,6 +379,7 @@ class Installation(GObject.Object):
         out_changed: Optional[bool] = None,
         cancellable: Optional[Gio.Cancellable] = None,
     ) -> bool: ...
+    @deprecated("Use flatpak_transaction_add_update() instead.")
     def update_full(
         self,
         flags: UpdateFlags,

src/gi-stubs/repository/Flatpak.pyi

@@ -7,6 +7,11 @@ from typing import Tuple
 from typing import Type
 from typing import TypeVar
 
+try:
+    from warnings import deprecated
+except ImportError:
+    from typing_extensions import deprecated
+
 from gi.repository import GLib
 from gi.repository import GObject