fix: Fix docstrings for OptioanlAttribute

- chore: Replace raw default value with class member, where possible

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

Author: AvishrantsSh

pptx-stubs/opc/oxml.pyi

@@ -69,7 +69,7 @@ class CT_Relationship(BaseOxmlElement):
     def target_ref(self, value: str) -> None: ...
     @property
     def targetMode(self) -> str:
-        """ST_TargetMode type-converted value of ``TargetMode`` attribute, or |INTERNAL|. Assigning the default value causes the attribute to be removed from the element."""
+        """ST_TargetMode type-converted value of ``TargetMode`` attribute, or |RELATIONSHIP_TARGET_MODE.INTERNAL| if not present. Assigning the default value causes the attribute to be removed from the element."""
         ...
 
     @targetMode.setter

pptx-stubs/oxml/chart/axis.pyi

@@ -290,7 +290,7 @@ class CT_DateAx(BaseAxisElement):
 class CT_LblOffset(BaseOxmlElement):
     @property
     def val(self) -> int:
-        """ST_LblOffset type-converted value of ``val`` attribute, or |100|. Assigning the default value causes the attribute to be removed from the element."""
+        """ST_LblOffset type-converted value of ``val`` attribute, or |100| if not present. Assigning the default value causes the attribute to be removed from the element."""
         ...
 
     @val.setter
@@ -299,7 +299,7 @@ class CT_LblOffset(BaseOxmlElement):
 class CT_Orientation(BaseOxmlElement):
     @property
     def val(self) -> str:
-        """ST_Orientation type-converted value of ``val`` attribute, or |minMax|. Assigning the default value causes the attribute to be removed from the element."""
+        """ST_Orientation type-converted value of ``val`` attribute, or |ST_Orientation.MIN_MAX| if not present. Assigning the default value causes the attribute to be removed from the element."""
         ...
 
     @val.setter
@@ -350,7 +350,7 @@ class CT_Scaling(BaseOxmlElement):
 class CT_TickLblPos(BaseOxmlElement):
     @property
     def val(self) -> XL_TICK_LABEL_POSITION | None:
-        """XL_TICK_LABEL_POSITION type-converted value of ``val`` attribute, or |None|. Assigning the default value causes the attribute to be removed from the element."""
+        """XL_TICK_LABEL_POSITION type-converted value of ``val`` attribute, or |None| if not present. Assigning the default value causes the attribute to be removed from the element."""
         ...
 
     @val.setter
@@ -359,7 +359,7 @@ class CT_TickLblPos(BaseOxmlElement):
 class CT_TickMark(BaseOxmlElement):
     @property
     def val(self) -> XL_TICK_MARK:
-        """XL_TICK_MARK type-converted value of ``val`` attribute, or |XL_TICK_MARK.CROSS|. Assigning the default value causes the attribute to be removed from the element."""
+        """XL_TICK_MARK type-converted value of ``val`` attribute, or |XL_TICK_MARK.CROSS| if not present. Assigning the default value causes the attribute to be removed from the element."""
         ...
 
     @val.setter

pptx-stubs/oxml/chart/legend.pyi

@@ -50,7 +50,7 @@ class CT_Legend(BaseOxmlElement):
 class CT_LegendPos(BaseOxmlElement):
     @property
     def val(self) -> XL_LEGEND_POSITION:
-        """XL_LEGEND_POSITION type-converted value of ``val`` attribute, or |XL_LEGEND_POSITION.RIGHT|. Assigning the default value causes the attribute to be removed from the element."""
+        """XL_LEGEND_POSITION type-converted value of ``val`` attribute, or |XL_LEGEND_POSITION.RIGHT| if not present. Assigning the default value causes the attribute to be removed from the element."""
         ...
 
     @val.setter

pptx-stubs/oxml/chart/plot.pyi

@@ -124,7 +124,7 @@ class CT_BarChart(BaseChartElement):
 class CT_BarDir(BaseOxmlElement):
     @property
     def val(self) -> str:
-        """ST_BarDir type-converted value of ``val`` attribute, or |col|. Assigning the default value causes the attribute to be removed from the element."""
+        """ST_BarDir type-converted value of ``val`` attribute, or |ST_BarDir.COL| if not present. Assigning the default value causes the attribute to be removed from the element."""
         ...
 
     @val.setter
@@ -166,7 +166,7 @@ class CT_BubbleChart(BaseChartElement):
 class CT_BubbleScale(BaseChartElement):
     @property
     def val(self) -> int:
-        """ST_BubbleScale type-converted value of ``val`` attribute, or |100|. Assigning the default value causes the attribute to be removed from the element."""
+        """ST_BubbleScale type-converted value of ``val`` attribute, or |100| if not present. Assigning the default value causes the attribute to be removed from the element."""
         ...
 
     @val.setter
@@ -199,7 +199,7 @@ class CT_DoughnutChart(BaseChartElement):
 class CT_GapAmount(BaseOxmlElement):
     @property
     def val(self) -> int:
-        """ST_GapAmount type-converted value of ``val`` attribute, or |150|. Assigning the default value causes the attribute to be removed from the element."""
+        """ST_GapAmount type-converted value of ``val`` attribute, or |150| if not present. Assigning the default value causes the attribute to be removed from the element."""
         ...
 
     @val.setter
@@ -250,7 +250,7 @@ class CT_LineChart(BaseChartElement):
 class CT_Overlap(BaseOxmlElement):
     @property
     def val(self) -> int:
-        """ST_Overlap type-converted value of ``val`` attribute, or |0|. Assigning the default value causes the attribute to be removed from the element."""
+        """ST_Overlap type-converted value of ``val`` attribute, or |0| if not present. Assigning the default value causes the attribute to be removed from the element."""
         ...
 
     @val.setter

pptx-stubs/oxml/chart/series.pyi

@@ -1,3 +1,4 @@
+from lxml.etree import _Element
 from pptx.oxml.chart.datalabel import CT_DLbl, CT_DLbls
 from pptx.oxml.chart.marker import CT_Marker
 from pptx.oxml.chart.shared import CT_Boolean, CT_Boolean_Explicit, CT_Tx, CT_UnsignedInt
@@ -6,8 +7,12 @@ from pptx.oxml.xmlchemy import BaseOxmlElement
 
 class CT_AxDataSource(BaseOxmlElement):
     @property
-    def multiLvlStrRef(self) -> BaseOxmlElement | None: ...
-    def get_or_add_multiLvlStrRef(self) -> BaseOxmlElement: ...
+    def multiLvlStrRef(self) -> _Element | None:
+        """``<c:multiLvlStrRef>`` child element or |None| if not present."""
+        ...
+    def get_or_add_multiLvlStrRef(self) -> _Element:
+        """Return the ``<c:multiLvlStrRef>`` child element, newly added if not present."""
+        ...
     @property
     def lvls(self) -> list[CT_Lvl]: ...
 
@@ -46,7 +51,10 @@ class CT_Lvl(BaseOxmlElement):
 
 class CT_NumDataSource(BaseOxmlElement):
     @property
-    def numRef(self) -> BaseOxmlElement: ...
+    def numRef(self) -> _Element:
+        """Required ``<c:numRef>`` child element."""
+        ...
+
     @property
     def ptCount_val(self) -> int: ...
     def pt_v(self, idx: int) -> float | None: ...
@@ -180,7 +188,7 @@ class CT_SeriesComposite(BaseOxmlElement):
 
 class CT_StrVal_NumVal_Composite(BaseOxmlElement):
     @property
-    def v(self) -> BaseOxmlElement:
+    def v(self) -> _Element:
         """Required ``<c:v>`` child element."""
         ...
 

pptx-stubs/oxml/chart/shared.pyi

@@ -1,11 +1,12 @@
+from lxml.etree import _Element
 from pptx.oxml.shapes.shared import CT_ShapeProperties
 from pptx.oxml.text import CT_TextBody
 from pptx.oxml.xmlchemy import BaseOxmlElement
 
 class CT_Boolean(BaseOxmlElement):
     @property
     def val(self) -> bool:
-        """XsdBoolean type-converted value of ``val`` attribute, or |True|. Assigning the default value causes the attribute to be removed from the element."""
+        """XsdBoolean type-converted value of ``val`` attribute, or |True| if not present. Assigning the default value causes the attribute to be removed from the element."""
         ...
 
     @val.setter
@@ -14,7 +15,7 @@ class CT_Boolean(BaseOxmlElement):
 class CT_Boolean_Explicit(BaseOxmlElement):
     @property
     def _val(self) -> bool:
-        """XsdBoolean type-converted value of ``val`` attribute, or |True|. Assigning the default value causes the attribute to be removed from the element."""
+        """XsdBoolean type-converted value of ``val`` attribute, or |True| if not present. Assigning the default value causes the attribute to be removed from the element."""
         ...
 
     @_val.setter
@@ -51,7 +52,7 @@ class CT_Layout(BaseOxmlElement):
 class CT_LayoutMode(BaseOxmlElement):
     @property
     def val(self) -> str:
-        """ST_LayoutMode type-converted value of ``val`` attribute, or |factor|. Assigning the default value causes the attribute to be removed from the element."""
+        """ST_LayoutMode type-converted value of ``val`` attribute, or |ST_LayoutMode.FACTOR| if not present. Assigning the default value causes the attribute to be removed from the element."""
         ...
 
     @val.setter
@@ -91,7 +92,7 @@ class CT_NumFmt(BaseOxmlElement):
     def formatCode(self, value: str) -> None: ...
     @property
     def sourceLinked(self) -> bool | None:
-        """XsdBoolean type-converted value of ``sourceLinked`` attribute, or |None|. Assigning the default value causes the attribute to be removed from the element."""
+        """XsdBoolean type-converted value of ``sourceLinked`` attribute, or |None| if not present. Assigning the default value causes the attribute to be removed from the element."""
         ...
 
     @sourceLinked.setter
@@ -124,11 +125,11 @@ class CT_Title(BaseOxmlElement):
 
 class CT_Tx(BaseOxmlElement):
     @property
-    def strRef(self) -> BaseOxmlElement | None:
+    def strRef(self) -> _Element | None:
         """``<c:strRef>`` child element or |None| if not present."""
         ...
 
-    def get_or_add_strRef(self) -> BaseOxmlElement:
+    def get_or_add_strRef(self) -> _Element:
         """Return the ``<c:strRef>`` child element, newly added if not present."""
         ...
 

pptx-stubs/oxml/dml/fill.pyi

@@ -15,7 +15,7 @@ from pptx.oxml.xmlchemy import BaseOxmlElement
 class CT_Blip(BaseOxmlElement):
     @property
     def rEmbed(self) -> str | None:
-        """ST_RelationshipId type-converted value of ``r:embed`` attribute, or |None|. Assigning the default value causes the attribute to be removed from the element."""
+        """ST_RelationshipId type-converted value of ``r:embed`` attribute, or |None| if not present. Assigning the default value causes the attribute to be removed from the element."""
         ...
 
     @rEmbed.setter
@@ -161,7 +161,7 @@ class CT_GroupFillProperties(BaseOxmlElement): ...
 class CT_LinearShadeProperties(BaseOxmlElement):
     @property
     def ang(self) -> float | None:
-        """ST_PositiveFixedAngle type-converted value of ``ang`` attribute, or |None|. Assigning the default value causes the attribute to be removed from the element."""
+        """ST_PositiveFixedAngle type-converted value of ``ang`` attribute, or |None| if not present. Assigning the default value causes the attribute to be removed from the element."""
         ...
 
     @ang.setter
@@ -190,7 +190,7 @@ class CT_PatternFillProperties(BaseOxmlElement):
 
     @property
     def prst(self) -> MSO_PATTERN_TYPE | None:
-        """MSO_PATTERN_TYPE type-converted value of ``prst`` attribute, or |None|. Assigning the default value causes the attribute to be removed from the element."""
+        """MSO_PATTERN_TYPE type-converted value of ``prst`` attribute, or |None| if not present. Assigning the default value causes the attribute to be removed from the element."""
         ...
 
     @prst.setter
@@ -199,28 +199,28 @@ class CT_PatternFillProperties(BaseOxmlElement):
 class CT_RelativeRect(BaseOxmlElement):
     @property
     def l(self) -> float:
-        """ST_Percentage type-converted value of ``l`` attribute, or |0.0|. Assigning the default value causes the attribute to be removed from the element."""
+        """ST_Percentage type-converted value of ``l`` attribute, or |0.0| if not present. Assigning the default value causes the attribute to be removed from the element."""
         ...
 
     @l.setter
     def l(self, value: float) -> None: ...
     @property
     def t(self) -> float:
-        """ST_Percentage type-converted value of ``t`` attribute, or |0.0|. Assigning the default value causes the attribute to be removed from the element."""
+        """ST_Percentage type-converted value of ``t`` attribute, or |0.0| if not present. Assigning the default value causes the attribute to be removed from the element."""
         ...
 
     @t.setter
     def t(self, value: float) -> None: ...
     @property
     def r(self) -> float:
-        """ST_Percentage type-converted value of ``r`` attribute, or |0.0|. Assigning the default value causes the attribute to be removed from the element."""
+        """ST_Percentage type-converted value of ``r`` attribute, or |0.0| if not present. Assigning the default value causes the attribute to be removed from the element."""
         ...
 
     @r.setter
     def r(self, value: float) -> None: ...
     @property
     def b(self) -> float:
-        """ST_Percentage type-converted value of ``b`` attribute, or |0.0|. Assigning the default value causes the attribute to be removed from the element."""
+        """ST_Percentage type-converted value of ``b`` attribute, or |0.0| if not present. Assigning the default value causes the attribute to be removed from the element."""
         ...
 
     @b.setter

pptx-stubs/oxml/dml/line.pyi

@@ -4,7 +4,7 @@ from pptx.oxml.xmlchemy import BaseOxmlElement
 class CT_PresetLineDashProperties(BaseOxmlElement):
     @property
     def val(self) -> MSO_LINE_DASH_STYLE | None:
-        """MSO_LINE_DASH_STYLE type-converted value of ``val`` attribute, or |None|. Assigning the default value causes the attribute to be removed from the element."""
+        """MSO_LINE_DASH_STYLE type-converted value of ``val`` attribute, or |None| if not present. Assigning the default value causes the attribute to be removed from the element."""
         ...
 
     @val.setter