Skip to content

Commit ef3e6a3

Browse files
AvishrantsShAvishrantsSh
committed
chore: Add initial stub support for dml, parts and text submodules
Signed-off-by: Avishrant Sharma <[email protected]>
1 parent 5f91ed6 commit ef3e6a3

File tree

18 files changed

+1590
-0
lines changed

18 files changed

+1590
-0
lines changed

‎pptx-stubs/__init__.pyi‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
from pptx.api import Presentation
2+
from pptx.opc.package import Part
3+
4+
content_type_to_part_class_map: dict[str, type[Part]] = ...

‎pptx-stubs/dml/__init__.pyi‎

Whitespace-only changes.

‎pptx-stubs/dml/chtfmt.pyi‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
from pptx.dml.fill import FillFormat
2+
from pptx.dml.line import LineFormat
3+
from pptx.shared import ElementProxy
4+
from pptx.util import lazyproperty
5+
6+
class ChartFormat(ElementProxy):
7+
"""
8+
The |ChartFormat| object provides access to visual shape properties for
9+
chart elements like |Axis|, |Series|, and |MajorGridlines|. It has two
10+
properties, :attr:`fill` and :attr:`line`, which return a |FillFormat|
11+
and |LineFormat| object respectively. The |ChartFormat| object is
12+
provided by the :attr:`format` property on the target axis, series, etc.
13+
"""
14+
@lazyproperty
15+
def fill(self) -> FillFormat:
16+
"""
17+
|FillFormat| instance for this object, providing access to fill
18+
properties such as fill color.
19+
"""
20+
...
21+
22+
@lazyproperty
23+
def line(self) -> LineFormat:
24+
"""
25+
The |LineFormat| object providing access to the visual properties of
26+
this object, such as line color and line style.
27+
"""
28+
...

‎pptx-stubs/dml/color.pyi‎

Lines changed: 164 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,164 @@
1+
from typing import Literal, Self
2+
3+
from pptx.enum.dml import MSO_COLOR_TYPE, MSO_THEME_COLOR, MSO_THEME_COLOR_INDEX
4+
from pptx.oxml.dml.color import CT_Color, CT_SRgbColor, _BaseColorElement
5+
6+
class ColorFormat:
7+
"""
8+
Provides access to color settings such as RGB color, theme color, and
9+
luminance adjustments.
10+
"""
11+
def __init__(self, eg_colorChoice_parent: CT_Color, color: _Color) -> None: ...
12+
@property
13+
def brightness(self) -> float:
14+
"""
15+
Read/write float value between -1.0 and 1.0 indicating the brightness
16+
adjustment for this color, e.g. -0.25 is 25% darker and 0.4 is 40%
17+
lighter. 0 means no brightness adjustment.
18+
"""
19+
...
20+
21+
@brightness.setter
22+
def brightness(self, value: float) -> None: ...
23+
@classmethod
24+
def from_colorchoice_parent(cls, eg_colorChoice_parent: CT_Color) -> Self: ...
25+
@property
26+
def rgb(self) -> RGBColor:
27+
"""
28+
|RGBColor| value of this color, or None if no RGB color is explicitly
29+
defined for this font. Setting this value to an |RGBColor| instance
30+
causes its type to change to MSO_COLOR_TYPE.RGB. If the color was a
31+
theme color with a brightness adjustment, the brightness adjustment
32+
is removed when changing it to an RGB color.
33+
"""
34+
...
35+
36+
@rgb.setter
37+
def rgb(self, rgb: RGBColor) -> None: ...
38+
@property
39+
def theme_color(self) -> MSO_THEME_COLOR_INDEX:
40+
"""Theme color value of this color.
41+
42+
Value is a member of :ref:`MsoThemeColorIndex`, e.g.
43+
``MSO_THEME_COLOR.ACCENT_1``. Raises AttributeError on access if the
44+
color is not type ``MSO_COLOR_TYPE.SCHEME``. Assigning a member of
45+
:ref:`MsoThemeColorIndex` causes the color's type to change to
46+
``MSO_COLOR_TYPE.SCHEME``.
47+
"""
48+
...
49+
50+
@theme_color.setter
51+
def theme_color(self, mso_theme_color_idx: MSO_THEME_COLOR_INDEX) -> None: ...
52+
@property
53+
def type(self) -> MSO_COLOR_TYPE:
54+
"""
55+
Read-only. A value from :ref:`MsoColorType`, either RGB or SCHEME,
56+
corresponding to the way this color is defined, or None if no color
57+
is defined at the level of this font.
58+
"""
59+
...
60+
61+
class _Color:
62+
"""
63+
Object factory for color object of the appropriate type, also the base
64+
class for all color type classes such as SRgbColor.
65+
"""
66+
def __new__(cls, xClr: _BaseColorElement | None) -> Self: ...
67+
def __init__(self, xClr: _BaseColorElement | None) -> None: ...
68+
@property
69+
def brightness(self) -> float: ...
70+
@brightness.setter
71+
def brightness(self, value: float) -> None: ...
72+
@property
73+
def color_type(self) -> MSO_COLOR_TYPE: ...
74+
@property
75+
def rgb(self) -> RGBColor:
76+
"""
77+
Raises TypeError on access unless overridden by subclass.
78+
"""
79+
...
80+
81+
@property
82+
def theme_color(self) -> Literal[MSO_THEME_COLOR_INDEX.NOT_THEME_COLOR]:
83+
"""
84+
Raises TypeError on access unless overridden by subclass.
85+
"""
86+
...
87+
88+
class _HslColor(_Color):
89+
@property
90+
def color_type(self) -> Literal[MSO_COLOR_TYPE.HSL]: ...
91+
92+
class _NoneColor(_Color):
93+
@property
94+
def color_type(self) -> None: ...
95+
@property
96+
def theme_color(self):
97+
"""
98+
Raise TypeError on attempt to access .theme_color when no color
99+
choice is present.
100+
"""
101+
...
102+
103+
class _PrstColor(_Color):
104+
@property
105+
def color_type(self) -> Literal[MSO_COLOR_TYPE.PRESET]: ...
106+
107+
class _SchemeColor(_Color):
108+
def __init__(self, schemeClr) -> None: ...
109+
@property
110+
def color_type(self) -> Literal[MSO_COLOR_TYPE.SCHEME]: ...
111+
@property
112+
def theme_color(self) -> MSO_THEME_COLOR | None:
113+
"""
114+
Theme color value of this color, one of those defined in the
115+
MSO_THEME_COLOR enumeration, e.g. MSO_THEME_COLOR.ACCENT_1. None if
116+
no theme color is explicitly defined for this font. Setting this to a
117+
value in MSO_THEME_COLOR causes the color's type to change to
118+
``MSO_COLOR_TYPE.SCHEME``.
119+
"""
120+
...
121+
122+
@theme_color.setter
123+
def theme_color(self, mso_theme_color_idx: MSO_THEME_COLOR) -> None: ...
124+
125+
class _ScRgbColor(_Color):
126+
@property
127+
def color_type(self) -> Literal[MSO_COLOR_TYPE.SCRGB]: ...
128+
129+
class _SRgbColor(_Color):
130+
def __init__(self, srgbClr: CT_SRgbColor) -> None: ...
131+
@property
132+
def color_type(self) -> Literal[MSO_COLOR_TYPE.RGB]: ...
133+
@property
134+
def rgb(self) -> RGBColor:
135+
"""
136+
|RGBColor| value of this color, corresponding to the value in the
137+
required ``val`` attribute of the ``<a:srgbColr>`` element.
138+
"""
139+
...
140+
141+
@rgb.setter
142+
def rgb(self, rgb) -> None: ...
143+
144+
class _SysColor(_Color):
145+
@property
146+
def color_type(self) -> Literal[MSO_COLOR_TYPE.SYSTEM]: ...
147+
148+
class RGBColor(tuple[int, int, int]):
149+
"""
150+
Immutable value object defining a particular RGB color.
151+
"""
152+
def __new__(cls, r: int, g: int, b: int) -> Self: ...
153+
def __str__(self) -> str:
154+
"""
155+
Return a hex string rgb value, like '3C2F80'
156+
"""
157+
...
158+
159+
@classmethod
160+
def from_string(cls, rgb_hex_str: str) -> Self:
161+
"""
162+
Return a new instance from an RGB color hex string like ``'3C2F80'``.
163+
"""
164+
...

‎pptx-stubs/dml/effect.pyi‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
from pptx.oxml.shapes.groupshape import CT_GroupShapeProperties
2+
from pptx.oxml.shapes.shared import CT_ShapeProperties
3+
4+
class ShadowFormat:
5+
"""Provides access to shadow effect on a shape."""
6+
def __init__(self, spPr: CT_ShapeProperties | CT_GroupShapeProperties) -> None: ...
7+
@property
8+
def inherit(self) -> bool:
9+
"""True if shape inherits shadow settings.
10+
11+
Read/write. An explicitly-defined shadow setting on a shape causes
12+
this property to return |False|. A shape with no explicitly-defined
13+
shadow setting inherits its shadow settings from the style hierarchy
14+
(and so returns |True|).
15+
16+
Assigning |True| causes any explicitly-defined shadow setting to be
17+
removed and inheritance is restored. Note this has the side-effect of
18+
removing **all** explicitly-defined effects, such as glow and
19+
reflection, and restoring inheritance for all effects on the shape.
20+
Assigning |False| causes the inheritance link to be broken and **no**
21+
effects to appear on the shape.
22+
"""
23+
...
24+
25+
@inherit.setter
26+
def inherit(self, value: bool) -> None: ...

‎pptx-stubs/dml/line.pyi‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
from pptx.dml.color import ColorFormat
2+
from pptx.dml.fill import FillFormat
3+
from pptx.enum.dml import MSO_LINE_DASH_STYLE
4+
from pptx.util import Length, lazyproperty
5+
6+
class LineFormat:
7+
"""Provides access to line properties such as color, style, and width.
8+
9+
A LineFormat object is typically accessed via the ``.line`` property of
10+
a shape such as |Shape| or |Picture|.
11+
"""
12+
def __init__(self, parent) -> None: ...
13+
@lazyproperty
14+
def color(self) -> ColorFormat:
15+
"""
16+
The |ColorFormat| instance that provides access to the color settings
17+
for this line. Essentially a shortcut for ``line.fill.fore_color``.
18+
As a side-effect, accessing this property causes the line fill type
19+
to be set to ``MSO_FILL.SOLID``. If this sounds risky for your use
20+
case, use ``line.fill.type`` to non-destructively discover the
21+
existing fill type.
22+
"""
23+
...
24+
25+
@property
26+
def dash_style(self) -> MSO_LINE_DASH_STYLE | None:
27+
"""Return value indicating line style.
28+
29+
Returns a member of :ref:`MsoLineDashStyle` indicating line style, or
30+
|None| if no explicit value has been set. When no explicit value has
31+
been set, the line dash style is inherited from the style hierarchy.
32+
33+
Assigning |None| removes any existing explicitly-defined dash style.
34+
"""
35+
...
36+
37+
@dash_style.setter
38+
def dash_style(self, dash_style: MSO_LINE_DASH_STYLE | None) -> None: ...
39+
@lazyproperty
40+
def fill(self) -> FillFormat:
41+
"""
42+
|FillFormat| instance for this line, providing access to fill
43+
properties such as foreground color.
44+
"""
45+
...
46+
47+
@property
48+
def width(self) -> Length:
49+
"""
50+
The width of the line expressed as an integer number of :ref:`English
51+
Metric Units <EMU>`. The returned value is an instance of |Length|,
52+
a value class having properties such as `.inches`, `.cm`, and `.pt`
53+
for converting the value into convenient units.
54+
"""
55+
...
56+
57+
@width.setter
58+
def width(self, emu: Length) -> None: ...

‎pptx-stubs/parts/__init__.pyi‎

Whitespace-only changes.

‎pptx-stubs/parts/chart.pyi‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
from typing import Generic, Self
2+
3+
from pptx.chart.chart import Chart
4+
from pptx.chart.data import ChartData
5+
from pptx.chart.plot import _PlotType
6+
from pptx.chart.series import _SeriesType
7+
from pptx.enum.chart import XL_CHART_TYPE
8+
from pptx.opc.package import XmlPart
9+
from pptx.oxml.chart.chart import CT_ChartSpace
10+
from pptx.package import Package
11+
from pptx.parts.embeddedpackage import EmbeddedXlsxPart
12+
from pptx.util import lazyproperty
13+
14+
class ChartPart(XmlPart, Generic[_SeriesType, _PlotType]):
15+
"""A chart part.
16+
17+
Corresponds to parts having partnames matching ppt/charts/chart[1-9][0-9]*.xml
18+
"""
19+
20+
partname_template: str = ...
21+
@classmethod
22+
def new(cls, chart_type: XL_CHART_TYPE, chart_data: ChartData, package: Package) -> Self:
23+
"""Return new |ChartPart| instance added to `package`.
24+
25+
Returned chart-part contains a chart of `chart_type` depicting `chart_data`.
26+
"""
27+
...
28+
29+
@lazyproperty
30+
def chart(self) -> Chart[_SeriesType, _PlotType]:
31+
"""|Chart| object representing the chart in this part."""
32+
...
33+
34+
@lazyproperty
35+
def chart_workbook(self) -> ChartWorkbook:
36+
"""
37+
The |ChartWorkbook| object providing access to the external chart
38+
data in a linked or embedded Excel workbook.
39+
"""
40+
...
41+
42+
class ChartWorkbook(Generic[_SeriesType, _PlotType]):
43+
"""Provides access to external chart data in a linked or embedded Excel workbook."""
44+
def __init__(self, chartSpace: CT_ChartSpace, chart_part: ChartPart[_SeriesType, _PlotType]) -> None: ...
45+
def update_from_xlsx_blob(self, xlsx_blob: bytes) -> None:
46+
"""
47+
Replace the Excel spreadsheet in the related |EmbeddedXlsxPart| with
48+
the Excel binary in *xlsx_blob*, adding a new |EmbeddedXlsxPart| if
49+
there isn't one.
50+
"""
51+
...
52+
53+
@property
54+
def xlsx_part(self) -> EmbeddedXlsxPart | None:
55+
"""Optional |EmbeddedXlsxPart| object containing data for this chart.
56+
57+
This related part has its rId at `c:chartSpace/c:externalData/@rId`. This value
58+
is |None| if there is no `<c:externalData>` element.
59+
"""
60+
...
61+
62+
@xlsx_part.setter
63+
def xlsx_part(self, xlsx_part: EmbeddedXlsxPart) -> None:
64+
"""
65+
Set the related |EmbeddedXlsxPart| to *xlsx_part*. Assume one does
66+
not already exist.
67+
"""
68+
...

0 commit comments

Comments
 (0)