python-pptx2 2.13.0__py3-none-any.whl

pptx2/_svg.py

@@ -0,0 +1,155 @@
+"""SVG support for ``ShapeTree.add_svg_picture``.
+
+Modern PowerPoint requires every embedded SVG to ship alongside a PNG
+fallback: the ``<a:blip>`` references the PNG and an
+``<asvg:svgBlip>`` extension references the SVG.  This module provides
+the helpers that drive that wiring — SVG detection, blob loading,
+optional rasterisation via ``cairosvg``, and OOXML element rewriting.
+
+``cairosvg`` is an *optional* dependency: callers can supply their own
+PNG fallback (``png_fallback=`` argument on ``add_svg_picture``) and the
+import is never attempted, so installs without ``cairosvg`` keep
+working.  The import is deferred to first use and routed through a
+clear error message when missing.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import IO, Tuple, Union
+
+from lxml import etree
+
+from pptx2.opc.constants import CONTENT_TYPE as CT
+from pptx2.oxml.ns import nsuri, qn
+
+PathOrFile = Union[str, "os.PathLike[str]", IO[bytes], bytes]
+"""Either a filesystem path, a binary file-like, or a raw blob."""
+
+
+# {96DAC541-7B7A-43D3-8B79-37D633B846F1} is the well-known URI for the
+# Microsoft "SVG Image Extension" element introduced with Office 2016.
+_SVG_EXT_URI = "{96DAC541-7B7A-43D3-8B79-37D633B846F1}"
+
+
+class CairoSvgUnavailable(RuntimeError):
+    """Raised when SVG rasterisation is needed but ``cairosvg`` is missing."""
+
+
+def load_image_blob(source: PathOrFile) -> Tuple[bytes, str | None]:
+    """Return ``(blob, filename)`` for `source`.
+
+    `source` may be a path, a binary file-like, or a raw ``bytes``
+    blob.  The filename component is best-effort and is only used as a
+    nice-to-have for the partname; ``None`` is returned for in-memory
+    sources.
+
+    .. note::
+       File-like sources are rewound with ``source.seek(0)`` before
+       reading when seeking is supported, so the *entire* contents of
+       the stream are loaded regardless of where the cursor was when
+       the function was called.  This matches the behavior of
+       :meth:`Image.from_file` (used by ``add_picture``) and means
+       callers who pass a partially-read stream will get the full blob,
+       not just the unread tail.  Pass a :class:`bytes` blob directly
+       if you want to feed the function a pre-sliced subset of a
+       stream.
+    """
+    if isinstance(source, (bytes, bytearray)):
+        return bytes(source), None
+    if isinstance(source, (str, os.PathLike)):
+        with open(source, "rb") as f:
+            return f.read(), os.path.basename(os.fspath(source))
+    # Assume file-like.  Match `Image.from_file`'s rewind-then-read
+    # convention so behavior is consistent across the picture APIs.
+    if callable(getattr(source, "seek", None)):
+        source.seek(0)
+    return source.read(), None
+
+
+def looks_like_svg(blob: bytes) -> bool:
+    """Heuristic: does `blob` smell like an SVG document?"""
+    head = blob[:512].lstrip()
+    if not head:
+        return False
+    # Allow leading XML declaration / DOCTYPE; just look for "<svg" up
+    # near the start.  Real SVG sniffing would require an XML parse,
+    # which is overkill for a one-shot helper.
+    lowered = head.lower()
+    return b"<svg" in lowered
+
+
+def rasterize_svg(svg_blob: bytes, *, output_size: tuple[int, int] | None = None) -> bytes:
+    """Rasterise `svg_blob` to PNG bytes using ``cairosvg``.
+
+    `output_size` is an optional ``(width_px, height_px)`` pair.  When
+    omitted, ``cairosvg`` uses the SVG's intrinsic size, which is
+    usually the right thing for embedding.  Raises
+    :class:`CairoSvgUnavailable` when ``cairosvg`` isn't installed.
+    """
+    try:
+        import cairosvg  # type: ignore[import-not-found]
+    except ImportError as exc:
+        raise CairoSvgUnavailable(
+            "rasterising SVG requires the optional `cairosvg` dependency; "
+            "install it with `pip install cairosvg`, or pass an explicit "
+            "`png_fallback=` argument to add_svg_picture()."
+        ) from exc
+
+    kwargs = {}
+    if output_size is not None:
+        kwargs["output_width"] = int(output_size[0])
+        kwargs["output_height"] = int(output_size[1])
+    return cairosvg.svg2png(bytestring=svg_blob, **kwargs)
+
+
+def add_svg_blip_extension(pic_elm, svg_rId: str) -> None:
+    """Inject an ``<asvg:svgBlip>`` extension into the picture's blip.
+
+    `pic_elm` is the ``<p:pic>`` lxml element returned by ``new_pic``.
+    `svg_rId` is the relationship id of the SVG image part.
+    """
+    blip = pic_elm.find(".//" + qn("a:blip"))
+    if blip is None:
+        raise ValueError("picture has no <a:blip> to attach the SVG extension to")
+    extLst = blip.find(qn("a:extLst"))
+    if extLst is None:
+        extLst = etree.SubElement(blip, qn("a:extLst"))
+    ext = etree.SubElement(extLst, qn("a:ext"), uri=_SVG_EXT_URI)
+    asvg_uri = nsuri("asvg")
+    svgBlip = etree.SubElement(
+        ext,
+        "{%s}svgBlip" % asvg_uri,
+        nsmap={"asvg": asvg_uri},
+    )
+    svgBlip.set(qn("r:embed"), svg_rId)
+
+
+def add_svg_image_part(slide_part, svg_blob: bytes, filename: str | None = None):
+    """Register `svg_blob` as a new SVG image part on `slide_part`'s package.
+
+    Returns ``(image_part, rId)``: the freshly minted
+    :class:`pptx2.parts.image.ImagePart` plus the relationship id that
+    points the slide at it.  Bypasses the Pillow-driven ``Image``
+    constructor (which can't read SVG) and constructs the part directly
+    with ``content_type='image/svg+xml'``.
+    """
+    from pptx2.opc.constants import RELATIONSHIP_TYPE as RT
+    from pptx2.parts.image import ImagePart
+
+    package = slide_part.package
+    partname = package.next_image_partname("svg")
+    image_part = ImagePart(
+        partname,
+        SVG_CONTENT_TYPE,
+        package,
+        svg_blob,
+        filename=filename,
+    )
+    rId = slide_part.relate_to(image_part, RT.IMAGE)
+    return image_part, rId
+
+
+# Re-exported here so callers in ``shapetree.py`` don't need to know
+# about the constants module organisation.
+SVG_CONTENT_TYPE = CT.SVG

pptx2/_template_applier.py

@@ -0,0 +1,292 @@
+"""Template application machinery for ``Presentation.apply_template()``."""
+
+from __future__ import annotations
+
+import warnings
+from copy import deepcopy
+from typing import TYPE_CHECKING
+
+from pptx2.opc.constants import RELATIONSHIP_TYPE as RT
+from pptx2.opc.packuri import PackURI
+
+if TYPE_CHECKING:
+    from pptx2.opc.package import Part
+    from pptx2.package import Package
+    from pptx2.parts.presentation import PresentationPart
+    from pptx2.parts.slide import SlideLayoutPart, SlideMasterPart, SlidePart
+    from pptx2.slide import Slide
+
+
+def apply_template(
+    dst_prs_part: PresentationPart,
+    template_prs_part: PresentationPart,
+) -> None:
+    """Re-point every slide in *dst_prs_part* at the masters/layouts from *template_prs_part*.
+
+    Existing slide content (shapes, text, animations) is preserved.
+    Each slide's layout is matched to the closest layout in the template (by name, then by
+    type, then fallback to the template's first layout).
+
+    After all slides are remapped the old master/layout/theme parts that are no longer
+    referenced are dropped automatically when the package is saved (they are no longer
+    reachable from any relationship).
+
+    Parameters
+    ----------
+    dst_prs_part:
+        The presentation to modify in place.
+    template_prs_part:
+        The template presentation whose masters/layouts/themes are to be applied.
+    """
+    applier = _TemplateApplier(dst_prs_part, template_prs_part)
+    applier.run()
+
+
+class _TemplateApplier:
+    """Stateful helper for template application."""
+
+    def __init__(
+        self,
+        dst_prs_part: PresentationPart,
+        tpl_prs_part: PresentationPart,
+    ) -> None:
+        self._dst_prs_part = dst_prs_part
+        self._tpl_prs_part = tpl_prs_part
+        self._dst_package: Package = dst_prs_part.package  # type: ignore[assignment]
+        # Tracks partnames already reserved during this run to avoid collisions
+        self._reserved: set[str] = set()
+
+    def run(self) -> None:
+        """Execute the template application."""
+        # 1. Clone the template masters (with themes + layouts) into the destination
+        tpl_master_to_dst_master = self._clone_template_masters()
+
+        # 2. Build a flat list of all template layout parts (for matching)
+        tpl_layouts: list[SlideLayoutPart] = []
+        for tpl_master_part, dst_master_part in tpl_master_to_dst_master.items():
+            for rel in tpl_master_part.rels.values():
+                if rel.is_external or rel.reltype != RT.SLIDE_LAYOUT:
+                    continue
+                tpl_layouts.append(rel.target_part)  # type: ignore[arg-type]
+
+        # Map tpl layout partname → corresponding dst layout part
+        tpl_partname_to_dst_layout: dict[str, SlideLayoutPart] = {}
+        for tpl_master_part, dst_master_part in tpl_master_to_dst_master.items():
+            for tpl_rel, dst_rel in zip(
+                [r for r in tpl_master_part.rels.values() if not r.is_external and r.reltype == RT.SLIDE_LAYOUT],
+                [r for r in dst_master_part.rels.values() if not r.is_external and r.reltype == RT.SLIDE_LAYOUT],
+            ):
+                tpl_partname_to_dst_layout[tpl_rel.target_part.partname] = dst_rel.target_part  # type: ignore[assignment]
+
+        # Build dst layouts list in the same order as tpl_layouts (parallel)
+        dst_layouts: list[SlideLayoutPart] = [
+            tpl_partname_to_dst_layout[lp.partname]  # type: ignore[index]
+            for lp in tpl_layouts
+            if lp.partname in tpl_partname_to_dst_layout
+        ]
+
+        # 3. Remap each existing slide to the best-matching template layout
+        dst_prs_element = self._dst_prs_part._element  # pyright: ignore[reportPrivateUsage]
+        sldIdLst = dst_prs_element.sldIdLst
+        if sldIdLst is not None:
+            for sldId in list(sldIdLst.sldId_lst):
+                slide_part: SlidePart = self._dst_prs_part.related_part(sldId.rId)  # type: ignore[assignment]
+                self._remap_slide(slide_part, tpl_layouts, dst_layouts)
+
+        # 4. Remove old masters from the presentation element
+        # (unreachable parts are not included when the package is saved)
+        self._drop_old_masters(set(tpl_master_to_dst_master.values()))
+
+        # 5. Register new masters in presentation element
+        for dst_master_part in tpl_master_to_dst_master.values():
+            rId = self._dst_prs_part.relate_to(dst_master_part, RT.SLIDE_MASTER)
+            sldMasterIdLst = dst_prs_element.get_or_add_sldMasterIdLst()
+            sldMasterIdLst._add_sldMasterId(rId=rId)  # pyright: ignore[reportAttributeAccessIssue]
+
+    # ------------------------------------------------------------------
+    # Master cloning
+    # ------------------------------------------------------------------
+
+    def _clone_template_masters(self) -> dict[SlideMasterPart, SlideMasterPart]:
+        """Clone each master in the template into the destination.
+
+        Returns a mapping: template SlideMasterPart → cloned destination SlideMasterPart.
+        """
+        result: dict[SlideMasterPart, SlideMasterPart] = {}
+        dst_package = self._dst_package
+        tpl_prs_element = self._tpl_prs_part._element  # pyright: ignore[reportPrivateUsage]
+
+        if tpl_prs_element.sldMasterIdLst is None:
+            return result
+
+        for entry in tpl_prs_element.sldMasterIdLst.sldMasterId_lst:
+            tpl_master_part: SlideMasterPart = self._tpl_prs_part.related_part(entry.rId)  # type: ignore[assignment]
+
+            # Clone theme
+            dst_theme_part: Part | None = None
+            try:
+                src_theme = tpl_master_part.part_related_by(RT.THEME)
+                theme_pn = self._next_partname("/ppt/theme/theme%d.xml")
+                dst_theme_part = _clone_part(src_theme, theme_pn, dst_package)
+            except KeyError:
+                pass
+
+            # Clone master
+            master_pn = self._next_partname("/ppt/slideMasters/slideMaster%d.xml")
+            dst_master_part = _clone_xml_part(tpl_master_part, master_pn, dst_package)
+            if dst_theme_part is not None:
+                dst_master_part.relate_to(dst_theme_part, RT.THEME)
+
+            # Clone layouts
+            for rel in tpl_master_part.rels.values():
+                if rel.is_external or rel.reltype != RT.SLIDE_LAYOUT:
+                    continue
+                src_lo: SlideLayoutPart = rel.target_part  # type: ignore[assignment]
+                lo_pn = self._next_partname("/ppt/slideLayouts/slideLayout%d.xml")
+                dst_lo = _clone_xml_part(src_lo, lo_pn, dst_package)
+                dst_lo.relate_to(dst_master_part, RT.SLIDE_MASTER)
+                dst_master_part.relate_to(dst_lo, RT.SLIDE_LAYOUT)
+
+            result[tpl_master_part] = dst_master_part  # type: ignore[assignment]
+
+        return result
+
+    # ------------------------------------------------------------------
+    # Slide remapping
+    # ------------------------------------------------------------------
+
+    def _remap_slide(
+        self,
+        slide_part: SlidePart,
+        tpl_layouts: list[SlideLayoutPart],
+        dst_layouts: list[SlideLayoutPart],
+    ) -> None:
+        """Replace the slide's layout relationship to point to a template layout."""
+        # Find the current layout rel and remove it
+        old_layout_rId: str | None = None
+        for rId, rel in list(slide_part.rels.items()):
+            if not rel.is_external and rel.reltype == RT.SLIDE_LAYOUT:
+                old_layout_rId = rId
+                break
+
+        if not dst_layouts:
+            warnings.warn(
+                "apply_template: no layouts available in the template; "
+                "slide layout relationship could not be updated.",
+                stacklevel=3,
+            )
+            return
+
+        # Determine current slide's layout info for matching
+        current_lo_name: str = ""
+        current_lo_type: str = ""
+        if old_layout_rId is not None:
+            old_lo_part: SlideLayoutPart = slide_part.related_part(old_layout_rId)  # type: ignore[assignment]
+            try:
+                current_lo_name = old_lo_part._element.cSld.name  # pyright: ignore[reportPrivateUsage]
+            except AttributeError:
+                pass
+            current_lo_type = (old_lo_part._element.get("type") or "")  # pyright: ignore[reportPrivateUsage]
+
+        # Match: name, then type, then first
+        matched_dst_lo: SlideLayoutPart | None = None
+        for tpl_lo, dst_lo in zip(tpl_layouts, dst_layouts):
+            tpl_name = tpl_lo._element.cSld.name  # pyright: ignore[reportPrivateUsage]
+            if tpl_name == current_lo_name:
+                matched_dst_lo = dst_lo
+                break
+        if matched_dst_lo is None and current_lo_type:
+            for tpl_lo, dst_lo in zip(tpl_layouts, dst_layouts):
+                tpl_type = tpl_lo._element.get("type") or ""  # pyright: ignore[reportPrivateUsage]
+                if tpl_type == current_lo_type:
+                    matched_dst_lo = dst_lo
+                    break
+        if matched_dst_lo is None:
+            matched_dst_lo = dst_layouts[0]
+
+        # Remove old layout relationship
+        if old_layout_rId is not None:
+            slide_part.rels.pop(old_layout_rId)
+
+        # Add new layout relationship
+        slide_part.relate_to(matched_dst_lo, RT.SLIDE_LAYOUT)
+
+    # ------------------------------------------------------------------
+    # Old master removal
+    # ------------------------------------------------------------------
+
+    def _drop_old_masters(self, new_masters: set[SlideMasterPart]) -> None:
+        """Remove old master entries from the presentation element.
+
+        Also removes any direct presentation→theme relationship, since the
+        theme is now owned by the new master.
+
+        The old Part objects remain in memory but will not be written to the package
+        because they are no longer reachable from any relationship.
+        """
+        prs_element = self._dst_prs_part._element  # pyright: ignore[reportPrivateUsage]
+        sldMasterIdLst = prs_element.sldMasterIdLst
+
+        if sldMasterIdLst is None:
+            return
+
+        # Collect rIds that point to OLD masters (not in new_masters)
+        old_rIds: list[str] = []
+        for entry in list(sldMasterIdLst.sldMasterId_lst):
+            part = self._dst_prs_part.related_part(entry.rId)
+            if part not in new_masters:
+                old_rIds.append(entry.rId)
+
+        # Remove relationships to old masters
+        for rId in old_rIds:
+            self._dst_prs_part.rels.pop(rId)
+
+        # Remove any direct presentation→theme relationship so the old theme
+        # is no longer reachable from the presentation.
+        theme_rIds_to_remove: list[str] = []
+        for rId, rel in list(self._dst_prs_part.rels.items()):
+            if not rel.is_external and rel.reltype == RT.THEME:
+                theme_rIds_to_remove.append(rId)
+        for rId in theme_rIds_to_remove:
+            self._dst_prs_part.rels.pop(rId)
+
+        # Remove the entire sldMasterIdLst — it will be rebuilt in run()
+        prs_element.remove(sldMasterIdLst)
+
+    # ------------------------------------------------------------------
+    # Partname helpers
+    # ------------------------------------------------------------------
+
+    def _next_partname(self, tmpl: str) -> PackURI:
+        """Return the next non-colliding partname, accounting for locally reserved names."""
+        prefix = tmpl[: (tmpl % 42).find("42")]
+        existing = {
+            p.partname for p in self._dst_package.iter_parts()
+            if p.partname.startswith(prefix)
+        }
+        taken = existing | {pn for pn in self._reserved if pn.startswith(prefix)}
+        n = 1
+        while True:
+            candidate = tmpl % n
+            if candidate not in taken:
+                self._reserved.add(candidate)
+                return PackURI(candidate)
+            n += 1
+
+
+# ---------------------------------------------------------------------------
+# Part-copy helpers (shared logic)
+# ---------------------------------------------------------------------------
+
+
+def _clone_part(src_part: Part, new_partname: PackURI, dst_package: Package) -> Part:
+    from pptx2.opc.package import PartFactory
+
+    return PartFactory(new_partname, src_part.content_type, dst_package, blob=src_part.blob)
+
+
+def _clone_xml_part(src_part: Part, new_partname: PackURI, dst_package: Package) -> Part:
+    from pptx2.opc.package import XmlPart
+
+    new_element = deepcopy(src_part._element)  # pyright: ignore[reportPrivateUsage]
+    return src_part.__class__(new_partname, src_part.content_type, dst_package, new_element)

pptx2/_textstyle.py

@@ -0,0 +1,187 @@
+"""Internal shared text-styling vocabulary.
+
+One place to translate the short, string-flavoured keywords the public
+surface accepts (``align="center"``, ``anchor="middle"``, ``size_pt=11``,
+``color="#1F2937"``) into the enum / :class:`~pptx2.util.Length`
+values the XML layer wants.
+
+Used by :meth:`ShapeTree.add_text` and :meth:`pptx2.table._Cell.format`
+so the same words mean the same thing wherever text is styled.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Sequence
+
+from pptx2._color import coerce_color
+from pptx2.enum.text import MSO_VERTICAL_ANCHOR, PP_PARAGRAPH_ALIGNMENT
+from pptx2.util import Length, Pt
+
+ALIGN_MAP = {
+    "left": PP_PARAGRAPH_ALIGNMENT.LEFT,
+    "right": PP_PARAGRAPH_ALIGNMENT.RIGHT,
+    "center": PP_PARAGRAPH_ALIGNMENT.CENTER,
+    "centre": PP_PARAGRAPH_ALIGNMENT.CENTER,
+    "justify": PP_PARAGRAPH_ALIGNMENT.JUSTIFY,
+}
+
+ANCHOR_MAP = {
+    "top": MSO_VERTICAL_ANCHOR.TOP,
+    "middle": MSO_VERTICAL_ANCHOR.MIDDLE,
+    "center": MSO_VERTICAL_ANCHOR.MIDDLE,
+    "centre": MSO_VERTICAL_ANCHOR.MIDDLE,
+    "bottom": MSO_VERTICAL_ANCHOR.BOTTOM,
+}
+
+
+def coerce_align(value: str) -> PP_PARAGRAPH_ALIGNMENT:
+    """Return the `PP_ALIGN` member named by `value` (case-insensitive)."""
+    try:
+        return ALIGN_MAP[str(value).lower()]
+    except KeyError:
+        raise ValueError(
+            f"align must be one of {sorted(set(ALIGN_MAP))}; got {value!r}"
+        ) from None
+
+
+def coerce_anchor(value: str) -> MSO_VERTICAL_ANCHOR:
+    """Return the `MSO_VERTICAL_ANCHOR` member named by `value` (case-insensitive)."""
+    try:
+        return ANCHOR_MAP[str(value).lower()]
+    except KeyError:
+        raise ValueError(
+            f"anchor must be one of {sorted(set(ANCHOR_MAP))}; got {value!r}"
+        ) from None
+
+
+def coerce_length(value: Any) -> Length:
+    """Coerce a point number or a `Length` to a `Length`."""
+    return value if isinstance(value, Length) else Pt(float(value))
+
+
+
+def apply_margins(
+    tf: Any, margin: float | Length | Sequence[float | Length] | None
+) -> None:
+    """Set text-frame insets from a scalar or a ``(top, right, bottom, left)`` sequence.
+
+    Scalars in points (or any :class:`~pptx2.util.Length`) — ``0`` means
+    "flush to the edge", which is what a dense table cell usually wants.
+    """
+    if margin is None:
+        return
+    if isinstance(margin, (tuple, list)):
+        if len(margin) != 4:
+            raise ValueError(
+                "margin tuple must have 4 elements (top, right, bottom, left); "
+                f"got {len(margin)}"
+            )
+        top, right, bottom, left = (coerce_length(v) for v in margin)
+    else:
+        top = right = bottom = left = coerce_length(margin)
+    tf.margin_top, tf.margin_right = top, right
+    tf.margin_bottom, tf.margin_left = bottom, left
+
+
+def apply_text_style(
+    tf: Any,
+    *,
+    font: str | None = None,
+    size_pt: float | None = None,
+    bold: bool | None = None,
+    italic: bool | None = None,
+    color: Any = None,
+    align: str | None = None,
+    anchor: str | None = None,
+    margin: float | Length | Sequence[float | Length] | None = None,
+    word_wrap: bool | None = None,
+    paragraph_defaults: bool = False,
+) -> None:
+    """Apply the shared text-styling keywords to text frame `tf`.
+
+    Every keyword is optional and ``None`` means "leave as-is", so this can be
+    layered over text that already carries formatting.  `paragraph_defaults`
+    additionally writes the run properties onto each paragraph's default run
+    properties, so text added to the frame *later* inherits the styling —
+    what a table cell wants, and what a one-shot ``add_text`` does not need.
+    """
+    if word_wrap is not None:
+        tf.word_wrap = bool(word_wrap)
+    apply_margins(tf, margin)
+    if anchor is not None:
+        tf.vertical_anchor = coerce_anchor(anchor)
+
+    align_value = None if align is None else coerce_align(align)
+    rgb = None if color is None else coerce_color(color)
+    size = None if size_pt is None else coerce_length(size_pt)
+
+    for paragraph in tf.paragraphs:
+        if align_value is not None:
+            paragraph.alignment = align_value
+        fonts = [run.font for run in paragraph.runs]
+        if paragraph_defaults:
+            fonts.append(paragraph.font)
+        for f in fonts:
+            if font is not None:
+                f.name = font
+            if size is not None:
+                f.size = size
+            if bold is not None:
+                f.bold = bool(bold)
+            if italic is not None:
+                f.italic = bool(italic)
+            if rgb is not None:
+                f.color.rgb = rgb
+
+
+def apply_body_defaults(
+    tf: Any,
+    *,
+    font: str | None = None,
+    size_pt: float | None = None,
+    bold: bool | None = None,
+    italic: bool | None = None,
+    color: Any = None,
+    align: str | None = None,
+) -> None:
+    """Write text styling to `tf`'s text-body defaults (`<a:lstStyle>`).
+
+    Styling only the existing paragraphs and runs is lost the moment the frame
+    is repopulated: ``TextFrame.text = ...`` drops every ``<a:p>`` and builds
+    fresh, unstyled ones.  `<a:lstStyle>` survives that (``clear_content()``
+    removes only the paragraphs), so defaults written here still apply to text
+    assigned afterwards — which is what makes "style the header row, then fill
+    in the cells" behave the way it reads.
+
+    Only level-1 defaults are written; explicit run properties still win.
+    """
+    from pptx2.text.text import Font
+
+    lvl1pPr = tf._txBody.get_or_add_lstStyle().get_or_add_lvl1pPr()
+    if align is not None:
+        lvl1pPr.algn = coerce_align(align)
+    if all(v is None for v in (font, size_pt, bold, italic, color)):
+        return
+    default_font = Font(lvl1pPr.get_or_add_defRPr())
+    if font is not None:
+        default_font.name = font
+    if size_pt is not None:
+        default_font.size = coerce_length(size_pt)
+    if bold is not None:
+        default_font.bold = bool(bold)
+    if italic is not None:
+        default_font.italic = bool(italic)
+    if color is not None:
+        default_font.color.rgb = coerce_color(color)
+
+
+__all__ = [
+    "ALIGN_MAP",
+    "ANCHOR_MAP",
+    "apply_body_defaults",
+    "apply_margins",
+    "apply_text_style",
+    "coerce_align",
+    "coerce_anchor",
+    "coerce_length",
+]