A while back I experimented with executing user-provided Python. It seemed a small step at the time, but I had a hunch it would turn out to be a much bigger thing.
Coding it was straightforward but two things delayed releasing it:
- Documentation is tricky.
- The python-pptx API is (necessarily) not for the faint of heart.
But why bother in the first place?
While it is possible to inject any Python code you like that isn’t really the point. There are things I want in presentations that can’t be expressed with Markdown. Here are two examples:
- Graphs
- Table cell fine tuning
Actually the latter can be done with <span> elements and CSS – but it’s not as flexible as I’d like.
So, if I could expose what Python-pptx is capable of, I could make the run-Python support useful.
So that’s what I set out to do.
How To Invoke The New Function
This is actually pretty straightforward. Here is a simple sample of a slide with a bullet point and a trivial piece of Python.
### My Slide Title
* A bullet point
``` run-python
print("Hello world")
```
This code doesn’t do anything useful. But it makes the point you can embed arbitrary Python code. The real challenge was to teach my code to do something useful.
Making Inline Python Easier To Use
I’ve already mentioned it’s not that easy to drive python-pptx so I thought about how to make it easier. I wrote some helper functions, focused on things hard to express in Markdown which might actually be useful extensions.
I haven’t done any research on what people need; The helper functions just do things that patently made my programming life easier.
I’ve also ensured that useful things are exposed. Two examples of exposed objects are:
- The current slide
- The rendering rectangle you can use
I expect many use cases revolve around the slide md2pptx is currently creating. Further, it’s useful to tell the user code a safe area to render into.
My initial expected use cases are twofold:
- Adding content to a slide. Initially I worked on this for graphing. And this is where the rendering rectangle idea came from. Of course, you could render outside of this rectangle but you might collide with other shapes on the slide.
- Modifying content to a slide. A good example of this might be to filter cells in an existing table.
Both of these examples – graphing and table filtering – caused me to create a helper routine to read an external CSV file into an array:
- You could run md2pptx every day against the latest version of a CSV file and create the same graphs from it, just with fresh data.
- You could populate a fresh set of tables every day, perhaps turning some rows red – depending on the data.
So this was what I initially released.
Further Developments
Since the initial release I’ve done a number of things, most notably:
- Added support for checklists and refined it somewhat. So you can – from a CSV file – create a checklist with (optionally coloured) ticks and crosses.
- Selective bullet removal – as a sort of between-bullets paragraph function.
- Tweaked graphing to make it more useful.
- Added a helper routine for drawing arbitrary PowerPoint shapes.
These might be small things but they do illustrate one point: Version 5 is proving to be a great testbed for experimenting with python-pptx capabilities – and some of these did indeed get “shrink wrapped”.
Documentation
For me documentation isn’t that much fun to write. But it has to be done.
It’s the one thing that delays me releasing new levels of md2pptx most of all.
However, there is a brand new section towards the end of the User Guide – with the function descriptions and some examples.
Wrap Up – With An Important Caveat
My companion app mdpre might be useful here. A couple of examples illustrate why:
- You could include code inline with
=include. - You could include data inline with
=include, too.
In fact I have been doing this for years – to pull in presentation fragments.
A word of warning: Because you can execute arbitrary Python code you need to be careful about where it came from.
Certainly – because it’s open source – you can inspect my helper routines – in runPython.py. And you might well create your own analogue.
Philosophically you might consider md2pptx is a long way from turning Markdown to slides. I’d say it’s still that. But, more generally, it’s turning textual data into slides.
It just got a lot more flexible and powerful in Version 5. And 5.2.2 is out, with more helper functions. I can’t say I’ll add more functions – or what they’ll be – but I probably will; This experiment got fun and surprisingly useful.
I’ll also say my checklist function is in use “in Production”: When I create the stub presentation files (Markdown, naturally) I now create a tracking presentation. It includes a CSV file that contains the checklist data. It’s easy to tick the database builds and presentations off as they get done. It’s a nice way of showing professionalism at the beginning of the workshop – or indeed leading up to it.
Making Of
I originally wrote this post when I had just released Version 5. I’m completing it on a flight to New York, to begin a visit to IBM Poughkeepsie. This actually allowed me to talk about the things that have happened to md2pptx since Version 5 debuted – which is quite a lot. And to show I really am taking the opportunity to experiment – now that I can.
11 Months On
That flight in January seems like a long time ago; It’s been a busy year – what with the z17 launch and a heavy caseload.
But md2pptx did roll on. Within Version 5 , for instance, the “checklist” function got enhanced with custom graphics – which permitted additional checklist item states (to look reasonable).
And Version 6 has been out for a while, with several tweaks within that version. I suppose I should write about it…
Mainframe, Performance, Topics 