chore: Add initial stubs for pptx.text, pptx.dml and pptx.parts modules

- chore: Correct typing hints for generator expressions
- chore: Remove redundant docstrings

Signed-off-by: Avishrant Sharma <[email protected]>

Author: AvishrantsSh

pptx-stubs/action.pyi

@@ -7,73 +7,27 @@ from pptx.slide import Slide
 from pptx.util import lazyproperty
 
 class ActionSetting(Subshape):
-    """Properties specifying how a shape or run reacts to mouse actions."""
+    _element: CT_NonVisualDrawingProps | CT_TextCharacterProperties
+    _hover: bool
     def __init__(
         self, xPr: CT_NonVisualDrawingProps | CT_TextCharacterProperties, parent: BaseShape, hover: bool = ...
     ) -> None: ...
     @property
-    def action(self) -> PP_ACTION_TYPE:
-        """Member of :ref:`PpActionType` enumeration, such as `PP_ACTION.HYPERLINK`.
-
-        The returned member indicates the type of action that will result when the
-        specified shape or text is clicked or the mouse pointer is positioned over the
-        shape during a slide show.
-
-        If there is no click-action or the click-action value is not recognized (is not
-        one of the official `MsoPpAction` values) then `PP_ACTION.NONE` is returned.
-        """
-        ...
-
+    def action(self) -> PP_ACTION_TYPE: ...
     @lazyproperty
-    def hyperlink(self) -> Hyperlink:
-        """
-        A |Hyperlink| object representing the hyperlink action defined on
-        this click or hover mouse event. A |Hyperlink| object is always
-        returned, even if no hyperlink or other click action is defined.
-        """
-        ...
-
+    def hyperlink(self) -> Hyperlink: ...
     @property
-    def target_slide(self) -> Slide | None:
-        """
-        A reference to the slide in this presentation that is the target of
-        the slide jump action in this shape. Slide jump actions include
-        `PP_ACTION.FIRST_SLIDE`, `LAST_SLIDE`, `NEXT_SLIDE`,
-        `PREVIOUS_SLIDE`, and `NAMED_SLIDE`. Returns |None| for all other
-        actions. In particular, the `LAST_SLIDE_VIEWED` action and the `PLAY`
-        (start other presentation) actions are not supported.
-
-        A slide object may be assigned to this property, which makes the
-        shape an "internal hyperlink" to the assigened slide::
-
-            slide, target_slide = prs.slides[0], prs.slides[1]
-            shape = slide.shapes[0]
-            shape.target_slide = target_slide
-
-        Assigning |None| removes any slide jump action. Note that this is
-        accomplished by removing any action present (such as a hyperlink),
-        without first checking that it is a slide jump action.
-        """
-        ...
-
+    def target_slide(self) -> Slide | None: ...
     @target_slide.setter
     def target_slide(self, slide: Slide | None) -> None: ...
 
 class Hyperlink(Subshape):
-    """Represents a hyperlink action on a shape or text run."""
+    _element: CT_NonVisualDrawingProps | CT_TextCharacterProperties
+    _hover: bool
     def __init__(
         self, xPr: CT_NonVisualDrawingProps | CT_TextCharacterProperties, parent: BaseShape, hover: bool = ...
     ) -> None: ...
     @property
-    def address(self) -> str | None:
-        """Read/write. The URL of the hyperlink.
-
-        URL can be on http, https, mailto, or file scheme; others may work. Returns |None| if no
-        hyperlink is defined, including when another action such as `RUN_MACRO` is defined on the
-        object. Assigning |None| removes any action defined on the object, whether it is a hyperlink
-        action or not.
-        """
-        ...
-
+    def address(self) -> str | None: ...
     @address.setter
     def address(self, url: str | None) -> None: ...

pptx-stubs/api.pyi

@@ -2,11 +2,4 @@ from typing import IO
 
 from pptx import presentation
 
-def Presentation(pptx: str | IO[bytes] | None = ...) -> presentation.Presentation:
-    """
-    Return a |Presentation| object loaded from *pptx*, where *pptx* can be
-    either a path to a ``.pptx`` file (a string) or a file-like object. If
-    *pptx* is missing or ``None``, the built-in default presentation
-    "template" is loaded.
-    """
-    ...
+def Presentation(pptx: str | IO[bytes] | None = ...) -> presentation.Presentation: ...

pptx-stubs/chart/category.pyi

@@ -1,13 +1,14 @@
 from collections.abc import Generator, Iterable, Sequence
-from typing import Any, Self
+from typing import Self
 
 from pptx.oxml.chart.plot import BaseChartElement
 from pptx.oxml.chart.series import CT_Lvl, CT_StrVal_NumVal_Composite
 
 class Categories(Sequence[Category]):
+    _xChart: BaseChartElement
     def __init__(self, xChart: BaseChartElement) -> None: ...
     def __getitem__(self, idx) -> Category: ...
-    def __iter__(self) -> Generator[Category, Any, None]: ...
+    def __iter__(self) -> Generator[Category]: ...
     def __len__(self) -> int: ...
     @property
     def depth(self) -> int: ...
@@ -17,6 +18,9 @@ class Categories(Sequence[Category]):
     def levels(self) -> list[CategoryLevel]: ...
 
 class Category(str):
+    _element: CT_StrVal_NumVal_Composite
+    _pt: CT_StrVal_NumVal_Composite
+    _idx: int | None
     def __new__(cls, pt: CT_StrVal_NumVal_Composite | None, *args) -> Self: ...
     def __init__(self, pt: CT_StrVal_NumVal_Composite | None, idx: int | None = ...) -> None: ...
     @property
@@ -25,6 +29,8 @@ class Category(str):
     def label(self) -> str: ...
 
 class CategoryLevel(Sequence):
+    _lvl: CT_Lvl
+    _element: CT_Lvl
     def __init__(self, lvl: CT_Lvl) -> None: ...
     def __getitem__(self, offset: int) -> Category: ...
     def __len__(self) -> int: ...

pptx-stubs/chart/data.pyi

@@ -74,7 +74,7 @@ class Categories(Sequence[Category]):
     @property
     def leaf_count(self) -> int: ...
     @property
-    def levels(self) -> Generator[list[tuple[Any, Any]], Any, None]: ...
+    def levels(self) -> Generator[list[tuple[Any, Any]]]: ...
     @property
     def number_format(self) -> str: ...
     @number_format.setter

pptx-stubs/chart/series.pyi

@@ -1,5 +1,4 @@
 from collections.abc import Generator, Sequence
-from typing import Any
 
 from pptx.chart.datalabel import DataLabels
 from pptx.chart.marker import Marker
@@ -49,7 +48,7 @@ class PieSeries(_BaseCategorySeries): ...
 class RadarSeries(_BaseCategorySeries, _MarkerMixin): ...
 
 class XySeries(_BaseSeries, _MarkerMixin):
-    def iter_values(self) -> Generator[float, Any, None]: ...
+    def iter_values(self) -> Generator[float]: ...
     @lazyproperty
     def points(self) -> XyPoints: ...
     @property

pptx-stubs/dml/chtfmt.pyi

@@ -4,25 +4,7 @@ from pptx.shared import ElementProxy
 from pptx.util import lazyproperty
 
 class ChartFormat(ElementProxy):
-    """
-    The |ChartFormat| object provides access to visual shape properties for
-    chart elements like |Axis|, |Series|, and |MajorGridlines|. It has two
-    properties, :attr:`fill` and :attr:`line`, which return a |FillFormat|
-    and |LineFormat| object respectively. The |ChartFormat| object is
-    provided by the :attr:`format` property on the target axis, series, etc.
-    """
     @lazyproperty
-    def fill(self) -> FillFormat:
-        """
-        |FillFormat| instance for this object, providing access to fill
-        properties such as fill color.
-        """
-        ...
-
+    def fill(self) -> FillFormat: ...
     @lazyproperty
-    def line(self) -> LineFormat:
-        """
-        The |LineFormat| object providing access to the visual properties of
-        this object, such as line color and line style.
-        """
-        ...
+    def line(self) -> LineFormat: ...

pptx-stubs/dml/color.pyi

@@ -1,89 +1,55 @@
 from typing import Literal, Self
 
 from pptx.enum.dml import MSO_COLOR_TYPE, MSO_THEME_COLOR, MSO_THEME_COLOR_INDEX
-from pptx.oxml.dml.color import CT_Color, CT_SRgbColor, _BaseColorElement
+from pptx.oxml.dml.color import (
+    CT_Color,
+    CT_HslColor,
+    CT_PresetColor,
+    CT_SchemeColor,
+    CT_ScRgbColor,
+    CT_SRgbColor,
+    CT_SystemColor,
+)
+
+type ColorElement = CT_HslColor | CT_PresetColor | CT_SchemeColor | CT_ScRgbColor | CT_ScRgbColor | CT_SystemColor
 
 class ColorFormat:
-    """
-    Provides access to color settings such as RGB color, theme color, and
-    luminance adjustments.
-    """
+    _xFill: CT_Color
+    _color: _Color
     def __init__(self, eg_colorChoice_parent: CT_Color, color: _Color) -> None: ...
     @property
-    def brightness(self) -> float:
-        """
-        Read/write float value between -1.0 and 1.0 indicating the brightness
-        adjustment for this color, e.g. -0.25 is 25% darker and 0.4 is 40%
-        lighter. 0 means no brightness adjustment.
-        """
-        ...
-
+    def brightness(self) -> float: ...
     @brightness.setter
     def brightness(self, value: float) -> None: ...
     @classmethod
     def from_colorchoice_parent(cls, eg_colorChoice_parent: CT_Color) -> Self: ...
     @property
-    def rgb(self) -> RGBColor:
-        """
-        |RGBColor| value of this color, or None if no RGB color is explicitly
-        defined for this font. Setting this value to an |RGBColor| instance
-        causes its type to change to MSO_COLOR_TYPE.RGB. If the color was a
-        theme color with a brightness adjustment, the brightness adjustment
-        is removed when changing it to an RGB color.
-        """
-        ...
-
+    def rgb(self) -> RGBColor: ...
     @rgb.setter
     def rgb(self, rgb: RGBColor) -> None: ...
     @property
-    def theme_color(self) -> MSO_THEME_COLOR_INDEX:
-        """Theme color value of this color.
-
-        Value is a member of :ref:`MsoThemeColorIndex`, e.g.
-        ``MSO_THEME_COLOR.ACCENT_1``. Raises AttributeError on access if the
-        color is not type ``MSO_COLOR_TYPE.SCHEME``. Assigning a member of
-        :ref:`MsoThemeColorIndex` causes the color's type to change to
-        ``MSO_COLOR_TYPE.SCHEME``.
-        """
-        ...
-
+    def theme_color(self) -> MSO_THEME_COLOR_INDEX: ...
     @theme_color.setter
     def theme_color(self, mso_theme_color_idx: MSO_THEME_COLOR_INDEX) -> None: ...
     @property
-    def type(self) -> MSO_COLOR_TYPE:
-        """
-        Read-only. A value from :ref:`MsoColorType`, either RGB or SCHEME,
-        corresponding to the way this color is defined, or None if no color
-        is defined at the level of this font.
-        """
-        ...
+    def type(self) -> MSO_COLOR_TYPE: ...
 
 class _Color:
-    """
-    Object factory for color object of the appropriate type, also the base
-    class for all color type classes such as SRgbColor.
-    """
-    def __new__(cls, xClr: _BaseColorElement | None) -> Self: ...
-    def __init__(self, xClr: _BaseColorElement | None) -> None: ...
+    _xclr: ColorElement
+    def __new__(cls, xClr: ColorElement | None) -> Self: ...
+    def __init__(self, xClr: ColorElement | None) -> None: ...
     @property
     def brightness(self) -> float: ...
     @brightness.setter
     def brightness(self, value: float) -> None: ...
     @property
     def color_type(self) -> MSO_COLOR_TYPE: ...
     @property
-    def rgb(self) -> RGBColor:
-        """
-        Raises TypeError on access unless overridden by subclass.
-        """
-        ...
-
+    def rgb(self) -> RGBColor: ...
     @property
-    def theme_color(self) -> Literal[MSO_THEME_COLOR_INDEX.NOT_THEME_COLOR]:
-        """
-        Raises TypeError on access unless overridden by subclass.
-        """
-        ...
+    def theme_color(self) -> Literal[MSO_THEME_COLOR_INDEX.NOT_THEME_COLOR]: ...
+    def _shade(self, value: float): ...
+    def _tint(self, value: float): ...
 
 class _HslColor(_Color):
     @property
@@ -93,12 +59,7 @@ class _NoneColor(_Color):
     @property
     def color_type(self) -> None: ...
     @property
-    def theme_color(self):
-        """
-        Raise TypeError on attempt to access .theme_color when no color
-        choice is present.
-        """
-        ...
+    def theme_color(self): ...
 
 class _PrstColor(_Color):
     @property
@@ -109,16 +70,7 @@ class _SchemeColor(_Color):
     @property
     def color_type(self) -> Literal[MSO_COLOR_TYPE.SCHEME]: ...
     @property
-    def theme_color(self) -> MSO_THEME_COLOR | None:
-        """
-        Theme color value of this color, one of those defined in the
-        MSO_THEME_COLOR enumeration, e.g. MSO_THEME_COLOR.ACCENT_1. None if
-        no theme color is explicitly defined for this font. Setting this to a
-        value in MSO_THEME_COLOR causes the color's type to change to
-        ``MSO_COLOR_TYPE.SCHEME``.
-        """
-        ...
-
+    def theme_color(self) -> MSO_THEME_COLOR | None: ...
     @theme_color.setter
     def theme_color(self, mso_theme_color_idx: MSO_THEME_COLOR) -> None: ...
 
@@ -131,13 +83,7 @@ class _SRgbColor(_Color):
     @property
     def color_type(self) -> Literal[MSO_COLOR_TYPE.RGB]: ...
     @property
-    def rgb(self) -> RGBColor:
-        """
-        |RGBColor| value of this color, corresponding to the value in the
-        required ``val`` attribute of the ``<a:srgbColr>`` element.
-        """
-        ...
-
+    def rgb(self) -> RGBColor: ...
     @rgb.setter
     def rgb(self, rgb) -> None: ...
 
@@ -146,19 +92,7 @@ class _SysColor(_Color):
     def color_type(self) -> Literal[MSO_COLOR_TYPE.SYSTEM]: ...
 
 class RGBColor(tuple[int, int, int]):
-    """
-    Immutable value object defining a particular RGB color.
-    """
     def __new__(cls, r: int, g: int, b: int) -> Self: ...
-    def __str__(self) -> str:
-        """
-        Return a hex string rgb value, like '3C2F80'
-        """
-        ...
-
+    def __str__(self) -> str: ...
     @classmethod
-    def from_string(cls, rgb_hex_str: str) -> Self:
-        """
-        Return a new instance from an RGB color hex string like ``'3C2F80'``.
-        """
-        ...
+    def from_string(cls, rgb_hex_str: str) -> Self: ...

pptx-stubs/dml/effect.pyi

@@ -2,25 +2,9 @@ from pptx.oxml.shapes.groupshape import CT_GroupShapeProperties
 from pptx.oxml.shapes.shared import CT_ShapeProperties
 
 class ShadowFormat:
-    """Provides access to shadow effect on a shape."""
+    _element: CT_ShapeProperties | CT_GroupShapeProperties
     def __init__(self, spPr: CT_ShapeProperties | CT_GroupShapeProperties) -> None: ...
     @property
-    def inherit(self) -> bool:
-        """True if shape inherits shadow settings.
-
-        Read/write. An explicitly-defined shadow setting on a shape causes
-        this property to return |False|. A shape with no explicitly-defined
-        shadow setting inherits its shadow settings from the style hierarchy
-        (and so returns |True|).
-
-        Assigning |True| causes any explicitly-defined shadow setting to be
-        removed and inheritance is restored. Note this has the side-effect of
-        removing **all** explicitly-defined effects, such as glow and
-        reflection, and restoring inheritance for all effects on the shape.
-        Assigning |False| causes the inheritance link to be broken and **no**
-        effects to appear on the shape.
-        """
-        ...
-
+    def inherit(self) -> bool: ...
     @inherit.setter
     def inherit(self, value: bool) -> None: ...