newsworthy-slides 1.6.0

Generate PPTX slides and presentations from HTML markup.

Installing

pip install newsworthy_slides

Using

This library has one main function: slides_from_xml() which lets you generate and slides from a custom HTML structure (described below).

Basic usage:

from newsworthy_slides import slides_from_xml

slides_xml = """
<slide layout="Title and content">
  <placeholder type="text">
    Hello world!
  </placeholder>
</slide>
"""

# Generate to new, empty presentation
pres = slides_from_xml(slides_xml)

# Generate to existing presentation
pres = slides_from_xml(slides_xml, "path/to/my_base_slides.pptx")

# pres is an instance of pptx.Presentation and can be saved easily:
pres.save('my_presentation.pptx')

The XML structure

Slides

A slide must always have a layout attribute referring to the name of a slide layout.

<slide layout="Title and content">
</slide>

A slide may have position attribute which defines where in the presentation the slide is to be added.

A slide consists of a number of placeholders.

<slide layout="Title and content">
  <placeholder type="text">
    Hello world!
  </placeholder>
</slide>

Each placeholder must have a type attribute, which can be either text, image, table. The type attribute defines how the content of the tag is to be interpreted.

The placeholders may also have a name attribute. This attribute should refer to a placeholder name in the slide layout.

<slide layout="Title and content">
  <placeholder type="text" name="Text Placeholder 1">Hello</placeholder>
  <placeholder type="text" name="Text Placeholder 2">World!</placeholder>
</slide>

If no placeholder name is defined the placeholders will be positioned in order.

<slide layout="Title and content">
  <placeholder type="text">First placeholder</placeholder>
  <placeholder type="text">Second placeholder</placeholder>
</slide>

The different placeholders types are defined below.

Text placeholders

Text placeholders may contain plain text or basic html. <p> and <li> tags are interpreted as paragraphs.

<placeholder type="text">
  Hello world!
</placeholder>

<placeholder type="text">
  <p>Hello Earth!</p>
  <p>Hello Mars!</p>
</placeholder>

<placeholder type="text" auto-size="text-to-fit-shape">
  <li>Hello Earth!</li>
  <li>Hello Mars!</li>
  <li>Hello Jupiter!</li>
  <li>Hello Saturn!</li>
  <li>Hello Uranus!</li>
</placeholder>

<strong>, <i>/<em> and <a> tags may be used for inline formating and linking.

The auto-size attribute may be set to autosize either the text (text-to-fit-shape) or the shape (shape-to-fit-text).

<placeholder type="text">
  Hello <strong>world</strong>. Considering a <a href="http://outer.space">Mars</a>?
</placeholder>

Image placeholders

An image placeholder recognizes <img> tags and picks up the path (or url) to the image from the src attribute.

<placeholder type="image" vertical-alignment="top>
  <img src="path/to/image.png">
</placeholder>

Use attributes vertical-alignment (or va) and horizontal-alignment (or ha) for positioning.

Note that the placeholder explicitly has to be either a picture or an object placeholder. This has to be set manually in Powerpoint. At the moment of writing Google Slides does not support picture placeholders (neither does Libre Office).

Table placeholders

A table placeholder should contain an html table. All <tr> tags are parsed as rows. <td> and <th> tags are parsed as cells. The cells may contain same basic text formatting as paragraphs (<strong> for bold, <i> for italic etc).

Cells with class="value" are interpreted as numbers and right-aligned.

<thead> and <tbody> may be present, but does not bring any meaning. <caption> is _not_ parsed.

<placeholder type="table">
  <table>
      <tr>
        <td>Country</td>
        <td>Happiness</td>
      </tr>
      <tr>
        <td>Finland</td>
        <td class="value">9.5</td>
      </tr>
      <tr>
        <td>Sweden</td>
        <td class="value">8.5</td>
      </tr>
  </table>
</placeholder>

Notes

A slide may contain <notes> tag containing slide notes. The content will be parsed as text just as regular text placeholders.

<notes>
  <li>Here is an important thing to keep in mind!</<li>
</notes>

Presentation metadata

Presentation level metadata such as title, author and comments may be defined as attributes of a <presentation> tag. Available properties equals the core properties of the pptx library.

<presentation title="My Report" author="John Smith" created="2020-01-01">
</presentation>

Developing

To run tests:

python3 -m pytest test

Deployment

To deploy a new version to PyPi:

1. Update Changelog below.

2. Update version.py

3. Build: python3 setup.py sdist bdist_wheel

4. Upload: python3 -m twine upload dist/newsworthy_slides-X.Y.X*

…assuming you have Twine installed (pip install twine) and configured.

Changelog

• 1.6.0

  • New feature: Notes

• 1.5.0

  • Enable alignment of images.

• 1.4.0

  • Enable autosizing of text.

• 1.3.0

  • Enable insertion of image to general purpose object placeholders.

• 1.2.0

  • Adds ability to parse presentation level metadata.

• 1.1.1

  • Bug fix: Handle negative rotation.

• 1.1.0

  • Makes it possible to rotate images.

• 1.0.2

  • Fixes ordering bug in table

• 1.0.1

  • Add custom exception if image is missing

• 1.0.0

  • First version