Various annotations extracted from #9511

stubs/openpyxl/@tests/stubtest_allowlist.txt

@@ -44,6 +44,8 @@ openpyxl\.descriptors\.(base\.)?Typed\.allow_none
 # Inconsistent methods because
 # - using the default value results in an error because of the runtime type-guards
 # - or, keyword arguments are explicitly specified
+openpyxl.cell.Cell.__init__
+openpyxl.cell.cell.Cell.__init__
 openpyxl.cell.text.PhoneticProperties.__init__
 openpyxl.cell.text.PhoneticText.__init__
 openpyxl.chart.axis._BaseAxis.__init__

stubs/openpyxl/openpyxl/cell/cell.pyi

@@ -39,11 +39,12 @@ class Cell(StyleableObject):
     row: int
     column: int
     data_type: str
+    # row and column are never meant to be None and would lead to errors
     def __init__(
         self,
         worksheet: Worksheet,
-        row: int | None = None,
-        column: int | None = None,
+        row: int,
+        column: int,
         value: str | float | datetime | None = None,
         style_array: StyleArray | None = None,
     ) -> None: ...

stubs/openpyxl/openpyxl/chartsheet/chartsheet.pyi

@@ -34,7 +34,7 @@ class Chartsheet(_WorkbookChild, Serialisable):
     extLst: Typed[ExtensionList, Literal[True]]
     sheet_state: Set[_VisibilityType]
     headerFooter: Typed[_HeaderFooter, Literal[False]]
-    HeaderFooter: Alias
+    HeaderFooter: Alias  # type: ignore[assignment] # Different from parent class
     __elements__: ClassVar[tuple[str, ...]]
     __attrs__: ClassVar[tuple[str, ...]]
     def __init__(

stubs/openpyxl/openpyxl/reader/workbook.pyi

@@ -2,22 +2,24 @@ from _typeshed import Incomplete
 from collections.abc import Generator
 from zipfile import ZipFile
 
-from openpyxl.packaging.relationship import RelationshipList
+from openpyxl.packaging.relationship import Relationship, RelationshipList
+from openpyxl.packaging.workbook import PivotCache
 from openpyxl.pivot.cache import CacheDefinition
 from openpyxl.workbook import Workbook
 
 class WorkbookParser:
     archive: ZipFile
-    workbook_part_name: Incomplete
+    workbook_part_name: str
     wb: Workbook
-    keep_links: Incomplete
-    sheets: Incomplete
-    def __init__(self, archive: ZipFile, workbook_part_name, keep_links: bool = True) -> None: ...
+    keep_links: bool
+    sheets: list[Incomplete]
+    def __init__(self, archive: ZipFile, workbook_part_name: str, keep_links: bool = True) -> None: ...
     @property
     def rels(self) -> RelationshipList: ...
-    caches: Incomplete
+    # Errors if "parse" is never called.
+    caches: list[PivotCache]
     def parse(self) -> None: ...
-    def find_sheets(self) -> Generator[Incomplete, None, None]: ...
+    def find_sheets(self) -> Generator[tuple[Incomplete, Relationship], None, None]: ...
     def assign_names(self) -> None: ...
     @property
     def pivot_caches(self) -> dict[int, CacheDefinition]: ...

stubs/openpyxl/openpyxl/styles/differential.pyi

@@ -1,6 +1,6 @@
-from _typeshed import Incomplete
+from _typeshed import Incomplete, Unused
 from typing import ClassVar
-from typing_extensions import Literal
+from typing_extensions import Literal, SupportsIndex
 
 from openpyxl.descriptors.base import Alias, Typed
 from openpyxl.descriptors.excel import ExtensionList
@@ -34,10 +34,10 @@ class DifferentialStyleList(Serialisable):
     dxf: Incomplete
     styles: Alias
     __attrs__: ClassVar[tuple[str, ...]]
-    def __init__(self, dxf=(), count: Incomplete | None = None) -> None: ...
-    def append(self, dxf) -> None: ...
-    def add(self, dxf): ...
+    def __init__(self, dxf=(), count: Unused = None) -> None: ...
+    def append(self, dxf: DifferentialStyle) -> None: ...
+    def add(self, dxf: DifferentialStyle) -> int: ...
     def __bool__(self) -> bool: ...
-    def __getitem__(self, idx): ...
+    def __getitem__(self, idx: SupportsIndex) -> DifferentialStyle: ...
     @property
     def count(self) -> int: ...

stubs/openpyxl/openpyxl/styles/fills.pyi

@@ -113,4 +113,6 @@ class GradientFill(Fill):
         stop=(),
     ) -> None: ...
     def __iter__(self) -> Iterator[tuple[str, str]]: ...
-    def to_tree(self, tagname: Unused = None, namespace: Unused = None, idx: Unused = None): ...  # type: ignore[override]
+    def to_tree(  # type: ignore[override]
+        self, tagname: Unused = None, namespace: Unused = None, idx: Unused = None
+    ) -> Element: ...

stubs/openpyxl/openpyxl/styles/named_styles.pyi

@@ -8,9 +8,11 @@ from openpyxl.descriptors.excel import ExtensionList
 from openpyxl.descriptors.serialisable import Serialisable
 from openpyxl.styles.alignment import Alignment
 from openpyxl.styles.borders import Border
+from openpyxl.styles.cell_style import CellStyle, StyleArray
 from openpyxl.styles.fills import Fill
 from openpyxl.styles.fonts import Font
 from openpyxl.styles.protection import Protection
+from openpyxl.workbook.workbook import Workbook
 
 class NamedStyle(Serialisable):
     font: Typed[Font, Literal[False]]
@@ -41,16 +43,16 @@ class NamedStyle(Serialisable):
     def __iter__(self) -> Iterator[tuple[str, str]]: ...
     @property
     def xfId(self) -> int | None: ...
-    def bind(self, wb) -> None: ...
-    def as_tuple(self): ...
-    def as_xf(self): ...
-    def as_name(self): ...
+    def bind(self, wb: Workbook) -> None: ...
+    def as_tuple(self) -> StyleArray: ...
+    def as_xf(self) -> CellStyle: ...
+    def as_name(self) -> _NamedCellStyle: ...
 
-class NamedStyleList(list[Incomplete]):
+class NamedStyleList(list[NamedStyle]):
     @property
     def names(self) -> list[str]: ...
-    def __getitem__(self, key): ...
-    def append(self, style) -> None: ...
+    def __getitem__(self, key: int | str) -> NamedStyle: ...  # type: ignore[override]
+    def append(self, style: NamedStyle) -> None: ...
 
 class _NamedCellStyle(Serialisable):
     tagname: ClassVar[str]

stubs/openpyxl/openpyxl/styles/numbers.pyi

@@ -1,7 +1,7 @@
 from _typeshed import ConvertibleToInt, Incomplete, Unused
 from re import Pattern
 from typing import ClassVar, overload
-from typing_extensions import Final, Literal, TypeGuard
+from typing_extensions import Final, Literal, SupportsIndex, TypeGuard
 
 from openpyxl.descriptors import Strict, String
 from openpyxl.descriptors.base import Integer
@@ -58,7 +58,7 @@ def is_datetime(fmt: None) -> None: ...
 @overload
 def is_datetime(fmt: str) -> Literal["datetime", "date", "time"] | None: ...
 def is_builtin(fmt: str | None) -> TypeGuard[str]: ...
-def builtin_format_code(index): ...
+def builtin_format_code(index: int) -> str | None: ...
 @overload
 def builtin_format_id(fmt: None) -> None: ...
 @overload
@@ -81,4 +81,4 @@ class NumberFormatList(Serialisable):
     def __init__(self, count: Unused = None, numFmt=()) -> None: ...
     @property
     def count(self) -> int: ...
-    def __getitem__(self, idx): ...
+    def __getitem__(self, idx: SupportsIndex) -> NumberFormat: ...

stubs/openpyxl/openpyxl/utils/cell.pyi

@@ -1,11 +1,13 @@
-from _typeshed import Incomplete
 from collections.abc import Generator
 from re import Pattern
-from typing_extensions import Final
+from typing_extensions import Final, TypeAlias
+
+# "1:1" | "A1:A1" | "A:A"
+_RangeBoundariesTuple: TypeAlias = tuple[None, int, None, int] | tuple[int, int, int, int] | tuple[int, None, int, None]
 
 COORD_RE: Final[Pattern[str]]
-COL_RANGE: Final = """[A-Z]{1,3}:[A-Z]{1,3}:"""
-ROW_RANGE: Final = r"""\d+:\d+:"""
+COL_RANGE: Final = "[A-Z]{1,3}:[A-Z]{1,3}:"
+ROW_RANGE: Final = r"\d+:\d+:"
 RANGE_EXPR: Final[str]
 ABSOLUTE_RE: Final[Pattern[str]]
 SHEET_TITLE: Final[str]
@@ -16,9 +18,9 @@ def coordinate_from_string(coord_string: str) -> tuple[str, int]: ...
 def absolute_coordinate(coord_string: str) -> str: ...
 def get_column_letter(idx: int) -> str: ...
 def column_index_from_string(str_col: str) -> int: ...
-def range_boundaries(range_string: str) -> tuple[int, int, int, int]: ...
-def rows_from_range(range_string) -> Generator[Incomplete, None, None]: ...
-def cols_from_range(range_string) -> Generator[Incomplete, None, None]: ...
+def range_boundaries(range_string: str) -> _RangeBoundariesTuple: ...
+def rows_from_range(range_string: str) -> Generator[tuple[str, ...], None, None]: ...
+def cols_from_range(range_string: str) -> Generator[tuple[str, ...], None, None]: ...
 def coordinate_to_tuple(coordinate: str) -> tuple[int, int]: ...
-def range_to_tuple(range_string: str) -> tuple[str, tuple[int, int, int, int]]: ...
+def range_to_tuple(range_string: str) -> tuple[str, _RangeBoundariesTuple]: ...
 def quote_sheetname(sheetname: str) -> str: ...

stubs/openpyxl/openpyxl/utils/escape.pyi

@@ -1,2 +1,2 @@
-def escape(value): ...
-def unescape(value): ...
+def escape(value: str) -> str: ...
+def unescape(value: str) -> str: ...

stubs/openpyxl/openpyxl/workbook/child.pyi

@@ -1,17 +1,17 @@
-from _typeshed import Incomplete
+from collections.abc import Iterable
 from re import Pattern
 from typing_extensions import Final
 
 from openpyxl import _Decodable
 from openpyxl.workbook.workbook import Workbook
-from openpyxl.worksheet.header_footer import HeaderFooterItem
+from openpyxl.worksheet.header_footer import HeaderFooter, HeaderFooterItem
 
 INVALID_TITLE_REGEX: Final[Pattern[str]]
 
-def avoid_duplicate_name(names, value): ...
+def avoid_duplicate_name(names: Iterable[str], value: str) -> str: ...
 
 class _WorkbookChild:
-    HeaderFooter: Incomplete
+    HeaderFooter: HeaderFooter
     def __init__(self, parent: Workbook | None = None, title: str | _Decodable | None = None) -> None: ...
     @property
     def parent(self) -> Workbook | None: ...

stubs/openpyxl/openpyxl/workbook/workbook.pyi

@@ -1,6 +1,7 @@
-from _typeshed import Incomplete
+from _typeshed import Incomplete, Unused
 from collections.abc import Iterator
 from datetime import datetime
+from typing import Any
 from typing_extensions import Final
 from zipfile import ZipFile
 
@@ -46,7 +47,10 @@ class Workbook:
     def active(self) -> _WorkbookChild | None: ...
     @active.setter
     def active(self, value: _WorkbookChild | int) -> None: ...
-    def create_sheet(self, title: str | _Decodable | None = None, index: int | None = None): ...
+    # Could be generic based on write_only
+    def create_sheet(
+        self, title: str | _Decodable | None = None, index: int | None = None
+    ) -> Any: ...  # AnyOf[WriteOnlyWorksheet, Worksheet]
     def move_sheet(self, sheet: Worksheet | str, offset: int = 0) -> None: ...
     def remove(self, worksheet: Worksheet) -> None: ...
     def remove_sheet(self, worksheet: Worksheet) -> None: ...
@@ -66,11 +70,7 @@ class Workbook:
     @property
     def sheetnames(self) -> list[str]: ...
     def create_named_range(
-        self,
-        name: str,
-        worksheet: Worksheet | None = None,
-        value: str | Incomplete | None = None,
-        scope: Incomplete | None = None,
+        self, name: str, worksheet: Worksheet | None = None, value: str | Incomplete | None = None, scope: Unused = None
     ) -> None: ...
     def add_named_style(self, style: NamedStyle) -> None: ...
     @property

stubs/openpyxl/openpyxl/worksheet/_read_only.pyi

@@ -4,9 +4,10 @@ from collections.abc import Generator
 from openpyxl import _VisibilityType
 from openpyxl.cell import _CellValue
 from openpyxl.cell.cell import Cell
+from openpyxl.utils.cell import _RangeBoundariesTuple
 from openpyxl.worksheet.worksheet import Worksheet
 
-def read_dimension(source): ...
+def read_dimension(source) -> _RangeBoundariesTuple | None: ...
 
 class ReadOnlyWorksheet:
     cell = Worksheet.cell

stubs/openpyxl/openpyxl/worksheet/_reader.pyi

@@ -1,11 +1,14 @@
-from _typeshed import Incomplete
+from _typeshed import Incomplete, SupportsGetItem, Unused
 from collections.abc import Container, Generator
 from datetime import datetime
 from typing_extensions import Final
+from xml.etree.ElementTree import _FileRead
 
 from openpyxl.cell.rich_text import CellRichText
-from openpyxl.descriptors.serialisable import _ChildSerialisableTreeElement
+from openpyxl.descriptors.serialisable import _ChildSerialisableTreeElement, _SerialisableTreeElement
+from openpyxl.utils.cell import _RangeBoundariesTuple
 
+from ..xml._functions_overloads import _HasAttrib, _SupportsIterAndAttrib
 from .hyperlink import HyperlinkList
 from .pagebreak import ColBreak, RowBreak
 from .protection import SheetProtection
@@ -46,15 +49,15 @@ class WorkSheetParser:
     min_row: Incomplete | None
     min_col: Incomplete | None
     epoch: datetime
-    source: Incomplete
-    shared_strings: Incomplete
+    source: _FileRead
+    shared_strings: SupportsGetItem[int, Incomplete]
     data_only: bool
     shared_formulae: dict[Incomplete, Incomplete]
     row_counter: int
     col_counter: int
     tables: TablePartList
-    date_formats: Container[Incomplete]
-    timedelta_formats: Container[Incomplete]
+    date_formats: Container[int]
+    timedelta_formats: Container[int]
     row_dimensions: dict[Incomplete, Incomplete]
     column_dimensions: dict[Incomplete, Incomplete]
     number_formats: list[Incomplete]
@@ -70,39 +73,41 @@ class WorkSheetParser:
 
     def __init__(
         self,
-        src,
-        shared_strings,
+        src: _FileRead,
+        shared_strings: SupportsGetItem[int, Incomplete],
         data_only: bool = False,
         epoch: datetime = ...,
-        date_formats: Container[Incomplete] = ...,
-        timedelta_formats: Container[Incomplete] = ...,
+        date_formats: Container[int] = ...,
+        timedelta_formats: Container[int] = ...,
         rich_text: bool = False,
     ) -> None: ...
     def parse(self) -> Generator[Incomplete, None, None]: ...
-    def parse_dimensions(self): ...
-    def parse_cell(self, element): ...
+    def parse_dimensions(self) -> _RangeBoundariesTuple | None: ...
+    def parse_cell(self, element) -> dict[str, Incomplete]: ...
     def parse_formula(self, element): ...
-    def parse_column_dimensions(self, col) -> None: ...
-    def parse_row(self, row): ...
-    def parse_formatting(self, element) -> None: ...
-    def parse_sheet_protection(self, element) -> None: ...
-    def parse_extensions(self, element) -> None: ...
-    def parse_legacy(self, element) -> None: ...
-    def parse_row_breaks(self, element) -> None: ...
-    def parse_col_breaks(self, element) -> None: ...
-    def parse_custom_views(self, element) -> None: ...
+    def parse_column_dimensions(self, col: _HasAttrib) -> None: ...
+    def parse_row(self, row: _SupportsIterAndAttrib) -> tuple[int, list[dict[str, Incomplete]]]: ...
+    def parse_formatting(self, element: _ChildSerialisableTreeElement) -> None: ...
+    def parse_sheet_protection(self, element: _SerialisableTreeElement) -> None: ...
+    def parse_extensions(self, element: _ChildSerialisableTreeElement) -> None: ...
+    def parse_legacy(self, element: _ChildSerialisableTreeElement) -> None: ...
+    def parse_row_breaks(self, element: _ChildSerialisableTreeElement) -> None: ...
+    def parse_col_breaks(self, element: _ChildSerialisableTreeElement) -> None: ...
+    def parse_custom_views(self, element: Unused) -> None: ...
 
 class WorksheetReader:
     ws: Incomplete
-    parser: Incomplete
-    tables: Incomplete
-    def __init__(self, ws, xml_source, shared_strings, data_only, rich_text: bool) -> None: ...
+    parser: WorkSheetParser
+    tables: list[Incomplete]
+    def __init__(
+        self, ws, xml_source: _FileRead, shared_strings: SupportsGetItem[int, Incomplete], data_only: bool, rich_text: bool
+    ) -> None: ...
     def bind_cells(self) -> None: ...
     def bind_formatting(self) -> None: ...
     def bind_tables(self) -> None: ...
     def bind_merged_cells(self) -> None: ...
     def bind_hyperlinks(self) -> None: ...
-    def normalize_merged_cell_link(self, coord): ...
+    def normalize_merged_cell_link(self, coord: str) -> Incomplete | None: ...
     def bind_col_dimensions(self) -> None: ...
     def bind_row_dimensions(self) -> None: ...
     def bind_properties(self) -> None: ...

stubs/openpyxl/openpyxl/worksheet/_writer.pyi

@@ -14,20 +14,20 @@ _OutType: TypeAlias = _SupportsCloseAndWrite | StrPath
 
 ALL_TEMP_FILES: list[str]
 
-def create_temporary_file(suffix: str = ""): ...
+def create_temporary_file(suffix: str = "") -> str: ...
 
 class WorksheetWriter:
     ws: Incomplete
     out: _OutType
-    xf: Incomplete
+    xf: Generator[Incomplete | None, Incomplete, None]
     def __init__(self, ws, out: _OutType | None = None) -> None: ...
     def write_properties(self) -> None: ...
     def write_dimensions(self) -> None: ...
     def write_format(self) -> None: ...
     def write_views(self) -> None: ...
     def write_cols(self) -> None: ...
     def write_top(self) -> None: ...
-    def rows(self): ...
+    def rows(self) -> list[tuple[int, list[Incomplete]]]: ...
     def write_rows(self) -> None: ...
     def write_row(self, xf, row, row_idx) -> None: ...
     def write_protection(self) -> None: ...
@@ -50,5 +50,5 @@ class WorksheetWriter:
     def write_tail(self) -> None: ...
     def write(self) -> None: ...
     def close(self) -> None: ...
-    def read(self): ...
+    def read(self) -> bytes: ...
     def cleanup(self) -> None: ...