Skip to content

Commit af36a15

Browse files
AvasamAvasam
authored
Complete openpyxl title type annotations (#10563)
1 parent da946f3 commit af36a15

14 files changed

+42
-26
lines changed

‎stubs/openpyxl/openpyxl/__init__.pyi

+6
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
from typing import Protocol
2+
13
from openpyxl.compat.numbers import NUMPY as NUMPY
24
from openpyxl.reader.excel import load_workbook as load_workbook
35
from openpyxl.workbook import Workbook as Workbook
@@ -14,3 +16,7 @@ from ._constants import (
1416

1517
DEBUG: bool
1618
open = load_workbook
19+
20+
# Utility types reused elsewhere
21+
class _Decodable(Protocol): # noqa: Y046
22+
def decode(self, __encoding: str) -> str: ...

‎stubs/openpyxl/openpyxl/chart/_chart.pyi

+2-1
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ from typing_extensions import Literal, TypeAlias
55
from openpyxl.chart.layout import Layout
66
from openpyxl.chart.legend import Legend
77
from openpyxl.chart.shapes import GraphicalProperties
8+
from openpyxl.chart.title import TitleDescriptor
89
from openpyxl.descriptors.base import Alias, Bool, Integer, MinMax, Set, Typed, _ConvertibleToInt
910
from openpyxl.descriptors.serialisable import Serialisable
1011

@@ -25,7 +26,7 @@ class ChartBase(Serialisable):
2526
display_blanks: Set[_ChartBaseDisplayBlanks]
2627
ser: Incomplete
2728
series: Alias
28-
title: Incomplete
29+
title: TitleDescriptor
2930
anchor: str
3031
width: int
3132
height: float

‎stubs/openpyxl/openpyxl/chart/axis.pyi

+4-3
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ from typing_extensions import Literal, TypeAlias
55
from openpyxl.chart.layout import Layout
66
from openpyxl.chart.shapes import GraphicalProperties
77
from openpyxl.chart.text import RichText, Text
8+
from openpyxl.chart.title import Title, TitleDescriptor
89
from openpyxl.descriptors.base import Alias, Typed, _ConvertibleToBool, _ConvertibleToFloat, _ConvertibleToInt
910
from openpyxl.descriptors.excel import ExtensionList
1011
from openpyxl.descriptors.nested import (
@@ -70,7 +71,7 @@ class _BaseAxis(Serialisable):
7071
axPos: NestedSet[_BaseAxisAxPos]
7172
majorGridlines: Typed[ChartLines, Literal[True]]
7273
minorGridlines: Typed[ChartLines, Literal[True]]
73-
title: Incomplete
74+
title: TitleDescriptor
7475
numFmt: Incomplete
7576
number_format: Alias
7677
majorTickMark: NestedNoneSet[_BaseAxisTickMark]
@@ -93,7 +94,7 @@ class _BaseAxis(Serialisable):
9394
axPos: _HasTagAndGet[_BaseAxisAxPos] | _BaseAxisAxPos,
9495
majorGridlines: ChartLines | None,
9596
minorGridlines: ChartLines | None,
96-
title: Incomplete | None,
97+
title: str | Title | None,
9798
numFmt: Incomplete | None,
9899
majorTickMark: _NestedNoneSetParam[_BaseAxisTickMark],
99100
minorTickMark: _NestedNoneSetParam[_BaseAxisTickMark],
@@ -113,7 +114,7 @@ class _BaseAxis(Serialisable):
113114
axPos: _HasTagAndGet[_BaseAxisAxPos] | _BaseAxisAxPos = "l",
114115
majorGridlines: ChartLines | None = None,
115116
minorGridlines: ChartLines | None = None,
116-
title: Incomplete | None = None,
117+
title: str | Title | None = None,
117118
numFmt: Incomplete | None = None,
118119
majorTickMark: Incomplete | None = None,
119120
minorTickMark: Incomplete | None = None,

‎stubs/openpyxl/openpyxl/chart/reference.pyi

+2-2
Original file line numberDiff line numberDiff line change
@@ -7,8 +7,8 @@ from openpyxl.descriptors import Strict
77
from openpyxl.descriptors.base import MinMax, String, _ConvertibleToInt
88

99
class DummyWorksheet:
10-
title: Incomplete
11-
def __init__(self, title) -> None: ...
10+
title: str
11+
def __init__(self, title: str) -> None: ...
1212

1313
class Reference(Strict):
1414
min_row: MinMax[int, Literal[False]]

‎stubs/openpyxl/openpyxl/chart/series_factory.pyi

+1-1
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,6 @@ def SeriesFactory(
44
values,
55
xvalues: Incomplete | None = None,
66
zvalues: Incomplete | None = None,
7-
title: Incomplete | None = None,
7+
title: object = None,
88
title_from_data: bool = False,
99
): ...

‎stubs/openpyxl/openpyxl/chart/title.pyi

+4-4
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
from _typeshed import Incomplete, Unused
1+
from _typeshed import Unused
22
from typing import ClassVar
33
from typing_extensions import Literal
44

@@ -35,9 +35,9 @@ class Title(Serialisable):
3535
extLst: Unused = None,
3636
) -> None: ...
3737

38-
def title_maker(text): ...
38+
def title_maker(text) -> Title: ...
3939

40-
class TitleDescriptor(Typed[Title, Incomplete]):
40+
class TitleDescriptor(Typed[Title, Literal[True]]):
4141
expected_type: type[Title]
4242
allow_none: Literal[True]
43-
def __set__(self, instance: Serialisable | Strict, value) -> None: ...
43+
def __set__(self, instance: Serialisable | Strict, value: str | Title | None) -> None: ...

‎stubs/openpyxl/openpyxl/chartsheet/chartsheet.pyi

+2-1
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@ from _typeshed import Incomplete, Unused
22
from typing import ClassVar
33
from typing_extensions import Literal, TypeAlias
44

5+
from openpyxl import _Decodable
56
from openpyxl.chartsheet.custom import CustomChartsheetViews
67
from openpyxl.chartsheet.properties import ChartsheetProperties
78
from openpyxl.chartsheet.protection import ChartsheetProtection
@@ -52,7 +53,7 @@ class Chartsheet(_WorkbookChild, Serialisable):
5253
webPublishItems: WebPublishItems | None = None,
5354
extLst: Unused = None,
5455
parent: Incomplete | None = None,
55-
title: str = "",
56+
title: str | _Decodable | None = "",
5657
sheet_state: _ChartsheetSheetState = "visible",
5758
) -> None: ...
5859
def add_chart(self, chart) -> None: ...

‎stubs/openpyxl/openpyxl/workbook/child.pyi

+4-2
Original file line numberDiff line numberDiff line change
@@ -2,21 +2,23 @@ from _typeshed import Incomplete
22
from re import Pattern
33
from typing_extensions import Final
44

5+
from openpyxl import _Decodable
6+
57
INVALID_TITLE_REGEX: Final[Pattern[str]]
68

79
def avoid_duplicate_name(names, value): ...
810

911
class _WorkbookChild:
1012
HeaderFooter: Incomplete
11-
def __init__(self, parent: Incomplete | None = None, title: Incomplete | None = None) -> None: ...
13+
def __init__(self, parent: Incomplete | None = None, title: str | _Decodable | None = None) -> None: ...
1214
@property
1315
def parent(self): ...
1416
@property
1517
def encoding(self): ...
1618
@property
1719
def title(self) -> str: ...
1820
@title.setter
19-
def title(self, value: str | bytes) -> None: ...
21+
def title(self, value: str | _Decodable) -> None: ...
2022
@property
2123
def oddHeader(self): ...
2224
@oddHeader.setter

‎stubs/openpyxl/openpyxl/workbook/workbook.pyi

+3-2
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@ from datetime import datetime
44
from typing import IO
55
from typing_extensions import Final
66

7+
from openpyxl import _Decodable
78
from openpyxl.chartsheet.chartsheet import Chartsheet
89
from openpyxl.styles.named_styles import NamedStyle
910
from openpyxl.workbook.child import _WorkbookChild
@@ -45,11 +46,11 @@ class Workbook:
4546
def active(self) -> _WorkbookChild | None: ...
4647
@active.setter
4748
def active(self, value: _WorkbookChild | int) -> None: ...
48-
def create_sheet(self, title: str | None = None, index: int | None = None): ...
49+
def create_sheet(self, title: str | _Decodable | None = None, index: int | None = None): ...
4950
def move_sheet(self, sheet: Worksheet | str, offset: int = 0) -> None: ...
5051
def remove(self, worksheet: Worksheet) -> None: ...
5152
def remove_sheet(self, worksheet: Worksheet) -> None: ...
52-
def create_chartsheet(self, title: str | None = None, index: int | None = None) -> Chartsheet: ...
53+
def create_chartsheet(self, title: str | _Decodable | None = None, index: int | None = None) -> Chartsheet: ...
5354
def get_sheet_by_name(self, name: str) -> Worksheet: ...
5455
def __contains__(self, key: str) -> bool: ...
5556
def index(self, worksheet: Worksheet) -> int: ...

‎stubs/openpyxl/openpyxl/worksheet/_read_only.pyi

+2-2
Original file line numberDiff line numberDiff line change
@@ -14,9 +14,9 @@ class ReadOnlyWorksheet:
1414
__getitem__ = Worksheet.__getitem__
1515
__iter__ = Worksheet.__iter__
1616
parent: Incomplete
17-
title: Incomplete
17+
title: str
1818
sheet_state: str
19-
def __init__(self, parent_workbook, title, worksheet_path, shared_strings) -> None: ...
19+
def __init__(self, parent_workbook, title: str, worksheet_path, shared_strings) -> None: ...
2020
def calculate_dimension(self, force: bool = False): ...
2121
def reset_dimensions(self) -> None: ...
2222
@property

‎stubs/openpyxl/openpyxl/worksheet/_write_only.pyi

+2-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
from _typeshed import Incomplete
22

3+
from openpyxl import _Decodable
34
from openpyxl.workbook.child import _WorkbookChild
45

56
class WriteOnlyWorksheet(_WorkbookChild):
@@ -17,7 +18,7 @@ class WriteOnlyWorksheet(_WorkbookChild):
1718
print_area: Incomplete
1819
@property
1920
def sheet_view(self): ...
20-
def __init__(self, parent, title) -> None: ...
21+
def __init__(self, parent, title: str | _Decodable | None) -> None: ...
2122
@property
2223
def closed(self): ...
2324
def close(self) -> None: ...

‎stubs/openpyxl/openpyxl/worksheet/cell_range.pyi

+6-4
Original file line numberDiff line numberDiff line change
@@ -12,17 +12,19 @@ class CellRange(Serialisable):
1212
min_row: MinMax[int, Literal[False]]
1313
max_col: MinMax[int, Literal[False]]
1414
max_row: MinMax[int, Literal[False]]
15-
title: Incomplete
15+
# Could be None if the caller forgot to set title and range_string doesn't contain "!"
16+
# but that's not intended and will lead to errors (ie: can't be None in __str__)
17+
title: str
1618

1719
@overload
1820
def __init__(
1921
self,
20-
range_string: Incomplete,
22+
range_string: str | None,
2123
min_col: Unused = None,
2224
min_row: Unused = None,
2325
max_col: Unused = None,
2426
max_row: Unused = None,
25-
title: Incomplete | None = None,
27+
title: str | None = None,
2628
) -> None: ...
2729
@overload
2830
def __init__(
@@ -33,7 +35,7 @@ class CellRange(Serialisable):
3335
min_row: _ConvertibleToInt,
3436
max_col: _ConvertibleToInt,
3537
max_row: _ConvertibleToInt,
36-
title: Incomplete | None = None,
38+
title: str,
3739
) -> None: ...
3840
@property
3941
def bounds(self): ...

‎stubs/openpyxl/openpyxl/worksheet/print_settings.pyi

+2-2
Original file line numberDiff line numberDiff line change
@@ -40,12 +40,12 @@ class PrintTitles(Strict):
4040
title: String[Literal[False]]
4141
def __init__(self, cols: ColRange | None = None, rows: RowRange | None = None, title: str = "") -> None: ...
4242
@classmethod
43-
def from_string(cls, value) -> Self: ...
43+
def from_string(cls, value: str) -> Self: ...
4444
def __eq__(self, other: object) -> bool: ...
4545

4646
class PrintArea(MultiCellRange):
4747
title: str
4848
@classmethod
4949
def from_string(cls, value) -> Self: ...
50-
def __init__(self, ranges=(), title: str = "") -> None: ...
50+
def __init__(self, ranges=(), title: Unused = "") -> None: ...
5151
def __eq__(self, other): ...

‎stubs/openpyxl/openpyxl/worksheet/worksheet.pyi

+2-1
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@ from datetime import datetime
44
from typing import Any, overload
55
from typing_extensions import Final, Literal
66

7+
from openpyxl import _Decodable
78
from openpyxl.cell.cell import Cell, _CellValue
89
from openpyxl.formatting.formatting import ConditionalFormattingList
910
from openpyxl.workbook.child import _WorkbookChild
@@ -66,7 +67,7 @@ class Worksheet(_WorkbookChild):
6667
sheet_format: SheetFormatProperties
6768
scenarios: ScenarioList
6869

69-
def __init__(self, parent: Workbook, title: str | None = None) -> None: ...
70+
def __init__(self, parent: Workbook, title: str | _Decodable | None = None) -> None: ...
7071
@property
7172
def sheet_view(self) -> SheetView: ...
7273
@property

0 commit comments

Comments
 (0)