Skip to content

Commit

Permalink
v5.4 3 exit routine points
Browse files Browse the repository at this point in the history
  • Loading branch information
@MartinPacker
MartinPacker committed Feb 23, 2025
1 parent 3f3a2de commit f6fc910
Show file tree
Hide file tree
Showing 5 changed files with 192 additions and 16 deletions.
51 changes: 46 additions & 5 deletions docs/user-guide.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1313,6 +1313,12 @@ <h3 id="table-of-contents">Table Of Contents<a class="headerlink" href="#table-o
</ul>
</li>
<li><a href="#slide-transitions-transition">Slide Transitions - <code>Transition</code></a></li>
<li><a href="#python-exit-routines">Python Exit Routines</a><ul>
<li><a href="#after-loading-onpresentationinitialisation">After Loading - <code>onPresentationInitialisation</code></a></li>
<li><a href="#before-saving-onpresentationbeforesave">Before Saving - <code>onPresentationBeforeSave</code></a></li>
<li><a href="#after-saving-onpresentationaftersave">After Saving - <code>onPresentationAfterSave</code></a></li>
</ul>
</li>
</ul>
</li>
<li><a href="#dynamic-metadata">Dynamic Metadata</a><ul>
Expand Down Expand Up @@ -1644,9 +1650,9 @@ <h2 id="change-log">Change Log<a class="headerlink" href="#change-log" title="Pe
</thead>
<tbody>
<tr>
<td align="left">5.3.1+</td>
<td align="right">22&nbsp;February&nbsp;2025</td>
<td align="left">Added the ability to run Python code from named files in <a href="#running-inline-python"><code>run-python</code></a>.</td>
<td align="left">5.4</td>
<td align="right">23&nbsp;February&nbsp;2025</td>
<td align="left">Added the ability to run Python code from named files in <a href="#running-inline-python"><code>run-python</code></a>. Added <a href="#python-exit-routines">3 exit routine points</a> where user Python code can run.</td>
</tr>
<tr>
<td align="left">5.3.1</td>
Expand Down Expand Up @@ -4353,6 +4359,40 @@ <h4 id="slide-transitions-transition">Slide Transitions - <code>Transition</code
</ul>
<p>The default is <code>no</code> - which prevents slide transition effects being generated.</p>
<p>You can override this value with <a href="#transition-dynamic">Dynamic Metadata</a>.</p>
<p><a id="python-exit-routines"></a></p>
<h4 id="python-exit-routines">Python Exit Routines<a class="headerlink" href="#python-exit-routines" title="Permanent link"></a></h4>
<p>With md2pptx you can specify python &ldquo;exit routines&rdquo; - files containing python code.</p>
<p>These routines run</p>
<ul>
<li><a href="#after-loading-onpresentationinitialisation">When any template presentation has been loaded</a>, or even if none has been specified.</li>
<li><a href="#before-saving-onpresentationbeforesave">Just before the presentation is saved</a>.</li>
<li><a href="#after-saving-onpresentationaftersave">Just after the presentation is saved</a>.</li>
</ul>
<p>Each routine has access to the python-pptx <a href="https://python-pptx.readthedocs.io/en/latest/api/presentation.html#presentation-objects">Presentation</a> object - in variable <code>prs</code>.</p>
<p>Before writing or using exit routines others have supplied see <a href="#an-important-caution">An Important Caution</a>.</p>
<p><strong>Note:</strong> You can run python within an individual slide&rsquo;s processing.
See <a href="#running-inline-python">Running Inline Python</a>.</p>
<p><a id="after-loading-onpresentationinitialisation"></a></p>
<h5 id="after-loading-onpresentationinitialisation">After Loading - <code>onPresentationInitialisation</code><a class="headerlink" href="#after-loading-onpresentationinitialisation" title="Permanent link"></a></h5>
<p>With suitable code at this exit point you could adjust the presentation&rsquo;s properties.
For example</p>
<pre><code>from pptx.util import Inches

prs.slide_height = Inches(10.0)
</code></pre>
<p>This would, obviously set the height of each slide to 10 inches.</p>
<p><a id="before-saving-onpresentationbeforesave"></a></p>
<h5 id="before-saving-onpresentationbeforesave">Before Saving - <code>onPresentationBeforeSave</code><a class="headerlink" href="#before-saving-onpresentationbeforesave" title="Permanent link"></a></h5>
<p>Again, this exit point could allow you to adjust properties of the presentation.
This is the last opportunity before the presentation is saved.</p>
<p><a id="after-saving-onpresentationaftersave"></a></p>
<h5 id="after-saving-onpresentationaftersave">After Saving - <code>onPresentationAfterSave</code><a class="headerlink" href="#after-saving-onpresentationaftersave" title="Permanent link"></a></h5>
<p>When this code runs the <code>prs</code> variable is still available.
You might use this exit point to save an adjusted copy of the presentation.
For example</p>
<pre><code>prs.save("Mycopy.pptx")
</code></pre>
<p>Or you might want to run some analysis on the presentation you&rsquo;ve just created.</p>
<p><a id="dynamic-metadata"></a></p>
<h3 id="dynamic-metadata">Dynamic Metadata<a class="headerlink" href="#dynamic-metadata" title="Permanent link"></a></h3>
<p>md2pptx can alter some in-effect settings, starting at a particular slide. Straight after the heading code a special form of (HTML) comment like so:</p>
Expand Down Expand Up @@ -4738,14 +4778,15 @@ <h2 id="running-inline-python">Running Inline Python<a class="headerlink" href="
<p><a id="an-important-caution"></a></p>
<h3 id="an-important-caution">An Important Caution<a class="headerlink" href="#an-important-caution" title="Permanent link"></a></h3>
<p>The support described in <a href="#running-inline-python">Running Inline Python</a> allows you to run <strong>arbitary python code</strong>. It would be unwise to embed python code of unknown provenance.
Use only code you directly write (or, of known provenance, embedded with <a href="https://github.com/MartinPacker/mdpre">mdpre</a>&lsquo;s <code>=include</code> capability or as an optional parameter to the invocation).</p>
Use only code you directly write (or, of known provenance, embedded with <a href="https://github.com/MartinPacker/mdpre">mdpre</a>&lsquo;s <code>=include</code> capability, or as an optional parameter to the invocation).</p>
<p>In general, though, this function is worth exploring - if it enables you turn flat files into presentations that you otherwise couldn&rsquo;t make that way.</p>
<p><a id="how-to-invoke-python-in-md2pptx"></a></p>
<h3 id="how-to-invoke-python-in-md2pptx">How To Invoke Python In md2pptx<a class="headerlink" href="#how-to-invoke-python-in-md2pptx" title="Permanent link"></a></h3>
<p>There are two ways you can invoke Python in md2pptx:</p>
<p>There are three ways you can invoke Python in md2pptx:</p>
<ul>
<li><a href="#coding-inline-python">Coding Inline Python</a></li>
<li><a href="#importing-python-from-a-file">Importing Python From A File</a></li>
<li><a href="#python-exit-routines">Python Exit Routines</a></li>
</ul>
<p><strong>Note:</strong> You can invoke Python in a file from inline python.</p>
<p><a id="coding-inline-python"></a></p>
Expand Down
8 changes: 6 additions & 2 deletions docs/user-guide.log
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,8 +5,8 @@ mdpre Markdown Preprocessor v0.6.9 (17 September, 2024)
Def mdpre_date = 17 September, 2024
Def mdpre_level = 0.6.9
Def userid = martinpacker
Def time = 17&colon;26
Def date = 22 February&comma; 2025
Def time = 16&colon;09
Def date = 23 February&comma; 2025
Def TOC = Table Of Contents
Def md = Markdown
Def pp = Powerpoint
Expand Down Expand Up @@ -192,6 +192,10 @@ CSV Stop
..... ..... ..... ..... Section Navigation Button Colour - `SectionArrowsColour`
..... ..... ..... ..... Make Expandable Sections - `SectionsExpand`
..... ..... ..... Slide Transitions - `Transition`
..... ..... ..... Python Exit Routines
..... ..... ..... ..... After Loading - `onPresentationInitialisation`
..... ..... ..... ..... Before Saving - `onPresentationBeforeSave`
..... ..... ..... ..... After Saving - `onPresentationAfterSave`
..... ..... Dynamic Metadata
..... ..... ..... `hidden`
..... ..... ..... Tables
Expand Down
58 changes: 55 additions & 3 deletions docs/user-guide.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -180,6 +180,10 @@ As you can see in the [change log](#change-log), md2pptx is frequently updated -
* [Section Navigation Button Colour - `SectionArrowsColour`](#section-navigation-button-colour-sectionarrowscolour)
* [Make Expandable Sections - `SectionsExpand`](#make-expandable-sections-sectionsexpand)
* [Slide Transitions - `Transition`](#slide-transitions-transition)
* [Python Exit Routines](#python-exit-routines)
* [After Loading - `onPresentationInitialisation`](#after-loading-onpresentationinitialisation)
* [Before Saving - `onPresentationBeforeSave`](#before-saving-onpresentationbeforesave)
* [After Saving - `onPresentationAfterSave`](#after-saving-onpresentationaftersave)
* [Dynamic Metadata](#dynamic-metadata)
* [`hidden`](#hidden)
* [Tables](#tables)
Expand Down Expand Up @@ -445,7 +449,7 @@ To quote from the python-pptx license statement:

|Level|Date|What|
|:-|-:|:-|
|5.3.1+|22&nbsp;February&nbsp;2025|Added the ability to run Python code from named files in [`run-python`](#running-inline-python).|
|5.4|23&nbsp;February&nbsp;2025|Added the ability to run Python code from named files in [`run-python`](#running-inline-python). Added [3 exit routine points](#python-exit-routines) where user Python code can run.|
|5.3.1|16&nbsp;February&nbsp;2025|Added a double-headed arrow&comma; an oval&comma; double lines&comma; and line widths to [Annotations](#annotations-related-helper-routines). Added optional drop shadows for tables with [`tableShadow`](#controlling-whether-tables-have-drop-shadows-tableshadow).|
|5.3|11&nbsp;February&nbsp;2025|Added [Annotations](#annotations-related-helper-routines) to [`run-python`](#running-inline-python).|
|5.2.2|31&nbsp;December&nbsp;2024|[Checklist](#checklist-related-helper-routines) items can be richer&comma; for example using `<span>` elements.|
Expand Down Expand Up @@ -3237,6 +3241,53 @@ The default is `no` - which prevents slide transition effects being generated.

You can override this value with [Dynamic Metadata](#transition-dynamic).

<a id="python-exit-routines"></a>
#### Python Exit Routines

With md2pptx you can specify python "exit routines" - files containing python code.

These routines run

* [When any template presentation has been loaded](#after-loading-onpresentationinitialisation), or even if none has been specified.
* [Just before the presentation is saved](#before-saving-onpresentationbeforesave).
* [Just after the presentation is saved](#after-saving-onpresentationaftersave).

Each routine has access to the python-pptx [Presentation](https://python-pptx.readthedocs.io/en/latest/api/presentation.html#presentation-objects) object - in variable `prs`.

Before writing or using exit routines others have supplied see [An Important Caution](#an-important-caution).

**Note:** You can run python within an individual slide's processing.
See [Running Inline Python](#running-inline-python).

<a id="after-loading-onpresentationinitialisation"></a>
##### After Loading - `onPresentationInitialisation`

With suitable code at this exit point you could adjust the presentation's properties.
For example

from pptx.util import Inches

prs.slide_height = Inches(10.0)

This would, obviously set the height of each slide to 10 inches.

<a id="before-saving-onpresentationbeforesave"></a>
##### Before Saving - `onPresentationBeforeSave`

Again, this exit point could allow you to adjust properties of the presentation.
This is the last opportunity before the presentation is saved.

<a id="after-saving-onpresentationaftersave"></a>
##### After Saving - `onPresentationAfterSave`

When this code runs the `prs` variable is still available.
You might use this exit point to save an adjusted copy of the presentation.
For example

prs.save("Mycopy.pptx")

Or you might want to run some analysis on the presentation you've just created.

<a id="dynamic-metadata"></a>
### Dynamic Metadata

Expand Down Expand Up @@ -3710,17 +3761,18 @@ For more information see [ContentSplit](#split-proportions-contentsplit).
### An Important Caution

The support described in [Running Inline Python](#running-inline-python) allows you to run **arbitary python code**. It would be unwise to embed python code of unknown provenance.
Use only code you directly write (or, of known provenance, embedded with [mdpre](https://github.com/MartinPacker/mdpre)'s `=include` capability or as an optional parameter to the invocation).
Use only code you directly write (or, of known provenance, embedded with [mdpre](https://github.com/MartinPacker/mdpre)'s `=include` capability, or as an optional parameter to the invocation).

In general, though, this function is worth exploring - if it enables you turn flat files into presentations that you otherwise couldn't make that way.

<a id="how-to-invoke-python-in-md2pptx"></a>
### How To Invoke Python In md2pptx

There are two ways you can invoke Python in md2pptx:
There are three ways you can invoke Python in md2pptx:

* [Coding Inline Python](#coding-inline-python)
* [Importing Python From A File](#importing-python-from-a-file)
* [Python Exit Routines](#python-exit-routines)

**Note:** You can invoke Python in a file from inline python.

Expand Down
54 changes: 51 additions & 3 deletions docs/user-guide.mdp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -162,7 +162,7 @@ To quote from the python-pptx license statement:
=colalign l r l
=csv
Level,Date,What
5.3.1+,22&nbsp;February&nbsp;2025,Added the ability to run Python code from named files in [`run-python`](#running-inline-python).
5.4,23&nbsp;February&nbsp;2025,Added the ability to run Python code from named files in [`run-python`](#running-inline-python). Added [3 exit routine points](#python-exit-routines) where user Python code can run.
5.3.1,16&nbsp;February&nbsp;2025,Added a double-headed arrow&comma; an oval&comma; double lines&comma; and line widths to [Annotations](#annotations-related-helper-routines). Added optional drop shadows for tables with [`tableShadow`](#controlling-whether-tables-have-drop-shadows-tableshadow).
5.3,11&nbsp;February&nbsp;2025,Added [Annotations](#annotations-related-helper-routines) to [`run-python`](#running-inline-python).
5.2.2,31&nbsp;December&nbsp;2024,[Checklist](#checklist-related-helper-routines) items can be richer&comma; for example using `<span>` elements.
Expand Down Expand Up @@ -3267,6 +3267,53 @@ The default is `no` - which prevents slide transition effects being generated.

You can override this value with [Dynamic Metadata](#transition-dynamic).

<a id="python-exit-routines"></a>
#### Python Exit Routines

With md2pptx you can specify python "exit routines" - files containing python code.

These routines run

* [When any template presentation has been loaded](#after-loading-onpresentationinitialisation), or even if none has been specified.
* [Just before the presentation is saved](#before-saving-onpresentationbeforesave).
* [Just after the presentation is saved](#after-saving-onpresentationaftersave).

Each routine has access to the python-pptx [Presentation](https://python-pptx.readthedocs.io/en/latest/api/presentation.html#presentation-objects) object - in variable `prs`.

Before writing or using exit routines others have supplied see [An Important Caution](#an-important-caution).

**Note:** You can run python within an individual slide's processing.
See [Running Inline Python](#running-inline-python).

<a id="after-loading-onpresentationinitialisation"></a>
##### After Loading - `onPresentationInitialisation`

With suitable code at this exit point you could adjust the presentation's properties.
For example

from pptx.util import Inches

prs.slide_height = Inches(10.0)

This would, obviously set the height of each slide to 10 inches.

<a id="before-saving-onpresentationbeforesave"></a>
##### Before Saving - `onPresentationBeforeSave`

Again, this exit point could allow you to adjust properties of the presentation.
This is the last opportunity before the presentation is saved.

<a id="after-saving-onpresentationaftersave"></a>
##### After Saving - `onPresentationAfterSave`

When this code runs the `prs` variable is still available.
You might use this exit point to save an adjusted copy of the presentation.
For example

prs.save("Mycopy.pptx")

Or you might want to run some analysis on the presentation you've just created.

<a id="dynamic-metadata"></a>
### Dynamic Metadata

Expand Down Expand Up @@ -3770,17 +3817,18 @@ For more information see [ContentSplit](#split-proportions-contentsplit).

The support described in [Running Inline Python](#running-inline-python) allows you to run **arbitary python code**. \
It would be unwise to embed python code of unknown provenance.
Use only code you directly write (or, of known provenance, embedded with [mdpre](https://github.com/MartinPacker/mdpre)'s `=include` capability or as an optional parameter to the invocation).
Use only code you directly write (or, of known provenance, embedded with [mdpre](https://github.com/MartinPacker/mdpre)'s `=include` capability, or as an optional parameter to the invocation).

In general, though, this function is worth exploring - if it enables you turn flat files into presentations that you otherwise couldn't make that way.

<a id="how-to-invoke-python-in-md2pptx"></a>
### How To Invoke Python In md2pptx

There are two ways you can invoke Python in md2pptx:
There are three ways you can invoke Python in md2pptx:

* [Coding Inline Python](#coding-inline-python)
* [Importing Python From A File](#importing-python-from-a-file)
* [Python Exit Routines](#python-exit-routines)

**Note:** You can invoke Python in a file from inline python.

Expand Down
37 changes: 34 additions & 3 deletions md2pptx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -86,8 +86,8 @@ except:
have_graphviz = False


md2pptx_level = "5.3.1+"
md2pptx_date = "22 February, 2025"
md2pptx_level = "5.4"
md2pptx_date = "23 February, 2025"

namespaceURL = {
"mc": "http://schemas.openxmlformats.org/markup-compatibility/2006",
Expand Down Expand Up @@ -4566,6 +4566,15 @@ globals.processingOptions.setOptionValuesArray(
]
)

# "on" exit files initialisation
globals.processingOptions.setOptionValuesArray(
[
["onPresentationInitialisation", ""],
["onPresentationBeforeSave", ""],
["onPresentationAfterSave", ""],
]
)

######################################################################################
# #
# Prime for footnotes #
Expand Down Expand Up @@ -4665,7 +4674,13 @@ for line in metadata_lines:
elif name == "backgroundimage":
globals.processingOptions.setOptionValues(name, value)


elif name in [
"onpresentationinitialisation",
"onpresentationbeforesave",
"onpresentationaftersave",
]:
globals.processingOptions.setOptionValues(name, value)
print(value, "<===")

elif name in [
"sectiontitlesize",
Expand Down Expand Up @@ -5125,6 +5140,11 @@ else:
for slide in prs.slides:
slide.slideInfo = None

# Maybe call an exit as the presentation is initialised
onPresentationInitialisation = globals.processingOptions.getCurrentOption("onPresentationInitialisation")
if onPresentationInitialisation != "":
exec(open(onPresentationInitialisation).read())

# Following might be used in slide footers
prs.lastSectionTitle = ""
prs.lastSectionSlide = None
Expand Down Expand Up @@ -6315,8 +6335,19 @@ except:
if globals.processingOptions.getCurrentOption("SectionsExpand"):
createExpandingSections(prs)

# Maybe call an exit before the presentation is saved
onPresentationBeforeSave = globals.processingOptions.getCurrentOption("onPresentationBeforeSave")
if onPresentationBeforeSave != "":
exec(open(onPresentationBeforeSave).read())

prs.save(output_filename)

# Maybe call an exit after the presentation is saved
onPresentationAfterSave = globals.processingOptions.getCurrentOption("onPresentationAfterSave")
if onPresentationAfterSave != "":
exec(open(onPresentationAfterSave).read())


elapsed_time = time.time() - start_time

print(
Expand Down

0 comments on commit f6fc910

Please sign in to comment.