feat: Complete draft 1 for typehints

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

Author: AvishrantsSh

.gitignore

@@ -39,9 +39,8 @@ coverage.xml
 htmlcov/
 coverage/
 .cache/
-stub.py
 
 # Stub project specific
 # Keep only .pyi and metadata
 *.py
-!**/*.pyi
+!**/*.pyi

pptx-stubs/chart/chart.pyi

@@ -4,7 +4,7 @@ from pptx.chart.axis import CategoryAxis, DateAxis, ValueAxis
 from pptx.chart.data import _BaseChartData
 from pptx.chart.legend import Legend
 from pptx.chart.plot import _BasePlot
-from pptx.chart.series import SeriesCollection, _BaseSeries
+from pptx.chart.series import SeriesCollection, _BaseCategorySeries, _BaseSeries
 from pptx.dml.chtfmt import ChartFormat
 from pptx.enum.chart import XL_CHART_TYPE
 from pptx.oxml.chart.chart import CT_ChartSpace, CT_PlotArea
@@ -15,6 +15,7 @@ from pptx.text.text import Font, TextFrame
 from pptx.util import lazyproperty
 
 class Chart[SeriesType: _BaseSeries, PlotType: _BasePlot](PartElementProxy):
+    _chartSpace: CT_ChartSpace
     def __init__(self, chartSpace: CT_ChartSpace, chart_part: ChartPart) -> None: ...
     @property
     def category_axis(self) -> CategoryAxis | DateAxis | ValueAxis: ...
@@ -46,7 +47,16 @@ class Chart[SeriesType: _BaseSeries, PlotType: _BasePlot](PartElementProxy):
     @property
     def value_axis(self) -> ValueAxis: ...
 
+DefaultChart = Chart[_BaseSeries | _BaseCategorySeries, _BasePlot]
+"""Type-checking alias.
+
+This symbol exists only in stubs and is not available at runtime.
+Do not import or reference it in production code. Always import this under
+`TYPE_CHECKING` guards.
+"""
+
 class ChartTitle(ElementProxy):
+    _title: CT_Title
     def __init__(self, title: CT_Title) -> None: ...
     @lazyproperty
     def format(self) -> ChartFormat: ...
@@ -58,6 +68,8 @@ class ChartTitle(ElementProxy):
     def text_frame(self) -> TextFrame: ...
 
 class _Plots[PlotType: _BasePlot](Sequence[PlotType]):
+    _plotArea: CT_PlotArea
+    _chart: Chart
     def __init__(self, plotArea: CT_PlotArea, chart: Chart) -> None: ...
     def __getitem__(self, index: slice | int) -> PlotType: ...
     def __len__(self) -> int: ...

pptx-stubs/enum/__init__.pyi

@@ -0,0 +1,20 @@
+from pptx.enum.base import BaseEnum
+
+class PP_ACTION_TYPE(BaseEnum):
+    END_SHOW = ...
+    FIRST_SLIDE = ...
+    HYPERLINK = ...
+    LAST_SLIDE = ...
+    LAST_SLIDE_VIEWED = ...
+    NAMED_SLIDE = ...
+    NAMED_SLIDE_SHOW = ...
+    NEXT_SLIDE = ...
+    NONE = ...
+    OPEN_FILE = ...
+    OLE_VERB = ...
+    PLAY = ...
+    PREVIOUS_SLIDE = ...
+    RUN_MACRO = ...
+    RUN_PROGRAM = ...
+
+PP_ACTION = PP_ACTION_TYPE

pptx-stubs/enum/action.pyi

@@ -0,0 +1,22 @@
+import enum
+from typing import Any, Self
+
+class BaseEnum(int, enum.Enum):
+    def __new__(cls, ms_api_value: int, docstr: str) -> Self: ...
+    def __str__(self) -> str: ...
+
+class BaseXmlEnum[T: BaseXmlEnum](int, enum.Enum):
+    xml_value: str | None
+    def __new__(cls, ms_api_value: int, xml_value: str | None, docstr: str) -> Self: ...
+    def __str__(self) -> str: ...
+    @classmethod
+    def from_xml(cls, xml_value: str) -> Self: ...
+    @classmethod
+    def to_xml(cls: type[T], value: int | T) -> str: ...
+    @classmethod
+    def validate(cls: type[T], value: T) -> None: ...
+
+class DocsPageFormatter:
+    def __init__(self, clsname: str, clsdict: dict[str, Any]) -> None: ...
+    @property
+    def page_str(self) -> str: ...

pptx-stubs/enum/base.pyi

@@ -0,0 +1,135 @@
+from pptx.enum.base import BaseEnum, BaseXmlEnum
+
+class XL_AXIS_CROSSES(BaseXmlEnum):
+    AUTOMATIC = ...
+    CUSTOM = ...
+    MAXIMUM = ...
+    MINIMUM = ...
+
+class XL_CATEGORY_TYPE(BaseEnum):
+    AUTOMATIC_SCALE = ...
+    CATEGORY_SCALE = ...
+    TIME_SCALE = ...
+
+class XL_CHART_TYPE(BaseEnum):
+    THREE_D_AREA = ...
+    THREE_D_AREA_STACKED = ...
+    THREE_D_AREA_STACKED_100 = ...
+    THREE_D_BAR_CLUSTERED = ...
+    THREE_D_BAR_STACKED = ...
+    THREE_D_BAR_STACKED_100 = ...
+    THREE_D_COLUMN = ...
+    THREE_D_COLUMN_CLUSTERED = ...
+    THREE_D_COLUMN_STACKED = ...
+    THREE_D_COLUMN_STACKED_100 = ...
+    THREE_D_LINE = ...
+    THREE_D_PIE = ...
+    THREE_D_PIE_EXPLODED = ...
+    AREA = ...
+    AREA_STACKED = ...
+    AREA_STACKED_100 = ...
+    BAR_CLUSTERED = ...
+    BAR_OF_PIE = ...
+    BAR_STACKED = ...
+    BAR_STACKED_100 = ...
+    BUBBLE = ...
+    BUBBLE_THREE_D_EFFECT = ...
+    COLUMN_CLUSTERED = ...
+    COLUMN_STACKED = ...
+    COLUMN_STACKED_100 = ...
+    CONE_BAR_CLUSTERED = ...
+    CONE_BAR_STACKED = ...
+    CONE_BAR_STACKED_100 = ...
+    CONE_COL = ...
+    CONE_COL_CLUSTERED = ...
+    CONE_COL_STACKED = ...
+    CONE_COL_STACKED_100 = ...
+    CYLINDER_BAR_CLUSTERED = ...
+    CYLINDER_BAR_STACKED = ...
+    CYLINDER_BAR_STACKED_100 = ...
+    CYLINDER_COL = ...
+    CYLINDER_COL_CLUSTERED = ...
+    CYLINDER_COL_STACKED = ...
+    CYLINDER_COL_STACKED_100 = ...
+    DOUGHNUT = ...
+    DOUGHNUT_EXPLODED = ...
+    LINE = ...
+    LINE_MARKERS = ...
+    LINE_MARKERS_STACKED = ...
+    LINE_MARKERS_STACKED_100 = ...
+    LINE_STACKED = ...
+    LINE_STACKED_100 = ...
+    PIE = ...
+    PIE_EXPLODED = ...
+    PIE_OF_PIE = ...
+    PYRAMID_BAR_CLUSTERED = ...
+    PYRAMID_BAR_STACKED = ...
+    PYRAMID_BAR_STACKED_100 = ...
+    PYRAMID_COL = ...
+    PYRAMID_COL_CLUSTERED = ...
+    PYRAMID_COL_STACKED = ...
+    PYRAMID_COL_STACKED_100 = ...
+    RADAR = ...
+    RADAR_FILLED = ...
+    RADAR_MARKERS = ...
+    STOCK_HLC = ...
+    STOCK_OHLC = ...
+    STOCK_VHLC = ...
+    STOCK_VOHLC = ...
+    SURFACE = ...
+    SURFACE_TOP_VIEW = ...
+    SURFACE_TOP_VIEW_WIREFRAME = ...
+    SURFACE_WIREFRAME = ...
+    XY_SCATTER = ...
+    XY_SCATTER_LINES = ...
+    XY_SCATTER_LINES_NO_MARKERS = ...
+    XY_SCATTER_SMOOTH = ...
+    XY_SCATTER_SMOOTH_NO_MARKERS = ...
+
+class XL_DATA_LABEL_POSITION(BaseXmlEnum):
+    ABOVE = ...
+    BELOW = ...
+    BEST_FIT = ...
+    CENTER = ...
+    INSIDE_BASE = ...
+    INSIDE_END = ...
+    LEFT = ...
+    MIXED = ...
+    OUTSIDE_END = ...
+    RIGHT = ...
+
+XL_LABEL_POSITION = XL_DATA_LABEL_POSITION
+
+class XL_LEGEND_POSITION(BaseXmlEnum):
+    BOTTOM = ...
+    CORNER = ...
+    CUSTOM = ...
+    LEFT = ...
+    RIGHT = ...
+    TOP = ...
+
+class XL_MARKER_STYLE(BaseXmlEnum):
+    AUTOMATIC = ...
+    CIRCLE = ...
+    DASH = ...
+    DIAMOND = ...
+    DOT = ...
+    NONE = ...
+    PICTURE = ...
+    PLUS = ...
+    SQUARE = ...
+    STAR = ...
+    TRIANGLE = ...
+    X = ...
+
+class XL_TICK_MARK(BaseXmlEnum):
+    CROSS = ...
+    INSIDE = ...
+    NONE = ...
+    OUTSIDE = ...
+
+class XL_TICK_LABEL_POSITION(BaseXmlEnum):
+    HIGH = ...
+    LOW = ...
+    NEXT_TO_AXIS = ...
+    NONE = ...

pptx-stubs/enum/chart.pyi

@@ -0,0 +1,114 @@
+from pptx.enum.base import BaseEnum, BaseXmlEnum
+
+class MSO_COLOR_TYPE(BaseEnum):
+    RGB = ...
+    SCHEME = ...
+    HSL = ...
+    PRESET = ...
+    SCRGB = ...
+    SYSTEM = ...
+
+class MSO_FILL_TYPE(BaseEnum):
+    BACKGROUND = ...
+    GRADIENT = ...
+    GROUP = ...
+    PATTERNED = ...
+    PICTURE = ...
+    SOLID = ...
+    TEXTURED = ...
+
+MSO_FILL = MSO_FILL_TYPE
+
+class MSO_LINE_DASH_STYLE(BaseXmlEnum):
+    DASH = ...
+    DASH_DOT = ...
+    DASH_DOT_DOT = ...
+    LONG_DASH = ...
+    LONG_DASH_DOT = ...
+    ROUND_DOT = ...
+    SOLID = ...
+    SQUARE_DOT = ...
+    DASH_STYLE_MIXED = ...
+
+MSO_LINE = MSO_LINE_DASH_STYLE
+
+class MSO_PATTERN_TYPE(BaseXmlEnum):
+    CROSS = ...
+    DARK_DOWNWARD_DIAGONAL = ...
+    DARK_HORIZONTAL = ...
+    DARK_UPWARD_DIAGONAL = ...
+    DARK_VERTICAL = ...
+    DASHED_DOWNWARD_DIAGONAL = ...
+    DASHED_HORIZONTAL = ...
+    DASHED_UPWARD_DIAGONAL = ...
+    DASHED_VERTICAL = ...
+    DIAGONAL_BRICK = ...
+    DIAGONAL_CROSS = ...
+    DIVOT = ...
+    DOTTED_DIAMOND = ...
+    DOTTED_GRID = ...
+    DOWNWARD_DIAGONAL = ...
+    HORIZONTAL = ...
+    HORIZONTAL_BRICK = ...
+    LARGE_CHECKER_BOARD = ...
+    LARGE_CONFETTI = ...
+    LARGE_GRID = ...
+    LIGHT_DOWNWARD_DIAGONAL = ...
+    LIGHT_HORIZONTAL = ...
+    LIGHT_UPWARD_DIAGONAL = ...
+    LIGHT_VERTICAL = ...
+    NARROW_HORIZONTAL = ...
+    NARROW_VERTICAL = ...
+    OUTLINED_DIAMOND = ...
+    PERCENT_10 = ...
+    PERCENT_20 = ...
+    PERCENT_25 = ...
+    PERCENT_30 = ...
+    ERCENT_40 = ...
+    PERCENT_5 = ...
+    PERCENT_50 = ...
+    PERCENT_60 = ...
+    PERCENT_70 = ...
+    PERCENT_75 = ...
+    PERCENT_80 = ...
+    PERCENT_90 = ...
+    PLAID = ...
+    SHINGLE = ...
+    SMALL_CHECKER_BOARD = ...
+    SMALL_CONFETTI = ...
+    SMALL_GRID = ...
+    SOLID_DIAMOND = ...
+    SPHERE = ...
+    TRELLIS = ...
+    UPWARD_DIAGONAL = ...
+    VERTICAL = ...
+    WAVE = ...
+    WEAVE = ...
+    WIDE_DOWNWARD_DIAGONAL = ...
+    WIDE_UPWARD_DIAGONAL = ...
+    ZIG_ZAG = ...
+    MIXED = ...
+
+MSO_PATTERN = MSO_PATTERN_TYPE
+
+class MSO_THEME_COLOR_INDEX(BaseXmlEnum):
+    NOT_THEME_COLOR = ...
+    ACCENT_1 = ...
+    ACCENT_2 = ...
+    ACCENT_3 = ...
+    ACCENT_4 = ...
+    ACCENT_5 = ...
+    ACCENT_6 = ...
+    BACKGROUND_1 = ...
+    BACKGROUND_2 = ...
+    DARK_1 = ...
+    DARK_2 = ...
+    FOLLOWED_HYPERLINK = ...
+    HYPERLINK = ...
+    LIGHT_1 = ...
+    LIGHT_2 = ...
+    TEXT_1 = ...
+    TEXT_2 = ...
+    MIXED = ...
+
+MSO_THEME_COLOR = MSO_THEME_COLOR_INDEX