【Python×PowerPoint】Editing text in paragraphs with python-pptx


In this article, we will continue to introduce the “python-pptx” library, which allows you to manipulate “PowerPoint” in Python.

In the previous article, we explained the basic operations of “installing pytnon-pptx ~ creating files“, “adding slides“, and “inserting content into the place folder“.

So we have omitted duplicated contents. We recommend that you read the previous article here.

Links to other articles in the series are also provided below.

<Index of articles>
  • 【Serials #1】How to install the library and create files and slides ->>
  • Serials #2How to insert documents into paragraphs and set fonts ->>
  • Serials #3】Insert a graph (scatter or line chart) on a slide ->>
  • Serials #4】Inserting a table on a slide ->>
  • Serials #5】Inserting shapes (autoshapes, images, boxes) into slides ->>

In this second article in the series, we will focus on setting and editing the text of “Title“, “Heading” and “Body and Bullet Points“.

The existence of “text” is important in the creation of presentation contents, and is related to “ease of understanding” and “appeal”.

In the previous article, we mentioned how to set the text in the place folder (the template for the content), but you can also edit and set the “font,” “paragraphs,” “indentation,” and other details even further.

It requires an overview of the TextFrame object and its related object methods (properties). In this article, we will discuss the TextFrame object and focus on text editing.

Please stay with us until the end of this article as you will learn the following.

What you will learn in this article
  • TextFrame objects that manage text and the related objects under them
  • Setting a string for each paragraph(Object)
  • Advanced settings such as text color and indentation (Run object)

The next section will provide a detailed description of each object.

The usage of various classes and functions introduced in this article is just an example. Please refer to the “Official Documentation” below for details and clarifications.

Official documentation for “python-pptx”


1. TextFrame object to manage slide text

This section describes the “TextFrame” class, which is indispensable for setting text using python-pptx.

This section will start with an overview of what the “TextFrame” is, how to retrieve the object, and how to actually set the text.

1.1 What is TextFrame?

As mentioned earlier, python-pptx places text (strings) in a framework called a “TextFrame“.

As shown in Fig1, PowerPoint is composed of various elements (*) such as place folder (TITLE, BODY, etc.), shapes (AutoShape), graphs, tables, etc.

(*All elements on the presentation are treated as Shape objects.)

Fig1. Elements that make up PowerPoint (re-capitulation)

Each of these elements has an area where text can be inserted, and this area is called a “TextFrame”.

You usually enter text into these elements without much thought, but when you manipulate them programmatically, you must go through this TextFrame (object).

Fig2. TextFrame area of slide components

Further, we will deepen our understanding of the contents of this TextFrame.

If the TextFrame is a frame that manages text, it is composed of a collection of related subordinate objects, such as paragraphs and letters (words).

This makes it possible to support detailed text settings such as indentation and font formatting.

For example, you want to set up text with the following three styles.

  1. Case of setting a string for one line (one paragraph)
  2. Case of setting up a multi-line string by separating paragraphs
  3. Cases with advanced settings such as text color and indentation

Not all of ➀②➂ can be handled by the TextFrame object alone. As shown in Fig3, they must be handled by linking related objects under the TextFrame object.

Fig. 3 Different use of objects in text editing

Fig4 illustrates the relationship of each object on the actual slide. This is an example of setting a string in a text box (Shape object).

As shown in the figure, each Shape object has one independent TextFrame object. Paragraph objects is placed inside the TextFrame object, and Run objects is assigned to each character.

図4 スライドを構成するテキスト関連のオブジェクト
  • TextBox(Shape Object)… Red box line
  • TextFrame (TextFrame Object) … Light blue box line
  • Paragraph (Paragraph Object) … Green box line
  • Characters/Words (Run Object) … Blue box line

In the next section, we will discuss the details of each object and its related methods and attributes.

1.2 Getting and setting a TextFrame object

The TextFrame object can be obtained from the text_frame property of the Shape object such as a text box or shape into which you want to insert text.※

(※ The Shape object is explained in detail in <article.5>.)

TextFrame Object

Shape Object.text_frame property

return: TextFrame Object

The main methods and properties of the TextFrame object include the following.

【TextFrame ObjectFuntions】Other details
text propertySet/Get string in text frame
autosize propertyAutomatic adjustment of font sizeMSO_AUTO_SIZE Class
word_wrap propertySet/Get character wrapping・折り返す場合はTrueを指定
vertical_anchor propertyCharacter Vertical PositionMSO_VERTICAL_ANCHOR Class
margin_top(bottom) propertyAdjust the top and bottom margins
margin_left(right) propertyAdjust left and right margins
Table1. Main properties of TextFrame object

Use the text property to set text in a frame. Font size cannot be specified directly on the TextFrame and is handled by automatic size adjustment using the autosize property. Font size can be specified in the Paragraph and Run layers, which will be explained later.

In addition, the vertical_anchor property controls the position of text within the frame, and the margin_* property adjusts the margins of the frame. (Fig.5)

Fig5 Positioning by margin_* property


Here is an example related to the TextFrame object. The code outline is to examine the attributes of a Shape object in a slide. Then set the text to the TextFrame of each Shape object. Enable text size and wrapping within the frame.<List1>

from pptx import Presentation
from pptx.enum.text import MSO_AUTO_SIZE   # Import of MOS_AUTO_SIZE class

prs = Presentation('0218_Blog.pptx')

sld0 = prs.slides[0]

for shape in sld0.shapes:           # Extracts elements from slides and displays their types
    print(shape.name)               # >> Title 1, Text box 3, Arrows: right 4, Callout: circular 12
    if not shape.has_text_frame:    # Check if the shape object contains a TextFrame
    textFrame = shape.text_frame                         # Get TextFrame from various Shape objects
    textFrame.text = 'Pythonのサンプルプログラムです'      # Set text in TextFrame
    textFrame.autosize = MSO_AUTO_SIZE.TEXT_TO_FIT_SHAPE # TextFrame text size auto-adjustment
    textFrame.word_wrap = True                           # Enable auto text wrapping

Now, let me explain the key points.

Lines 10,11:【Check inclusion of TextFrame】

Not all shapes on a slide can have text inserted into them. If you try to get a TextFrame from a Shape object that has no text settings, an error will be issued.

Therefore, for all Shape objects, first check for the inclusion of TextFrame with the has_text_frame property.

Lines 16,17:【Size and Wrap Settings】

Shapes have unique frame sizes. If you set text without thinking, the text may break off in the middle or may not display well.

Therefore, the autosize property is set to automatically adjust the text size to fit within the

frame, and the word_wrap property is set to “True” to enable string wrapping.

The result of executing the code is as follows.

The text “This is a sample Python program” has been set for the “Title Place Folder,” “Text Box,” and “Shape.” It also reflects the size and wrap settings that fit into the frame of each Shape object.

Fig6. Result of execution of List1

2. Adding a paragraph (Paragraph object)


The unit that manages paragraphs in a TextFrame object is the Paragraph object.

A TextFrame object has at least one paragraph by default. If you want to set up text that consists of multiple lines of paragraphs, you must add a Paragraph.

2.1 Adding and Getting the Paragraph Object

Use the add_paragraph() method to add a paragraph (Paragraph object) to a TextFrame object and the paragraphs property to get it.

Normally, paragraphs are assumed to have more than one, so they are managed as collections (iterable objects with Paragraph objects as elements) in the TextFrame object.

Getting the Paragraph object

TextFrame Object.add_paragraph()

return: None( added to Paragraph Object collection)

TextFrame Object.paragraphs property

return: Collection of Paragraph Object

TextFrame Object.paragraphs[index] property

arg: inex: Index of collection elements

return: Paragraph Object

2.2 Methods and properties of the Paragraph object

The following methods and properties are provided under the Paragraph object to operate on the paragraph layer.

【Paragraph Object】Functions】【Other details】
text propertySet/Get string in paragraph
level propertySet/Get paragraph
indentation level
・Specify the level in the range of 0~8
font propertySet the font
(Get Font object)
Font ObjectRelated Attributes
bold, size,i talic, color
alignment propertySpecify the horizontal position
of strings
line_spacing propertySpecify the height between linesSpecify by pt (point), etc.
space_after(before) propertySpacing between previous and
next paragraphs
Specify by pt (point), etc.
Table2 Main Attributes of Paragraph Objects

Font can be set by using the font property on the layer after the paragraph. There is also the level property, which allows you to specify indentation of paragraphs in nine levels, and other properties that specify spacing between lines or paragraphs. (Fig.7)

Fig7. Attributes of the Paragraph object


Now, let’s check an example of operation on the Paragraph layer using sample code.

The code summary is to add a paragraph to the Shape object (text box) on the slide to see the effect of the attributes of Table2.

from pptx import Presentation
from pptx.enum.text import PP_ALIGN       # Enume the horizontal position of the paragraph
from pptx.enum.dml import MSO_THEME_COLOR # Enume in theme color
from pptx.util import Pt                  # Definition of units (points)

prs = Presentation("Paragraph_Sample.pptx")
sld0 = prs.slides[0]

# Examining the attribute information of a Shape object (text box)
# TextFrame objects can be included if the has_text_frame attribute is "True
for sp in sld0.shapes:
    print(sp.shape_type, sp.name, sp.has_text_frame)
    # >> TEXT_BOX (17) テキスト ボックス 1 True
    # >> TEXT_BOX (17) テキスト ボックス 2 True
    # >> TEXT_BOX (17) テキスト ボックス 3 True
    # >> TEXT_BOX (17) テキスト ボックス 4 True

# Add two paragraphs to the TextFrame object
for dumy in range(2):

# Paragraph indentation adjustment -----------------------------------------------
paras = sld0.shapes[0].text_frame.paragraphs

for i, para in enumerate(paras, 0):
    para.text = "段落ごとに字下げを指定する"
    para.level = i

# Horizontal Positioning --------------------------------------------------------

paras = sld0.shapes[1].text_frame.paragraphs

for i, para in enumerate(paras, 0):
    para.text = "段落ごとの水平位置(左/中央/右揃え)を指定する"
    para.alignment = List_PP_ALIGN[i]

# String font settings ---------------------------------------------------------

paras = sld0.shapes[2].text_frame.paragraphs

for i, para in enumerate(paras, 0):
    para.text = "段落レベルで文字列のフォントを調整"
    para.font.color.theme_color = List_MSO_THEME_COLOR[i]  # フォントの色
    para.font.bold = True  # フォントの大きさ

# Paragraph spacing ------------------------------------------------------------

paras = sld0.shapes[3].text_frame.paragraphs
for para in paras:
    para.text = "段落間の間隔(space_after)のPt(15)で調整"
    para.space_after = Pt(15)


The following is an explanation of key points.

Lines 21~25:【Add paragraphs to TextFrame】

For statement loop adds two paragraphs to each Shape object. Use the add_paragraph() method of the TextFrame object to add a paragraph.

Also, as mentioned above, the Shape object contains one paragraph from the beginning, so the number of loops is the number of paragraphs you need minus one.

Lines 29~33:【Indentation of a paragraph】

Expand a collection of Paragraphs with For statement and the Enumerate function. For individual paragraphs, set the text and paragraph level with the level property. The indentation level is set to the index obtained from the Enumerate function.

Subsequent processes follow the same procedure to obtain indexes.

Lines 38~43:【Justify horizontally】

The horizontal alignment of each paragraph is set by the alignment property.

The setting value specifies the Enume option of the PP_ALIGN class as “LEFT (left-align)”, “CENTER (center-align)”, or “RIGHT (right-align)”.

Lines 48~54:【Font Settings】

Each detailed font setting for an entire paragraph is configured via the font property. Here, the text color is set with the Enume option of the MSO_THEME_COLOR class and the font is bold. The Font object is described below.

Finally, the space adjustment between paragraphs is specified with the space_after property.

In this case, we have adjusted the spacing to 15 points.

The result of executing the code is as follows.

The paragraph level attributes “indentation,” “horizontal alignment,” “font setting,” and “spacing” are reflected. (Fig.8)

Fig8 Result of List2 execution

3. Character (Run object) setting

The Run object is a unit that manages individual characters (words) within a paragraph. By managing them separately as Run objects, font formatting can be specified for each character.

3.1 Adding and Getting Run Objects

To add a word (Run object) to a Paragraph, use the add_run() method. Also, use the runs property to get it.

Since text is usually composed of multiple words, Run objects are managed together as a collection (an iterable object whose elements are Run objects) within a paragraph.

Get and set the Run object

Paragraph Object.add_run() method

return: Run Object(Also added to collection)

Paragraph Object.runs property

return: Collection of Run Object (iterable)

Paragraph Object.runs[index]

arg: inex: Index of element

return : Run Object Get specific Run object by index

The parent-child relationship between various objects and key methods and properties can be organized as follows. (Fig9)

Fig9. Hierarchical structure of objects related to text settings

3.2 Properties of the Run object

The following properties are provided under the Run object to allow operation on character units. Attributes are provided to set the character (text property) and font (font property).

Run Object【Functions】【Other Details】
text propertySet/Get character
font propertySet the font and
Getting a Font object
Font Object】Related Attributes
hyperlink.address propertyAssign hyperlinksWebsite URL, etc.
Table3 Run Object Attributes


Check the code for an example of adding and editing text using the Run object.

The code summary is to set the text in a paragraph using the Run object and specify the text color.<List3>

from pptx import Presentation
from pptx.dml.color import RGBColor

prs = Presentation()

title_slide_layout = prs.slide_layouts[1]      	# Get layout object for "Title and Content"
sld0 = prs.slides.add_slide(title_slide_layout) # Add new slide

for s in sld0.shapes:   			# Extract elements in slides, display types
    print(s.name)        			# >> Title 1 Content Placeholder 2

sld0.shapes[0].text = 'タイトルの文字色を変更します'
pg = sld0.shapes[0].text_frame.paragraphs[0]
rn = pg.runs[0]     			# Get a Run object to manipulate the paragraph

rn.font.color.rgb = RGBColor(50, 185, 20)    	# Specify character color for font.color.rgb property of run object

tf = sld0.shapes[0].text_frame
tf.add_paragraph()                       	# Adding a paragraph
pg = sld0.shapes[0].text_frame.paragraphs[1]   	# Get paragraphs added

rn0 = pg.add_run()                    		# Add run object to collection
rn0.text = '文字列1'                  		# Set text in paragraphs
rn0.font.color.rgb = RGBColor(255, 0, 0) 	# Set color (red) for paragraph text

rn1 = pg.add_run()
rn1.text = '文字列2'
rn1.font.color.rgb = RGBColor(0, 255, 0) 		# Set color (green) for paragraph text

rn2 = pg.add_run()
rn2.text = '文字列3'
rn2.font.color.rgb = RGBColor(0, 0, 255)  	# Set color (blue) for paragraph text


The following is an explanation of key points.

Lines 14~16: 【Getting the Run object】

In line 14, the text property is used to set the string directly to the new ”Place Folder TITLE” (Shape object).

At this point, TextFrame, Paragraph, and even Run objects are automatically generated and can be referenced. Since there is only one character added, there is only one Run object in the paragraph, which can be accessed with runs[0].

Line 18:【Formatting String】

The font property of the Run object is used to apply the font formatting.

This example further uses the color property to set the text color. The key point is that formatting can be applied to individual characters, rather than to entire paragraphs.

Lines 25~27:【Add string】

The add_run() method is used to add and retrieve the Run object, and the text property (of the Run) is used to add a string. (Lines 29~31, 33~35 are also appended with strings in the same way)

The result of executing the code is as follows.

The Run object allows font formatting at the character level. (Fig10)

Fig10. Result of List3 execution

3.3 Font Formatting

This section summarizes the properties related to the Font object that can be set in the paragraph and text layers.

【Font Object】【Functions】【Other details】
color.rgb propertyFont color setting (RGB)RGBColor class】 ex)RGBColor(255, 255, 255)
color.theme_color propertyFont color setting (Theme color)option of the【MSO_THEME_COLOR clsss
italic propertyItalic text settingTrue(valid)/False(Invalid)
bold propertyBold text settingTrue(valid)/False(Invalid)
name propertySet/Get font nameex) ‘Calibri’
size propertySet/Get Font SizeSpecify by Pt(point), etc.
underline propertyUnderline settingTrue(valid)/False(Invalid) or
option of the【MSO_UNDERLINE class
Table 4 Font object attributes

The above properties allow you to set a series of font formatting settings. In addition to the above, the fill property seems to be also provided, but it is omitted because it has no effect (cannot be confirmed).

Also, font formatting is inherited from higher level objects unless otherwise specified.

In other words, it is inherited in the order of “TextFrame object” → “Paragraph object” → “Run object”, but you can update the formatting by setting the font on the current layer.

4. Summary

How was it?

In this article, we explained how to edit text on a slide using the “python-ppptxlibrary.

As mentioned earlier, text editing is always necessary in the creation of PowerPoint documents with figures and tables as the main content. We hope this article will be of some help to you.

Finally, let us summarize the contents of this article.

. In “python-pptx”, text is managed in units of frame areas (TextFrame object) and paragraphs (Paragraph object).

. To add new text, get and add the Paragraph object, set the text and style with the attributes under it.

. To edit by character, add or get another Run object. By doing so, you can append characters (words) and set fonts.




Thank you for reading to the end.