python-pptx Documentation

python-pptx is a Python library designed for creating and updating PowerPoint (.pptx) files. It is commonly used for:

• Generating customized presentations from database content (e.g., for web applications).
• Automating engineering status reports from work management systems.
• Performing bulk updates to existing presentation libraries.
• Automating the production of specific slides to avoid manual entry.

python-pptx is a Python library designed for creating, reading, and updating PowerPoint (.pptx) files. It is useful for:

• Generating presentations from dynamic content: Create slides from database queries, analytics output, or JSON payloads.
• Automating slide production: Automate the creation of repetitive or tedious slides.
• Analyzing PowerPoint files: Extract text and images from a corpus of PowerPoint files for tasks like search indexing.

The library runs on any Python-capable platform (including macOS and Linux) and does not require the Microsoft PowerPoint application to be installed or licensed.

python-pptx is an industrial-grade library designed for creating, reading, and updating PowerPoint (.pptx) files. It supports a wide range of Open XML presentation elements, allowing for robust automation in commercial settings.

Key capabilities include:

• Round-trip support: Read and save Open XML presentations (.pptx) while preserving elements.
• Slide manipulation: Add new slides to a presentation.
• Text handling: Populate text placeholders (e.g., bullet slides), add textboxes, and manipulate font properties like size and bold.
• Media and Shapes: Add images at arbitrary positions/sizes, add auto shapes (polygons, flowcharts, etc.), and add tables.
• Data Visualization: Add and manipulate column, bar, line, and pie charts.
• Metadata: Access and change core document properties such as title and subject.

Grouping in PowerPoint is recursive: a GroupShape can contain other GroupShape objects.

In the underlying XML, a group shape is represented by the <p:grpSp> element (type CT_GroupShape). The root shape tree of a slide (p:spTree) uses this same XML type, though it behaves slightly differently than a standard group shape.

In PowerPoint, all text is contained within a shape. Only AutoShapes (which include text placeholders, text boxes, and geometric auto shapes) can directly contain text. These correspond to the <p:sp> XML element.

The text hierarchy is structured as follows:

1. TextFrame: Represented by a TextFrame object, every auto shape has one.
2. Paragraph: A TextFrame contains one or more paragraphs.
3. Elements: Each paragraph contains a sequence of zero or more elements, which can be:
   • Runs (<a:r>): Sequences of text.
   • Line Breaks (<a:br>).
   • Fields (<a:fld>).

A slide is the primary visual container in a presentation, holding shape objects.

Key concepts for developers:

• Ownership: Slides are owned by the presentation object.
• Slide ID: Each slide is assigned a unique integer identifier (starting at 256 and incrementing by 1).
• ID Scope: The Slide ID is unique only within a single presentation. It is managed by the presentation part and is not recorded in the slide's own XML. Instead, it maps to a relationship ID in the presentation XML.
• Persistence: Changing the order of slides does not change their IDs. Deleted slide IDs are not reused.

A ChartData object is used to specify the data depicted in a chart when creating a new chart or replacing data for an existing one. The specific subclass required depends on the chart type:

• Category charts: Use CategoryChartData.
• XY charts: Use XyChartData.
• Bubble charts: Use BubbleChartData.

PowerPoint supports 73 distinct chart types, which are implemented in python-pptx using 16 base XML elements (e.g., c:barChart, c:pie3DChart). The specific chart type used is determined by differentiating these base elements through child elements and attributes such as c:grouping, c:shape, c:barDir, or c:marker.

When working with charts, you should be aware that a single XML element can represent multiple logical chart types depending on its configuration.

In python-pptx, Slide, SlideLayout, and SlideMaster objects all share common behaviors as they are all considered types of slides. The fundamental visual content container for a slide is the shape object.

One shared attribute across these objects is the name (stored in the XML as p:sld/p:cSld/@name).

Note on Slide Naming:

• PowerPoint automatically populates names in SlideLayout objects.
• In Slide and SlideMaster objects, the name attribute is often unpopulated.
• If a slide has no explicit name, PowerPoint displays a default name like 'Slide {n}' (where n is the sequence number), but this default name is not written to the underlying XML attribute.
• In the PowerPoint UI outline pane, the slide title is used instead of the name if a title exists.

In the MS Office API, an AutoShape (referred to as a shape in the PowerPoint UI) is a shape with preset geometry, such as a rectangle, circle, or star.

An AutoShape consists of:

• Type: A preset geometry (there are 187 pre-defined types).
• Outline: A line style (can be None).
• Fill: A fill color/pattern (can be None).
• Effect: Visual effects (can be None).
• Position and Size: Defined by its location and dimensions on the slide.

In the underlying XML, each auto shape is contained within a <p:sp> element.

Text in PowerPoint is organized into a three-level hierarchy. To manipulate text, you must navigate through these levels:

1. .Shape.text_frame: The container for all text in a shape. It controls margins, vertical alignment, wrapping, and auto-fit behavior.
2. .TextFrame.paragraphs: A sequence of paragraphs within a text frame. Every text frame contains at least one paragraph.
3. ._Paragraph.runs: The lowest level where actual text resides. Runs provide character-level formatting (font, size, color, bold, etc.).