Type openpyxl functions module and its usages

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 @@
  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