Add @deprecated decorator to openpyxl (#11535)

stubs/openpyxl/openpyxl/styles/proxy.pyi

@@ -1,9 +1,12 @@
+from typing_extensions import deprecated
+
 class StyleProxy:
     def __init__(self, target) -> None: ...
     def __getattr__(self, attr: str): ...
     def __setattr__(self, attr: str, value) -> None: ...
     def __copy__(self): ...
     def __add__(self, other): ...
+    @deprecated("Use copy(obj) or cell.obj = cell.obj + other")
     def copy(self, **kw): ...
     def __eq__(self, other: object) -> bool: ...
     def __ne__(self, other: object) -> bool: ...

stubs/openpyxl/openpyxl/workbook/workbook.pyi

@@ -2,6 +2,7 @@ from _typeshed import Incomplete, Unused
 from collections.abc import Iterator
 from datetime import datetime
 from typing import Any, Final
+from typing_extensions import deprecated
 from zipfile import ZipFile
 
 from openpyxl import _Decodable, _ZipFileFileProtocol
@@ -52,22 +53,27 @@ class Workbook:
     ) -> Any: ...  # AnyOf[WriteOnlyWorksheet, Worksheet]
     def move_sheet(self, sheet: Worksheet | str, offset: int = 0) -> None: ...
     def remove(self, worksheet: Worksheet) -> None: ...
+    @deprecated("Use wb.remove(worksheet) or del wb[sheetname]")
     def remove_sheet(self, worksheet: Worksheet) -> None: ...
     def create_chartsheet(self, title: str | _Decodable | None = None, index: int | None = None) -> Chartsheet: ...
+    @deprecated("Use wb[sheetname]")
     def get_sheet_by_name(self, name: str) -> Worksheet: ...
     def __contains__(self, key: str) -> bool: ...
     def index(self, worksheet: Worksheet) -> int: ...
+    @deprecated("Use wb.index(worksheet)")
     def get_index(self, worksheet: Worksheet) -> int: ...
     def __getitem__(self, key: str) -> Worksheet: ...
     def __delitem__(self, key: str) -> None: ...
     def __iter__(self) -> Iterator[Worksheet]: ...
+    @deprecated("Use wb.sheetnames")
     def get_sheet_names(self) -> list[Worksheet]: ...
     @property
     def worksheets(self) -> list[Worksheet]: ...
     @property
     def chartsheets(self) -> list[Chartsheet]: ...
     @property
     def sheetnames(self) -> list[str]: ...
+    @deprecated("Assign scoped named ranges directly to worksheets or global ones to the workbook. Deprecated in 3.1")
     def create_named_range(
         self, name: str, worksheet: Worksheet | None = None, value: str | Incomplete | None = None, scope: Unused = None
     ) -> None: ...

stubs/openpyxl/openpyxl/worksheet/worksheet.pyi

@@ -3,6 +3,7 @@ from collections.abc import Generator, Iterable, Iterator
 from datetime import datetime
 from types import GeneratorType
 from typing import Any, Final, Literal, NoReturn, overload
+from typing_extensions import deprecated
 
 from openpyxl import _Decodable, _VisibilityType
 from openpyxl.cell import _CellValue
@@ -218,8 +219,9 @@ class Worksheet(_WorkbookChild):
         end_row: ConvertibleToInt,
         end_column: ConvertibleToInt,
     ) -> None: ...
-    # deprecated: Will always raise: TypeError: 'set' object is not subscriptable
+    # Will always raise: TypeError: 'set' object is not subscriptable
     @property
+    @deprecated("Use ws.merged_cells.ranges")
     def merged_cell_ranges(self) -> NoReturn: ...
     def unmerge_cells(
         self,

stubs/openpyxl/openpyxl/xml/functions.pyi

@@ -2,7 +2,7 @@ from _typeshed import Incomplete
 from re import Pattern
 from typing import Final
 
-# Can actually be imported from a mix of xml, lxml, et_xmlfile as defusedxml
+# Can actually be imported from a mix of xml, lxml, et_xmlfile and defusedxml
 # But et_xmlfile is untyped. openpyxl does not directly depend on lxml/lxml-stubs.
 # And forcing a dependency on defusedxml felt overkill as it just wraps xml
 # So for typing purposes, let's pretend xml is the only dependency.