Commit 5a3d837
committed
feat: Slide / Master / Layout headers-footers public API (Phase 2)
Public Python API for the headers/footers/slide-numbers/dates epic (#20).
Phase 2 lands the user-facing surface on top of the Phase 1 (PR #48)
OOXML primitives. Phase 3 adds Field-based date auto-update; Phase 5
adds the HandoutMaster Python class and watermark helper.
Changes:
- pptx.slide._HeaderFooterVisibility (NEW) — mixin providing the four
`show_*` properties (show_slide_number, show_footer, show_date,
show_header) for any template element that carries a `<p:hf>` child.
Inherited by SlideLayout, SlideMaster, and NotesMaster. Getter
semantics: `<p:hf>` absent → True (PowerPoint default); present →
the effective attribute value (each defaults to True per Phase 1's
OptionalAttribute(default=True)). Setter semantics: assigning True
when `<p:hf>` is absent is a no-op (default-True needs no element);
assigning False creates `<p:hf>` via the Phase 1 ZeroOrOne accessor
(`get_or_add_hf`) and writes the attribute as "0". An existing
`<p:hf>` element is retained when all attrs become True — avoiding
low-value XML churn on toggle-back-on.
- pptx.slide.Slide — gains `has_footer`, `footer` (str | None, with
setter), `has_slide_number` (read-only — auto-filled by PowerPoint),
`has_date`, and `date_text` (str | None, with setter, Fixed-mode only;
`<a:fld>` auto-update remains Phase 3 scope). Two private helpers
centralize the placeholder iteration: `_first_ph_of_type` walks the
slide's own placeholders, `_layout_ph_of_type` walks the layout's
placeholders for the clone-on-first-write path. Both return the first
match in document order. Text getters call `text_frame.text` on the
matched placeholder; text setters clone the layout placeholder via
`self.shapes.clone_placeholder` when the slide has no matching
placeholder yet, mirroring how PowerPoint promotes a layout-level
placeholder to slide-level on first edit. Setting None or "" clears
the text but does not remove the placeholder shape. Setting a
non-empty string when the layout itself has no FOOTER (or DATE)
placeholder raises ValueError with a precise message.
Design notes:
- The mixin lives in pptx.slide (not a separate module) because its
three users all live there and the API surface is small. The
`_element` annotation on the mixin is a union of the three concrete
template element types, gated by a TYPE_CHECKING import so runtime
attribute access works on whichever element type the concrete class
carries.
- Slide accessors lean on `placeholder_format.type` for type discovery
rather than poking `element.ph_type`, matching the established
`NotesSlide.notes_placeholder` style in this same file. The lookup
helpers return `None` rather than raising so callers can use them
as `is None` guards.
- The footer/date setters intentionally do NOT remove the placeholder
on clear. Removing a shape just because its text is empty would be
surprising and would also strip layout-derived formatting; clearing
text matches what PowerPoint does when the user backspaces footer
content.
Test counts:
- tests/test_slide.py: +41 new test methods covering all 38 ISCs in
the working ISA (12 template `show_*` getter/setter cases across
SlideLayout / SlideMaster / NotesMaster; Slide.footer/has_footer
with cloning, idempotent rewrite, clear-on-None, ValueError on no
layout placeholder; Slide.has_slide_number; Slide.has_date and
date_text with the parallel set; helper coverage for first-match
document-order semantics).
- pytest: 3598 passed (3514 baseline + 84 new — includes pytest
parameterizations counted by collection rather than by `def`),
0 failed. Wall clock 5.11s.
- ruff check: All checks passed. ruff format: 216 files already
formatted (no diff).
- behave: 1048 scenarios passed, 0 failed (zero regression vs Phase 1
baseline).
- uat/uat_headers_footers_phase2.py: PASS — toggles
`layout.show_footer = False` on Layout 0 of test.pptx, sets
`slide.footer = "Phase 2 round-trip"` on Slide 0, saves, reopens,
and asserts both round-trip.
Refs #20.
Builds on Phase 1 (PR #48 / commit 0223199).1 parent 4daba7e commit 5a3d837
2 files changed
Lines changed: 662 additions & 5 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
24 | 24 | | |
25 | 25 | | |
26 | 26 | | |
| 27 | + | |
27 | 28 | | |
28 | 29 | | |
| 30 | + | |
29 | 31 | | |
30 | 32 | | |
31 | 33 | | |
32 | 34 | | |
33 | 35 | | |
34 | 36 | | |
35 | | - | |
| 37 | + | |
36 | 38 | | |
37 | 39 | | |
38 | 40 | | |
| |||
92 | 94 | | |
93 | 95 | | |
94 | 96 | | |
95 | | - | |
| 97 | + | |
| 98 | + | |
| 99 | + | |
| 100 | + | |
| 101 | + | |
| 102 | + | |
| 103 | + | |
| 104 | + | |
| 105 | + | |
| 106 | + | |
| 107 | + | |
| 108 | + | |
| 109 | + | |
| 110 | + | |
| 111 | + | |
| 112 | + | |
| 113 | + | |
| 114 | + | |
| 115 | + | |
| 116 | + | |
| 117 | + | |
| 118 | + | |
| 119 | + | |
| 120 | + | |
| 121 | + | |
| 122 | + | |
| 123 | + | |
| 124 | + | |
| 125 | + | |
| 126 | + | |
| 127 | + | |
| 128 | + | |
| 129 | + | |
| 130 | + | |
| 131 | + | |
| 132 | + | |
| 133 | + | |
| 134 | + | |
| 135 | + | |
| 136 | + | |
| 137 | + | |
| 138 | + | |
| 139 | + | |
| 140 | + | |
| 141 | + | |
| 142 | + | |
| 143 | + | |
| 144 | + | |
| 145 | + | |
| 146 | + | |
| 147 | + | |
| 148 | + | |
| 149 | + | |
| 150 | + | |
| 151 | + | |
| 152 | + | |
| 153 | + | |
| 154 | + | |
| 155 | + | |
| 156 | + | |
| 157 | + | |
| 158 | + | |
| 159 | + | |
| 160 | + | |
| 161 | + | |
| 162 | + | |
| 163 | + | |
| 164 | + | |
| 165 | + | |
| 166 | + | |
| 167 | + | |
| 168 | + | |
| 169 | + | |
| 170 | + | |
| 171 | + | |
| 172 | + | |
| 173 | + | |
| 174 | + | |
96 | 175 | | |
97 | 176 | | |
98 | 177 | | |
| |||
214 | 293 | | |
215 | 294 | | |
216 | 295 | | |
| 296 | + | |
| 297 | + | |
| 298 | + | |
| 299 | + | |
| 300 | + | |
| 301 | + | |
| 302 | + | |
| 303 | + | |
| 304 | + | |
| 305 | + | |
| 306 | + | |
| 307 | + | |
| 308 | + | |
| 309 | + | |
| 310 | + | |
| 311 | + | |
| 312 | + | |
| 313 | + | |
| 314 | + | |
| 315 | + | |
| 316 | + | |
| 317 | + | |
| 318 | + | |
| 319 | + | |
| 320 | + | |
| 321 | + | |
| 322 | + | |
217 | 323 | | |
218 | 324 | | |
219 | 325 | | |
| |||
223 | 329 | | |
224 | 330 | | |
225 | 331 | | |
| 332 | + | |
| 333 | + | |
| 334 | + | |
| 335 | + | |
| 336 | + | |
| 337 | + | |
| 338 | + | |
| 339 | + | |
| 340 | + | |
| 341 | + | |
| 342 | + | |
| 343 | + | |
| 344 | + | |
| 345 | + | |
| 346 | + | |
| 347 | + | |
| 348 | + | |
| 349 | + | |
| 350 | + | |
| 351 | + | |
| 352 | + | |
| 353 | + | |
| 354 | + | |
| 355 | + | |
| 356 | + | |
| 357 | + | |
| 358 | + | |
| 359 | + | |
| 360 | + | |
| 361 | + | |
| 362 | + | |
| 363 | + | |
| 364 | + | |
| 365 | + | |
| 366 | + | |
| 367 | + | |
| 368 | + | |
| 369 | + | |
| 370 | + | |
| 371 | + | |
| 372 | + | |
| 373 | + | |
| 374 | + | |
| 375 | + | |
| 376 | + | |
| 377 | + | |
| 378 | + | |
| 379 | + | |
| 380 | + | |
| 381 | + | |
| 382 | + | |
| 383 | + | |
| 384 | + | |
| 385 | + | |
226 | 386 | | |
227 | 387 | | |
228 | 388 | | |
| |||
247 | 407 | | |
248 | 408 | | |
249 | 409 | | |
| 410 | + | |
| 411 | + | |
| 412 | + | |
| 413 | + | |
| 414 | + | |
| 415 | + | |
| 416 | + | |
| 417 | + | |
| 418 | + | |
| 419 | + | |
| 420 | + | |
| 421 | + | |
| 422 | + | |
| 423 | + | |
| 424 | + | |
| 425 | + | |
| 426 | + | |
| 427 | + | |
| 428 | + | |
| 429 | + | |
| 430 | + | |
| 431 | + | |
250 | 432 | | |
251 | 433 | | |
252 | 434 | | |
| |||
426 | 608 | | |
427 | 609 | | |
428 | 610 | | |
429 | | - | |
| 611 | + | |
430 | 612 | | |
431 | 613 | | |
432 | 614 | | |
| |||
544 | 726 | | |
545 | 727 | | |
546 | 728 | | |
547 | | - | |
| 729 | + | |
548 | 730 | | |
549 | 731 | | |
550 | 732 | | |
| |||
0 commit comments