0
# Python-PPTX
1

2
A comprehensive Python library for creating, reading, and updating Microsoft PowerPoint 2007+ (.pptx) files programmatically. Python-PPTX enables developers to generate dynamic presentations from data sources like databases, APIs, or analytics outputs without requiring PowerPoint installation.
3

4
## Package Information
5

6
- **Package Name**: python-pptx
7
- **Language**: Python
8
- **Installation**: `pip install python-pptx`
9

10
## Core Imports
11

12
```python
13
from pptx import Presentation
14
```
15

16
Common patterns for working with specific components:
17

18
```python
19
from pptx.util import Inches, Cm, Pt
20
from pptx.enum.text import PP_PARAGRAPH_ALIGNMENT
21
from pptx.enum.shapes import MSO_SHAPE
22
from pptx.chart.data import CategoryChartData
23
from pptx.enum.chart import XL_CHART_TYPE
24
from pptx.dml.color import RGBColor
25
```
26

27
## Basic Usage
28

29
```python
30
from pptx import Presentation
31
from pptx.util import Inches
32
from pptx.enum.shapes import MSO_SHAPE
33

34
# Create a new presentation
35
prs = Presentation()
36

37
# Add a slide with title and content layout
38
slide_layout = prs.slide_layouts[1]  # Title and Content layout
39
slide = prs.slides.add_slide(slide_layout)
40

41
# Add title and content
42
title = slide.shapes.title
43
title.text = "My Presentation Title"
44

45
content = slide.placeholders[1]  # Content placeholder
46
tf = content.text_frame
47
tf.text = "This is the first bullet point"
48

49
# Add another bullet point
50
p = tf.add_paragraph()
51
p.text = "This is the second bullet point"
52
p.level = 1
53

54
# Add a shape
55
left = top = width = height = Inches(1)
56
shape = slide.shapes.add_shape(
57
    MSO_SHAPE.RECTANGLE, left, top, width, height
58
)
59
shape.text = "This is a text box"
60

61
# Save the presentation
62
prs.save('my-presentation.pptx')
63
```
64

65
## Architecture
66

67
Python-PPTX follows a hierarchical object model that mirrors PowerPoint's document structure:
68

69
- **Presentation**: Top-level container managing slides, masters, and document properties
70
- **Slides**: Collection of individual slides with content and formatting
71
- **Shapes**: Visual elements (text boxes, images, charts, tables) within slides
72
- **Text Framework**: Rich text handling with runs, paragraphs, and character formatting
73
- **Drawing ML (DML)**: Low-level drawing and formatting capabilities
74

75
The library is built on Open Packaging Conventions (OPC) and Office Open XML standards, providing robust XML parsing and generation capabilities for reliable .pptx file handling.
76

77
## Capabilities
78

79
### Presentation Management
80

81
Core functionality for creating, opening, and saving PowerPoint presentations. Includes slide management, master templates, and document properties.
82

83
```python { .api }
84
from typing import IO
85
from pptx import presentation
86

87
def Presentation(pptx: str | IO[bytes] | None = None) -> presentation.Presentation:
88
    """
89
    Create or load a presentation.
90
    
91
    Parameters:
92
    - pptx: str | IO[bytes] | None, path to .pptx file, file-like object, or None for new presentation
93
    
94
    Returns:
95
    presentation.Presentation object
96
    """
97

98
class Presentation:
99
    """Main presentation object containing slides and configuration."""
100
    slides: Slides
101
    slide_layouts: SlideLayouts  
102
    slide_masters: SlideMasters
103
    slide_width: int  # in EMU
104
    slide_height: int  # in EMU
105
    core_properties: CoreProperties
106
    
107
    def save(self, file):
108
        """Save presentation to file path or file-like object."""
109
```
110

111
[Presentation Management](./presentation.md)
112

113
### Slide Operations
114

115
Creating, accessing, and managing slides within presentations. Includes slide layouts, masters, and slide-specific properties.
116

117
```python { .api }
118
class Slides:
119
    """Collection of slides in a presentation."""
120
    def add_slide(self, slide_layout): ...
121
    def __getitem__(self, index): ...
122
    def __len__(self): ...
123

124
class Slide:
125
    """Individual slide with shapes and properties."""
126
    shapes: SlideShapes
127
    slide_layout: SlideLayout
128
    notes_slide: NotesSlide
129
    
130
    @property
131
    def name(self): ...
132
```
133

134
[Slide Operations](./slides.md)
135

136
### Shape Creation and Manipulation  
137

138
Adding and configuring visual elements including text boxes, images, autoshapes, and connectors. Covers shape properties, positioning, and styling.
139

140
```python { .api }
141
class SlideShapes:
142
    """Collection of shapes on a slide."""
143
    def add_textbox(self, left, top, width, height): ...
144
    def add_picture(self, image_file, left, top, width=None, height=None): ...
145
    def add_shape(self, autoshape_type, left, top, width, height): ...
146
    def add_table(self, rows, cols, left, top, width, height): ...
147
    def add_chart(self, chart_type, x, y, cx, cy, chart_data): ...
148
    
149
class BaseShape:
150
    """Base class for all shapes."""
151
    name: str
152
    shape_type: MSO_SHAPE_TYPE
153
    left: int  # position in EMU
154
    top: int
155
    width: int
156
    height: int
157
```
158

159
[Shapes](./shapes.md)
160

161
### Text Formatting and Typography
162

163
Rich text handling including paragraphs, runs, fonts, colors, and alignment. Supports advanced typography features and text frame management.
164

165
```python { .api }
166
class TextFrame:
167
    """Container for text content."""
168
    paragraphs: list
169
    text: str
170
    def add_paragraph(self): ...
171
    
172
class Font:
173
    """Text formatting properties."""
174
    name: str
175
    size: Pt
176
    bold: bool
177
    italic: bool
178
    color: ColorFormat
179
    underline: bool
180
```
181

182
[Text](./text.md)
183

184
### Chart Creation and Data Visualization
185

186
Creating and configuring charts including bar, line, pie, scatter, and bubble charts. Includes data binding, formatting, and chart element customization.
187

188
```python { .api }
189
class CategoryChartData:
190
    """Data container for category-based charts."""
191
    def add_series(self, name, values=None): ...
192
    
193
class Chart:
194
    """Chart object with plot area, legend, and axes."""
195
    chart_type: XL_CHART_TYPE
196
    plots: list
197
    legend: Legend
198
    value_axis: ValueAxis
199
    category_axis: CategoryAxis
200
```
201

202
[Charts](./charts.md)
203

204
### Table Creation and Formatting
205

206
Creating and styling tables with cells, rows, and columns. Includes cell merging, text formatting, and table-wide styling options.
207

208
```python { .api }
209
class Table:
210
    """Table with rows and columns."""
211
    rows: _RowCollection
212
    columns: _ColumnCollection
213
    def cell(self, row_idx, col_idx): ...
214
    
215
class _Cell:
216
    """Individual table cell."""
217
    text: str
218
    text_frame: TextFrame
219
    fill: FillFormat
220
    def merge(self, other_cell): ...
221
```
222

223
[Tables](./tables.md)
224

225
### Colors and Visual Formatting
226

227
Color specification and visual formatting including fills, lines, shadows, and effects. Supports RGB, theme colors, and transparency.
228

229
```python { .api }
230
class RGBColor:
231
    """RGB color specification."""
232
    def __init__(self, r, g, b): ...
233
    
234
class ColorFormat:
235
    """Color formatting with type-specific properties."""
236
    rgb: RGBColor
237
    theme_color: MSO_THEME_COLOR_INDEX
238
    brightness: float
239
    
240
class FillFormat:
241
    """Fill formatting for shapes and text."""
242
    solid(): ...
243
    gradient(): ...
244
    patterned(): ...
245
```
246

247
[Colors and Formatting](./formatting.md)
248

249
### Measurement Units and Utilities
250

251
Length measurements, positioning utilities, and helper functions for working with PowerPoint's coordinate system and measurements.  
252

253
```python { .api }
254
def Inches(inches): 
255
    """Create Length from inches measurement."""
256
def Cm(cm):
257
    """Create Length from centimeters measurement."""  
258
def Pt(points):
259
    """Create Length from points measurement."""
260
def Mm(mm):
261
    """Create Length from millimeters measurement."""
262
    
263
class Length:
264
    """Length measurement with unit conversion."""
265
    inches: float
266
    cm: float
267
    pt: float
268
    mm: float
269
```
270

271
[Utilities](./utilities.md)
272

273
## Error Handling
274

275
```python { .api }
276
class PythonPptxError(Exception):
277
    """Base exception for python-pptx operations."""
278

279
class PackageNotFoundError(PythonPptxError):
280
    """Raised when .pptx file cannot be found."""
281
    
282
class InvalidXmlError(PythonPptxError):
283
    """Raised when XML content is invalid."""
284
```
285

286
Common error scenarios:
287
- File not found or permission issues when opening/saving presentations
288
- Invalid image formats when adding pictures  
289
- Malformed chart data when creating visualizations
290
- Unsupported .pptx features in older PowerPoint versions