Rich text handling including paragraphs, runs, fonts, colors, and alignment. Supports advanced typography features and text frame management for professional document formatting.
Manage text containers that hold paragraphs and provide text-level formatting options.
class TextFrame:
"""Container for text content with paragraph collections."""
@property
def text(self) -> str:
"""Plain text content of entire text frame."""
@text.setter
def text(self, text: str):
"""Set plain text, replacing all existing content."""
@property
def paragraphs(self) -> list:
"""List of paragraphs in text frame."""
def add_paragraph(self) -> _Paragraph:
"""
Add a new paragraph to text frame.
Returns:
New _Paragraph object
"""
def clear(self):
"""Remove all text content."""
@property
def auto_size(self) -> MSO_AUTO_SIZE:
"""Text auto-sizing behavior."""
@auto_size.setter
def auto_size(self, auto_size: MSO_AUTO_SIZE):
"""Set auto-sizing behavior."""
@property
def margin_left(self) -> int:
"""Left margin in EMU."""
@margin_left.setter
def margin_left(self, margin: int):
"""Set left margin."""
@property
def margin_top(self) -> int:
"""Top margin in EMU."""
@margin_top.setter
def margin_top(self, margin: int):
"""Set top margin."""
@property
def margin_right(self) -> int:
"""Right margin in EMU."""
@margin_right.setter
def margin_right(self, margin: int):
"""Set right margin."""
@property
def margin_bottom(self) -> int:
"""Bottom margin in EMU."""
@margin_bottom.setter
def margin_bottom(self, margin: int):
"""Set bottom margin."""
@property
def vertical_anchor(self) -> MSO_VERTICAL_ANCHOR:
"""Vertical alignment of text within frame."""
@vertical_anchor.setter
def vertical_anchor(self, anchor: MSO_VERTICAL_ANCHOR):
"""Set vertical alignment."""
@property
def word_wrap(self) -> bool:
"""True if text wraps within frame boundaries."""
@word_wrap.setter
def word_wrap(self, wrap: bool):
"""Set word wrapping behavior."""Manage individual paragraphs with alignment, spacing, and bullet formatting.
class _Paragraph:
"""Individual paragraph within a text frame."""
@property
def text(self) -> str:
"""Plain text content of paragraph."""
@text.setter
def text(self, text: str):
"""Set paragraph text, replacing existing content."""
@property
def runs(self) -> list:
"""List of runs (formatted text segments) in paragraph."""
def add_run(self) -> _Run:
"""
Add a new run to paragraph.
Returns:
New _Run object for additional text
"""
def clear(self):
"""Remove all text content from paragraph."""
@property
def alignment(self) -> PP_PARAGRAPH_ALIGNMENT:
"""Paragraph alignment."""
@alignment.setter
def alignment(self, alignment: PP_PARAGRAPH_ALIGNMENT):
"""Set paragraph alignment."""
@property
def level(self) -> int:
"""Indentation level (0-8) for bullet hierarchies."""
@level.setter
def level(self, level: int):
"""Set indentation level."""
@property
def space_before(self) -> int:
"""Space before paragraph in EMU."""
@space_before.setter
def space_before(self, space: int):
"""Set space before paragraph."""
@property
def space_after(self) -> int:
"""Space after paragraph in EMU."""
@space_after.setter
def space_after(self, space: int):
"""Set space after paragraph."""
@property
def line_spacing(self) -> float:
"""Line spacing as multiple of line height."""
@line_spacing.setter
def line_spacing(self, spacing: float):
"""Set line spacing multiplier."""
@property
def font(self) -> Font:
"""Default font for paragraph."""Format individual text segments within paragraphs with specific font properties.
class _Run:
"""Text run with consistent formatting within a paragraph."""
@property
def text(self) -> str:
"""Text content of run."""
@text.setter
def text(self, text: str):
"""Set run text content."""
@property
def font(self) -> Font:
"""Font formatting for this run."""
@property
def hyperlink(self) -> _Hyperlink:
"""Hyperlink properties if run contains hyperlink."""Comprehensive font and character formatting options.
class Font:
"""Text formatting properties for characters."""
@property
def name(self) -> str:
"""Font family name."""
@name.setter
def name(self, name: str):
"""Set font family."""
@property
def size(self) -> Pt:
"""Font size in points."""
@size.setter
def size(self, size: Pt):
"""Set font size."""
@property
def bold(self) -> bool:
"""True if text is bold."""
@bold.setter
def bold(self, bold: bool):
"""Set bold formatting."""
@property
def italic(self) -> bool:
"""True if text is italic."""
@italic.setter
def italic(self, italic: bool):
"""Set italic formatting."""
@property
def underline(self) -> bool:
"""True if text is underlined."""
@underline.setter
def underline(self, underline: bool):
"""Set underline formatting."""
@property
def color(self) -> ColorFormat:
"""Text color formatting."""
@property
def language_id(self) -> MSO_LANGUAGE_ID:
"""Language identifier for spell checking."""
@language_id.setter
def language_id(self, language_id: MSO_LANGUAGE_ID):
"""Set language for spell checking."""Create and manage hyperlinks within text content.
class _Hyperlink:
"""Hyperlink within text run."""
@property
def address(self) -> str:
"""URL or file path for hyperlink."""
@address.setter
def address(self, address: str):
"""Set hyperlink address."""
@property
def tooltip(self) -> str:
"""Tooltip text displayed on hover."""
@tooltip.setter
def tooltip(self, tooltip: str):
"""Set hyperlink tooltip."""Control how text fits within text frames and shapes.
from pptx.enum.text import MSO_AUTO_SIZE
MSO_AUTO_SIZE.NONE # No auto-sizing
MSO_AUTO_SIZE.SHAPE_TO_FIT_TEXT # Expand shape to fit text
MSO_AUTO_SIZE.TEXT_TO_FIT_SHAPE # Shrink text to fit shapefrom pptx.enum.text import PP_PARAGRAPH_ALIGNMENT, MSO_VERTICAL_ANCHOR
# Horizontal alignment
PP_PARAGRAPH_ALIGNMENT.LEFT
PP_PARAGRAPH_ALIGNMENT.CENTER
PP_PARAGRAPH_ALIGNMENT.RIGHT
PP_PARAGRAPH_ALIGNMENT.JUSTIFY
PP_PARAGRAPH_ALIGNMENT.DISTRIBUTE
# Vertical alignment
MSO_VERTICAL_ANCHOR.TOP
MSO_VERTICAL_ANCHOR.MIDDLE
MSO_VERTICAL_ANCHOR.BOTTOMUsage examples:
from pptx import Presentation
from pptx.util import Inches, Pt
from pptx.dml.color import RGBColor
from pptx.enum.text import PP_PARAGRAPH_ALIGNMENT, MSO_AUTO_SIZE, MSO_VERTICAL_ANCHOR
prs = Presentation()
slide = prs.slides.add_slide(prs.slide_layouts[6]) # Blank layout
# Add text box with rich formatting
textbox = slide.shapes.add_textbox(Inches(1), Inches(1), Inches(4), Inches(3))
tf = textbox.text_frame
# Configure text frame
tf.auto_size = MSO_AUTO_SIZE.SHAPE_TO_FIT_TEXT
tf.vertical_anchor = MSO_VERTICAL_ANCHOR.MIDDLE
tf.margin_left = Inches(0.1)
tf.margin_right = Inches(0.1)
# Add first paragraph with formatting
p1 = tf.paragraphs[0]
p1.text = "Main Heading"
p1.alignment = PP_PARAGRAPH_ALIGNMENT.CENTER
p1.font.name = "Arial"
p1.font.size = Pt(24)
p1.font.bold = True
p1.font.color.rgb = RGBColor(0, 100, 200)
# Add second paragraph
p2 = tf.add_paragraph()
p2.text = "This is regular text with "
p2.alignment = PP_PARAGRAPH_ALIGNMENT.LEFT
p2.font.size = Pt(14)
# Add formatted run within paragraph
run = p2.add_run()
run.text = "bold emphasis"
run.font.bold = True
run.font.color.rgb = RGBColor(255, 0, 0)
# Continue with regular text
run2 = p2.add_run()
run2.text = " and normal text again."
# Add bulleted list
p3 = tf.add_paragraph()
p3.text = "First bullet point"
p3.level = 0
p3.font.size = Pt(12)
p4 = tf.add_paragraph()
p4.text = "Second bullet point"
p4.level = 0
p5 = tf.add_paragraph()
p5.text = "Sub-bullet point"
p5.level = 1
# Add paragraph with hyperlink
p6 = tf.add_paragraph()
p6.text = "Visit our website: "
run_link = p6.add_run()
run_link.text = "example.com"
hlink = run_link.hyperlink
hlink.address = "http://www.example.com"
hlink.tooltip = "Go to example.com"
# Working with placeholder text
title_slide = prs.slides.add_slide(prs.slide_layouts[0])
title_shape = title_slide.shapes.title
title_tf = title_shape.text_frame
# Format title
title_tf.text = "Formatted Title"
title_p = title_tf.paragraphs[0]
title_p.font.name = "Calibri"
title_p.font.size = Pt(36)
title_p.font.bold = True
title_p.alignment = PP_PARAGRAPH_ALIGNMENT.CENTER
prs.save('text-formatting-example.pptx')from pptx.util import Pt
# Multi-level bullet formatting
for i, bullet_text in enumerate(["Main point", "Sub point", "Detail", "Sub detail"]):
p = tf.add_paragraph()
p.text = bullet_text
p.level = i # Indent level 0-3
p.font.size = Pt(14 - i) # Decreasing font size
# Line spacing and paragraph spacing
p = tf.add_paragraph()
p.text = "Paragraph with custom spacing"
p.space_before = Pt(12) # 12pt before
p.space_after = Pt(6) # 6pt after
p.line_spacing = 1.5 # 1.5x line spacing
# Character-level language settings for spell check
run = p.add_run()
run.text = "Texte en français"
run.font.language_id = MSO_LANGUAGE_ID.FRENCH