### Example XML for Picture Placeholder

Source: https://github.com/scanny/python-pptx/blob/master/docs/dev/analysis/placeholders/slide-placeholders/picture-placeholder.md

An example of the XML structure for an unpopulated picture-only placeholder.

```xml
<p:sp>
  <p:nvSpPr>
    <p:cNvPr id="3" name="Picture Placeholder 2"/>
    <p:cNvSpPr>
      <a:spLocks noGrp="1"/>
    </p:cNvSpPr>
    <p:nvPr>
      <p:ph type="pic" idx="1"/>
    </p:nvPr>
  </p:nvSpPr>
  <p:spPr>
    <a:xfrm>
      <a:off x="1792288" y="612775"/>
      <a:ext cx="5486400" cy="4114800"/>
    </a:xfrm>
  </p:spPr>
  <p:txBody>
    <a:bodyPr/>
    <a:lstStyle>
      <!-- a:lvl{n}pPr for n in 1:9 -->
    </a:lstStyle>
    <a:p>
      <a:endParaRPr lang="en-US"/>
    </a:p>
  </p:txBody>
</p:sp>
```

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

### Install behave for acceptance testing

Source: https://github.com/scanny/python-pptx/blob/master/docs/dev/development_practices.md

Install the behave package to support behavior-driven development and acceptance testing.

```bash
pip install behave
```

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

### Add Hyperlink to Text Run (Full Example)

Source: https://github.com/scanny/python-pptx/blob/master/docs/dev/analysis/txt-hyperlink.md

This example demonstrates adding a hyperlink to a text run, including the necessary steps to get the paragraph and run objects. The hyperlink's target address is set to a GitHub repository.

```python
p = shape.text_frame.paragraphs[0]
r = p.add_run()
r.text = 'link to python-pptx @ GitHub'
hlink = r.hyperlink
hlink.address = 'https://github.com/scanny/python-pptx'
```

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

### Example XML for Populated Picture Placeholder

Source: https://github.com/scanny/python-pptx/blob/master/docs/dev/analysis/placeholders/slide-placeholders/picture-placeholder.md

An example of the XML structure for a picture-only placeholder that has been populated with an image.

```xml
<p:pic>
  <p:nvPicPr>
    <p:cNvPr id="8" name="Picture Placeholder 7"
             descr="aphrodite.brinsmead.jpg"/>
    <p:cNvPicPr>
      <a:picLocks noGrp="1" noChangeAspect="1"/>
    </p:cNvPicPr>
    <p:nvPr>
      <p:ph type="pic" idx="1"/>
    </p:nvPr>
  </p:nvPicPr>
  <p:blipFill>
    <a:blip r:embed="rId2">
      <a:extLst>
        <a:ext uri="{28A0092B-C50C-407E-A947-70E740481C1C}">
          <a14:useLocalDpi xmlns:a14="http://../drawing/2010/main" val="0"/>
        </a:ext>
      </a:extLst>
    </a:blip>
    <a:srcRect t="20000" b="20000"/>  <!-- 20% crop, top and bottom -->
    <a:stretch>
      <a:fillRect/>
    </a:stretch>
  </p:blipFill>
  <p:spPr/>
</p:pic>
```

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

### Example XML for Unpopulated Placeholder

Source: https://github.com/scanny/python-pptx/blob/master/docs/dev/analysis/placeholders/slide-placeholders/picture-placeholder.md

An example of the XML structure for an unpopulated picture-only placeholder on a slide.

```xml
<p:sp>
  <p:nvSpPr>
    <p:cNvPr id="7" name="Picture Placeholder 6"/>
    <p:cNvSpPr>
      <a:spLocks noGrp="1"/>
    </p:cNvSpPr>
    <p:nvPr>
      <p:ph type="pic" idx="1"/>
    </p:nvPr>
  </p:nvSpPr>
  <p:spPr/>
</p:sp>
```

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

### Import Presentation Class

Source: https://github.com/scanny/python-pptx/blob/master/docs/api/presentation.md

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

```python
from pptx import Presentation
```

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

### Modifying Fill Properties

Source: https://github.com/scanny/python-pptx/blob/master/docs/dev/analysis/dml-fill.md

Examples of setting solid fill, color formats, transparency, and removing fills.

```python
>>> fill.solid()
>>> fill.type
1  # MSO_FILL.SOLID

>>> fill.fore_color = 'anything'
AttributeError: can't set attribute  # .fore_color is read-only
>>> fore_color = fill.fore_color
>>> assert(isinstance(fore_color, ColorFormat))

>>> fore_color.rgb = RGBColor(0x3F, 0x2c, 0x36)
>>> fore_color.theme_color = MSO_THEME_COLOR.ACCENT_1
>>> fore_color.brightness = -0.25

>>> fill.transparency
0.0
>>> fill.transparency = 0.25  # sets opacity to 75%

>>> sp.fill = None  # removes any fill, fill is inherited from theme

fill.solid()
fill.fore_color.rgb = RGBColor(0x01, 0x23, 0x45)
fill.fore_color.theme_color = MSO_THEME_COLOR.ACCENT_1
fill.fore_color.brightness = 0.25
fill.transparency = 0.25
shape.fill = None
fill.background()  # is almost free once the rest is in place
```

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

### Configure shape fill types

Source: https://github.com/scanny/python-pptx/blob/master/docs/user/autoshapes.md

Examples for setting solid colors, theme colors, and transparent backgrounds for shapes.

```python
>>> fill = shape.fill
>>> fill.solid()
>>> fill.fore_color.rgb = RGBColor(255, 0, 0)
```

```python
>>> from pptx.enum.dml import MSO_THEME_COLOR
>>> fill = shape.fill
>>> fill.solid()
>>> fill.fore_color.theme_color = MSO_THEME_COLOR.ACCENT_1
>>> fill.fore_color.brightness = -0.25
```

```python
>>> shape.fill.background()
```

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

### XML for a Populated Table Placeholder

Source: https://github.com/scanny/python-pptx/blob/master/docs/dev/analysis/placeholders/slide-placeholders/table-placeholder.md

Example XML for a table-only placeholder that has been populated with a table.

```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>
```

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

### Exception Hierarchy Example

Source: https://github.com/scanny/python-pptx/blob/master/docs/dev/resources/odds_and_ends.md

Illustrates the exception hierarchy for built-in exceptions, referencing an external file for details.

```default
Exception hierarchy
-------------------

The class hierarchy for built-in exceptions is:

.. literalinclude:: ../../Lib/test/exception_hierarchy.txt
```

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

### Start with Default Presentation

Source: https://github.com/scanny/python-pptx/blob/master/docs/user/concepts.md

Create a new presentation based on the library's default template by calling the Presentation constructor without arguments.

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

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

### XML for a Table Placeholder

Source: https://github.com/scanny/python-pptx/blob/master/docs/dev/analysis/placeholders/slide-placeholders/table-placeholder.md

Example XML structure for a table-only layout placeholder.

```xml
<p:sp>
  <p:nvSpPr>
    <p:cNvPr id="3" name="Table Placeholder 2"/>
    <p:cNvSpPr>
      <a:spLocks noGrp="1"/>
    </p:cNvSpPr>
    <p:nvPr>
      <p:ph type="tbl" sz="quarter" idx="10"/>
    </p:nvPr>
  </p:nvSpPr>
  <p:spPr>
    <a:xfrm>
      <a:off x="2743200" y="2057400"/>
      <a:ext cx="3657600" cy="2743200"/>
    </a:xfrm>
    <a:prstGeom prst="rect">
      <a:avLst/>
    </a:prstGeom>
  </p:spPr>
  <p:txBody>
    <a:bodyPr vert="horz"/>
    <a:lstStyle/>
    <a:p>
      <a:endParaRPr lang="en-US"/>
    </a:p>
  </p:txBody>
</p:sp>
```

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

### Font Color Protocol Examples

Source: https://github.com/scanny/python-pptx/blob/master/docs/dev/analysis/txt-font-color.md

Demonstrates the expected behavior and usage of the Font.color attribute and related ColorFormat properties in python-pptx.

```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
```

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

### XML for an Unpopulated Table Placeholder

Source: https://github.com/scanny/python-pptx/blob/master/docs/dev/analysis/placeholders/slide-placeholders/table-placeholder.md

Example XML for an unpopulated table-only placeholder on a slide.

```xml
<p:sp>
  <p:nvSpPr>
    <p:cNvPr id="2" name="Table Placeholder 1"/>
    <p:cNvSpPr>
      <a:spLocks noGrp="1"/>
    </p:cNvSpPr>
    <p:nvPr>
      <p:ph type="tbl" sz="quarter" idx="10"/>
    </p:nvPr>
  </p:nvSpPr>
  <p:spPr/>
</p:sp>
```

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

### XML Specimens for Shape Fills

Source: https://github.com/scanny/python-pptx/blob/master/docs/dev/analysis/dml-fill.md

Examples of XML structures for inherited, solid, and patterned fills.

```xml
<p:spPr>
   ...
  <a:prstGeom prst="roundRect">
    <a:avLst/>
  </a:prstGeom>
</p:spPr>
```

```xml
<p:spPr>
   ...
  <a:prstGeom prst="roundRect">
    <a:avLst/>
  </a:prstGeom>
  <a:solidFill>
    <a:srgbClr val="2CB731"/>
  </a:solidFill>
</p:spPr>
```

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

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

### Example usage of AddOLEObject

Source: https://github.com/scanny/python-pptx/blob/master/docs/dev/analysis/shp-ole-object.md

Demonstrates the basic syntax for adding an embedded OLE object to a slide's shapes collection.

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

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

### Slide's Relationship File Example

Source: https://github.com/scanny/python-pptx/blob/master/docs/dev/resources/about_relationships.md

Demonstrates the XML structure of a slide's relationship file, defining relationships to other parts.

```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>
```

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

### Series-level Marker Configuration XML

Source: https://github.com/scanny/python-pptx/blob/master/docs/dev/analysis/cht-marker.md

Example of defining marker properties for all data points within a series.

```xml
<c:ser>
  <!-- ... -->
  <c:marker>
    <c:spPr>
      <a:solidFill>
        <a:schemeClr val="accent4">
          <a:lumMod val="60000"/>
          <a:lumOff val="40000"/>
        </a:schemeClr>
      </a:solidFill>
      <a:ln>
        <a:solidFill>
          <a:schemeClr val="accent6">
            <a:alpha val="51000"/>
          </a:schemeClr>
        </a:solidFill>
      </a:ln>
    </c:spPr>
  </c:marker>
  <!-- ... -->
</c:ser>
```

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

### XML Element Variable Naming Convention

Source: https://github.com/scanny/python-pptx/blob/master/docs/dev/resources/odds_and_ends.md

Example demonstrating the convention of naming variables after the XML tag they hold.

```python
sldMaster = etree.parse(‘sldMaster1.xml’)
```

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

### Add AutoShapes to a Presentation

Source: https://github.com/scanny/python-pptx/blob/master/docs/user/quickstart.md

This example demonstrates adding various AutoShapes, such as a pentagon and chevrons, to a slide. It shows how to position and add text to these shapes.

```python
from pptx import Presentation
from pptx.enum.shapes import MSO_SHAPE
from pptx.util import Inches

prs = Presentation()
title_only_slide_layout = prs.slide_layouts[5]
slide = prs.slides.add_slide(title_only_slide_layout)
shapes = slide.shapes

shapes.title.text = 'Adding an AutoShape'

left = Inches(0.93)  # 0.93" centers this overall set of shapes
top = Inches(3.0)
width = Inches(1.75)
height = Inches(1.0)

shape = shapes.add_shape(MSO_SHAPE.PENTAGON, left, top, width, height)
shape.text = 'Step 1'

left = left + width - Inches(0.4)
width = Inches(2.0)  # chevrons need more width for visual balance

for n in range(2, 6):
    shape = shapes.add_shape(MSO_SHAPE.CHEVRON, left, top, width, height)
    shape.text = 'Step %d' % n
    left = left + width - Inches(0.4)

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

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

### XML Date Axis Configuration

Source: https://github.com/scanny/python-pptx/blob/master/docs/dev/analysis/cht-date-axis.md

Example of the XML elements used to define base and major units for a date axis.

```default
<c:baseTimeUnit val="days"/>
<c:majorUnit val="1.0"/>
<c:majorTimeUnit val="months"/>
<c:minorUnit val="1.0"/>
```

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

### Example Legend XML Configuration

Source: https://github.com/scanny/python-pptx/blob/master/docs/dev/analysis/cht-legend.md

This XML specimen shows a typical configuration for a chart legend, including its position, layout, and styling.

```xml
<c:legend>
  <c:legendPos val="t"/>
  <c:layout>
    <c:manualLayout>
      <c:xMode val="edge"/>
      <c:yMode val="edge"/>
      <c:x val="0.321245570866142"/>
      <c:y val="0.025"/>
      <c:w val="0.532508858267717"/>
      <c:h val="0.0854055118110236"/>
    </c:manualLayout>
  </c:layout>
  <c:overlay val="1"/>
  <c:spPr>
    <a:solidFill>
      <a:schemeClr val="accent6">
        <a:lumMod val="20000"/>
        <a:lumOff val="80000"/>
      </a:schemeClr>
    </a:solidFill>
  </c:spPr>
  <c:txPr>
    <a:bodyPr/>
    <a:lstStyle/>
    <a:p>
      <a:pPr>
        <a:defRPr sz="1600" b="0" i="1" baseline="0"/>
      </a:pPr>
      <a:endParaRPr lang="en-US"/>
    </a:p>
  </c:txPr>
</c:legend>
```

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

### Example Series XML Structure

Source: https://github.com/scanny/python-pptx/blob/master/docs/dev/analysis/cht-plot-data.md

Illustrates the XML structure for a chart series, including category and value references and their cached data.

```xml
<c:ser>
  <!-- ... -->
  <c:cat>
    <c:strRef>
      <c:f>Sheet1!$A$2:$A$4</c:f>
      <c:strCache>
        <c:ptCount val="3"/>
        <c:pt idx="0">
          <c:v>Foo</c:v>
        </c:pt>
        <c:pt idx="1">
          <c:v>Bar</c:v>
        </c:pt>
        <c:pt idx="2">
          <c:v>Baz</c:v>
        </c:pt>
      </c:strCache>
    </c:strRef>
  </c:cat>
  <c:val>
    <c:numRef>
      <c:f>Sheet1!$B$2:$B$4</c:f>
      <c:numCache>
        <c:ptCount val="3"/>
        <c:pt idx="0">
          <c:v>1.2</c:v>
        </c:pt>
        <c:pt idx="1">
          <c:v>2.3</c:v>
        </c:pt>
        <c:pt idx="2">
          <c:v>3.4</c:v>
        </c:pt>
      </c:numCache>
    </c:numRef>
  </c:val>
</c:ser>
```

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

### Creating a Straight Connector

Source: https://github.com/scanny/python-pptx/blob/master/docs/dev/analysis/shp-connector.md

This code demonstrates how to add a straight connector shape to a presentation. You need to specify the connector type and the start and end coordinates.

```python
>>> line = shapes.add_connector(
...     MSO_CONNECTOR.STRAIGHT, start_x, start_y, end_x, end_y
... )
```

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

### Obtain FreeformBuilder Object

Source: https://github.com/scanny/python-pptx/blob/master/docs/dev/analysis/shp-freeform.md

Get a FreeformBuilder object to start creating a freeform shape. The arguments specify the starting pen location and scaling.

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

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

### Initialize and Save a Presentation

Source: https://context7.com/scanny/python-pptx/llms.txt

Demonstrates how to create a new presentation, open an existing one, or load from a file-like object, and access basic properties.

```python
from pptx import Presentation

# Create a new presentation from default template
prs = Presentation()

# Or open an existing presentation
prs = Presentation('existing-presentation.pptx')

# Or from a file-like object
with open('presentation.pptx', 'rb') as f:
    prs = Presentation(f)

# Access presentation properties
print(f"Slide count: {len(prs.slides)}")
print(f"Slide width: {prs.slide_width.inches} inches")
print(f"Slide height: {prs.slide_height.inches} inches")

# Save the presentation
prs.save('output.pptx')
```

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

### Create a new presentation

Source: https://github.com/scanny/python-pptx/blob/master/docs/user/presentations.md

Initializes a new presentation from the default template and saves it to a file.

```python
from pptx import Presentation

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

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

### Load Presentation from File

Source: https://github.com/scanny/python-pptx/blob/master/docs/user/concepts.md

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)
```

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

### Presentation Initialization

Source: https://github.com/scanny/python-pptx/blob/master/docs/api/presentation.md

How to initialize a presentation object from a file path.

```APIDOC
## Presentation(path_to_pptx_file)

### Description
Opens an existing PowerPoint presentation file and returns a Presentation object, which serves as the root for accessing slides and shapes.

### Method
Function Call

### Parameters
#### Path Parameters
- **path_to_pptx_file** (string) - Required - The file system path to the .pptx file.

### Response
#### Success Response (200)
- **Presentation** (object) - The root object representing the presentation structure.
```

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

### Open and save using file-like objects

Source: https://github.com/scanny/python-pptx/blob/master/docs/user/presentations.md

Demonstrates loading and saving presentations using file streams or BytesIO objects instead of direct file paths.

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

# or

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

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

### Auto Shape Adjustment Values XML

Source: https://github.com/scanny/python-pptx/blob/master/docs/dev/analysis/shp-autoshape.md

This XML snippet shows how adjustment values for an autoshape are represented. The `<a:gd>` element defines a guide, which is a variable used in expressions to modify the shape's geometry. The `name` attribute identifies the guide, and `fmla` contains the formula.

```xml
<a:prstGeom prst="roundRect">
  <a:avLst>
    <a:gd name="adj" fmla="val 30346"/>
  </a:avLst>
</a:prstGeom>
```

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

### Configure Shape Fill and Line Formatting

Source: https://context7.com/scanny/python-pptx/llms.txt

Shows how to apply solid colors, theme colors, transparency, and custom line styles to various shapes.

```python
from pptx import Presentation
from pptx.enum.shapes import MSO_SHAPE
from pptx.enum.dml import MSO_THEME_COLOR, MSO_LINE_DASH_STYLE
from pptx.util import Inches, Pt
from pptx.dml.color import RGBColor

prs = Presentation()
slide = prs.slides.add_slide(prs.slide_layouts[6])

# Shape with solid fill
shape1 = slide.shapes.add_shape(
    MSO_SHAPE.RECTANGLE, Inches(0.5), Inches(0.5), Inches(2), Inches(1)
)
fill = shape1.fill
fill.solid()
fill.fore_color.rgb = RGBColor(0xFF, 0x69, 0xB4)  # Hot pink

# Shape with theme color fill
shape2 = slide.shapes.add_shape(
    MSO_SHAPE.RECTANGLE, Inches(3), Inches(0.5), Inches(2), Inches(1)
)
fill = shape2.fill
fill.solid()
fill.fore_color.theme_color = MSO_THEME_COLOR.ACCENT_2
fill.fore_color.brightness = 0.4  # 40% lighter

# Shape with no fill (transparent)
shape3 = slide.shapes.add_shape(
    MSO_SHAPE.RECTANGLE, Inches(5.5), Inches(0.5), Inches(2), Inches(1)
)
shape3.fill.background()

# Shape with custom line formatting
shape4 = slide.shapes.add_shape(
    MSO_SHAPE.OVAL, Inches(0.5), Inches(2), Inches(2), Inches(2)
)
shape4.fill.solid()
shape4.fill.fore_color.rgb = RGBColor(0x87, 0xCE, 0xEB)  # Sky blue

line = shape4.line
line.color.rgb = RGBColor(0x00, 0x00, 0x8B)  # Dark blue
line.width = Pt(3)

# Shape with dashed line
shape5 = slide.shapes.add_shape(
    MSO_SHAPE.OVAL, Inches(3), Inches(2), Inches(2), Inches(2)
)
shape5.fill.background()
line = shape5.line
line.color.rgb = RGBColor(0xFF, 0x00, 0x00)
line.width = Pt(2)
line.dash_style = MSO_LINE_DASH_STYLE.DASH_DOT

# Transparent line
shape6 = slide.shapes.add_shape(
    MSO_SHAPE.ROUNDED_RECTANGLE, Inches(5.5), Inches(2), Inches(2), Inches(2)
)
shape6.fill.solid()
shape6.fill.fore_color.rgb = RGBColor(0x90, 0xEE, 0x90)  # Light green
shape6.line.fill.background()  # No outline

prs.save('fill-line-example.pptx')
```

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

### Merging Table Cells

Source: https://github.com/scanny/python-pptx/blob/master/docs/dev/analysis/tbl-merge.md

Merges a 2x2 range of cells starting from the top-left corner.

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

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

### Load and Access Presentation Components

Source: https://github.com/scanny/python-pptx/blob/master/docs/api/presentation.md

Load an existing presentation file and access its first slide and first shape. This example demonstrates basic navigation within the presentation object graph.

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

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

# add a picture shape to slide
pic = sld.shapes.add_picture(path, x, y, cx, cy)
```

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

### Get and set paragraph space before and after

Source: https://github.com/scanny/python-pptx/blob/master/docs/dev/analysis/txt-para-spacing.md

Demonstrates accessing and modifying the space_before property of a paragraph.

```python
>>> paragraph = TextFrame.add_paragraph()
>>> paragraph.space_before
0
>>> paragraph.space_before = Pt(6)
>>> paragraph.space_before
76200
>>> paragraph.space_before.pt
6.0
```

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

### Accessing Tick Labels

Source: https://github.com/scanny/python-pptx/blob/master/docs/dev/analysis/cht-tick-labels.md

Demonstrates how to get the tick_labels object for both value and category axes.

```python
>>> tick_labels = value_axis.tick_labels

>>> tick_labels.font
<pptx.text.Font object at 0xdeadbeef1>
```

```python
# offset property is only available on category axis
>>> tick_labels = category_axis.tick_labels
```

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

### Add Slides and Populate Placeholders

Source: https://context7.com/scanny/python-pptx/llms.txt

Shows how to add slides using specific layouts and populate title and content placeholders with text and bullet points.

```python
from pptx import Presentation

prs = Presentation()

# Common slide layouts (indices may vary by template):
# 0 = Title Slide
# 1 = Title and Content (bullet slide)
# 5 = Title Only
# 6 = Blank

# Add a title slide
title_slide_layout = prs.slide_layouts[0]
slide = prs.slides.add_slide(title_slide_layout)

# Access and populate title placeholder
title = slide.shapes.title
title.text = "My Presentation Title"

# Access subtitle placeholder
subtitle = slide.placeholders[1]
subtitle.text = "Created with python-pptx"

# Add a bullet slide
bullet_layout = prs.slide_layouts[1]
slide2 = prs.slides.add_slide(bullet_layout)
slide2.shapes.title.text = "Agenda"

# Populate bullet points
body = slide2.placeholders[1]
tf = body.text_frame
tf.text = "First bullet point"

p = tf.add_paragraph()
p.text = "Second bullet point"
p.level = 0

p = tf.add_paragraph()
p.text = "Sub-bullet point"
p.level = 1

prs.save('slides-example.pptx')
```

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

### Slide Relationship XML

Source: https://github.com/scanny/python-pptx/blob/master/docs/dev/analysis/sld-layout.md

Example of a slide's relationship file specifying its associated layout.

```xml
<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">
  <Relationship
    Id="rId1"
    Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/slideLayout"
    Target="../slideLayouts/slideLayout1.xml"/>
</Relationships>
```

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

### Picture Shape XML

Source: https://github.com/scanny/python-pptx/blob/master/docs/dev/analysis/shp-picture.md

Example XML for a picture shape as added by PowerPoint Mac 2011.

```xml
<p:pic>
  <p:nvPicPr>
    <p:cNvPr id="2" name="Picture 1" descr="sonic.gif"/>
    <p:cNvPicPr>
      <a:picLocks noChangeAspect="1"/>
    </p:cNvPicPr>
    <p:nvPr/>
  </p:nvPicPr>
  <p:blipFill>
    <a:blip r:embed="rId2">
      <a:extLst>
        <a:ext uri="{28A0092B-C50C-407E-A947-70E740481C1C}">
          <a14:useLocalDpi
            xmlns:a14="http://schemas.microsoft.com/office/drawing/2010/main"
            val="0"/>
        </a:ext>
      </a:extLst>
    </a:blip>
    <a:stretch>
      <a:fillRect/>
    </a:stretch>
  </p:blipFill>
  <p:spPr>
    <a:xfrm>
      <a:off x="2730500" y="1143000"/>
      <a:ext cx="3683000" cy="4572000"/>
    </a:xfrm>
    <a:prstGeom prst="rect">
      <a:avLst/>
    </a:prstGeom>
  </p:spPr>
</p:pic>
```

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

### Manage Slide Placeholders

Source: https://context7.com/scanny/python-pptx/llms.txt

Illustrates how to inspect layout placeholders and populate them with content like pictures and text.

```python
from pptx import Presentation
from pptx.chart.data import CategoryChartData
from pptx.enum.chart import XL_CHART_TYPE

prs = Presentation()

# List all placeholders in a layout
layout = prs.slide_layouts[8]  # Picture with Caption layout
for shape in layout.placeholders:
    print(f"idx: {shape.placeholder_format.idx}, type: {shape.placeholder_format.type}, name: {shape.name}")

# Add slide and work with placeholders
slide = prs.slides.add_slide(layout)

# Access placeholders by idx
for shape in slide.placeholders:
    phf = shape.placeholder_format
    print(f"idx: {phf.idx}, type: {phf.type}, name: {shape.name}")

# Set title text
if slide.shapes.title:
    slide.shapes.title.text = "Picture Slide"

# Insert picture into picture placeholder
picture_placeholder = slide.placeholders[1]  # Picture placeholder
picture = picture_placeholder.insert_picture('image.png')

# Access text placeholder
text_placeholder = slide.placeholders[2]
text_placeholder.text = "Caption for the image"

# --- Using Table Placeholder (requires custom template) ---
# prs = Presentation('template-with-table-placeholder.pptx')
# slide = prs.slides.add_slide(prs.slide_layouts[1])
# table_placeholder = slide.placeholders[10]
# graphic_frame = table_placeholder.insert_table(rows=3, cols=3)
# table = graphic_frame.table
# table.cell(0, 0).text = "Header"

# --- Using Chart Placeholder (requires custom template) ---
# chart_placeholder = slide.placeholders[10]
# chart_data = CategoryChartData()
# chart_data.categories = ['A', 'B', 'C']
# chart_data.add_series('Series 1', (1, 2, 3))
```

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

### Accessing Tick Labels

Source: https://github.com/scanny/python-pptx/blob/master/docs/dev/analysis/cht-tick-labels.md

Demonstrates how to get the tick_labels object from a value axis or category axis.

```APIDOC
## Accessing Tick Labels

### Description
Get the tick_labels object associated with a chart axis.

### Method
Attribute Access

### Endpoint
N/A (Object Property)

### Parameters
None

### Request Example
```python
# For value axis
value_axis = chart.value_axis
tick_labels = value_axis.tick_labels

# For category axis
category_axis = chart.category_axis
tick_labels = category_axis.tick_labels
```

### Response
#### Success Response (200)
- **tick_labels** (pptx.chart.axis.TickLabels) - The tick labels object for the axis.

#### Response Example
```python
# Example of accessing tick_labels object
>>> tick_labels = value_axis.tick_labels
>>> print(tick_labels)
<pptx.chart.axis.TickLabels object at 0x...>
```
```

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

### Create Pie and XY Scatter Charts

Source: https://context7.com/scanny/python-pptx/llms.txt

Demonstrates adding charts to slides, configuring chart data, and setting chart properties like legends and data labels.

```python
# --- Pie Chart ---
slide2 = prs.slides.add_slide(prs.slide_layouts[5])
slide2.shapes.title.text = "Market Share"

chart_data = CategoryChartData()
chart_data.categories = ['Product A', 'Product B', 'Product C', 'Other']
chart_data.add_series('Market Share', (35.2, 28.7, 22.1, 14.0))

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

chart.has_legend = True
chart.legend.position = XL_LEGEND_POSITION.RIGHT
chart.plots[0].has_data_labels = True
chart.plots[0].data_labels.number_format = '0.0%'

# --- XY Scatter Chart ---
slide3 = prs.slides.add_slide(prs.slide_layouts[5])
slide3.shapes.title.text = "Performance Analysis"

chart_data = XyChartData()
series_1 = chart_data.add_series('Model A')
series_1.add_data_point(1.0, 2.5)
series_1.add_data_point(2.0, 4.2)
series_1.add_data_point(3.0, 3.8)
series_1.add_data_point(4.0, 5.1)

series_2 = chart_data.add_series('Model B')
series_2.add_data_point(1.2, 3.1)
series_2.add_data_point(2.3, 2.9)
series_2.add_data_point(3.1, 4.5)
series_2.add_data_point(4.2, 4.8)

chart = slide3.shapes.add_chart(
    XL_CHART_TYPE.XY_SCATTER, x, y, cx, cy, chart_data
).chart

chart.has_legend = True

prs.save('charts-example.pptx')
```

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

### Minimal Slide Background XML Structure

Source: https://github.com/scanny/python-pptx/blob/master/docs/dev/analysis/sld-background.md

An example of the minimal XML structure for a slide background with no fill.

```xml
<p:cSld>
  <p:bg>
    <p:bgPr>
      <a:noFill/>
      <a:effectLst/>
    </p:bgPr>
  </p:bg>
  ...
</p:cSld>
```

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

### Cropped Picture XML

Source: https://github.com/scanny/python-pptx/blob/master/docs/dev/analysis/shp-picture.md

Example XML for a cropped picture, showing the p:blipFill child element.

```xml
<p:blipFill rotWithShape="1">
  <a:blip r:embed="rId2"/>
  <a:srcRect l="9330" t="15904" r="21873" b="28227"/>
  <a:stretch/>
</p:blipFill>
```

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

### Initialize Slide with Table Placeholder

Source: https://github.com/scanny/python-pptx/blob/master/docs/user/table.md

Create a new slide using a layout that contains a table placeholder.

```python
>>> prs = Presentation('template.pptx')
>>> slide = prs.slides.add_slide(prs.slide_layouts[2])
```

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

### XML and Python Color Assertion Example

Source: https://github.com/scanny/python-pptx/blob/master/docs/dev/analysis/txt-font-color.md

Demonstrates how to represent a solid color fill in XML and provides corresponding Python assertions to verify the color type, RGB values, scheme color, and brightness.

```xml
<a:ln>
  <a:solidFill>
    <a:srgbClr val="123456"/>
  </a:solidFill>
</a:ln>
```

```python
assert font.color.type == MSO_COLOR_TYPE.RGB
assert font.color.rgb == RGB(0x12, 0x34, 0x56)
assert font.color.schemeClr == MSO_THEME_COLOR.NONE
assert font.color.brightness == 0.0
```

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

### Simple Column Chart XML Specimen

Source: https://github.com/scanny/python-pptx/blob/master/docs/dev/analysis/cht-access-xlsx.md

An example of the XML structure for a simple column chart space.

```xml
<?xml version='1.0' encoding='UTF-8' standalone='yes'?>
<c:chartSpace
    xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main"
    xmlns:c="http://schemas.openxmlformats.org/drawingml/2006/chart"
    xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships"
    >
  <c:date1904 val="0"/>
  <c:lang val="en-US"/>
  <c:roundedCorners val="0"/>
  <mc:AlternateContent xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006">
    <mc:Choice xmlns:c14="http://schemas.microsoft.com/office/drawing/2007/8/2/chart"
               Requires="c14">
      <c14:style val="102"/>
    </mc:Choice>
    <mc:Fallback>
      <c:style val="2"/>
    </mc:Fallback>
  </mc:AlternateContent>
  <c:chart>
    <!-- 179 rows elided -->
  </c:chart>
  <c:txPr>
    <a:bodyPr/>
    <a:lstStyle/>
    <a:p>
      <a:pPr>
        <a:defRPr sz="1800"/>
      </a:pPr>
      <a:endParaRPr lang="en-US"/>
    </a:p>
  </c:txPr>
  <c:externalData r:id="rId1">
    <c:autoUpdate val="0"/>
  </c:externalData>
</c:chartSpace>
```

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

### Utilize Unit Conversion Classes

Source: https://context7.com/scanny/python-pptx/llms.txt

Demonstrates the use of utility classes from `pptx.util` for converting measurements between inches, centimeters, millimeters, points, and the internal English Metric Units (EMU).

```python
from pptx.util import Inches, Cm, Mm, Pt, Emu

# Create length values in different units
length_inches = Inches(1.5)
length_cm = Cm(3.81)
length_mm = Mm(38.1)
length_pt = Pt(108)
length_emu = Emu(914400)  # EMU directly

# All convert to EMU internally
print(f"Inches(1.5) = {length_inches} EMU")  # 1371600
print(f"Cm(3.81) = {length_cm} EMU")          # 1371600
print(f"Pt(72) = {Pt(72)} EMU")               # 914400
```

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

### Open an existing presentation

Source: https://github.com/scanny/python-pptx/blob/master/docs/user/presentations.md

Loads an existing PowerPoint file for modification and saves it to a new location.

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

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

### XML Specimen for Tick Labels

Source: https://github.com/scanny/python-pptx/blob/master/docs/dev/analysis/cht-tick-labels.md

An example of the XML structure related to tick labels within a category axis.

```APIDOC
## XML Specimen for Category Axis Tick Labels

### Description
This XML specimen illustrates how tick label-related elements are represented within the XML structure of a category axis in a chart.

### Method
N/A

### Endpoint
N/A

### Parameters
None

### XML Structure
```xml
<c:catAx>
  <c:axId val="-2097691448"/>
  <c:scaling>
    <c:orientation val="minMax"/>
  </c:scaling>
  <c:axPos val="b"/>
  <c:numFmt formatCode="General" sourceLinked="0"/>
  <c:tickLblPos val="nextTo"/>
  <c:txPr>
    <a:bodyPr/>
    <a:lstStyle/>
    <a:p>
      <a:pPr>
        <a:defRPr sz="1000"/>
      </a:pPr>
      <a:endParaRPr lang="en-US"/>
    </a:p>
  </c:txPr>
  <c:crossAx val="-2097683336"/>
  <c:crosses val="autoZero"/>
  <c:lblAlgn val="ctr"/>
  <c:lblOffset val="100"/>
  <c:noMultiLvlLbl val="0"/>
</c:catAx>
```

### Key Elements
* **`<c:numFmt>`**: Defines the number format and its linked status.
* **`<c:lblOffset>`**: Specifies the offset for tick labels.

### Response
N/A
```

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

### XML Specimen for Axis with Gridlines

Source: https://github.com/scanny/python-pptx/blob/master/docs/dev/analysis/cht-axis-has-gridlines.md

An example of the XML structure for a category axis that includes both major and minor gridlines.

```APIDOC
## XML Specimen: Category Axis with Gridlines

### Description
This XML specimen illustrates the structure of a category axis (`<c:catAx>`) that has both major and minor gridlines enabled, as well as other common axis configurations.

### XML Structure
```xml
<c:catAx>
  <c:axId val="-2097691448"/>
  <c:scaling>
    <c:orientation val="minMax"/>
  </c:scaling>
  <c:delete val="0"/>
  <c:axPos val="b"/>
  <c:majorGridlines/>
  <c:minorGridlines/>
  <c:numFmt formatCode="General" sourceLinked="0"/>
  <c:majorTickMark val="out"/>
  <c:minorTickMark val="none"/>
  <c:tickLblPos val="nextTo"/>
  <c:txPr>
    <a:bodyPr/>
    <a:lstStyle/>
    <a:p>
      <a:pPr>
        <a:defRPr sz="1000"/>
      </a:pPr>
      <a:endParaRPr lang="en-US"/>
    </a:p>
  </c:txPr>
  <c:crossAx val="-2097683336"/>
  <c:crosses val="autoZero"/>
  <c:auto val="1"/>
  <c:lblAlgn val="ctr"/>
  <c:lblOffset val="100"/>
  <c:noMultiLvlLbl val="0"/>
</c:catAx>
```

### Key Elements for Gridlines
- **`<c:majorGridlines/>`**: Indicates the presence of major gridlines.
- **`<c:minorGridlines/>`**: Indicates the presence of minor gridlines.

### Formatting
Line formatting for gridlines is typically specified within a child `<c:spPr>` element, which is not detailed in this specific specimen but is referenced in the XML Semantics section.
```

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

### Paragraph Spacing Properties

Source: https://github.com/scanny/python-pptx/blob/master/docs/dev/analysis/txt-para-spacing.md

Methods for getting and setting space before, space after, and line spacing for paragraphs within a TextFrame.

```APIDOC
## Paragraph Spacing Properties

### Description
Manage the vertical spacing of paragraphs, including space before, space after, and line spacing. Spacing can be defined in points (Pt) or lines.

### Properties
- **space_before** (Length/int) - Read/Write - The amount of space before the paragraph.
- **space_after** (Length/int) - Read/Write - The amount of space after the paragraph.
- **line_spacing** (float/Length) - Read/Write - The spacing between base lines. Defaults to 1.0 (lines). If set to a float, it represents lines; if set to a Length (e.g., Pt), it represents points.

### Usage Example
```python
# Set space before to 6 points
paragraph.space_before = Pt(6)

# Set line spacing to 18 points
paragraph.line_spacing = Pt(18)

# Check if line spacing is in lines
if isinstance(paragraph.line_spacing, float):
    print("Spacing is set in lines")
```
```

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

### Accessing and Inspecting Slide Placeholders

Source: https://github.com/scanny/python-pptx/blob/master/docs/dev/analysis/placeholders/slide-placeholders/index.md

Demonstrates how to access slide placeholders, inspect their properties, and insert content like tables. Use this to understand the structure and capabilities of placeholders on a slide.

```python
slide = prs.slides[0]
slide.shapes
slide.shapes[0]
slide_placeholders = slide.placeholders
len(slide_placeholders)
slide_placeholders[1]
slide_placeholders[1].type
slide_placeholders.get(idx=1)
slide_placeholders[1]._sp.spPr.xfrm
slide_placeholders[1].width
table = slide_placeholders[1].insert_table(rows=2, cols=2)
len(slide_placeholders)
```

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

### Managing DataLabel position

Source: https://github.com/scanny/python-pptx/blob/master/docs/dev/analysis/cht-data-labels.md

Use the XL_DATA_LABEL_POSITION enumeration to get or set the position of data labels relative to their markers.

```python
>>> data_labels = plot.data_labels
>>> data_labels.position
OUTSIDE_END (2)
>>> data_labels.position = XL_DATA_LABEL_POSITION.INSIDE_END
>>> data_labels.position
INSIDE_END (3)
```

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

### Configure text frame autofit settings

Source: https://github.com/scanny/python-pptx/blob/master/docs/dev/analysis/shp-autofit.md

Demonstrates how to inspect and modify the auto_size property of a text frame using MSO_AUTO_SIZE constants.

```python
>>> text_frame = shape.text_frame
>>> text_frame.auto_size
None
>>> text_frame.auto_size = MSO_AUTO_SIZE.SHAPE_TO_FIT_TEXT
>>> text_frame.auto_size
1
>>> text_frame.auto_size = MSO_AUTO_SIZE.TEXT_TO_FIT_SHAPE
>>> text_frame.auto_size
2
>>> str(text_frame.auto_size)
'MSO_AUTO_SIZE.TEXT_TO_FIT_SHAPE'
>>> text_frame.auto_size = MSO_AUTO_SIZE.NONE
>>> text_frame.auto_size
0
>>> text_frame.auto_size = None
>>> text_frame.auto_size
None
```

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

### Initialize XmlEnumeration Subclasses

Source: https://github.com/scanny/python-pptx/blob/master/docs/dev/analysis/enumerations.md

Proposed implementation for initializing subclasses of XmlEnumeration using __init__ to set up settings collection.

```python
def __init__(cls, clsname, bases, clsdict):
    cls._collect_valid_settings = []
```

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

### Convert units using English Metric Units (EMU)

Source: https://github.com/scanny/python-pptx/blob/master/docs/user/autoshapes.md

Demonstrates how to use utility classes to convert between inches, points, and internal EMU values.

```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
```