Complete openpyxl title type annotations (#10563)

stubs/openpyxl/openpyxl/__init__.pyi

@@ -1,3 +1,5 @@
+from typing import Protocol
+
 from openpyxl.compat.numbers import NUMPY as NUMPY
 from openpyxl.reader.excel import load_workbook as load_workbook
 from openpyxl.workbook import Workbook as Workbook
@@ -14,3 +16,7 @@ from ._constants import (
 
 DEBUG: bool
 open = load_workbook
+
+# Utility types reused elsewhere
+class _Decodable(Protocol):  # noqa: Y046
+    def decode(self, __encoding: str) -> str: ...

stubs/openpyxl/openpyxl/chart/_chart.pyi

@@ -5,6 +5,7 @@ from typing_extensions import Literal, TypeAlias
 from openpyxl.chart.layout import Layout
 from openpyxl.chart.legend import Legend
 from openpyxl.chart.shapes import GraphicalProperties
+from openpyxl.chart.title import TitleDescriptor
 from openpyxl.descriptors.base import Alias, Bool, Integer, MinMax, Set, Typed, _ConvertibleToInt
 from openpyxl.descriptors.serialisable import Serialisable
 
@@ -25,7 +26,7 @@ class ChartBase(Serialisable):
     display_blanks: Set[_ChartBaseDisplayBlanks]
     ser: Incomplete
     series: Alias
-    title: Incomplete
+    title: TitleDescriptor
     anchor: str
     width: int
     height: float

stubs/openpyxl/openpyxl/chart/axis.pyi

@@ -5,6 +5,7 @@ from typing_extensions import Literal, TypeAlias
 from openpyxl.chart.layout import Layout
 from openpyxl.chart.shapes import GraphicalProperties
 from openpyxl.chart.text import RichText, Text
+from openpyxl.chart.title import Title, TitleDescriptor
 from openpyxl.descriptors.base import Alias, Typed, _ConvertibleToBool, _ConvertibleToFloat, _ConvertibleToInt
 from openpyxl.descriptors.excel import ExtensionList
 from openpyxl.descriptors.nested import (
@@ -70,7 +71,7 @@ class _BaseAxis(Serialisable):
     axPos: NestedSet[_BaseAxisAxPos]
     majorGridlines: Typed[ChartLines, Literal[True]]
     minorGridlines: Typed[ChartLines, Literal[True]]
-    title: Incomplete
+    title: TitleDescriptor
     numFmt: Incomplete
     number_format: Alias
     majorTickMark: NestedNoneSet[_BaseAxisTickMark]
@@ -93,7 +94,7 @@ class _BaseAxis(Serialisable):
         axPos: _HasTagAndGet[_BaseAxisAxPos] | _BaseAxisAxPos,
         majorGridlines: ChartLines | None,
         minorGridlines: ChartLines | None,
-        title: Incomplete | None,
+        title: str | Title | None,
         numFmt: Incomplete | None,
         majorTickMark: _NestedNoneSetParam[_BaseAxisTickMark],
         minorTickMark: _NestedNoneSetParam[_BaseAxisTickMark],
@@ -113,7 +114,7 @@ class _BaseAxis(Serialisable):
         axPos: _HasTagAndGet[_BaseAxisAxPos] | _BaseAxisAxPos = "l",
         majorGridlines: ChartLines | None = None,
         minorGridlines: ChartLines | None = None,
-        title: Incomplete | None = None,
+        title: str | Title | None = None,
         numFmt: Incomplete | None = None,
         majorTickMark: Incomplete | None = None,
         minorTickMark: Incomplete | None = None,

stubs/openpyxl/openpyxl/chart/reference.pyi

@@ -7,8 +7,8 @@ from openpyxl.descriptors import Strict
 from openpyxl.descriptors.base import MinMax, String, _ConvertibleToInt
 
 class DummyWorksheet:
-    title: Incomplete
-    def __init__(self, title) -> None: ...
+    title: str
+    def __init__(self, title: str) -> None: ...
 
 class Reference(Strict):
     min_row: MinMax[int, Literal[False]]

stubs/openpyxl/openpyxl/chart/series_factory.pyi

@@ -4,6 +4,6 @@ def SeriesFactory(
     values,
     xvalues: Incomplete | None = None,
     zvalues: Incomplete | None = None,
-    title: Incomplete | None = None,
+    title: object = None,
     title_from_data: bool = False,
 ): ...

stubs/openpyxl/openpyxl/chart/title.pyi

@@ -1,4 +1,4 @@
-from _typeshed import Incomplete, Unused
+from _typeshed import Unused
 from typing import ClassVar
 from typing_extensions import Literal
 
@@ -35,9 +35,9 @@ class Title(Serialisable):
         extLst: Unused = None,
     ) -> None: ...
 
-def title_maker(text): ...
+def title_maker(text) -> Title: ...
 
-class TitleDescriptor(Typed[Title, Incomplete]):
+class TitleDescriptor(Typed[Title, Literal[True]]):
     expected_type: type[Title]
     allow_none: Literal[True]
-    def __set__(self, instance: Serialisable | Strict, value) -> None: ...
+    def __set__(self, instance: Serialisable | Strict, value: str | Title | None) -> None: ...

stubs/openpyxl/openpyxl/chartsheet/chartsheet.pyi

@@ -2,6 +2,7 @@ from _typeshed import Incomplete, Unused
 from typing import ClassVar
 from typing_extensions import Literal, TypeAlias
 
+from openpyxl import _Decodable
 from openpyxl.chartsheet.custom import CustomChartsheetViews
 from openpyxl.chartsheet.properties import ChartsheetProperties
 from openpyxl.chartsheet.protection import ChartsheetProtection
@@ -52,7 +53,7 @@ class Chartsheet(_WorkbookChild, Serialisable):
         webPublishItems: WebPublishItems | None = None,
         extLst: Unused = None,
         parent: Incomplete | None = None,
-        title: str = "",
+        title: str | _Decodable | None = "",
         sheet_state: _ChartsheetSheetState = "visible",
     ) -> None: ...
     def add_chart(self, chart) -> None: ...

stubs/openpyxl/openpyxl/workbook/child.pyi

@@ -2,13 +2,15 @@ from _typeshed import Incomplete
 from re import Pattern
 from typing_extensions import Final
 
+from openpyxl import _Decodable
+
 INVALID_TITLE_REGEX: Final[Pattern[str]]
 
 def avoid_duplicate_name(names, value): ...
 
 class _WorkbookChild:
     HeaderFooter: Incomplete
-    def __init__(self, parent: Incomplete | None = None, title: Incomplete | None = None) -> None: ...
+    def __init__(self, parent: Incomplete | None = None, title: str | _Decodable | None = None) -> None: ...
     @property
     def parent(self): ...
     @property
@@ -16,7 +18,7 @@ class _WorkbookChild:
     @property
     def title(self) -> str: ...
     @title.setter
-    def title(self, value: str | bytes) -> None: ...
+    def title(self, value: str | _Decodable) -> None: ...
     @property
     def oddHeader(self): ...
     @oddHeader.setter

stubs/openpyxl/openpyxl/workbook/workbook.pyi

@@ -4,6 +4,7 @@ from datetime import datetime
 from typing import IO
 from typing_extensions import Final
 
+from openpyxl import _Decodable
 from openpyxl.chartsheet.chartsheet import Chartsheet
 from openpyxl.styles.named_styles import NamedStyle
 from openpyxl.workbook.child import _WorkbookChild
@@ -45,11 +46,11 @@ class Workbook:
     def active(self) -> _WorkbookChild | None: ...
     @active.setter
     def active(self, value: _WorkbookChild | int) -> None: ...
-    def create_sheet(self, title: str | None = None, index: int | None = None): ...
+    def create_sheet(self, title: str | _Decodable | None = None, index: int | None = None): ...
     def move_sheet(self, sheet: Worksheet | str, offset: int = 0) -> None: ...
     def remove(self, worksheet: Worksheet) -> None: ...
     def remove_sheet(self, worksheet: Worksheet) -> None: ...
-    def create_chartsheet(self, title: str | None = None, index: int | None = None) -> Chartsheet: ...
+    def create_chartsheet(self, title: str | _Decodable | None = None, index: int | None = None) -> Chartsheet: ...
     def get_sheet_by_name(self, name: str) -> Worksheet: ...
     def __contains__(self, key: str) -> bool: ...
     def index(self, worksheet: Worksheet) -> int: ...

stubs/openpyxl/openpyxl/worksheet/_read_only.pyi

@@ -14,9 +14,9 @@ class ReadOnlyWorksheet:
     __getitem__ = Worksheet.__getitem__
     __iter__ = Worksheet.__iter__
     parent: Incomplete
-    title: Incomplete
+    title: str
     sheet_state: str
-    def __init__(self, parent_workbook, title, worksheet_path, shared_strings) -> None: ...
+    def __init__(self, parent_workbook, title: str, worksheet_path, shared_strings) -> None: ...
     def calculate_dimension(self, force: bool = False): ...
     def reset_dimensions(self) -> None: ...
     @property

stubs/openpyxl/openpyxl/worksheet/_write_only.pyi

@@ -1,5 +1,6 @@
 from _typeshed import Incomplete
 
+from openpyxl import _Decodable
 from openpyxl.workbook.child import _WorkbookChild
 
 class WriteOnlyWorksheet(_WorkbookChild):
@@ -17,7 +18,7 @@ class WriteOnlyWorksheet(_WorkbookChild):
     print_area: Incomplete
     @property
     def sheet_view(self): ...
-    def __init__(self, parent, title) -> None: ...
+    def __init__(self, parent, title: str | _Decodable | None) -> None: ...
     @property
     def closed(self): ...
     def close(self) -> None: ...

stubs/openpyxl/openpyxl/worksheet/cell_range.pyi

@@ -12,17 +12,19 @@ class CellRange(Serialisable):
     min_row: MinMax[int, Literal[False]]
     max_col: MinMax[int, Literal[False]]
     max_row: MinMax[int, Literal[False]]
-    title: Incomplete
+    # Could be None if the caller forgot to set title and range_string doesn't contain "!"
+    # but that's not intended and will lead to errors (ie: can't be None in __str__)
+    title: str
 
     @overload
     def __init__(
         self,
-        range_string: Incomplete,
+        range_string: str | None,
         min_col: Unused = None,
         min_row: Unused = None,
         max_col: Unused = None,
         max_row: Unused = None,
-        title: Incomplete | None = None,
+        title: str | None = None,
     ) -> None: ...
     @overload
     def __init__(
@@ -33,7 +35,7 @@ class CellRange(Serialisable):
         min_row: _ConvertibleToInt,
         max_col: _ConvertibleToInt,
         max_row: _ConvertibleToInt,
-        title: Incomplete | None = None,
+        title: str,
     ) -> None: ...
     @property
     def bounds(self): ...

stubs/openpyxl/openpyxl/worksheet/print_settings.pyi

@@ -40,12 +40,12 @@ class PrintTitles(Strict):
     title: String[Literal[False]]
     def __init__(self, cols: ColRange | None = None, rows: RowRange | None = None, title: str = "") -> None: ...
     @classmethod
-    def from_string(cls, value) -> Self: ...
+    def from_string(cls, value: str) -> Self: ...
     def __eq__(self, other: object) -> bool: ...
 
 class PrintArea(MultiCellRange):
     title: str
     @classmethod
     def from_string(cls, value) -> Self: ...
-    def __init__(self, ranges=(), title: str = "") -> None: ...
+    def __init__(self, ranges=(), title: Unused = "") -> None: ...
     def __eq__(self, other): ...

stubs/openpyxl/openpyxl/worksheet/worksheet.pyi

@@ -4,6 +4,7 @@ from datetime import datetime
 from typing import Any, overload
 from typing_extensions import Final, Literal
 
+from openpyxl import _Decodable
 from openpyxl.cell.cell import Cell, _CellValue
 from openpyxl.formatting.formatting import ConditionalFormattingList
 from openpyxl.workbook.child import _WorkbookChild
@@ -66,7 +67,7 @@ class Worksheet(_WorkbookChild):
     sheet_format: SheetFormatProperties
     scenarios: ScenarioList
 
-    def __init__(self, parent: Workbook, title: str | None = None) -> None: ...
+    def __init__(self, parent: Workbook, title: str | _Decodable | None = None) -> None: ...
     @property
     def sheet_view(self) -> SheetView: ...
     @property