worksheet: add overload signatures for cell, range and column methods

Author: mattmess1221

.github/workflows/python-lint.yml

@@ -30,7 +30,7 @@ jobs:
     - name: Install test dependencies
       run: |
         python -m pip install --upgrade pip
-        pip install pytest flake8 black ruff isort pylint polars pandas
+        pip install pytest flake8 black ruff isort pylint polars pandas typing-extensions
 
     - name: Test the code style
       run: |

Makefile

@@ -46,7 +46,7 @@ testpythons:
 	@~/.pythonbrew/pythons/Python-3.14.0/bin/py.test -q
 
 test_flake8:
-	@ls -1 xlsxwriter/*.py | egrep -v "theme|__init__" | xargs flake8 --show-source --max-line-length=88 --ignore=E203,W503
+	@ls -1 xlsxwriter/*.py | egrep -v "theme|__init__" | xargs flake8 --show-source --max-line-length=88 --ignore=E203,E704,W503
 	@flake8 --ignore=E501 xlsxwriter/theme.py
 	@find xlsxwriter/test -name \*.py | xargs flake8 --ignore=E501,F841,W503
 

xlsxwriter/worksheet.py

@@ -21,7 +21,17 @@
 from functools import wraps
 from io import BytesIO, StringIO
 from math import isinf, isnan
-from typing import Any, Dict, List, Literal, Optional, Union
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Callable,
+    Dict,
+    List,
+    Literal,
+    Optional,
+    TypeVar,
+    Union,
+)
 from warnings import warn
 
 from xlsxwriter.chart import Chart
@@ -52,6 +62,59 @@
 )
 from .xmlwriter import XMLwriter
 
+if TYPE_CHECKING:
+    from typing_extensions import Concatenate, ParamSpec, Protocol, overload
+
+    ReturnTypeT_co = TypeVar("ReturnTypeT_co", covariant=True)
+    P = ParamSpec("P")
+
+    class CellMethod(Protocol[P, ReturnTypeT_co]):
+        """Overloads to support cell notation."""
+
+        @overload
+        def __call__(
+            self, row: int, col: int, /, *args: P.args, **kwargs: P.kwargs
+        ) -> ReturnTypeT_co: ...
+
+        @overload
+        def __call__(
+            self, cell: str, /, *args: P.args, **kwargs: P.kwargs
+        ) -> ReturnTypeT_co: ...
+
+    class RangeMethod(Protocol[P, ReturnTypeT_co]):
+        """Overloads to support range notation."""
+
+        @overload
+        def __call__(
+            self,
+            first_row: int,
+            first_col: int,
+            last_row: int,
+            last_col: int,
+            /,
+            *args: P.args,
+            **kwargs: P.kwargs,
+        ) -> ReturnTypeT_co: ...
+
+        @overload
+        def __call__(
+            self, cell_range: str, /, *args: P.args, **kwargs: P.kwargs
+        ) -> ReturnTypeT_co: ...
+
+    class ColumnMethod(Protocol[P, ReturnTypeT_co]):
+        """Overloads to support column range notation."""
+
+        @overload
+        def __call__(
+            self, first_col: int, last_col: int, /, *args: P.args, **kwargs: P.kwargs
+        ) -> ReturnTypeT_co: ...
+
+        @overload
+        def __call__(
+            self, col_range: str, /, *args: P.args, **kwargs: P.kwargs
+        ) -> ReturnTypeT_co: ...
+
+
 re_dynamic_function = re.compile(
     r"""
     \bANCHORARRAY\(    |
@@ -92,7 +155,9 @@
 # Decorator functions.
 #
 ###############################################################################
-def convert_cell_args(method):
+def convert_cell_args(
+    method: "Callable[Concatenate[Any, int, int, P], ReturnTypeT_co]",
+) -> "CellMethod[P, ReturnTypeT_co]":
     """
     Decorator function to convert A1 notation in cell method calls
     to the default row/col notation.
@@ -116,7 +181,9 @@ def cell_wrapper(self, *args, **kwargs):
     return cell_wrapper
 
 
-def convert_range_args(method):
+def convert_range_args(
+    method: "Callable[Concatenate[Any, int, int, int, int, P], ReturnTypeT_co]",
+) -> "RangeMethod[P, ReturnTypeT_co]":
     """
     Decorator function to convert A1 notation in range method calls
     to the default row/col notation.
@@ -148,7 +215,9 @@ def cell_wrapper(self, *args, **kwargs):
     return cell_wrapper
 
 
-def convert_column_args(method):
+def convert_column_args(
+    method: "Callable[Concatenate[Any, int, int, P], ReturnTypeT_co]",
+) -> "ColumnMethod[P, ReturnTypeT_co]":
     """
     Decorator function to convert A1 notation in columns method calls
     to the default row/col notation.