Type openpyxl functions module and its usages (#10322)

stubs/openpyxl/@tests/stubtest_allowlist.txt

@@ -1,13 +1,14 @@
-# "cls" argument has wrong name in implementation.
-openpyxl.descriptors.slots.AutoSlotProperties.__new__
+# The actual runtime definition depends on what else is installed
+# (lxml, defusedxml, et_xmlfile)
+openpyxl.xml._functions_overloads
+openpyxl.xml.functions.Element.__iter__
+openpyxl.xml.functions.fromstring
+openpyxl.xml.functions.iterparse
+openpyxl.xml.functions.tostring
 
 # Requires numpy to be installed
 openpyxl.utils.dataframe
 
-# Element can be imported from lxml or xml.etree, so the attributes can
-# differ at runtime.
-openpyxl.xml.functions.Element.*
-
 # Fake getters
 openpyxl\.descriptors\..*\.__get__
 

stubs/openpyxl/@tests/test_cases/check_nested_descriptors.py

@@ -20,9 +20,9 @@ from openpyxl.descriptors.nested import (
     NestedString,
     NestedText,
     NestedValue,
-    _HasTagAndGet,
 )
 from openpyxl.descriptors.serialisable import Serialisable
+from openpyxl.xml._functions_overloads import _HasTagAndGet
 from openpyxl.xml.functions import Element
 
 _ = object()  # More concise discard object for casts

stubs/openpyxl/openpyxl/chart/_3d.pyi

@@ -6,9 +6,11 @@ from openpyxl.chart.picture import PictureOptions
 from openpyxl.chart.shapes import GraphicalProperties
 from openpyxl.descriptors.base import Alias, Typed, _ConvertibleToBool, _ConvertibleToFloat, _ConvertibleToInt
 from openpyxl.descriptors.excel import ExtensionList
-from openpyxl.descriptors.nested import NestedBool, NestedInteger, NestedMinMax, _HasTagAndGet
+from openpyxl.descriptors.nested import NestedBool, NestedInteger, NestedMinMax
 from openpyxl.descriptors.serialisable import Serialisable
 
+from ..xml._functions_overloads import _HasTagAndGet
+
 class View3D(Serialisable):
     tagname: ClassVar[str]
     rotX: NestedMinMax[float, Literal[True]]

stubs/openpyxl/openpyxl/chart/area_chart.pyi

@@ -6,8 +6,9 @@ from openpyxl.chart.axis import ChartLines, NumericAxis, SeriesAxis, TextAxis
 from openpyxl.chart.label import DataLabelList
 from openpyxl.descriptors.base import Alias, Typed, _ConvertibleToBool
 from openpyxl.descriptors.excel import ExtensionList
-from openpyxl.descriptors.nested import NestedBool, NestedSet, _HasTagAndGet
+from openpyxl.descriptors.nested import NestedBool, NestedSet
 
+from ..xml._functions_overloads import _HasTagAndGet
 from ._chart import ChartBase
 
 _AreaChartBaseGrouping: TypeAlias = Literal["percentStacked", "standard", "stacked"]

stubs/openpyxl/openpyxl/chart/axis.pyi

@@ -14,11 +14,12 @@ from openpyxl.descriptors.nested import (
     NestedMinMax,
     NestedNoneSet,
     NestedSet,
-    _HasTagAndGet,
     _NestedNoneSetParam,
 )
 from openpyxl.descriptors.serialisable import Serialisable
 
+from ..xml._functions_overloads import _HasTagAndGet
+
 _ScalingOrientation: TypeAlias = Literal["maxMin", "minMax"]
 _BaseAxisAxPos: TypeAlias = Literal["b", "l", "r", "t"]
 _BaseAxisTickMark: TypeAlias = Literal["cross", "in", "out"]

stubs/openpyxl/openpyxl/chart/bar_chart.pyi

@@ -6,8 +6,9 @@ from openpyxl.chart.axis import ChartLines, NumericAxis, SeriesAxis, TextAxis
 from openpyxl.chart.label import DataLabelList
 from openpyxl.descriptors.base import Alias, Typed, _ConvertibleToBool
 from openpyxl.descriptors.excel import ExtensionList
-from openpyxl.descriptors.nested import NestedBool, NestedNoneSet, NestedSet, _HasTagAndGet, _NestedNoneSetParam
+from openpyxl.descriptors.nested import NestedBool, NestedNoneSet, NestedSet, _NestedNoneSetParam
 
+from ..xml._functions_overloads import _HasTagAndGet
 from ._3d import _3DBase
 from ._chart import ChartBase
 

stubs/openpyxl/openpyxl/chart/bubble_chart.pyi

@@ -6,8 +6,9 @@ from openpyxl.chart.axis import NumericAxis
 from openpyxl.chart.label import DataLabelList
 from openpyxl.descriptors.base import Alias, Typed, _ConvertibleToBool, _ConvertibleToFloat
 from openpyxl.descriptors.excel import ExtensionList
-from openpyxl.descriptors.nested import NestedBool, NestedMinMax, NestedNoneSet, _HasTagAndGet, _NestedNoneSetParam
+from openpyxl.descriptors.nested import NestedBool, NestedMinMax, NestedNoneSet, _NestedNoneSetParam
 
+from ..xml._functions_overloads import _HasTagAndGet
 from ._chart import ChartBase
 
 _BubbleChartSizeRepresents: TypeAlias = Literal["area", "w"]

stubs/openpyxl/openpyxl/chart/chartspace.pyi

@@ -11,10 +11,12 @@ from openpyxl.chart.text import RichText
 from openpyxl.chart.title import Title
 from openpyxl.descriptors.base import Alias, String, Typed, _ConvertibleToBool, _ConvertibleToFloat
 from openpyxl.descriptors.excel import ExtensionList
-from openpyxl.descriptors.nested import NestedBool, NestedMinMax, NestedNoneSet, NestedString, _HasTagAndGet, _NestedNoneSetParam
+from openpyxl.descriptors.nested import NestedBool, NestedMinMax, NestedNoneSet, NestedString, _NestedNoneSetParam
 from openpyxl.descriptors.serialisable import Serialisable
 from openpyxl.drawing.colors import ColorMapping
 
+from ..xml._functions_overloads import _HasTagAndGet
+
 _ChartContainerDispBlanksAs: TypeAlias = Literal["span", "gap", "zero"]
 
 class ChartContainer(Serialisable):

stubs/openpyxl/openpyxl/chart/data_source.pyi

@@ -5,9 +5,11 @@ from typing_extensions import Literal
 from openpyxl.descriptors import Strict
 from openpyxl.descriptors.base import Alias, Bool, Integer, String, Typed, _ConvertibleToBool, _ConvertibleToInt
 from openpyxl.descriptors.excel import ExtensionList
-from openpyxl.descriptors.nested import NestedInteger, NestedText, _HasTagAndGet
+from openpyxl.descriptors.nested import NestedInteger, NestedText
 from openpyxl.descriptors.serialisable import Serialisable
 
+from ..xml._functions_overloads import _HasTagAndGet
+
 class NumFmt(Serialisable):
     formatCode: String[Literal[False]]
     sourceLinked: Bool[Literal[False]]

stubs/openpyxl/openpyxl/chart/error_bar.pyi

@@ -6,9 +6,11 @@ from openpyxl.chart.data_source import NumDataSource
 from openpyxl.chart.shapes import GraphicalProperties
 from openpyxl.descriptors.base import Alias, Typed, _ConvertibleToBool, _ConvertibleToFloat
 from openpyxl.descriptors.excel import ExtensionList
-from openpyxl.descriptors.nested import NestedBool, NestedFloat, NestedNoneSet, NestedSet, _HasTagAndGet, _NestedNoneSetParam
+from openpyxl.descriptors.nested import NestedBool, NestedFloat, NestedNoneSet, NestedSet, _NestedNoneSetParam
 from openpyxl.descriptors.serialisable import Serialisable
 
+from ..xml._functions_overloads import _HasTagAndGet
+
 _ErrorBarsErrBarType: TypeAlias = Literal["both", "minus", "plus"]
 _ErrorBarsErrValType: TypeAlias = Literal["cust", "fixedVal", "percentage", "stdDev", "stdErr"]
 _ErrorBarsErrDir: TypeAlias = Literal["x", "y"]

stubs/openpyxl/openpyxl/chart/label.pyi

@@ -6,9 +6,11 @@ from openpyxl.chart.shapes import GraphicalProperties
 from openpyxl.chart.text import RichText
 from openpyxl.descriptors.base import Alias, Typed, _ConvertibleToBool, _ConvertibleToInt
 from openpyxl.descriptors.excel import ExtensionList
-from openpyxl.descriptors.nested import NestedBool, NestedInteger, NestedNoneSet, NestedString, _HasTagAndGet, _NestedNoneSetParam
+from openpyxl.descriptors.nested import NestedBool, NestedInteger, NestedNoneSet, NestedString, _NestedNoneSetParam
 from openpyxl.descriptors.serialisable import Serialisable as Serialisable
 
+from ..xml._functions_overloads import _HasTagAndGet
+
 _DataLabelBaseDLblPos: TypeAlias = Literal["bestFit", "b", "ctr", "inBase", "inEnd", "l", "outEnd", "r", "t"]
 
 class _DataLabelBase(Serialisable):

stubs/openpyxl/openpyxl/chart/layout.pyi

@@ -4,9 +4,11 @@ from typing_extensions import Literal, TypeAlias
 
 from openpyxl.descriptors.base import Alias, Typed, _ConvertibleToFloat
 from openpyxl.descriptors.excel import ExtensionList
-from openpyxl.descriptors.nested import NestedMinMax, NestedNoneSet, NestedSet, _HasTagAndGet, _NestedNoneSetParam
+from openpyxl.descriptors.nested import NestedMinMax, NestedNoneSet, NestedSet, _NestedNoneSetParam
 from openpyxl.descriptors.serialisable import Serialisable
 
+from ..xml._functions_overloads import _HasTagAndGet
+
 _ManualLayoutMode: TypeAlias = Literal["edge", "factor"]
 _ManualLayoutLayoutTarget: TypeAlias = Literal["inner", "outer"]
 

stubs/openpyxl/openpyxl/chart/legend.pyi

@@ -7,9 +7,11 @@ from openpyxl.chart.shapes import GraphicalProperties
 from openpyxl.chart.text import RichText
 from openpyxl.descriptors.base import Alias, Typed, _ConvertibleToBool, _ConvertibleToInt
 from openpyxl.descriptors.excel import ExtensionList
-from openpyxl.descriptors.nested import NestedBool, NestedInteger, NestedSet, _HasTagAndGet
+from openpyxl.descriptors.nested import NestedBool, NestedInteger, NestedSet
 from openpyxl.descriptors.serialisable import Serialisable
 
+from ..xml._functions_overloads import _HasTagAndGet
+
 _LegendLegendPos: TypeAlias = Literal["b", "tr", "l", "r", "t"]
 
 class LegendEntry(Serialisable):

stubs/openpyxl/openpyxl/chart/line_chart.pyi

@@ -7,8 +7,9 @@ from openpyxl.chart.label import DataLabelList
 from openpyxl.chart.updown_bars import UpDownBars
 from openpyxl.descriptors.base import Alias, Typed, _ConvertibleToBool
 from openpyxl.descriptors.excel import ExtensionList
-from openpyxl.descriptors.nested import NestedBool, NestedSet, _HasTagAndGet
+from openpyxl.descriptors.nested import NestedBool, NestedSet
 
+from ..xml._functions_overloads import _HasTagAndGet
 from ._chart import ChartBase
 
 _LineChartBaseGrouping: TypeAlias = Literal["percentStacked", "standard", "stacked"]

stubs/openpyxl/openpyxl/chart/marker.pyi

@@ -6,9 +6,11 @@ from openpyxl.chart.picture import PictureOptions
 from openpyxl.chart.shapes import GraphicalProperties
 from openpyxl.descriptors.base import Alias, Typed, _ConvertibleToBool, _ConvertibleToFloat, _ConvertibleToInt
 from openpyxl.descriptors.excel import ExtensionList
-from openpyxl.descriptors.nested import NestedBool, NestedInteger, NestedMinMax, NestedNoneSet, _HasTagAndGet, _NestedNoneSetParam
+from openpyxl.descriptors.nested import NestedBool, NestedInteger, NestedMinMax, NestedNoneSet, _NestedNoneSetParam
 from openpyxl.descriptors.serialisable import Serialisable
 
+from ..xml._functions_overloads import _HasTagAndGet
+
 _MarkerSymbol: TypeAlias = Literal[
     "circle", "dash", "diamond", "dot", "picture", "plus", "square", "star", "triangle", "x", "auto"
 ]

stubs/openpyxl/openpyxl/chart/picture.pyi

@@ -2,9 +2,11 @@ from typing import ClassVar
 from typing_extensions import Literal, TypeAlias
 
 from openpyxl.descriptors.base import _ConvertibleToBool, _ConvertibleToFloat
-from openpyxl.descriptors.nested import NestedBool, NestedFloat, NestedNoneSet, _HasTagAndGet, _NestedNoneSetParam
+from openpyxl.descriptors.nested import NestedBool, NestedFloat, NestedNoneSet, _NestedNoneSetParam
 from openpyxl.descriptors.serialisable import Serialisable
 
+from ..xml._functions_overloads import _HasTagAndGet
+
 _PictureOptionsPictureFormat: TypeAlias = Literal["stretch", "stack", "stackScale"]
 
 class PictureOptions(Serialisable):

stubs/openpyxl/openpyxl/chart/pie_chart.pyi

@@ -6,17 +6,10 @@ from openpyxl.chart.axis import ChartLines
 from openpyxl.chart.label import DataLabelList
 from openpyxl.descriptors.base import Alias, Typed, _ConvertibleToBool, _ConvertibleToFloat
 from openpyxl.descriptors.excel import ExtensionList
-from openpyxl.descriptors.nested import (
-    NestedBool,
-    NestedFloat,
-    NestedMinMax,
-    NestedNoneSet,
-    NestedSet,
-    _HasTagAndGet,
-    _NestedNoneSetParam,
-)
+from openpyxl.descriptors.nested import NestedBool, NestedFloat, NestedMinMax, NestedNoneSet, NestedSet, _NestedNoneSetParam
 from openpyxl.descriptors.serialisable import Serialisable
 
+from ..xml._functions_overloads import _HasTagAndGet
 from ._chart import ChartBase
 
 _ProjectedPieChartOfPieType: TypeAlias = Literal["pie", "bar"]

stubs/openpyxl/openpyxl/chart/pivot.pyi

@@ -8,9 +8,11 @@ from openpyxl.chart.shapes import GraphicalProperties
 from openpyxl.chart.text import RichText
 from openpyxl.descriptors.base import Alias, Typed, _ConvertibleToInt
 from openpyxl.descriptors.excel import ExtensionList
-from openpyxl.descriptors.nested import NestedInteger, NestedText, _HasTagAndGet
+from openpyxl.descriptors.nested import NestedInteger, NestedText
 from openpyxl.descriptors.serialisable import Serialisable
 
+from ..xml._functions_overloads import _HasTagAndGet
+
 class PivotSource(Serialisable):
     tagname: ClassVar[str]
     name: NestedText[str, Literal[False]]

stubs/openpyxl/openpyxl/chart/plotarea.pyi

@@ -7,9 +7,11 @@ from openpyxl.chart.shapes import GraphicalProperties
 from openpyxl.chart.text import RichText
 from openpyxl.descriptors.base import Alias, Typed, _ConvertibleToBool
 from openpyxl.descriptors.excel import ExtensionList
-from openpyxl.descriptors.nested import NestedBool, _HasTagAndGet
+from openpyxl.descriptors.nested import NestedBool
 from openpyxl.descriptors.serialisable import Serialisable
 
+from ..xml._functions_overloads import _HasTagAndGet
+
 class DataTable(Serialisable):
     tagname: ClassVar[str]
     showHorzBorder: NestedBool[Literal[True]]

stubs/openpyxl/openpyxl/chart/radar_chart.pyi

@@ -6,8 +6,9 @@ from openpyxl.chart.axis import NumericAxis, TextAxis
 from openpyxl.chart.label import DataLabelList
 from openpyxl.descriptors.base import Alias, Typed, _ConvertibleToBool
 from openpyxl.descriptors.excel import ExtensionList
-from openpyxl.descriptors.nested import NestedBool, NestedSet, _HasTagAndGet
+from openpyxl.descriptors.nested import NestedBool, NestedSet
 
+from ..xml._functions_overloads import _HasTagAndGet
 from ._chart import ChartBase
 
 _RadarChartRadarStyle: TypeAlias = Literal["standard", "marker", "filled"]

stubs/openpyxl/openpyxl/chart/scatter_chart.pyi

@@ -6,8 +6,9 @@ from openpyxl.chart.axis import NumericAxis, TextAxis
 from openpyxl.chart.label import DataLabelList
 from openpyxl.descriptors.base import Alias, Typed, _ConvertibleToBool
 from openpyxl.descriptors.excel import ExtensionList
-from openpyxl.descriptors.nested import NestedBool, NestedNoneSet, _HasTagAndGet, _NestedNoneSetParam
+from openpyxl.descriptors.nested import NestedBool, NestedNoneSet, _NestedNoneSetParam
 
+from ..xml._functions_overloads import _HasTagAndGet
 from ._chart import ChartBase as ChartBase
 
 _ScatterChartScatterStyle: TypeAlias = Literal["line", "lineMarker", "marker", "smooth", "smoothMarker"]

stubs/openpyxl/openpyxl/chart/series.pyi

@@ -11,9 +11,11 @@ from openpyxl.chart.shapes import GraphicalProperties
 from openpyxl.chart.trendline import Trendline
 from openpyxl.descriptors.base import Alias, Typed, _ConvertibleToBool, _ConvertibleToInt
 from openpyxl.descriptors.excel import ExtensionList
-from openpyxl.descriptors.nested import NestedBool, NestedInteger, NestedNoneSet, NestedText, _HasTagAndGet, _NestedNoneSetParam
+from openpyxl.descriptors.nested import NestedBool, NestedInteger, NestedNoneSet, NestedText, _NestedNoneSetParam
 from openpyxl.descriptors.serialisable import Serialisable
 
+from ..xml._functions_overloads import _HasTagAndGet
+
 _SeriesShape: TypeAlias = Literal["cone", "coneToMax", "box", "cylinder", "pyramid", "pyramidToMax"]
 
 attribute_mapping: Incomplete

stubs/openpyxl/openpyxl/chart/shapes.pyi

@@ -3,12 +3,14 @@ from typing import ClassVar
 from typing_extensions import Literal, TypeAlias
 
 from openpyxl.descriptors.base import Alias, NoneSet, Typed, _ConvertibleToBool
-from openpyxl.descriptors.nested import EmptyTag, _HasTagAndGet
+from openpyxl.descriptors.nested import EmptyTag
 from openpyxl.descriptors.serialisable import Serialisable
 from openpyxl.drawing.fill import GradientFillProperties, PatternFillProperties
 from openpyxl.drawing.geometry import CustomGeometry2D, PresetGeometry2D, Scene3D, Shape3D, Transform2D
 from openpyxl.drawing.line import LineProperties
 
+from ..xml._functions_overloads import _HasTagAndGet
+
 _GraphicalPropertiesBwMode: TypeAlias = Literal[
     "clr", "auto", "gray", "ltGray", "invGray", "grayWhite", "blackGray", "blackWhite", "black", "white", "hidden"
 ]

stubs/openpyxl/openpyxl/chart/surface_chart.pyi

@@ -6,9 +6,10 @@ from openpyxl.chart.axis import NumericAxis, SeriesAxis, TextAxis
 from openpyxl.chart.shapes import GraphicalProperties
 from openpyxl.descriptors.base import Alias, Typed, _ConvertibleToBool, _ConvertibleToInt
 from openpyxl.descriptors.excel import ExtensionList
-from openpyxl.descriptors.nested import NestedBool, NestedInteger, _HasTagAndGet
+from openpyxl.descriptors.nested import NestedBool, NestedInteger
 from openpyxl.descriptors.serialisable import Serialisable
 
+from ..xml._functions_overloads import _HasTagAndGet
 from ._3d import _3DBase
 from ._chart import ChartBase
 

stubs/openpyxl/openpyxl/chart/title.pyi

@@ -8,9 +8,11 @@ from openpyxl.chart.text import RichText, Text
 from openpyxl.descriptors import Strict, Typed
 from openpyxl.descriptors.base import Alias, _ConvertibleToBool
 from openpyxl.descriptors.excel import ExtensionList
-from openpyxl.descriptors.nested import NestedBool, _HasTagAndGet
+from openpyxl.descriptors.nested import NestedBool
 from openpyxl.descriptors.serialisable import Serialisable
 
+from ..xml._functions_overloads import _HasTagAndGet
+
 class Title(Serialisable):
     tagname: ClassVar[str]
     tx: Typed[Text, Literal[True]]

stubs/openpyxl/openpyxl/chart/trendline.pyi

@@ -8,9 +8,11 @@ from openpyxl.chart.shapes import GraphicalProperties
 from openpyxl.chart.text import RichText, Text
 from openpyxl.descriptors.base import Alias, String, Typed, _ConvertibleToBool, _ConvertibleToFloat, _ConvertibleToInt
 from openpyxl.descriptors.excel import ExtensionList
-from openpyxl.descriptors.nested import NestedBool, NestedFloat, NestedInteger, NestedSet, _HasTagAndGet
+from openpyxl.descriptors.nested import NestedBool, NestedFloat, NestedInteger, NestedSet
 from openpyxl.descriptors.serialisable import Serialisable
 
+from ..xml._functions_overloads import _HasTagAndGet
+
 _TrendlineTrendlineType: TypeAlias = Literal["exp", "linear", "log", "movingAvg", "poly", "power"]
 
 class TrendlineLabel(Serialisable):

stubs/openpyxl/openpyxl/comments/shape_writer.pyi

@@ -1,4 +1,10 @@
 from _typeshed import Incomplete
+from typing import Any
+from typing_extensions import TypeAlias
+
+from ..xml._functions_overloads import _lxml_Element, _ParentElement
+
+_RootElement: TypeAlias = _ParentElement[Any] | _lxml_Element
 
 vmlns: str
 officens: str
@@ -9,6 +15,7 @@ class ShapeWriter:
     vml_path: Incomplete
     comments: Incomplete
     def __init__(self, comments) -> None: ...
-    def add_comment_shapetype(self, root) -> None: ...
-    def add_comment_shape(self, root, idx, coord, height, width) -> None: ...
-    def write(self, root): ...
+    def add_comment_shapetype(self, root: _RootElement) -> None: ...
+    def add_comment_shape(self, root: _RootElement, idx, coord, height, width) -> None: ...
+    # Any object missing "findall" is replaced by an Element
+    def write(self, root: _RootElement | None) -> str: ...

stubs/openpyxl/openpyxl/descriptors/nested.pyi

@@ -1,6 +1,6 @@
 from _typeshed import Incomplete, Unused
-from collections.abc import Callable, Iterable
-from typing import Any, ClassVar, NoReturn, Protocol, TypeVar, overload
+from collections.abc import Iterable
+from typing import Any, ClassVar, NoReturn, overload
 from typing_extensions import Literal, TypeAlias
 
 from openpyxl.descriptors import Strict
@@ -9,19 +9,9 @@ from openpyxl.descriptors.serialisable import Serialisable
 from openpyxl.drawing.fill import Blip
 from openpyxl.xml.functions import Element
 
+from ..xml._functions_overloads import _HasTagAndGet, _HasTagAndText
 from .base import _M, _N, _T, _ConvertibleToBool, _ConvertibleToFloat, _ConvertibleToInt, _ExpectedTypeParam
 
-_T_co = TypeVar("_T_co", covariant=True)
-
-# Usually an Element() from either lxml or xml.etree (has a 'tag' element)
-class _HasTagAndGet(Protocol[_T_co]):
-    tag: Any  # str | None | Callable[..., Any]
-    def get(self, __value: str) -> _T_co | None: ...
-
-class _HasTagAndText(Protocol):
-    tag: str | Callable[..., Any]
-    text: str
-
 _NestedNoneSetParam: TypeAlias = _HasTagAndGet[_T | Literal["none"] | None] | _T | Literal["none"] | None
 
 # NOTE: type: ignore[misc]: Class does not reimplement the relevant methods, so runtime also has incompatible supertypes

stubs/openpyxl/openpyxl/descriptors/serialisable.pyi

@@ -4,6 +4,8 @@ from typing_extensions import Final
 
 from openpyxl.descriptors import MetaSerialisable
 
+from ..xml._functions_overloads import _HasTagAndTextAndAttrib
+
 KEYWORDS: Final[frozenset[str]]
 seq_types: Final[tuple[type[list[Any]], type[tuple[Any, ...]]]]
 
@@ -19,7 +21,7 @@ class Serialisable(metaclass=MetaSerialisable):
     def tagname(self) -> str | NoReturn: ...
     namespace: ClassVar[str | None]
     @classmethod
-    def from_tree(cls, node): ...
+    def from_tree(cls, node: _HasTagAndTextAndAttrib): ...
     def to_tree(self, tagname: str | None = None, idx: Incomplete | None = None, namespace: str | None = None): ...
     def __iter__(self): ...
     def __eq__(self, other): ...

stubs/openpyxl/openpyxl/descriptors/slots.pyi

@@ -1,2 +1,2 @@
 class AutoSlotProperties(type):
-    def __new__(cls, classname, bases, dictionary): ...
+    def __new__(mcl, classname, bases, dictionary): ...

stubs/openpyxl/openpyxl/drawing/colors.pyi

@@ -5,9 +5,11 @@ from typing_extensions import Final, Literal, TypeAlias
 from openpyxl.descriptors import Strict, Typed
 from openpyxl.descriptors.base import Alias, Integer, MinMax, Set, _ConvertibleToBool, _ConvertibleToFloat, _ConvertibleToInt
 from openpyxl.descriptors.excel import ExtensionList
-from openpyxl.descriptors.nested import EmptyTag, NestedInteger, NestedNoneSet, NestedValue, _HasTagAndGet, _NestedNoneSetParam
+from openpyxl.descriptors.nested import EmptyTag, NestedInteger, NestedNoneSet, NestedValue, _NestedNoneSetParam
 from openpyxl.descriptors.serialisable import Serialisable
 
+from ..xml._functions_overloads import _HasTagAndGet
+
 _ColorSetType: TypeAlias = Literal[
     "dk1", "lt1", "dk2", "lt2", "accent1", "accent2", "accent3", "accent4", "accent5", "accent6", "hlink", "folHlink"
 ]

stubs/openpyxl/openpyxl/drawing/fill.pyi

@@ -15,7 +15,7 @@ from openpyxl.descriptors.base import (
     _ConvertibleToInt,
 )
 from openpyxl.descriptors.excel import ExtensionList
-from openpyxl.descriptors.nested import NestedNoneSet, NestedValue, _HasTagAndGet, _NestedNoneSetParam
+from openpyxl.descriptors.nested import NestedNoneSet, NestedValue, _NestedNoneSetParam
 from openpyxl.descriptors.serialisable import Serialisable
 from openpyxl.drawing.colors import ColorChoice, HSLColor, RGBPercent as _RGBPercent, SchemeColor, SystemColor, _PresetColors
 from openpyxl.drawing.effect import (
@@ -38,6 +38,8 @@ from openpyxl.drawing.effect import (
     TintEffect,
 )
 
+from ..xml._functions_overloads import _HasTagAndGet
+
 _PatternFillPropertiesPrst: TypeAlias = Literal[
     "pct5",
     "pct10",

stubs/openpyxl/openpyxl/drawing/line.pyi

@@ -13,10 +13,12 @@ from openpyxl.descriptors.base import (
     _ConvertibleToInt,
 )
 from openpyxl.descriptors.excel import ExtensionList
-from openpyxl.descriptors.nested import EmptyTag, NestedInteger, NestedNoneSet, _HasTagAndGet, _NestedNoneSetParam
+from openpyxl.descriptors.nested import EmptyTag, NestedInteger, NestedNoneSet, _NestedNoneSetParam
 from openpyxl.descriptors.serialisable import Serialisable
 from openpyxl.drawing.fill import GradientFillProperties, PatternFillProperties
 
+from ..xml._functions_overloads import _HasTagAndGet
+
 _LineEndPropertiesType: TypeAlias = Literal["none", "triangle", "stealth", "diamond", "oval", "arrow"]
 _LineEndPropertiesWLen: TypeAlias = Literal["sm", "med", "lg"]
 _LinePropertiesCap: TypeAlias = Literal["rnd", "sq", "flat"]

stubs/openpyxl/openpyxl/drawing/text.pyi

@@ -16,13 +16,15 @@ from openpyxl.descriptors.base import (
     _ConvertibleToInt,
 )
 from openpyxl.descriptors.excel import Coordinate, ExtensionList
-from openpyxl.descriptors.nested import EmptyTag, NestedBool, NestedInteger, NestedText, NestedValue, _HasTagAndGet
+from openpyxl.descriptors.nested import EmptyTag, NestedBool, NestedInteger, NestedText, NestedValue
 from openpyxl.descriptors.serialisable import Serialisable
 from openpyxl.drawing.effect import Color, EffectContainer, EffectList
 from openpyxl.drawing.fill import Blip, BlipFillProperties, GradientFillProperties, PatternFillProperties
 from openpyxl.drawing.geometry import Scene3D
 from openpyxl.drawing.line import LineProperties
 
+from ..xml._functions_overloads import _HasTagAndGet
+
 _CharacterPropertiesU: TypeAlias = Literal[
     "words",
     "sng",

stubs/openpyxl/openpyxl/pivot/cache.pyi

@@ -16,11 +16,13 @@ from openpyxl.descriptors.base import (
     _ConvertibleToInt,
 )
 from openpyxl.descriptors.excel import ExtensionList
-from openpyxl.descriptors.nested import NestedInteger, _HasTagAndGet
+from openpyxl.descriptors.nested import NestedInteger
 from openpyxl.descriptors.serialisable import Serialisable
 from openpyxl.pivot.fields import Error, Missing, Number, Text, TupleList
 from openpyxl.pivot.table import PivotArea
 
+from ..xml._functions_overloads import _HasTagAndGet
+
 _RangePrGroupBy: TypeAlias = Literal["range", "seconds", "minutes", "hours", "days", "months", "quarters", "years"]
 _CacheSourceType: TypeAlias = Literal["worksheet", "external", "consolidation", "scenario"]
 

stubs/openpyxl/openpyxl/styles/fonts.pyi

@@ -10,11 +10,12 @@ from openpyxl.descriptors.nested import (
     NestedMinMax,
     NestedNoneSet,
     NestedString,
-    _HasTagAndGet,
     _NestedNoneSetParam,
 )
 from openpyxl.descriptors.serialisable import Serialisable
 
+from ..xml._functions_overloads import _HasTagAndGet
+
 _FontU: TypeAlias = Literal["single", "double", "singleAccounting", "doubleAccounting"]
 _FontVertAlign: TypeAlias = Literal["superscript", "subscript", "baseline"]
 _FontScheme: TypeAlias = Literal["major", "minor"]

stubs/openpyxl/openpyxl/worksheet/_writer.pyi

@@ -1,5 +1,16 @@
-from _typeshed import Incomplete
+from _typeshed import Incomplete, ReadableBuffer, StrPath, Unused
 from collections.abc import Generator
+from typing import Protocol
+from typing_extensions import TypeAlias
+
+# WorksheetWriter.read has an explicit BytesIO branch. Let's make sure this protocol is viable for BytesIO too.
+class _SupportsCloseAndWrite(Protocol):
+    def write(self, __buffer: ReadableBuffer) -> Unused: ...
+    def close(self) -> Unused: ...
+
+# et_xmlfile.xmlfile accepts a str | _SupportsCloseAndWrite
+# lxml.etree.xmlfile should accept a StrPath | _SupportsClose https://lxml.de/api/lxml.etree.xmlfile-class.html
+_OutType: TypeAlias = _SupportsCloseAndWrite | StrPath
 
 ALL_TEMP_FILES: list[str]
 
@@ -7,9 +18,9 @@ def create_temporary_file(suffix: str = ""): ...
 
 class WorksheetWriter:
     ws: Incomplete
-    out: Incomplete
+    out: _OutType
     xf: Incomplete
-    def __init__(self, ws, out: Incomplete | None = None) -> 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: ...

stubs/openpyxl/openpyxl/xml/__init__.pyi

@@ -1,11 +1,11 @@
 from typing_extensions import Final
 
-def lxml_available(): ...
-def lxml_env_set(): ...
+def lxml_available() -> bool: ...
+def lxml_env_set() -> bool: ...
 
 LXML: Final[bool]
 
-def defusedxml_available(): ...
-def defusedxml_env_set(): ...
+def defusedxml_available() -> bool: ...
+def defusedxml_env_set() -> bool: ...
 
 DEFUSEDXML: Final[bool]

stubs/openpyxl/openpyxl/xml/_functions_overloads.pyi

@@ -0,0 +1,117 @@
+# This file does not exist at runtime. It is a helper file to overload imported functions in openpyxl.xml.functions
+
+import sys
+from _typeshed import Incomplete, ReadableBuffer
+from collections.abc import Iterable, Iterator, Mapping, Sequence
+from typing import Any, Protocol, TypeVar, overload
+from typing_extensions import TypeAlias
+from xml.etree.ElementTree import Element, ElementTree, QName, XMLParser, _FileRead
+
+_T = TypeVar("_T")
+_T_co = TypeVar("_T_co", covariant=True)
+
+# Useful protocols, see import comment in openpyxl/xml/functions.pyi
+
+# Comment from openpyxl.cell.rich_text.py
+# Usually an Element() from either lxml or xml.etree (has a 'tag' element)
+class _HasTag(Protocol):
+    tag: Any  # AnyOf[str, None, Callable[..., AnyOf[str, None]]]
+
+class _HasText(Protocol):
+    text: str
+
+class _HasTagAndGet(_HasTag, Protocol[_T_co]):
+    def get(self, __value: str) -> _T_co | None: ...
+
+class _HasTagAndText(_HasTag, _HasText, Protocol): ...  # noqa: Y046
+
+class _HasTagAndTextAndAttrib(_HasTag, _HasText, Protocol):  # noqa: Y046
+    attrib: Iterable[Any]  # AnyOf[dict[str, str], Iterable[tuple[str, str]]]
+
+class _ParentElement(Protocol[_T]):
+    def makeelement(self, __tag: str, __attrib: dict[str, str]) -> _T: ...
+    def append(self, __element: _T) -> object: ...
+
+# from lxml.etree import _Element
+_lxml_Element: TypeAlias = Element  # noqa: Y042
+# from lxml.etree import _ElementTree
+_lxml_ElementTree: TypeAlias = ElementTree  # noqa: Y042
+# from lxml.etree import QName
+_lxml_QName: TypeAlias = QName  # noqa: Y042
+
+# from xml.etree import fromstring
+@overload
+def SubElement(parent: _ParentElement[_T], tag: str, attrib: dict[str, str] = ..., **extra: str) -> _T: ...
+
+# from lxml.etree import fromstring
+@overload
+def SubElement(
+    _parent: _lxml_Element,  # This would be preferable as a protocol, but it's a C-Extension
+    _tag: str | bytes | _lxml_QName,
+    attrib: dict[str, str] | dict[bytes, bytes] | None = ...,
+    nsmap: Mapping[str, str] | None = ...,
+    **extra: str | bytes,
+) -> _lxml_ElementTree: ...
+
+# from xml.etree.ElementTree import fromstring
+@overload
+def fromstring(text: str | ReadableBuffer, parser: XMLParser | None = None) -> Element: ...
+
+# from lxml.etree import fromstring
+# But made partial, removing parser arg
+@overload
+def fromstring(text: str | bytes, *, base_url: str | bytes = ...) -> _lxml_Element: ...  # type: ignore[misc]  # Overlap with incompatible return types
+
+# from defusedxml.ElementTree import fromstring
+@overload
+def fromstring(text: str, forbid_dtd: bool = False, forbid_entities: bool = True, forbid_external: bool = True) -> int: ...
+
+# from xml.etree.ElementTree import tostring
+# But made partial, removing encoding arg
+if sys.version_info >= (3, 8):
+    @overload
+    def tostring(
+        element: Element,
+        method: str | None = "xml",
+        *,
+        xml_declaration: bool | None = None,
+        default_namespace: str | None = ...,
+        short_empty_elements: bool = ...,
+    ) -> str: ...
+
+else:
+    @overload
+    def tostring(element: Element, method: str | None = ..., *, short_empty_elements: bool = ...) -> str: ...
+
+# from lxml.etree import Element
+# But made partial, removing encoding arg
+@overload
+def tostring(
+    element_or_tree: _lxml_Element | _lxml_ElementTree,
+    method: str = ...,
+    xml_declaration: bool = ...,
+    pretty_print: bool = ...,
+    with_tail: bool = ...,
+    standalone: bool = ...,
+    doctype: str = ...,
+    exclusive: bool = ...,
+    with_comments: bool = ...,
+    inclusive_ns_prefixes: Incomplete = ...,
+) -> bytes: ...
+
+# from xml.etree.ElementTree import iterparse
+@overload
+def iterparse(
+    source: _FileRead, events: Sequence[str] | None = None, parser: XMLParser | None = None
+) -> Iterator[tuple[str, Any]]: ...
+
+# from defusedxml.ElementTree import iterparse
+@overload
+def iterparse(
+    source: _FileRead,
+    events: Sequence[str] | None = None,
+    parser: XMLParser | None = None,
+    forbid_dtd: bool = False,
+    forbid_entities: bool = True,
+    forbid_external: bool = True,
+) -> Iterator[tuple[str, Any]]: ...

stubs/openpyxl/openpyxl/xml/functions.pyi

@@ -1,8 +1,28 @@
+from _typeshed import Incomplete
 from re import Pattern
 from typing_extensions import Final
-from xml.etree.ElementTree import Element as Element  # possibly also imported from lxml
+
+# Can actually be imported from a mix of xml, lxml, et_xmlfile as defusedxml
+# But et_xmlfile is untyped. openpyxl does not directly depend on lxml/lxml-stubs.
+# And forcing a dependency on defusedxml felt overkill as it just wraps xml
+# So for typing purposes, let's pretend xml is the only dependency.
+# Prefer using protocols over these for parameters.
+from xml.etree.ElementTree import Element as Element, QName as QName
+
+from ._functions_overloads import (
+    SubElement as SubElement,
+    _HasTag,
+    _HasText,
+    fromstring as fromstring,
+    iterparse as iterparse,
+    tostring as tostring,
+)
+
+# from lxml.etree import xmlfile
+# from et_xmlfile import xmlfile
+xmlfile: Incomplete
 
 NS_REGEX: Final[Pattern[str]]
 
-def localname(node): ...
-def whitespace(node) -> None: ...
+def localname(node: _HasTag) -> str: ...
+def whitespace(node: _HasText) -> None: ...