Python-Pptx Documentation Release 0.6.21
Total Page:16
File Type:pdf, Size:1020Kb
python-pptx Documentation Release 0.6.21 Steve Canny Sep 20, 2021 Contents 1 Feature Support 3 2 User Guide 5 3 Community Guide 47 4 API Documentation 57 5 Contributor Guide 145 Python Module Index 511 Index 513 i ii python-pptx Documentation, Release 0.6.21 Release v0.6.21 (Installation) python-pptx is a Python library for creating and updating PowerPoint (.pptx) files. A typical use would be generating a customized PowerPoint presentation from database content, downloadable by clicking a link in a web application. Several developers have used it to automate production of presentation-ready engineering status reports based on information held in their work management system. It could also be used for making bulk updates to a library of presentations or simply to automate the production of a slide or two that would be tedious to get right by hand. More information is available in the python-pptx documentation. Browse examples with screenshots to get a quick idea what you can do with python-pptx. Contents 1 python-pptx Documentation, Release 0.6.21 2 Contents CHAPTER 1 Feature Support python-pptx has the following capabilities, with many more on the roadmap: • Round-trip any Open XML presentation (.pptx file) including all its elements • Add slides • Populate text placeholders, for example to create a bullet slide • Add image to slide at arbitrary position and size • Add textbox to a slide; manipulate text font size and bold • Add table to a slide • Add auto shapes (e.g. polygons, flowchart shapes, etc.) to a slide • Add and manipulate column, bar, line, and pie charts • Access and change core document properties such as title and subject Additional capabilities are actively being developed and added on a release cadence of roughly once per month. If you find a feature you need that python-pptx doesn’t yet have, reach out via the mailing list or issue tracker and we’ll see if we can jump the queue for you to pop it in there :) 3 python-pptx Documentation, Release 0.6.21 4 Chapter 1. Feature Support CHAPTER 2 User Guide 2.1 Introduction python-pptx is a Python library for creating and updating PowerPoint (.pptx) files. A typical use would be generating a customized PowerPoint presentation from database content, downloadble by clicking a link in a web application. Several developers have used it to automate production of presentation-ready engineering status reports based on information held in their work management system. It could also be used for making bulk updates to a library of presentations or simply to automate the production of a slide or two that would be tedious to get right by hand. This user guide is tutorial in nature, introducing concepts along with code examples that I hope will allow you to learn what you need while addressing the real-life PowerPoint challenges you’re working on. 2.1.1 python-pptx License The MIT License (MIT) Copyright (c) 2013 Steve Canny, https://github.com/scanny Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associ- ated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARIS- ING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 5 python-pptx Documentation, Release 0.6.21 2.2 Installing python-pptx is hosted on PyPI, so installing with pip is simple: pip install python-pptx python-pptx depends on the lxml package and Pillow, the modern version of the Python Imaging Library (PIL). The charting features depend on XlsxWriter. Both pip and easy_install will take care of satisfying these dependencies for you, but if you use the setup.py installation method you will need to install the dependencies yourself. Currently python-pptx requires Python 2.7, 3.3, 3.4, or 3.6. The tests are run against 2.7 and 3.6 on Travis CI. 2.2.1 Dependencies • Python 2.6, 2.7, 3.3, 3.4, or 3.6 • lxml • Pillow • XlsxWriter (to use charting features) 2.3 Getting Started A quick way to get started is by trying out some of the examples below to get a feel for how to use python-pptx. The API documentation can help you with the fine details of calling signatures and behaviors. 2.3.1 Hello World! example 6 Chapter 2. User Guide python-pptx Documentation, Release 0.6.21 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') 2.3.2 Bullet slide example from pptx import Presentation prs= Presentation() bullet_slide_layout= prs.slide_layouts[1] slide= prs.slides.add_slide(bullet_slide_layout) shapes= slide.shapes title_shape= shapes.title body_shape= shapes.placeholders[1] (continues on next page) 2.3. Getting Started 7 python-pptx Documentation, Release 0.6.21 (continued from previous page) title_shape.text='Adding a Bullet Slide' tf= body_shape.text_frame tf.text='Find the bullet slide layout' p= tf.add_paragraph() p.text='Use _TextFrame.text for first bullet' p.level=1 p= tf.add_paragraph() p.text='Use _TextFrame.add_paragraph() for subsequent bullets' p.level=2 prs.save('test.pptx') Not all shapes can contain text, but those that do always have at least one paragraph, even if that paragraph is empty and no text is visible within the shape. _BaseShape.has_text_frame can be used to determine whether a shape can contain text. (All shapes subclass _BaseShape.) When _BaseShape.has_text_frame is True, _BaseShape.text_frame.paragraphs[0] returns the first paragraph. The text of the first paragraph can be set using text_frame.paragraphs[0].text. As a shortcut, the writable properties _BaseShape.text and _TextFrame.text are provided to accomplish the same thing. Note that these last two calls delete all the shape’s paragraphs except the first one before setting the text it contains. 2.3.3 add_textbox() example from pptx import Presentation from pptx.util import Inches, Pt (continues on next page) 8 Chapter 2. User Guide python-pptx Documentation, Release 0.6.21 (continued from previous page) prs= Presentation() blank_slide_layout= prs.slide_layouts[6] slide= prs.slides.add_slide(blank_slide_layout) left= top= width= height= Inches(1) txBox= slide.shapes.add_textbox(left, top, width, height) tf= txBox.text_frame tf.text="This is text inside a textbox" p= tf.add_paragraph() p.text="This is a second paragraph that's bold" p.font.bold= True p= tf.add_paragraph() p.text="This is a third paragraph that's big" p.font.size= Pt(40) prs.save('test.pptx') 2.3.4 add_picture() example from pptx import Presentation from pptx.util import Inches img_path='monty-truth.png' (continues on next page) 2.3. Getting Started 9 python-pptx Documentation, Release 0.6.21 (continued from previous page) prs= Presentation() blank_slide_layout= prs.slide_layouts[6] slide= prs.slides.add_slide(blank_slide_layout) left= top= Inches(1) pic= slide.shapes.add_picture(img_path, left, top) left= Inches(5) height= Inches(5.5) pic= slide.shapes.add_picture(img_path, left, top, height=height) prs.save('test.pptx') 2.3.5 add_shape() example 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) (continues on next page) 10 Chapter 2. User Guide python-pptx Documentation, Release 0.6.21 (continued from previous page) 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') Constants representing each of the available auto shapes (like MSO_SHAPE.ROUNDED_RECT, MSO_SHAPE.CHEVRON, etc.) are listed on the autoshape-types page. 2.3.6 add_table() example from pptx import Presentation 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 (continues on next page) 2.3. Getting Started 11 python-pptx Documentation, Release 0.6.21 (continued from previous page) shapes.title.text='Adding a Table' rows= cols=2 left= top= Inches(2.0) width= Inches(6.0) height= Inches(0.8) table= shapes.add_table(rows, cols, left, top, width, height).table # set column widths table.columns[0].width= Inches(2.0) table.columns[1].width= Inches(4.0) # write column headings table.cell(0,0).text='Foo' table.cell(0,1).text='Bar' # write body cells table.cell(1,0).text='Baz' table.cell(1,1).text='Qux' prs.save('test.pptx') 2.3.7 Extract all text from slides in presentation from pptx import Presentation prs= Presentation(path_to_presentation) # text_runs will be populated with a list of strings, # one for each text run in presentation text_runs=[] for slide in prs.slides: for shape in slide.shapes: if not shape.has_text_frame: continue for paragraph in shape.text_frame.paragraphs: for run in paragraph.runs: text_runs.append(run.text) 2.4 Working with Presentations python-pptx allows you to create new presentations as well as make changes to existing ones.