From 334b5b4dbe5d7b63cceaff5e8f1dc3dd796fc506 Mon Sep 17 00:00:00 2001 From: Leo Date: Fri, 30 Oct 2026 01:15:43 -0700 Subject: [PATCH] Add slide visibility control --- docs/api/slides.rst | 3 +++ docs/dev/analysis/sld-slide.rst | 9 ++++++++ features/sld-slide.feature | 15 +++++++++++++ features/steps/slide.py | 38 ++++++++++++++++++++++++++++++++- requirements-test.txt | 5 +++-- src/pptx/oxml/slide.py | 3 ++- src/pptx/slide.py | 15 +++++++++++++ tests/test_slide.py | 32 +++++++++++++++++++++++++++ 8 files changed, 116 insertions(+), 4 deletions(-) diff --git a/docs/api/slides.rst b/docs/api/slides.rst index 1909ecd08..abb7881da 100644 --- a/docs/api/slides.rst +++ b/docs/api/slides.rst @@ -22,6 +22,9 @@ is not intended to be constructed directly. An individual |Slide| object is accessed by index from |Slides| or as the return value of :meth:`add_slide`. +Use ``slide.is_hidden = True`` to skip a slide during a slide show, and +assign ``False`` to show it again. Hidden slides remain in the collection. + .. autoclass:: pptx.slide.Slide() :members: :exclude-members: part diff --git a/docs/dev/analysis/sld-slide.rst b/docs/dev/analysis/sld-slide.rst index 95fd40636..c8b751cc2 100644 --- a/docs/dev/analysis/sld-slide.rst +++ b/docs/dev/analysis/sld-slide.rst @@ -28,6 +28,15 @@ enough not to reuse the id of the last added slide when it's been deleted as there doesn't seem to be any record in the XML of the max value assigned. +Hidden slides +------------- + +``Slide.is_hidden`` is the inverse of ``p:sld@show``. The schema default +for ``show`` is true, so an absent attribute means a visible slide. +Hiding a slide sets ``show="0"``; making it visible removes the attribute. +This does not remove the slide or alter its relationships or content. + + XML specimens ------------- diff --git a/features/sld-slide.feature b/features/sld-slide.feature index 1c8f88a88..c99518298 100644 --- a/features/sld-slide.feature +++ b/features/sld-slide.feature @@ -4,6 +4,21 @@ Feature: slide properties I need properties and methods on the slide object + Scenario: Slide.is_hidden defaults to False + Given a slide + Then slide.is_hidden is False + + Scenario: Hide and unhide a slide + Given a new presentation with a titled slide + When I set slide.is_hidden to True + And I save and reopen the presentation + Then slide.is_hidden is True + And the slide content and id are unchanged + When I set slide.is_hidden to False + And I save and reopen the presentation + Then slide.is_hidden is False + And the slide content and id are unchanged + Scenario Outline: Slide.background Given a Slide object having background as slide Then slide.background is a _Background object diff --git a/features/steps/slide.py b/features/steps/slide.py index a7527f36d..2ec149e35 100644 --- a/features/steps/slide.py +++ b/features/steps/slide.py @@ -2,7 +2,9 @@ from __future__ import annotations -from behave import given, then +import io + +from behave import given, then, when from helpers import test_pptx from pptx import Presentation @@ -28,6 +30,14 @@ def given_a_slide(context): context.slide = presentation.slides[0] +@given("a new presentation with a titled slide") +def given_a_new_presentation_with_a_titled_slide(context): + context.prs = Presentation() + context.slide = context.prs.slides.add_slide(context.prs.slide_layouts[0]) + context.slide.shapes.title.text = "Hidden slide" + context.slide_id = context.slide.slide_id + + @given("a slide having a notes slide") def given_a_slide_having_a_notes_slide(context): context.slide = Presentation(test_pptx("sld-notes")).slides[0] @@ -130,6 +140,32 @@ def then_slide_in_slide_layout_used_by_slides_is_True(context): assert context.slide in context.slide_layout.used_by_slides +@when("I set slide.is_hidden to {value}") +def when_I_set_slide_is_hidden(context, value): + context.slide.is_hidden = {"True": True, "False": False}[value] + + +@when("I save and reopen the presentation") +def when_I_save_and_reopen_the_presentation(context): + stream = io.BytesIO() + context.prs.save(stream) + stream.seek(0) + context.prs = Presentation(stream) + context.slide = context.prs.slides[0] + + +@then("the slide content and id are unchanged") +def then_the_slide_content_and_id_are_unchanged(context): + assert len(context.prs.slides) == 1 + assert context.slide.slide_id == context.slide_id + assert context.slide.shapes.title.text == "Hidden slide" + + +@then("slide.is_hidden is {value}") +def then_slide_is_hidden(context, value): + assert context.slide.is_hidden is {"True": True, "False": False}[value] + + @then("slide.background is a _Background object") def then_slide_background_is_a_Background_object(context): cls_name = context.slide.background.__class__.__name__ diff --git a/requirements-test.txt b/requirements-test.txt index 9ddd60fd7..181407fad 100644 --- a/requirements-test.txt +++ b/requirements-test.txt @@ -1,7 +1,8 @@ -r requirements.txt behave>=1.2.3 -pyparsing>=2.0.1 -pytest>=2.5 +# The compact XML test grammar uses the pre-3.2 pyparsing API. +pyparsing>=2.0.1,<3.2 +pytest>=2.5,<9 pytest-coverage pytest-xdist ruff diff --git a/src/pptx/oxml/slide.py b/src/pptx/oxml/slide.py index 37a9780f6..0c7e54634 100644 --- a/src/pptx/oxml/slide.py +++ b/src/pptx/oxml/slide.py @@ -7,7 +7,7 @@ from pptx.oxml import parse_from_template, parse_xml from pptx.oxml.dml.fill import CT_GradientFillProperties from pptx.oxml.ns import nsdecls -from pptx.oxml.simpletypes import XsdString +from pptx.oxml.simpletypes import XsdBoolean, XsdString from pptx.oxml.xmlchemy import ( BaseOxmlElement, Choice, @@ -163,6 +163,7 @@ class CT_Slide(_BaseSlideElement): cSld: CT_CommonSlideData = OneAndOnlyOne("p:cSld") # pyright: ignore[reportAssignmentType] clrMapOvr = ZeroOrOne("p:clrMapOvr", successors=_tag_seq[2:]) timing = ZeroOrOne("p:timing", successors=_tag_seq[4:]) + show: bool = OptionalAttribute("show", XsdBoolean, default=True) # pyright: ignore[reportAssignmentType] del _tag_seq @classmethod diff --git a/src/pptx/slide.py b/src/pptx/slide.py index 3b1b65d8e..1407a1643 100644 --- a/src/pptx/slide.py +++ b/src/pptx/slide.py @@ -201,6 +201,21 @@ def has_notes_slide(self) -> bool: """ return self.part.has_notes_slide + @property + def is_hidden(self) -> bool: + """|True| if this slide is skipped during a slide show. + + Read/write boolean. Hiding a slide keeps it in the presentation, + with its content and position unchanged. New slides are visible. + """ + return not self._element.show + + @is_hidden.setter + def is_hidden(self, value: bool): + if not isinstance(value, bool): + raise TypeError("is_hidden must be a bool") + self._element.show = not value + @property def notes_slide(self) -> NotesSlide: """The |NotesSlide| instance for this slide. diff --git a/tests/test_slide.py b/tests/test_slide.py index 74b528c3b..79610cf1b 100644 --- a/tests/test_slide.py +++ b/tests/test_slide.py @@ -297,6 +297,38 @@ def text_frame_(self, request): class DescribeSlide(object): """Unit-test suite for `pptx.slide.Slide` objects.""" + @pytest.mark.parametrize( + ("attributes", "expected"), + [ + ("", False), + ("{show=0}", True), + ("{show=false}", True), + ("{show=1}", False), + ("{show=true}", False), + ], + ) + def it_knows_whether_it_is_hidden(self, attributes, expected): + sld = element("p:sld%s/p:cSld" % attributes) + before = sld.xml + assert Slide(sld, None).is_hidden is expected + assert sld.xml == before + + @pytest.mark.parametrize("value", [True, False]) + def it_can_change_its_hidden_state(self, value): + initial = "p:sld/p:cSld" if value else "p:sld{show=0}/p:cSld" + slide = Slide(element(initial), None) + slide.is_hidden = value + assert slide.is_hidden is value + assert slide._element.get("show") == ("0" if value else None) + + @pytest.mark.parametrize("value", [None, 0, 1, "false", []]) + def it_rejects_non_boolean_hidden_states(self, value): + slide = Slide(element("p:sld{show=0}/p:cSld"), None) + before = slide._element.xml + with pytest.raises(TypeError): + slide.is_hidden = value + assert slide._element.xml == before + def it_is_a_BaseSlide_subclass(self, subclass_fixture): slide = subclass_fixture assert isinstance(slide, _BaseSlide)