feat(ergonomics): PathLike + PERCENT_40 typo + Slide.background.element fix (modernization Phase 1)

Phase 1 of issue #29 (Modernization & Ergonomics epic). Bundles three
small, mostly-orthogonal wins that the issue called out as "trivial
cherry-picks" plus a long-standing correctness bug that pollutes the
power-user surface. Defers `Font.color` no-mutate-on-read (closes
upstream scanny#1111/scanny#1074), `collections.abc` import sweep, and dev-tooling
modernization (uv / pyright strict) to Phase 2.

What this PR adds / fixes
-------------------------

1. **`pathlib.Path` / `os.PathLike` support across the API.** Closes
   upstream PR scanny#1123. The four entry points users
   most commonly hit with a `Path` now accept it without a TypeError:

   - `pptx.Presentation(path)` — open a deck from a Path
   - `prs.save(path)` — write a deck to a Path
   - `slide.shapes.add_picture(path, ...)` — embed an image by Path
   - `pptx.parts.image.Image.from_file(path)` — lower-level loader

   Each accepts any `os.PathLike[str]` (Path, custom subclasses, etc.)
   by coercing via `os.fspath(...)` at the boundary. Existing `str`
   and file-like-object callers are unaffected.

2. **`MSO_PATTERN_TYPE.PERCENT_40` typo fixed.** Closes upstream
   scanny#1131. The enum member was misspelled `ERCENT_40` (missing leading
   `P`). The fix renames to the correct `PERCENT_40` with no value
   change (xml_value remains `pct40`, integer value remains 6). Code
   that referenced the broken name needs to update — the broken name
   is gone deliberately, callers will get a clear AttributeError.

3. **`slide.background.element` returns the `<p:bg>` element.** Closes
   upstream issue scanny#1126. Previously `slide.background.element` (and
   the private `._element`) returned the parent `<p:cSld>` element
   instead of the actual `<p:bg>` background. Power users
   introspecting the XML now get the right node. The `<p:bg>` is
   materialized on construction (matching the legacy destructive
   behavior of accessing `.fill`); since `slide.background` is a
   lazyproperty, this only fires on first slide-background access,
   not on slide load.

Out of scope (for explicit Phase 2 follow-up)
---------------------------------------------

- **`Font.color` mutate-on-read** (closes upstream scanny#1111, scanny#1074) —
  the getter currently materializes `<a:solidFill>` on access, which
  means READING a font's color modifies the file. The fix requires a
  lazy ColorFormat wrapper that delays solidFill creation until the
  setter actually fires; that's a larger refactor that needs its own
  PR with careful review against the existing color/fill test suite.
- **`collections.abc` import sweep** (closes upstream scanny#771) — no
  remaining offenders in our fork's source tree (the upstream PR was
  authored against an older codebase). If any creep in via vendored
  fixes, Phase 2 will sweep.
- **Dev-tooling modernization** (uv, pyright strict, pytest-syrupy)
  — covered in the issue body but deserves its own PR per the
  issue's own "patch 1 / 2 / 3" framing.

Test coverage
-------------

- 15 new unit tests in `tests/test_modernization_phase1.py`:
  * 4 tests on `Presentation()` accepting Path/str/BytesIO/PathLike-subclass
  * 2 tests on `Presentation.save(Path)` round-trip
  * 1 test on `add_picture(Path)`
  * 3 tests on `Image.from_file(Path|str|stream)`
  * 2 tests on the PERCENT_40 typo fix
  * 3 tests on `slide.background.element` (returns `<p:bg>`,
    fill still works, RGB round-trip survives)
- 4 new behave scenarios in `features/modernization-phase1.feature`
- New `uat_modernization_phase1.py` (untracked per repo §6) — these
  are programmer ergonomics, not visual changes, so the UAT prints
  per-fix verification rather than producing a deck for visual review.

Verification
------------
```
$ python3 -m pytest tests/ -q | tail -3
3237 passed in 4.54s

$ ruff check src tests | tail -3
All checks passed!

$ python3 -m behave features/ --no-color | tail -3
1003 scenarios passed, 0 failed, 0 skipped
3010 steps passed, 0 failed, 0 skipped
```

Refs #29

Author: Matthew Horoszowski

features/modernization-phase1.feature

@@ -0,0 +1,27 @@
+Feature: Modernization Phase 1 — PathLike, PERCENT_40, slide.background.element
+  In order to use python-pptx with modern Python idioms
+  As a developer using python-pptx
+  I need pathlib.Path support, the PERCENT_40 enum typo fixed,
+  and slide.background.element to return the actual <p:bg> element
+
+
+  Scenario: Open a presentation from a pathlib.Path
+    Given a freshly-saved presentation at a Path
+     When I call Presentation(path) with the Path
+     Then I get a presentation back
+
+
+  Scenario: Save a presentation to a pathlib.Path
+    Given a fresh presentation
+     When I save it to a Path
+     Then a non-empty .pptx file exists at that Path
+
+
+  Scenario: PERCENT_40 enum is exposed with the correct name
+    Then MSO_PATTERN_TYPE.PERCENT_40 exists with xml_value pct40
+     And the broken name ERCENT_40 does not exist
+
+
+  Scenario: slide.background.element returns the <p:bg> element
+    Given a fresh slide on a fresh presentation
+     Then slide.background.element local-name is bg

features/steps/modernization.py

@@ -0,0 +1,82 @@
+"""Gherkin step implementations for Modernization Phase 1 (issue #29)."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from behave import given, then, when
+from environment import scratch_dir  # noqa: E402
+
+from pptx import Presentation
+from pptx.enum.dml import MSO_PATTERN_TYPE
+
+
+# given ===================================================
+
+
+@given("a freshly-saved presentation at a Path")
+def given_freshly_saved_presentation(context):
+    target = Path(scratch_dir) / "modernization_seed.pptx"
+    target.parent.mkdir(parents=True, exist_ok=True)
+    Presentation().save(target)
+    context.path = target
+
+
+@given("a fresh presentation")
+def given_fresh_presentation(context):
+    context.prs = Presentation()
+
+
+@given("a fresh slide on a fresh presentation")
+def given_fresh_slide(context):
+    prs = Presentation()
+    context.slide = prs.slides.add_slide(prs.slide_layouts[6])
+
+
+# when ====================================================
+
+
+@when("I call Presentation(path) with the Path")
+def when_call_presentation_with_path(context):
+    context.prs = Presentation(context.path)
+
+
+@when("I save it to a Path")
+def when_save_to_path(context):
+    target = Path(scratch_dir) / "modernization_out.pptx"
+    target.parent.mkdir(parents=True, exist_ok=True)
+    context.prs.save(target)
+    context.saved_path = target
+
+
+# then ====================================================
+
+
+@then("I get a presentation back")
+def then_presentation_back(context):
+    assert context.prs is not None
+
+
+@then("a non-empty .pptx file exists at that Path")
+def then_non_empty_file_exists(context):
+    assert context.saved_path.exists()
+    assert context.saved_path.stat().st_size > 0
+
+
+@then("MSO_PATTERN_TYPE.PERCENT_40 exists with xml_value pct40")
+def then_percent_40_correct(context):
+    assert MSO_PATTERN_TYPE.PERCENT_40.xml_value == "pct40"
+
+
+@then("the broken name ERCENT_40 does not exist")
+def then_ercent_40_absent(context):
+    assert hasattr(MSO_PATTERN_TYPE, "ERCENT_40") is False
+
+
+@then("slide.background.element local-name is bg")
+def then_background_element_is_bg(context):
+    from lxml import etree
+
+    bg_elm = context.slide.background.element
+    local = etree.QName(bg_elm.tag).localname
+    assert local == "bg", f"expected 'bg', got '{local}'"

src/pptx/api.py

@@ -18,16 +18,22 @@
     from pptx.parts.presentation import PresentationPart
 
 
-def Presentation(pptx: str | IO[bytes] | None = None) -> presentation.Presentation:
+def Presentation(
+    pptx: str | os.PathLike[str] | IO[bytes] | None = None,
+) -> presentation.Presentation:
     """
     Return a |Presentation| object loaded from *pptx*, where *pptx* can be
-    either a path to a ``.pptx`` file (a string) or a file-like object. If
-    *pptx* is missing or ``None``, the built-in default presentation
-    "template" is loaded.
+    a path to a ``.pptx`` file (a |str| or any |os.PathLike| object such as
+    |pathlib.Path|) or a file-like object. If *pptx* is missing or ``None``,
+    the built-in default presentation "template" is loaded.
     """
     if pptx is None:
         pptx = _default_pptx_path()
 
+    # ---accept os.PathLike (pathlib.Path, etc.) by coercing to str at the boundary---
+    if hasattr(pptx, "__fspath__"):
+        pptx = os.fspath(pptx)
+
     presentation_part = Package.open(pptx).main_document_part
 
     if not _is_pptx_package(presentation_part):

src/pptx/enum/dml.py

@@ -351,7 +351,7 @@ class MSO_PATTERN_TYPE(BaseXmlEnum):
     PERCENT_30 = (5, "pct30", "30% of the foreground color.")
     """30% of the foreground color."""
 
-    ERCENT_40 = (6, "pct40", "40% of the foreground color.")
+    PERCENT_40 = (6, "pct40", "40% of the foreground color.")
     """40% of the foreground color."""
 
     PERCENT_5 = (1, "pct5", "5% of the foreground color.")

src/pptx/parts/image.py

@@ -153,11 +153,15 @@ def from_blob(cls, blob: bytes, filename: str | None = None) -> Image:
         return cls(blob, filename)
 
     @classmethod
-    def from_file(cls, image_file: str | IO[bytes]) -> Image:
+    def from_file(cls, image_file: str | os.PathLike[str] | IO[bytes]) -> Image:
         """Return a new |Image| object loaded from `image_file`.
 
-        `image_file` can be either a path (str) or a file-like object.
+        `image_file` can be a path (|str| or any |os.PathLike| object such as
+        |pathlib.Path|) or a file-like object.
         """
+        # ---accept os.PathLike (pathlib.Path etc.) by coercing to str---
+        if hasattr(image_file, "__fspath__"):
+            image_file = os.fspath(image_file)
         if isinstance(image_file, str):
             # treat image_file as a path
             with open(image_file, "rb") as f:

src/pptx/presentation.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import os
 from typing import IO, TYPE_CHECKING, Iterable, cast
 
 from pptx.opc.constants import RELATIONSHIP_TYPE as RT
@@ -66,11 +67,15 @@ def notes_master(self) -> NotesMaster:
         """
         return self.part.notes_master
 
-    def save(self, file: str | IO[bytes]):
+    def save(self, file: str | os.PathLike[str] | IO[bytes]):
         """Writes this presentation to `file`.
 
-        `file` can be either a file-path or a file-like object open for writing bytes.
+        `file` can be a file-path (|str| or any |os.PathLike| object such as
+        |pathlib.Path|) or a file-like object open for writing bytes.
         """
+        # ---accept os.PathLike (pathlib.Path etc.) by coercing to str---
+        if hasattr(file, "__fspath__"):
+            file = os.fspath(file)
         self.part.save(file)
 
     @property

src/pptx/slide.py

@@ -595,10 +595,21 @@ class _Background(ElementProxy):
     Note that the presence of this object does not by itself imply an
     explicitly-defined background; a slide with an inherited background still
     has a |_Background| object.
+
+    Closes upstream issue #1126: prior to this fix, ``slide.background.element``
+    returned the parent ``<p:cSld>`` element instead of the actual ``<p:bg>``
+    background element. Power users introspecting the XML now get the right
+    node. The ``<p:bg>`` element is materialized on construction (matching
+    the legacy destructive behavior of accessing ``.fill``) — and since
+    ``slide.background`` is a |lazyproperty| upstream, this only fires on
+    first access of the slide's background, not on slide load.
     """
 
     def __init__(self, cSld: CT_CommonSlideData):
-        super(_Background, self).__init__(cSld)
+        # ---resolve to the <p:bg> element (creating if needed) so that
+        #    `_element` and `.element` point at the right node per issue #1126
+        bg = cSld.get_or_add_bg()
+        super(_Background, self).__init__(bg)
         self._cSld = cSld
 
     @lazyproperty