pptx-shapes 0.1.1

Python library for adding basic geometric shapes directly to PowerPoint (.pptx) slides by editing the XML structure.

pptx-shapes

Python library for adding basic geometric shapes directly to PowerPoint (.pptx) slides by editing the XML structure.

Features

• Add basic shapes (ellipse, line, polygon, etc.) to existing slides
• Control position, size, fill, stroke, and other styles
• Work directly with slides XML structure
• Save result as .pptx

Installation

pip install pptx-shapes

Quick Start

from pptx_shapes import Presentation
from pptx_shapes.shapes import Ellipse, Rectangle, TextBox
from pptx_shapes.style import FillStyle, FontFormat, FontStyle, StrokeStyle


with Presentation(presentation_path="empty.pptx") as presentation:
    presentation.add(shape=TextBox(
        x=23, y=4, width=12, height=2, angle=45,
        text="Hello from pptx-shapes!",
        style=FontStyle(size=32),
        formatting=FontFormat(bold=True)
    ))

    presentation.add(shape=Ellipse(
        x=20, y=2, dx=4, dy=4,
        fill=FillStyle(color="#7699d4")
    ))

    presentation.add(shape=Rectangle(
        x=18, y=8, width=4, height=8.5, radius=0.25, angle=30,
        fill=FillStyle(color="#dd7373"),
        stroke=StrokeStyle(color="magenta", thickness=3)
    ))

    presentation.save("result.pptx")

Supported Shapes

Currently, pptx-shapes supports the following geometric shapes:

Shape	Class	Description
Ellipse	Ellipse	Ellipse defined by top-left corner, diameters, and rotation angle
Line	Line	Straight line between two points
Rectange	Rectangle	Rectangle defined by top-left corner, size, corner radius and rotation angle
Polygon	Polygon	Arbitrary polygon defined by a list of points and rotation angle
TextBox	TextBox	Text container with position, size, rotation, and font style
Group	Group	A group of multiple shapes

Ellipse

An ellipse is defined by its top-left corner and the diameters in horizontal and vertical directions. It can be rotated by a given angle.

Ellipse(
    x=2, y=3.5, # top-left angle (cm)
    dx=4, dy=6, # diameters (cm)
    angle=30,   # optional rotation angle (degrees)
    fill=...,   # optional FillStyle
    stroke=...  # optional StrokeStyle
)

Parameters

• x, y: top-left corner coordinates in centimeters
• dx, dy: diameters in centimeters
• angle: the rotation angle of the ellipse in degrees (default is 0).
• fill: optional FillStyle to fill the ellipse
• stroke: optional StrokeStyle for the border

Line

A straight line connecting two points.

Line(
    x1=0.5, y1=1, # start point (cm)
    x2=1.5, y2=5, # end point (cm)
    stroke=...    # optional StrokeStyle
)

Parameters

• x1, y1: coordinates for the start point
• x2, y2: coordinates for the end point
• stroke: optional StrokeStyle for the stroke

Rectangle

A rectangle is defined by its top-left corner and its width and height. Like the ellipse, it can be rotated by a specific angle.

Rectangle(
    x=2, y=3.5,        # top-left angle (cm)
    width=4, height=6, # sizes (cm)
    angle=45,          # optional rotation angle (degrees)
    radius=0.05,       # optional radius of corner rounding (percents)
    fill=...,          # optional FillStyle
    stroke=...         # optional StrokeStyle
)

Parameters

• x, y: coordinates defining the top-left corner (cm)
• width, height: the width and height of the rectangle (cm)
• radius: the radius of rounded corners as a percentage of the width/height (default is 0)
• angle: the rotation angle of the rectangle in degrees (default is 0)
• fill: fill style
• stroke: stroke style

Polygon

A polygon can be an arbitrary shape defined by a list of points. It can also be rotated by an angle.

Polygon(
    points=[
        (11, 12),
        (13, 14),
        (11, 16),
        (9, 14),
        (11, 12)
    ],         # list of tuple points (cm)
    angle=15,  # optional rotation angle (degrees)
    fill=...,  # optional FillStyle
    stroke=... # optional StrokeStyle
)

Parameters

• points: a list of tuples of (x, y) coordinates that define the vertices of the polygon
• angle: the rotation angle of the polygon in degrees (default is 0)
• fill: fill style
• stroke: stroke style

TextBox

A text box that holds text with customizable size, font style, margins, and rotation. You can define margins (padding around the text), and enable auto_fit to automatically resize the box based on the text's length. If auto_fit is set to True, the width and height of the text box will be adjusted to accommodate the text content.

TextBbox(
    x=23, y=4,          # top-left angle (cm)
    width=12, height=2, # sizes (cm)
    text="Hello!",      # text content (new lines also possible)
    angle=45,           # optional rotation angle (degrees)
    auto_fit=False,     # fit sizes by the text content
    style=...,          # optional FontStyle
    formatting=...,     # optional FontFormat
    margin=...,         # optional Margin
    fill=...,           # optional FillStyle
    stroke=...          # optional StrokeStyle
)

Parameters

• x, y: coordinates defining the top-left corner (cm)
• width, height: the width and height of the text box
• text: the text content of the box
• angle: the rotation angle of the text box in degrees (default is 0)
• auto_fit: boolean that, when set to True, automatically adjusts the size of the text box to fit its
• style: style of the font (font size, color, etc.)
• formatting: formatting of the content (bold, italic, underline, ...)
• margin: (left, top, right, bottom) margins that define the inner spacing of the text box
• fill: fill style
• stroke: stroke style

Group

A group allows you to combine multiple shapes into one unit. This is useful for creating complex compositions of shapes that should be manipulated together.

Group(shapes=[
    Ellipse(...),
    Rectangle(...),
    ...
])

Parameters

• shapes: a list of Shape objects that you want to group together.

Style and formatting classes

The library provides several classes to define the style and formatting of shapes. These classes help customize the appearance of shapes, including their colors, borders, text styling, and margins.

FillStyle

Defines the fill color and opacity for a shape. The FillStyle class allows you to control the internal color of shapes like rectangles, ellipses, and more.

FillStyle(
    color="#7699d4", # hex, rgb or named color
    opacity=1
)

StrokeStyle

Defines the stroke (outline) of a shape, including its color, thickness, opacity, and line style. Use this class to customize the borders of shapes such as lines, rectangles, and ellipses.

StrokeStyle(
    color="#7699d4", # hex, rgb or named color
    thickness=1,     # width in pt
    opacity=1,
    dash="solid"
)

FontStyle

Defines the font style for text shape (TextBox). This includes font size, color, and alignments.

FontStyle(
    size=14,
    color="#000000",
    align="center",
    vertical_align="center"
)

FontFormat

Defines additional text formatting options for font styling. You can use this class to apply bold, italic, underline, or strike-through to text.

FontFormat(
    bold=False,
    italic=False,
    underline=False,
    strike=False
)

Margin

Defines the margins inside a TextBox. These margins control the inner spacing around the text content.

Margin(
    left=0.25,
    right=0.25,
    top=0.1,
    bottom=0.1
)

These formatting classes allow you to fine-tune the appearance of shapes and text on your slides. You can apply custom fills, strokes, fonts, and margins to make the presentation visually appealing and precise.

License

Licensed under the MIT License. Feel free to use it in your projects.

Contributing

Pull requests, issues, and feature ideas are very welcome!