### Install python-pptx using pip

Source: https://python-pptx.readthedocs.io/en/latest/user/install.html

Use this command to install the python-pptx library and its dependencies from PyPI.

```bash
pip install python-pptx

```

--------------------------------

### Start with Default Presentation

Source: https://python-pptx.readthedocs.io/en/latest/user/concepts.html

Create a new presentation based on the default template by calling the Presentation constructor without any arguments. This is useful for quick starts.

```python
# start with default presentation
prs = Presentation()
```

--------------------------------

### User Story: Just-Works Installation

Source: https://python-pptx.readthedocs.io/en/latest/dev/resources/python_packaging.html

This user story describes the desired outcome for a naive end-user installing a Python package, emphasizing a seamless and error-free installation process.

```gherkin
In order to enable a new capability in my computing environment
As a naive end-user
I would like installation to "just work" and not scare me with error
messages that don't indicate a real problem.

```

--------------------------------

### Start Freeform Path

Source: https://python-pptx.readthedocs.io/en/latest/_modules/pptx/shapes/freeform.html

Creates and returns an `a:path` element for the shape, adding an `a:moveTo` element representing the shape's starting point.

```python
    def _start_path(self, sp: CT_Shape) -> CT_Path2D:
        """Return a newly created `a:path` element added to `sp`.

        The returned `a:path` element has an `a:moveTo` element representing the shape starting
        point as its only child.
        """
        path = sp.add_path(w=self._dx, h=self._dy)
        path.add_moveTo(*self._local_to_shape(self._start_x, self._start_y))
        return path
```

--------------------------------

### User Story: Verify Installation

Source: https://python-pptx.readthedocs.io/en/latest/dev/resources/python_packaging.html

This user story details the requirements for a Python developer to verify a new installation by easily running the test suite without additional configuration.

```gherkin
In order to verify a new installation
As a python developer
I want to be able to easily run the test suite without having to invest in
any additional discovery or configuration.

```

--------------------------------

### Install behave for Acceptance Testing

Source: https://python-pptx.readthedocs.io/en/latest/dev/development_practices.html

Installs the 'behave' package, a tool used for acceptance testing in the development workflow.

```bash
pip install behave
```

--------------------------------

### Accessing and Setting ValueAxis Major Unit

Source: https://python-pptx.readthedocs.io/en/latest/dev/analysis/cht-axis-unit.html

Demonstrates how to get the current major unit setting, set an explicit value, and reset it to automatic behavior using `None`. An example of an invalid input is also shown.

```python
>>> value_axis = chart.value_axis
>>> value_axis.major_unit
None
>>> value_axis.major_unit = 10
>>> value_axis.major_unit
10.0
>>> value_axis.major_unit = -4.2
Traceback ...
ValueError: must be positive numeric value
>>> value_axis.major_unit = None
>>> value_axis.major_unit
None
```

--------------------------------

### Get and Set Brightness of a Color

Source: https://python-pptx.readthedocs.io/en/latest/_modules/pptx/dml/color.html

Demonstrates how to get the current brightness adjustment (tint or shade) of a color and how to set it. A positive value applies a tint (lighter), a negative value applies a shade (darker), and zero removes any brightness adjustment.

```python
lumMod, lumOff = self._xClr.lumMod, self._xClr.lumOff
# a tint is lighter, a shade is darker
# only tints have lumOff child
if lumOff is not None:
    brightness = lumOff.val
    return brightness
# which leaves shades, if lumMod is present
if lumMod is not None:
    brightness = lumMod.val - 1.0
    return brightness
# there's no brightness adjustment if no lum{Mod|Off} elements
return 0
```

```python
if value > 0:
    self._tint(value)
elif value < 0:
    self._shade(value)
else:
    self._xClr.clear_lum()
```

--------------------------------

### PP_ACTION_TYPE Usage Example

Source: https://python-pptx.readthedocs.io/en/latest/api/enum/PpActionType.html

Demonstrates how to import and assert the PP_ACTION_TYPE enumeration for a shape's click action.

```python
from pptx.enum.action import PP_ACTION

assert shape.click_action.action == PP_ACTION.HYPERLINK
```

--------------------------------

### Obtain FreeformBuilder Object

Source: https://python-pptx.readthedocs.io/en/latest/dev/analysis/shp-freeform.html

Get a FreeformBuilder object to start defining a custom shape. The x and y arguments set the starting pen location, and scale adjusts the rendered size.

```python
>>> freeform_builder = shapes.build_freeform(50, 0, scale=100/Inches(1))
>>> freeform_builder
<pptx.shapes.freeform.FreeformBuilder objext at 0x...>
```

--------------------------------

### Accessing Slides

Source: https://python-pptx.readthedocs.io/en/latest/user/concepts.html

Access individual slides within a presentation using the 'slides' attribute. This example shows how to get the first slide.

```python
prs = Presentation(path)
first_slide = prs.slides[0]
```

--------------------------------

### Load Presentation from File

Source: https://python-pptx.readthedocs.io/en/latest/user/concepts.html

Load an existing presentation file by providing its path to the Presentation constructor.

```python
from pptx import Presentation

path = 'slide-deck-foo.pptx'
prs = Presentation(path)
```

--------------------------------

### Access Slide Layouts

Source: https://python-pptx.readthedocs.io/en/latest/dev/analysis/sld-layout.html

Get the collection of slide layouts from a presentation object. This is the starting point for accessing and manipulating slide layouts.

```python
from pptx import Presentation
prs = Presentation()
slide_layouts = prs.slide_layouts
```

--------------------------------

### Getting Preset Geometry Identifier

Source: https://python-pptx.readthedocs.io/en/latest/_modules/pptx/shapes/autoshape.html

Returns the preset geometry identifier string for this auto shape. This string is used in XML to specify the shape's rendering geometry, for example, 'roundRect'.

```python
auto_shape.prst
```

--------------------------------

### Initialize FreeformBuilder

Source: https://python-pptx.readthedocs.io/en/latest/_modules/pptx/shapes/freeform.html

Creates a new FreeformBuilder instance. The initial pen location is specified in local coordinates.

```python
from pptx.util import Length
from pptx.shapes.freeform import FreeformBuilder

# Assuming 'shapes' is an instance of _BaseGroupShapes
# Example usage:
# builder = FreeformBuilder.new(shapes, start_x=100, start_y=100, x_scale=1.0, y_scale=1.0)
```

--------------------------------

### Rewrite Adjustment Guides to XML

Source: https://python-pptx.readthedocs.io/en/latest/_modules/pptx/shapes/autoshape.html

Writes the current adjustment values to the XML as guide elements. Any existing guide elements are overwritten. This is used to persist the state of shape adjustments.

```python
def _rewrite_guides(self):
    """Write `a:gd` elements to the XML, one for each adjustment value.

    Any existing guide elements are overwritten.
    """
    guides = [(adj.name, adj.val) for adj in self._adjustments_]
    self._prstGeom.rewrite_guides(guides)
```

--------------------------------

### Create and Save a New Presentation

Source: https://python-pptx.readthedocs.io/en/latest/user/presentations.html

Creates a new presentation from the default template and saves it to a file. This is useful for starting a new presentation from scratch.

```python
from pptx import Presentation

prs = Presentation()
prs.save('test.pptx')
```

--------------------------------

### CT_GeomGuideList Schema

Source: https://python-pptx.readthedocs.io/en/latest/dev/analysis/shp-preset-geom.html

Defines a list of geometric guides, where each guide is defined by a name and a formula.

```xml
<xsd:complexType name="CT_GeomGuideList">
  <xsd:sequence>
    <xsd:element name="gd" type="CT_GeomGuide" minOccurs="0" maxOccurs="unbounded"/>
  </xsd:sequence>
</xsd:complexType>
```

--------------------------------

### Comprehensive Line Formatting in DML

Source: https://python-pptx.readthedocs.io/en/latest/dev/analysis/dml-line.html

An example demonstrating multiple line formatting properties including gradient fill, dash style, and arrowheads. Use this for complex line designs.

```XML
<p:spPr>
  <a:xfrm>
    <a:off x="950964" y="1101493"/>
    <a:ext cx="1257921" cy="0"/>
  </a:xfrm>
  <a:prstGeom prst="line">
    <a:avLst/>
  </a:prstGeom>
  <a:ln w="57150" cap="rnd" cmpd="thickThin">
    <a:gradFill flip="none" rotWithShape="1">
      <a:gsLst>
        <a:gs pos="0">
          <a:schemeClr val="accent1"/>
        </a:gs>
        <a:gs pos="100000">
          <a:srgbClr val="FFFFFF"/>
        </a:gs>
      </a:gsLst>
      <a:lin ang="0" scaled="1"/>
      <a:tileRect/>
    </a:gradFill>
    <a:prstDash val="sysDash"/>
    <a:bevel/>
    <a:headEnd type="oval"/>
    <a:tailEnd type="diamond"/>
  </a:ln>
</p:spPr>
```

--------------------------------

### Update Adjustments with Actual Values

Source: https://python-pptx.readthedocs.io/en/latest/_modules/pptx/shapes/autoshape.html

Updates Adjustment objects with actual values derived from guide elements in the XML. It maps guide names to Adjustment objects and updates them if a match is found. Guides with non-matching names are ignored.

```python
def _update_adjustments_with_actuals(
    adjustments: Iterable[Adjustment], guides: Iterable[CT_GeomGuide]
):
    """Update |Adjustment| instances in `adjustments` with actual values held in `guides`.

    `guides` is a list of `a:gd` elements. Guides with a name that does not match an adjustment
    object are skipped.
    """
    adjustments_by_name = dict((adj.name, adj) for adj in adjustments)
    for gd in guides:
        name = gd.name
        actual = int(gd.fmla[4:])
        try:
            adjustment = adjustments_by_name[name]
        except KeyError:
            continue
        adjustment.actual = actual
    return
```

--------------------------------

### _start_path

Source: https://python-pptx.readthedocs.io/en/latest/_modules/pptx/shapes/freeform.html

Returns a newly created `a:path` element added to `sp`. The returned `a:path` element has an `a:moveTo` element representing the shape starting point as its only child.

```APIDOC
## method _start_path(sp: CT_Shape) -> CT_Path2D

### Description
Return a newly created `a:path` element added to `sp`.

The returned `a:path` element has an `a:moveTo` element representing the shape starting
point as its only child.

### Parameters
#### Path Parameters
- **sp** (CT_Shape) - The shape object to which the path will be added.

### Returns
CT_Path2D: The newly created `a:path` element.
```

--------------------------------

### Image Initialization

Source: https://python-pptx.readthedocs.io/en/latest/_modules/pptx/parts/image.html

Initializes an Image object with its binary data and an optional filename.

```python
def __init__(self, blob: bytes, filename: str | None):
    super(Image, self).__init__()
    self._blob = blob
    self._filename = filename
```

--------------------------------

### Table Creation and Access in python-pptx

Source: https://python-pptx.readthedocs.io/en/latest/community/updates.html

Demonstrates the updated method for adding tables and accessing them as a GraphicFrame object, reflecting changes in version 0.5.0.

```python
table = shapes.add_table(...)

# becomes

graphic_frame = shapes.add_table(...)
table = graphic_frame.table

# or

table = shapes.add_table(...).table
```

--------------------------------

### Slide Relationship Item Example

Source: https://python-pptx.readthedocs.io/en/latest/dev/resources/about_relationships.html

An example of a slide's relationship item (.rels file) defining relationships to other parts, including a slide layout and an image.

```xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Relationships xmlns="http://.../relationships">
  <Relationship Id="rId1" Type="http://.../slideLayout" Target=".../slideLayout2.xml"/>
  <Relationship Id="rId2" Type="http://.../image" Target=".../image1.png"/>
</Relationships>

```

--------------------------------

### Understanding and Using Unit Conversion Utilities

Source: https://python-pptx.readthedocs.io/en/latest/user/autoshapes.html

Demonstrates how to use utility classes like Inches and Pt from pptx.util to specify lengths and convert them between different units (inches, cm, points). The internal representation is in English Metric Units (EMU).

```python
>>> from pptx.util import Inches, Pt
>>> length = Inches(1)
>>> length
914400
>>> length.inches
1.0
>>> length.cm
2.54
>>> length.pt
72.0
>>> length = Pt(72)
>>> length
914400

```

--------------------------------

### Accessing and Setting Shape ID and Name

Source: https://python-pptx.readthedocs.io/en/latest/dev/analysis/shp-shapes.html

Demonstrates how to get the read-only `shape_id` and how to get and set the `name` property of a shape object. The `shape_id` is assigned by python-pptx.

```python
>>> shape.shape_id
42
>>> shape.name
u'Picture 5'
>>> shape.name = 'T501 - Foo; B. Baz; 2014'
>>> shape.name
u'T501 - Foo; B. Baz; 2014'
```

--------------------------------

### Font Color Protocol Example

Source: https://python-pptx.readthedocs.io/en/latest/dev/analysis/txt-font-color.html

Demonstrates the expected interactions with the Font.color property, including type checking, setting RGB values, theme colors, and brightness. Note that direct assignment to font.color is not supported.

```python
>>> assert isinstance(font.color, ColorFormat)

>>> font.color = 'anything'
AttributeError: can't set attribute

>>> assert font.color.type in MSO_COLOR_TYPE_INDEX
wouldn't actually work, but conceptually true

>>> font.color.rgb = RGB(0x3F, 0x2c, 0x36)

>>> font.color.theme_color = MSO_THEME_COLOR.ACCENT_1

>>> font.color.brightness = -0.25

```

--------------------------------

### Point Assignment Example

Source: https://python-pptx.readthedocs.io/en/latest/dev/analysis/cht-points.html

Illustrates how a point is constructed using corresponding values from xVal, yVal, and bubbleSize series at a given index.

```python
points[i] ~= Point(xVal.pts[i], yVal.pts[i], bubbleSize.pts[i])
```

--------------------------------

### Get Length of Slide Layouts

Source: https://python-pptx.readthedocs.io/en/latest/_modules/pptx/slide.html

Supports the len() built-in function to get the number of slide layouts in the collection, e.g., `len(slide_layouts) == 4`.

```python
def __len__(self) -> int:
    """Support len() built-in function, e.g. `len(slides) == 4`."""
    return len(self._sldLayoutIdLst)
```

--------------------------------

### Load Presentation from File or Default

Source: https://python-pptx.readthedocs.io/en/latest/_modules/pptx/api.html

Loads a `Presentation` object from a specified file path or a file-like object. If no source is provided, it loads the default presentation template. Includes validation to ensure the opened file is a valid PowerPoint package.

```python
from pptx import Presentation

# Load from a file path
pres = Presentation("my_presentation.pptx")

# Load from a file-like object
with open("my_presentation.pptx", "rb") as f:
    pres = Presentation(f)

# Load the default presentation template
pres = Presentation()
```

--------------------------------

### Example of Adding an Embedded XLSX Shape

Source: https://python-pptx.readthedocs.io/en/latest/dev/analysis/shp-ole-object.html

This example demonstrates how to add an OLE object, specifically an Excel file, to a slide. Ensure that `left`, `top`, `width`, `height`, and `file_name` are defined appropriately before execution.

```python
shapes = slide.shapes
embedded_xlsx_shape = shapes.AddOLEObject(left, top, width, height, file_name)
```

--------------------------------

### Open Presentation from File-like Object

Source: https://python-pptx.readthedocs.io/en/latest/user/presentations.html

Opens a presentation from a file-like object, such as a file opened in binary mode or a StringIO object. This is useful for handling presentations from network streams or databases.

```python
f = open('foobar.pptx')
prs = Presentation(f)
f.close()
```

```python
with open('foobar.pptx') as f:
    source_stream = StringIO(f.read())
prs = Presentation(source_stream)
source_stream.close()
```

--------------------------------

### Using MSO_THEME_COLOR_INDEX

Source: https://python-pptx.readthedocs.io/en/latest/api/enum/MsoThemeColorIndex.html

Demonstrates how to import and use the MSO_THEME_COLOR enumeration to check if a shape's fill color matches a specific theme color.

```python
from pptx.enum.dml import MSO_THEME_COLOR

shape.fill.solid()
shape.fill.fore_color.theme_color == MSO_THEME_COLOR.ACCENT_1
```

--------------------------------

### get

Source: https://python-pptx.readthedocs.io/en/latest/_modules/pptx/slide.html

Retrieves a specific slide from the presentation based on its ID.

```APIDOC
## get

### Description
Return the slide identified by int `slide_id` in this presentation.

Returns `default` if not found.

### Method
(Implicitly a method of a Slides collection)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
* **slide_id** (int) - The ID of the slide to retrieve.
* **default** (Slide | None) - The value to return if the slide is not found.

### Returns
* **Slide | None** - The requested slide, or the default value if not found.

### Raises
None explicitly mentioned.
```

--------------------------------

### Unpack Presentation using unzip

Source: https://python-pptx.readthedocs.io/en/latest/dev/analysis/placeholders/slide-placeholders/placeholders-in-new-slide.html

This command is used to unpack a presentation file into a directory for XML inspection. It requires the presentation file name and the target directory.

```bash
unzip white.pptx -d white
```

--------------------------------

### Open and Save an Existing Presentation

Source: https://python-pptx.readthedocs.io/en/latest/user/presentations.html

Opens an existing presentation file and saves it to a new file. This allows for modifications to existing presentations.

```python
prs = Presentation('existing-prs-file.pptx')
prs.save('new-file-name.pptx')
```

--------------------------------

### Get and Set Line Spacing for Paragraph

Source: https://python-pptx.readthedocs.io/en/latest/dev/analysis/txt-para-spacing.html

Shows how to get and set the line spacing of a paragraph. The default is 1.0 (lines). Line spacing can be set using Pt objects, which are converted to an internal Length representation. The .pt attribute can be used to retrieve the value in points.

```python
>>> paragraph = TextFrame.add_paragraph()
>>> paragraph.line_spacing
1.0
>>> isinstance(paragraph.line_spacing, float)
True
>>> paragraph.line_spacing = Pt(18)
>>> paragraph.line_spacing
228600
>>> isinstance(paragraph.line_spacing, Length)
True
>>> isinstance(paragraph.line_spacing, int)
True
>>> paragraph.line_spacing.pt
18.0
```

--------------------------------

### Getting Cell Bottom Margin

Source: https://python-pptx.readthedocs.io/en/latest/_modules/pptx/table.html

Retrieves the bottom margin of a cell.

```python
margin_bottom = cell.margin_bottom
```

--------------------------------

### Import Presentation Class

Source: https://python-pptx.readthedocs.io/en/latest/api/presentation.html

Import the Presentation class from the pptx package to begin working with presentations.

```python
from pptx import Presentation
```

--------------------------------

### Getting Cell Top Margin

Source: https://python-pptx.readthedocs.io/en/latest/_modules/pptx/table.html

Retrieves the top margin of a cell.

```python
margin_top = cell.margin_top
```

--------------------------------

### Setting Connector Begin X-Position

Source: https://python-pptx.readthedocs.io/en/latest/_modules/pptx/shapes/connector.html

Sets the X-coordinate of the connector's starting point. Adjusts the shape's width and flip state if necessary to accommodate the new position.

```python
connector.begin_x = Emu(10000)
```

--------------------------------

### Getting Cell Right Margin

Source: https://python-pptx.readthedocs.io/en/latest/_modules/pptx/table.html

Retrieves the right margin of a cell.

```python
margin_right = cell.margin_right
```

--------------------------------

### Presentation

Source: https://python-pptx.readthedocs.io/en/latest/_modules/pptx/api.html

Constructs a Presentation object. It can be initialized with a file path, a file-like object, or by loading the default template if no argument is provided.

```APIDOC
## Presentation

### Description
Constructs a Presentation object. It can be initialized with a file path, a file-like object, or by loading the default template if no argument is provided.

### Signature
Presentation(pptx: str | IO[bytes] | None = None) -> presentation.Presentation

### Parameters
#### Path Parameters
- **pptx** (str | IO[bytes] | None) - Optional. Either a path to a `.pptx` file (string) or a file-like object. If `None`, the default presentation template is loaded.

### Returns
- presentation.Presentation - A Presentation object loaded from the specified source.
```

--------------------------------

### Applying and Checking MSO_PATTERN_TYPE

Source: https://python-pptx.readthedocs.io/en/latest/api/enum/MsoPatternType.html

Demonstrates how to set a shape's fill to a patterned style and verify the applied pattern type using the MSO_PATTERN_TYPE enumeration.

```python
from pptx.enum.dml import MSO_PATTERN

fill = shape.fill
fill.patterned()
fill.pattern == MSO_PATTERN.WAVE
```

--------------------------------

### Getting Cell Left Margin

Source: https://python-pptx.readthedocs.io/en/latest/_modules/pptx/table.html

Retrieves the left margin of a cell.

```python
margin_left = cell.margin_left
```

--------------------------------

### Create and Configure Pie Chart

Source: https://python-pptx.readthedocs.io/en/latest/user/charts.html

Add a pie chart to a slide with categories and series data. This example shows how to configure the legend, enable data labels, set their format to percentage, and position them outside the slices.

```python
chart_data = ChartData()
chart_data.categories = ['West', 'East', 'North', 'South', 'Other']
chart_data.add_series('Series 1', (0.135, 0.324, 0.180, 0.235, 0.126))

chart = slide.shapes.add_chart(
    XL_CHART_TYPE.PIE, x, y, cx, cy, chart_data
).chart

chart.has_legend = True
chart.legend.position = XL_LEGEND_POSITION.BOTTOM
chart.legend.include_in_layout = False

chart.plots[0].has_data_labels = True
data_labels = chart.plots[0].data_labels
data_labels.number_format = '0%'
data_labels.position = XL_LABEL_POSITION.OUTSIDE_END
```

--------------------------------

### Getting Vertical Banding

Source: https://python-pptx.readthedocs.io/en/latest/_modules/pptx/table.html

Returns `True` if columns should have alternating shading.

```python
is_vert_banded = table.vert_banding
```

--------------------------------

### Series Index

Source: https://python-pptx.readthedocs.io/en/latest/_modules/pptx/chart/data.html

Gets the zero-based index of this series within its chart.

```python
@property
def index(self):
    """
    Zero-based integer indicating the sequence position of this series in
    its chart. For example, the second of three series would return `1`.
    """
    return self._chart_data.series_index(self)
```

--------------------------------

### Run Program

Source: https://python-pptx.readthedocs.io/en/latest/dev/analysis/shp-hyperlink.html

The 'program' action executes an external program. The Relationship element points to the target application using a file:// URL.

```XML
<p:sp>
  <p:nvSpPr>
    <p:cNvPr id="4" name="Rounded Rectangle 3">
      <a:hlinkClick r:id="rId2" action="ppaction://program"/>
    ...
</p:sp>
```

```XML
<Relationship
  Id="rId2"
  Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/hyperlink"
  Target="file:///C:\\Program%20Files%20(x86)\\Vim\\vim74\\gvim.exe"
  TargetMode="External"/>
```

--------------------------------

### Connecting Connector Begin Point

Source: https://python-pptx.readthedocs.io/en/latest/_modules/pptx/shapes/connector.html

Establishes or updates the connection for the beginning of a connector to a specified shape and connection point index.

```python
    def _connect_begin_to(self, shape, cxn_pt_idx):
        """
        Add or update a stCxn element for this connector that connects its
        begin point to the connection point of *shape* specified by
        *cxn_pt_idx*.
        """
        cNvCxnSpPr = self._element.nvCxnSpPr.cNvCxnSpPr
        stCxn = cNvCxnSpPr.get_or_add_stCxn()
        stCxn.id = shape.shape_id
        stCxn.idx = cxn_pt_idx
```

--------------------------------

### Fill Type Property

Source: https://python-pptx.readthedocs.io/en/latest/_modules/pptx/dml/fill.html

Gets the type of the fill, e.g. MSO_FILL_TYPE.SOLID.

```APIDOC
## type

### Description
The type of this fill, e.g. `MSO_FILL_TYPE.SOLID`.

### Property
`type`

### Returns
MSO_FILL_TYPE: The type of the fill.
```

--------------------------------

### Create a Presentation with a Title Slide

Source: https://python-pptx.readthedocs.io/en/latest/user/quickstart.html

This snippet demonstrates how to create a new presentation, add a title slide, and set the title and subtitle text. Save the presentation to a file named 'test.pptx'.

```python
from pptx import Presentation

prs = Presentation()
title_slide_layout = prs.slide_layouts[0]
slide = prs.slides.add_slide(title_slide_layout)
title = slide.shapes.title
subtitle = slide.placeholders[1]

title.text = "Hello, World!"
subtitle.text = "python-pptx was here!"

prs.save('test.pptx')

```

--------------------------------

### _SchemeColor.theme_color

Source: https://python-pptx.readthedocs.io/en/latest/_modules/pptx/dml/color.html

Get or set the theme color index for a scheme color.

```APIDOC
## theme_color

### Description
Get or set the theme color value for this color. This property allows you to specify a theme color from the `MSO_THEME_COLOR` enumeration. Setting this property changes the color's type to `MSO_COLOR_TYPE.SCHEME`.

### Method
- `get`: Returns the `MSO_THEME_COLOR` index.
- `set`: Accepts a value from the `MSO_THEME_COLOR` enumeration.

### Parameters
#### Setter Parameters
- **mso_theme_color_idx** (MSO_THEME_COLOR) - Required - The theme color index to apply.
```

--------------------------------

### ST_GeomGuideFormula Schema

Source: https://python-pptx.readthedocs.io/en/latest/dev/analysis/shp-preset-geom.html

A simple type restricting a string for geometric guide formulas.

```xml
<xsd:simpleType name="ST_GeomGuideFormula">
  <xsd:restriction base="xsd:string"/>
</xsd:simpleType>
```

--------------------------------

### ActionSetting Class Initialization

Source: https://python-pptx.readthedocs.io/en/latest/_modules/pptx/action.html

Initializes an ActionSetting object. This class manages properties for how a shape or text run reacts to mouse actions like clicks or hovers.

```python
class ActionSetting(Subshape):
    """Properties specifying how a shape or run reacts to mouse actions."""

    # -- The Subshape base class provides access to the Slide Part, which is needed to access
    # -- relationships, which is where hyperlinks live.

    def __init__(
        self,
        xPr: CT_NonVisualDrawingProps | CT_TextCharacterProperties,
        parent: BaseShape,
        hover: bool = False,
    ):
        super(ActionSetting, self).__init__(parent)
        # xPr is either a cNvPr or rPr element
        self._element = xPr
        # _hover determines use of `a:hlinkClick` or `a:hlinkHover`
        self._hover = hover
```

--------------------------------

### ST_GeomGuideName Schema

Source: https://python-pptx.readthedocs.io/en/latest/dev/analysis/shp-preset-geom.html

A simple type restricting a token for geometric guide names.

```xml
<xsd:simpleType name="ST_GeomGuideName">
  <xsd:restriction base="xsd:token"/>
</xsd:simpleType>
```

--------------------------------

### Variable Naming Convention Example

Source: https://python-pptx.readthedocs.io/en/latest/dev/resources/odds_and_ends.html

Demonstrates the convention for naming variables that hold XML elements. The variable name should match the element's tag name.

```python
Variables containing XML elements are named the same as the tag name of the element they hold. For example: sldMaster = etree.parse(‘sldMaster1.xml’)
```

--------------------------------

### Insert Table into Table Placeholder

Source: https://python-pptx.readthedocs.io/en/latest/user/placeholders-using.html

Shows how to use the `insert_table()` method on a table placeholder to create a table with specified rows and columns. The table inherits the position and width of the placeholder.

```python
prs = Presentation('having-table-placeholder.pptx')
slide = prs.slides.add_slide(prs.slide_layouts[1])
placeholder = slide.placeholders[10]  # idx key, not position
placeholder.name
placeholder.placeholder_format.type
graphic_frame = placeholder.insert_table(rows=2, cols=2)
table = graphic_frame.table
len(table.rows), len(table.columns)
```

--------------------------------

### Merging Cells

Source: https://python-pptx.readthedocs.io/en/latest/dev/analysis/tbl-merge.html

Shows how to merge a range of cells, starting from the top-left cell.

```python
>>> cell = table.cells(0, 0)
>>> other_cell = table.cells(1, 1)
>>> cell.merge(other_cell)
```

--------------------------------

### Patterned Fill XML Example

Source: https://python-pptx.readthedocs.io/en/latest/dev/analysis/dml-fill.html

This XML snippet illustrates a patterned fill, specifying the pattern preset and foreground/background colors using scheme colors.

```xml
<a:pattFill prst="ltDnDiag">
  <a:fgClr>
    <a:schemeClr val="accent1"/>
  </a:fgClr>
  <a:bgClr>
    <a:schemeClr val="accent6"/>
  </a:bgClr>
</a:pattFill>
```

--------------------------------

### TextFrame.margin_top

Source: https://python-pptx.readthedocs.io/en/latest/api/text.html

Gets or sets the top margin of the text frame as a Length value.

```APIDOC
## TextFrame.margin_top

### Description
Inset of text from top text frame border as `Length` value.

### Method
`margin_top` (getter/setter)

### Parameters
None

### Response
- `Length` value
```

--------------------------------

### TextFrame.margin_right

Source: https://python-pptx.readthedocs.io/en/latest/api/text.html

Gets or sets the right margin of the text frame as a Length value.

```APIDOC
## TextFrame.margin_right

### Description
Inset of text from right text frame border as `Length` value.

### Method
`margin_right` (getter/setter)

### Parameters
None

### Response
- `Length` value
```

--------------------------------

### Accessing and Inspecting Layout Placeholders

Source: https://python-pptx.readthedocs.io/en/latest/dev/analysis/placeholders/layout-placeholders.html

Demonstrates how to access slide layouts and their associated placeholders using the python-pptx library. Shows how to retrieve placeholder types, indices, and properties like width. Useful for understanding the structure of slide layouts and their constituent placeholders.

```python
slide_layout = prs.slide_layouts[0]
sld_layout
sld_layout.shapes
sld_layout.shapes[0]
layout_placeholders = sld_layout.placeholders
layout_placeholders
len(layout_placeholders)
layout_placeholders[1].type
layout_placeholders[2].idx
layout_placeholders.get(idx=0)
layout_placeholders.get(idx=666)
layout_placeholders[1]._sp.spPr.xfrm
layout_placeholders[1].width  # should inherit from master placehldr
8229600
```

--------------------------------

### TextFrame.margin_left

Source: https://python-pptx.readthedocs.io/en/latest/api/text.html

Gets or sets the left margin of the text frame as a Length value.

```APIDOC
## TextFrame.margin_left

### Description
Inset of text from left text frame border as `Length` value.

### Method
`margin_left` (getter/setter)

### Parameters
None

### Response
- `Length` value
```

--------------------------------

### TextFrame.margin_bottom

Source: https://python-pptx.readthedocs.io/en/latest/api/text.html

Gets or sets the bottom margin of the text frame as a Length value.

```APIDOC
## TextFrame.margin_bottom

### Description
`Length` value representing the inset of text from the bottom text frame border.
`pptx.util.Inches()` provides a convenient way of setting the value, e.g. text_frame.margin_bottom = Inches(0.05).

### Method
`margin_bottom` (getter/setter)

### Parameters
None

### Response
- `Length` value
```

--------------------------------

### Load and Access Presentation Elements

Source: https://python-pptx.readthedocs.io/en/latest/api/presentation.html

Load an existing presentation file and access its slides and shapes. This snippet demonstrates how to open a presentation and get a reference to the first shape on the first slide.

```python
# load a presentation
prs = Presentation(path_to_pptx_file)

# get reference to first shape in first slide
sp = prs.slides[0].shapes[0]
```

--------------------------------

### Gradient Angle Property

Source: https://python-pptx.readthedocs.io/en/latest/_modules/pptx/dml/fill.html

Gets or sets the angle of a linear gradient fill.

```APIDOC
## gradient_angle

### Description
Angle in float degrees of line of a linear gradient. Read/Write. May be |None|, indicating the angle is inherited from the style hierarchy. An angle of 0.0 corresponds to a left-to-right gradient. Increasing angles represent clockwise rotation of the line, for example 90.0 represents a top-to-bottom gradient. Raises |TypeError| when the fill type is not MSO_FILL_TYPE.GRADIENT. Raises |ValueError| for a non-linear gradient (e.g. a radial gradient).

### Property
`gradient_angle`

### Parameters
- **value** (float) - The angle in degrees for the gradient.

### Returns
float: The angle of the linear gradient, or None if inherited.

### Raises
- TypeError: If the fill type is not MSO_FILL_TYPE.GRADIENT.
- ValueError: If the gradient is not linear.
```

--------------------------------

### Example XML for a Populated Table Placeholder

Source: https://python-pptx.readthedocs.io/en/latest/dev/analysis/placeholders/slide-placeholders/table-placeholder.html

This XML shows a graphic frame that represents a table placeholder populated with a table, including its grid and a single row with one cell.

```xml
<p:graphicFrame>
  <p:nvGraphicFramePr>
    <p:cNvPr id="3" name="Table Placeholder 2"/>
    <p:cNvGraphicFramePr>
      <a:graphicFrameLocks noGrp="1"/>
    </p:cNvGraphicFramePr>
    <p:nvPr>
      <p:ph type="tbl" sz="quarter" idx="10"/>
      <p:extLst>
        <p:ext uri="{D42A27DB-BD31-4B8C-83A1-F6EECF244321}">
          <p14:modId xmlns:p14="http://../..nt/2010/main" val="933747684"/>
        </p:ext>
      </p:extLst>
    </p:nvPr>
  </p:nvGraphicFramePr>
  <p:xfrm>
    <a:off x="2743200" y="2057400"/>
    <a:ext cx="3657600" cy="3337560"/>
  </p:xfrm>
  <a:graphic>
    <a:graphicData uri="http://schemas.openxmlformats.org/drawingml/2006/table">
      <a:tbl>
        <a:tblPr firstRow="1" bandRow="1">
          <a:tableStyleId>{5C22544A-7EE6-4342-B048-85BDC9FD1C3A}</a:tableStyleId>
        </a:tblPr>
        <a:tblGrid>
          <a:gridCol w="457200"/>
        </a:tblGrid>
        <a:tr h="370840">
          <a:tc>
            <a:txBody>
              <a:bodyPr/>
              <a:lstStyle/>
              <a:p>
                <a:endParaRPr lang="en-US"/>
              </a:p>
            </a:txBody>
            <a:tcPr/>
          </a:tc>
        </a:tr>
      </a:tbl>
    </a:graphicData>
  </a:graphic>
</p:graphicFrame>
```

--------------------------------

### Get Number of Plots

Source: https://python-pptx.readthedocs.io/en/latest/_modules/pptx/chart/chart.html

Returns the total number of plots present in the chart.

```python
def __len__(self):
    return len(self._plotArea.xCharts)
```

--------------------------------

### Run Macro

Source: https://python-pptx.readthedocs.io/en/latest/dev/analysis/shp-hyperlink.html

Use the 'macro' action to execute a named macro. The 'name' parameter specifies the macro to run.

```XML
<p:sp>
  <p:nvSpPr>
    <p:cNvPr id="4" name="Rounded Rectangle 3">
      <a:hlinkClick r:id="" action="ppaction://macro?name=Hello"/>
    </p:cNvPr>
  ...
</p:sp>
```

--------------------------------

### Content Type to Class Mapping Example

Source: https://python-pptx.readthedocs.io/en/latest/dev/resources/about_packaging.html

Illustrates a dictionary mapping content types to their corresponding classes for unmarshalling. This is used to determine how to load different parts of a package.

```python
{ 'application/vnd...slide+xml'       : Slide
, 'application/vnd...slideLayout+xml' : SlideLayout
, ...
}

```