Improve openpyxl annotations (#9764)

Co-authored-by: ArnabRollin <[email protected]>
Co-authored-by: ArnabRollin <[email protected]>
Co-authored-by: Alex Waygood <[email protected]>

Author: 3 people

stubs/openpyxl/openpyxl/cell/cell.pyi

@@ -1,6 +1,11 @@
 from _typeshed import Incomplete
+from datetime import datetime
 
+from openpyxl.comments.comments import Comment
+from openpyxl.styles.cell_style import StyleArray
 from openpyxl.styles.styleable import StyleableObject
+from openpyxl.worksheet.hyperlink import Hyperlink
+from openpyxl.worksheet.worksheet import Worksheet
 
 __docformat__: str
 TIME_TYPES: Incomplete
@@ -19,60 +24,60 @@ TYPE_ERROR: str
 TYPE_FORMULA_CACHE_STRING: str
 VALID_TYPES: Incomplete
 
-def get_type(t, value): ...
-def get_time_format(t): ...
+def get_type(t: type, value: object) -> str | None: ...
+def get_time_format(t: datetime) -> str: ...
 
 class Cell(StyleableObject):
-    row: Incomplete
-    column: Incomplete
+    row: int
+    column: int
     data_type: str
     def __init__(
         self,
-        worksheet,
-        row: Incomplete | None = ...,
-        column: Incomplete | None = ...,
-        value: Incomplete | None = ...,
-        style_array: Incomplete | None = ...,
+        worksheet: Worksheet,
+        row: int | None = ...,
+        column: int | None = ...,
+        value: str | float | datetime | None = ...,
+        style_array: StyleArray | None = ...,
     ) -> None: ...
     @property
-    def coordinate(self): ...
+    def coordinate(self) -> str: ...
     @property
-    def col_idx(self): ...
+    def col_idx(self) -> int: ...
     @property
-    def column_letter(self): ...
+    def column_letter(self) -> str: ...
     @property
-    def encoding(self): ...
+    def encoding(self) -> str: ...
     @property
-    def base_date(self): ...
-    def check_string(self, value): ...
-    def check_error(self, value): ...
+    def base_date(self) -> datetime: ...
+    def check_string(self, value: str): ...
+    def check_error(self, value: object) -> str: ...
     @property
-    def value(self): ...
+    def value(self) -> str | float | datetime | None: ...
     @value.setter
-    def value(self, value) -> None: ...
+    def value(self, value: str | float | datetime | None) -> None: ...
     @property
-    def internal_value(self): ...
+    def internal_value(self) -> str | float | datetime | None: ...
     @property
-    def hyperlink(self): ...
+    def hyperlink(self) -> Hyperlink | None: ...
     @hyperlink.setter
-    def hyperlink(self, val) -> None: ...
+    def hyperlink(self, val: Hyperlink | str | None) -> None: ...
     @property
-    def is_date(self): ...
-    def offset(self, row: int = ..., column: int = ...): ...
+    def is_date(self) -> bool: ...
+    def offset(self, row: int = ..., column: int = ...) -> Cell: ...
     @property
-    def comment(self): ...
+    def comment(self) -> Comment | None: ...
     @comment.setter
-    def comment(self, value) -> None: ...
+    def comment(self, value: Comment | None) -> None: ...
 
 class MergedCell(StyleableObject):
     data_type: str
-    comment: Incomplete
-    hyperlink: Incomplete
-    row: Incomplete
-    column: Incomplete
-    def __init__(self, worksheet, row: Incomplete | None = ..., column: Incomplete | None = ...) -> None: ...
+    comment: Comment | None
+    hyperlink: Hyperlink | None
+    row: int
+    column: int
+    def __init__(self, worksheet: Worksheet, row: int | None = ..., column: int | None = ...) -> None: ...
     @property
-    def coordinate(self): ...
-    value: Incomplete
+    def coordinate(self) -> str: ...
+    value: str | float | int | datetime | None
 
-def WriteOnlyCell(ws: Incomplete | None = ..., value: Incomplete | None = ...): ...
+def WriteOnlyCell(ws: Worksheet | None = ..., value: str | float | datetime | None = ...) -> Cell: ...

stubs/openpyxl/openpyxl/reader/excel.pyi

@@ -1,4 +1,8 @@
-from _typeshed import Incomplete
+from _typeshed import Incomplete, StrPath, SupportsRead
+
+from openpyxl.chartsheet.chartsheet import Chartsheet
+from openpyxl.packaging.relationship import Relationship
+from openpyxl.workbook.workbook import Workbook
 
 SUPPORTED_FORMATS: Incomplete
 
@@ -10,7 +14,9 @@ class ExcelReader:
     data_only: Incomplete
     keep_links: Incomplete
     shared_strings: Incomplete
-    def __init__(self, fn, read_only: bool = ..., keep_vba=..., data_only: bool = ..., keep_links: bool = ...) -> None: ...
+    def __init__(
+        self, fn: SupportsRead[bytes] | str, read_only: bool = ..., keep_vba=..., data_only: bool = ..., keep_links: bool = ...
+    ) -> None: ...
     package: Incomplete
     def read_manifest(self) -> None: ...
     def read_strings(self) -> None: ...
@@ -19,8 +25,14 @@ class ExcelReader:
     def read_workbook(self) -> None: ...
     def read_properties(self) -> None: ...
     def read_theme(self) -> None: ...
-    def read_chartsheet(self, sheet, rel) -> None: ...
+    def read_chartsheet(self, sheet: Chartsheet, rel: Relationship) -> None: ...
     def read_worksheets(self) -> None: ...
     def read(self) -> None: ...
 
-def load_workbook(filename, read_only: bool = ..., keep_vba=..., data_only: bool = ..., keep_links: bool = ...): ...
+def load_workbook(
+    filename: SupportsRead[bytes] | StrPath,
+    read_only: bool = ...,
+    keep_vba: bool = ...,
+    data_only: bool = ...,
+    keep_links: bool = ...,
+) -> Workbook: ...

stubs/openpyxl/openpyxl/workbook/workbook.pyi

@@ -1,4 +1,14 @@
-from _typeshed import Incomplete
+from _typeshed import Incomplete, StrPath
+from collections.abc import Iterator
+from datetime import datetime
+from typing import IO
+
+from openpyxl.chartsheet.chartsheet import Chartsheet
+from openpyxl.styles.named_styles import NamedStyle
+from openpyxl.workbook.child import _WorkbookChild
+from openpyxl.workbook.defined_name import DefinedName
+from openpyxl.worksheet._write_only import WriteOnlyWorksheet
+from openpyxl.worksheet.worksheet import Worksheet
 
 INTEGER_TYPES: Incomplete
 
@@ -20,54 +30,54 @@ class Workbook:
     views: Incomplete
     def __init__(self, write_only: bool = ..., iso_dates: bool = ...) -> None: ...
     @property
-    def epoch(self): ...
+    def epoch(self) -> datetime: ...
     @epoch.setter
-    def epoch(self, value) -> None: ...
+    def epoch(self, value: datetime) -> None: ...
     @property
-    def read_only(self): ...
+    def read_only(self) -> bool: ...
     @property
-    def data_only(self): ...
+    def data_only(self) -> bool: ...
     @property
-    def write_only(self): ...
+    def write_only(self) -> bool: ...
     @property
-    def excel_base_date(self): ...
+    def excel_base_date(self) -> datetime: ...
     @property
-    def active(self): ...
+    def active(self) -> _WorkbookChild | None: ...
     @active.setter
-    def active(self, value) -> None: ...
-    def create_sheet(self, title: Incomplete | None = ..., index: Incomplete | None = ...): ...
-    def move_sheet(self, sheet, offset: int = ...) -> None: ...
-    def remove(self, worksheet) -> None: ...
-    def remove_sheet(self, worksheet) -> None: ...
-    def create_chartsheet(self, title: Incomplete | None = ..., index: Incomplete | None = ...): ...
-    def get_sheet_by_name(self, name): ...
-    def __contains__(self, key): ...
-    def index(self, worksheet): ...
-    def get_index(self, worksheet): ...
-    def __getitem__(self, key): ...
-    def __delitem__(self, key) -> None: ...
-    def __iter__(self): ...
-    def get_sheet_names(self): ...
+    def active(self, value: _WorkbookChild | int) -> None: ...
+    def create_sheet(self, title: str | None = ..., index: int | None = ...): ...
+    def move_sheet(self, sheet: Worksheet | str, offset: int = ...) -> None: ...
+    def remove(self, worksheet: Worksheet) -> None: ...
+    def remove_sheet(self, worksheet: Worksheet) -> None: ...
+    def create_chartsheet(self, title: str | None = ..., index: int | None = ...) -> Chartsheet: ...
+    def get_sheet_by_name(self, name: str) -> Worksheet: ...
+    def __contains__(self, key: str) -> bool: ...
+    def index(self, worksheet: Worksheet) -> int: ...
+    def get_index(self, worksheet: Worksheet) -> int: ...
+    def __getitem__(self, key: str) -> Worksheet: ...
+    def __delitem__(self, key: str) -> None: ...
+    def __iter__(self) -> Iterator[Worksheet]: ...
+    def get_sheet_names(self) -> list[Worksheet]: ...
     @property
-    def worksheets(self): ...
+    def worksheets(self) -> list[Worksheet]: ...
     @property
-    def chartsheets(self): ...
+    def chartsheets(self) -> list[Chartsheet]: ...
     @property
-    def sheetnames(self): ...
+    def sheetnames(self) -> list[str]: ...
     def create_named_range(
-        self, name, worksheet: Incomplete | None = ..., value: Incomplete | None = ..., scope: Incomplete | None = ...
+        self, name: str, worksheet: Worksheet | None = ..., value: str | Incomplete | None = ..., scope: Incomplete | None = ...
     ) -> None: ...
-    def add_named_style(self, style) -> None: ...
+    def add_named_style(self, style: NamedStyle) -> None: ...
     @property
-    def named_styles(self): ...
-    def get_named_ranges(self): ...
-    def add_named_range(self, named_range) -> None: ...
-    def get_named_range(self, name): ...
-    def remove_named_range(self, named_range) -> None: ...
+    def named_styles(self) -> list[str]: ...
+    def get_named_ranges(self) -> list[DefinedName] | tuple[DefinedName, ...]: ...
+    def add_named_range(self, named_range: DefinedName) -> None: ...
+    def get_named_range(self, name: str) -> DefinedName: ...
+    def remove_named_range(self, named_range: DefinedName) -> None: ...
     @property
-    def mime_type(self): ...
-    def save(self, filename) -> None: ...
+    def mime_type(self) -> str: ...
+    def save(self, filename: StrPath | IO[bytes]) -> None: ...
     @property
-    def style_names(self): ...
-    def copy_worksheet(self, from_worksheet): ...
+    def style_names(self) -> list[str]: ...
+    def copy_worksheet(self, from_worksheet: Worksheet) -> Worksheet | WriteOnlyWorksheet: ...
     def close(self) -> None: ...