python-pptx2 2.13.0__py3-none-any.whl

pptx2/types.py

@@ -0,0 +1,36 @@
+"""Abstract types used by `python-pptx`."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from typing_extensions import Protocol
+
+if TYPE_CHECKING:
+    from pptx2.opc.package import XmlPart
+    from pptx2.util import Length
+
+
+class ProvidesExtents(Protocol):
+    """An object that has width and height."""
+
+    @property
+    def height(self) -> Length:
+        """Distance between top and bottom extents of shape in EMUs."""
+        ...
+
+    @property
+    def width(self) -> Length:
+        """Distance between left and right extents of shape in EMUs."""
+        ...
+
+
+class ProvidesPart(Protocol):
+    """An object that provides access to its XmlPart.
+
+    This type is for objects that need access to their part, possibly because they need access to
+    the package or related parts.
+    """
+
+    @property
+    def part(self) -> XmlPart: ...

pptx2/util.py

@@ -0,0 +1,263 @@
+"""Utility functions and classes."""
+
+from __future__ import annotations
+
+import functools
+from typing import Any, Callable, Generic, TypeVar, cast
+
+
+def _coerce_emu(value):
+    """Internal: coerce a coordinate value to integer EMU.
+
+    Accepts int / Length passes through unchanged, floats are rounded
+    half-to-even, and ``None`` is passed through (callers may use ``None``
+    for "don't set"). ``bool`` is rejected — booleans are an int subclass
+    in Python but a boolean coordinate is always a programming error.
+
+    OOXML's ``CT_Point2D`` (``<a:off>``) requires ``x``/``y`` to be
+    ``xs:long`` and ``CT_PositiveSize2D`` (``<a:ext>``) requires
+    ``cx``/``cy`` to be ``xs:nonNegativeInteger``. Float-valued strings
+    in those attributes are schema-invalid; PowerPoint's strict
+    open-time validator rejects them with the "Repair?" dialog even
+    though python-pptx, the OOXML XSDs, and LibreOffice all accept
+    them silently. Coercing at constructor entry catches the common
+    case of ``(Inches(N) - gutter) / 2`` producing a float.
+    """
+    if value is None:
+        return None
+    if isinstance(value, bool):
+        raise TypeError("bool is not a valid EMU coordinate")
+    if isinstance(value, int):
+        return value
+    # Reject str/bytes explicitly — they're convertible via float() but
+    # passing a coordinate as a string is always a programming error,
+    # not a unit-conversion case we want to silently accept.
+    if isinstance(value, (str, bytes, bytearray)):
+        raise TypeError(
+            f"Expected int, float, or Emu-derived length; got "
+            f"{type(value).__name__}: {value!r}"
+        )
+    if isinstance(value, float):
+        try:
+            return int(round(value))
+        except (OverflowError, ValueError) as exc:
+            # NaN → ValueError, ±inf → OverflowError. Normalise to
+            # TypeError so callers get a single, informative exception.
+            raise TypeError(
+                f"Cannot coerce non-finite float to EMU: {value!r}"
+            ) from exc
+    try:
+        return int(round(float(value)))
+    except (TypeError, ValueError, OverflowError):
+        raise TypeError(
+            f"Expected int, float, or Emu-derived length; got "
+            f"{type(value).__name__}: {value!r}"
+        )
+
+
+class Length(int):
+    """Base class for length classes Inches, Emu, Cm, Mm, and Pt.
+
+    Provides properties for converting length values to convenient units.
+    """
+
+    _EMUS_PER_INCH = 914400
+    _EMUS_PER_CENTIPOINT = 127
+    _EMUS_PER_CM = 360000
+    _EMUS_PER_MM = 36000
+    _EMUS_PER_PT = 12700
+
+    def __new__(cls, emu: int):
+        return int.__new__(cls, emu)
+
+    @property
+    def inches(self) -> float:
+        """Floating point length in inches."""
+        return self / float(self._EMUS_PER_INCH)
+
+    @property
+    def centipoints(self) -> int:
+        """Integer length in hundredths of a point (1/7200 inch).
+
+        Used internally because PowerPoint stores font size in centipoints.
+        """
+        return self // self._EMUS_PER_CENTIPOINT
+
+    @property
+    def cm(self) -> float:
+        """Floating point length in centimeters."""
+        return self / float(self._EMUS_PER_CM)
+
+    @property
+    def emu(self) -> int:
+        """Integer length in English Metric Units."""
+        return self
+
+    @property
+    def mm(self) -> float:
+        """Floating point length in millimeters."""
+        return self / float(self._EMUS_PER_MM)
+
+    @property
+    def pt(self) -> float:
+        """Floating point length in points."""
+        return self / float(self._EMUS_PER_PT)
+
+
+class Inches(Length):
+    """Convenience constructor for length in inches."""
+
+    def __new__(cls, inches: float):
+        emu = int(inches * Length._EMUS_PER_INCH)
+        return Length.__new__(cls, emu)
+
+
+class Centipoints(Length):
+    """Convenience constructor for length in hundredths of a point."""
+
+    def __new__(cls, centipoints: int):
+        emu = int(centipoints * Length._EMUS_PER_CENTIPOINT)
+        return Length.__new__(cls, emu)
+
+
+class Cm(Length):
+    """Convenience constructor for length in centimeters."""
+
+    def __new__(cls, cm: float):
+        emu = int(cm * Length._EMUS_PER_CM)
+        return Length.__new__(cls, emu)
+
+
+class Emu(Length):
+    """Convenience constructor for length in english metric units."""
+
+    def __new__(cls, emu: int):
+        return Length.__new__(cls, int(emu))
+
+
+class Mm(Length):
+    """Convenience constructor for length in millimeters."""
+
+    def __new__(cls, mm: float):
+        emu = int(mm * Length._EMUS_PER_MM)
+        return Length.__new__(cls, emu)
+
+
+class Pt(Length):
+    """Convenience value class for specifying a length in points."""
+
+    def __new__(cls, points: float):
+        emu = int(points * Length._EMUS_PER_PT)
+        return Length.__new__(cls, emu)
+
+
+_T = TypeVar("_T")
+
+
+class lazyproperty(Generic[_T]):
+    """Decorator like @property, but evaluated only on first access.
+
+    Like @property, this can only be used to decorate methods having only a `self` parameter, and
+    is accessed like an attribute on an instance, i.e. trailing parentheses are not used. Unlike
+    @property, the decorated method is only evaluated on first access; the resulting value is
+    cached and that same value returned on second and later access without re-evaluation of the
+    method.
+
+    Like @property, this class produces a *data descriptor* object, which is stored in the __dict__
+    of the *class* under the name of the decorated method ('fget' nominally). The cached value is
+    stored in the __dict__ of the *instance* under that same name.
+
+    Because it is a data descriptor (as opposed to a *non-data descriptor*), its `__get__()` method
+    is executed on each access of the decorated attribute; the __dict__ item of the same name is
+    "shadowed" by the descriptor.
+
+    While this may represent a performance improvement over a property, its greater benefit may be
+    its other characteristics. One common use is to construct collaborator objects, removing that
+    "real work" from the constructor, while still only executing once. It also de-couples client
+    code from any sequencing considerations; if it's accessed from more than one location, it's
+    assured it will be ready whenever needed.
+
+    Loosely based on: https://stackoverflow.com/a/6849299/1902513.
+
+    A lazyproperty is read-only. There is no counterpart to the optional "setter" (or deleter)
+    behavior of an @property. This is critically important to maintaining its immutability and
+    idempotence guarantees. Attempting to assign to a lazyproperty raises AttributeError
+    unconditionally.
+
+    The parameter names in the methods below correspond to this usage example::
+
+        class Obj(object)
+
+            @lazyproperty
+            def fget(self):
+                return 'some result'
+
+        obj = Obj()
+
+    Not suitable for wrapping a function (as opposed to a method) because it is not callable.
+    """
+
+    def __init__(self, fget: Callable[..., _T]) -> None:
+        """*fget* is the decorated method (a "getter" function).
+
+        A lazyproperty is read-only, so there is only an *fget* function (a regular
+        @property can also have an fset and fdel function). This name was chosen for
+        consistency with Python's `property` class which uses this name for the
+        corresponding parameter.
+        """
+        # --- maintain a reference to the wrapped getter method
+        self._fget = fget
+        # --- and store the name of that decorated method
+        self._name = fget.__name__
+        # --- adopt fget's __name__, __doc__, and other attributes
+        functools.update_wrapper(self, fget)  # pyright: ignore
+
+    def __get__(self, obj: Any, type: Any = None) -> _T:
+        """Called on each access of 'fget' attribute on class or instance.
+
+        *self* is this instance of a lazyproperty descriptor "wrapping" the property
+        method it decorates (`fget`, nominally).
+
+        *obj* is the "host" object instance when the attribute is accessed from an
+        object instance, e.g. `obj = Obj(); obj.fget`. *obj* is None when accessed on
+        the class, e.g. `Obj.fget`.
+
+        *type* is the class hosting the decorated getter method (`fget`) on both class
+        and instance attribute access.
+        """
+        # --- when accessed on class, e.g. Obj.fget, just return this descriptor
+        # --- instance (patched above to look like fget).
+        if obj is None:
+            return self  # type: ignore
+
+        # --- when accessed on instance, start by checking instance __dict__ for
+        # --- item with key matching the wrapped function's name
+        value = obj.__dict__.get(self._name)
+        if value is None:
+            # --- on first access, the __dict__ item will be absent. Evaluate fget()
+            # --- and store that value in the (otherwise unused) host-object
+            # --- __dict__ value of same name ('fget' nominally)
+            value = self._fget(obj)
+            obj.__dict__[self._name] = value
+        return cast(_T, value)
+
+    def __set__(self, obj: Any, value: Any) -> None:
+        """Raises unconditionally, to preserve read-only behavior.
+
+        This decorator is intended to implement immutable (and idempotent) object
+        attributes. For that reason, assignment to this property must be explicitly
+        prevented.
+
+        If this __set__ method was not present, this descriptor would become a
+        *non-data descriptor*. That would be nice because the cached value would be
+        accessed directly once set (__dict__ attrs have precedence over non-data
+        descriptors on instance attribute lookup). The problem is, there would be
+        nothing to stop assignment to the cached value, which would overwrite the result
+        of `fget()` and break both the immutability and idempotence guarantees of this
+        decorator.
+
+        The performance with this __set__() method in place was roughly 0.4 usec per
+        access when measured on a 2.8GHz development machine; so quite snappy and
+        probably not a rich target for optimization efforts.
+        """
+        raise AttributeError("can't set attribute")

python_pptx2-2.13.0.dist-info/METADATA

@@ -0,0 +1,351 @@
+Metadata-Version: 2.4
+Name: python-pptx2
+Version: 2.13.0
+Summary: Create, read, and update PowerPoint 2007+ (.pptx) files. Fork of power-pptx / python-pptx, published as python-pptx2.
+Author: Matěj Štágl
+Author-email: stagl@wattlescript.org
+Maintainer: Matěj Štágl
+Maintainer-email: stagl@wattlescript.org
+License: MIT
+Project-URL: Changelog, https://github.com/lofcz/python-pptx2/blob/master/HISTORY.rst
+Project-URL: Documentation, https://github.com/lofcz/python-pptx2
+Project-URL: Homepage, https://github.com/lofcz/python-pptx2
+Project-URL: Issues, https://github.com/lofcz/python-pptx2/issues
+Project-URL: Repository, https://github.com/lofcz/python-pptx2
+Project-URL: Roadmap, https://github.com/lofcz/python-pptx2/blob/master/ROADMAP.md
+Project-URL: ParentFork, https://github.com/CodeHalwell/power-pptx
+Project-URL: Upstream, https://github.com/scanny/python-pptx
+Project-URL: UpstreamDocumentation, https://python-pptx.readthedocs.io/en/latest/
+Keywords: powerpoint,ppt,pptx,openxml,office,presentation
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Office Suites
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Description-Content-Type: text/x-rst
+License-File: LICENSE
+Requires-Dist: Pillow>=3.3.2
+Requires-Dist: XlsxWriter>=0.5.7
+Requires-Dist: lxml>=3.1.0
+Requires-Dist: typing_extensions>=4.9.0
+Provides-Extra: math
+Requires-Dist: latex2mathml>=3.0; extra == "math"
+Requires-Dist: mathml2omml>=0.0.2; extra == "math"
+Dynamic: license-file
+
+python-pptx2
+=============
+
+|PyPI| |PyPI - Python Versions| |CI| |License| |Documentation|
+
+.. |PyPI| image:: https://img.shields.io/pypi/v/python-pptx2.svg
+   :target: https://pypi.org/project/python-pptx2/
+   :alt: PyPI
+
+.. |PyPI - Python Versions| image:: https://img.shields.io/pypi/pyversions/python-pptx2.svg
+   :target: https://pypi.org/project/python-pptx2/
+   :alt: Python 3.9 – 3.13
+
+.. |CI| image:: https://github.com/lofcz/python-pptx2/actions/workflows/ci.yml/badge.svg
+   :target: https://github.com/lofcz/python-pptx2/actions/workflows/ci.yml
+   :alt: CI status
+
+.. |License| image:: https://img.shields.io/badge/license-MIT-blue.svg
+   :target: https://github.com/lofcz/python-pptx2/blob/master/LICENSE
+   :alt: MIT License
+
+.. |Documentation| image:: https://img.shields.io/badge/docs-github.com%2Flofcz%2Fpython--pptx2-blue.svg
+   :target: https://github.com/lofcz/python-pptx2
+   :alt: Documentation
+
+**PowerPoint decks from Python, that actually fit.**
+
+*python-pptx2* is a fork of `power-pptx`_ (Daniel Halwell) and, through
+it, of `python-pptx`_ by `Steve Canny`_. It is a Python library for
+creating, reading, and updating PowerPoint (.pptx) files, plus native
+LaTeX equations.
+
++----------------+----------------------------------------------------------+
+| **Package**    | ``python-pptx2`` on PyPI (imports as ``pptx2``)          |
++----------------+----------------------------------------------------------+
+| **Python**     | 3.9 – 3.13                                               |
++----------------+----------------------------------------------------------+
+| **License**    | MIT                                                      |
++----------------+----------------------------------------------------------+
+| **Source**     | https://github.com/lofcz/python-pptx2                    |
++----------------+----------------------------------------------------------+
+
+.. _`power-pptx`: https://github.com/CodeHalwell/power-pptx
+
+A typical use is generating a PowerPoint presentation from dynamic
+content such as a database query, an analytics output, an LLM payload,
+or a JSON spec — and downloading the generated .pptx file. It runs on
+any Python-capable platform (macOS, Linux, Windows) and does not
+require Microsoft PowerPoint to be installed or licensed.
+
+**Why this fork exists: space-aware authoring.**  The headline
+proposition is that text doesn't overflow its container and shapes
+don't slide off the edges of the slide.  Three layered tools used
+together catch ~all real-world layout issues:
+
+1. ``TextFrame.fit_text(...)`` measures with Pillow font metrics and
+   bakes a fitting size into the XML *before* save.
+2. ``text_frame.auto_size = MSO_AUTO_SIZE.TEXT_TO_FIT_SHAPE`` lets
+   PowerPoint shrink at render time as a fallback.
+3. ``slide.lint()`` catches what slipped through; ``auto_fix()`` (or
+   the one-call ``slide.tidy()``) nudges off-slide shapes back inside.
+
+Reach for python-pptx2 whenever the deck is generated dynamically and
+has to look right without manual cleanup.
+
+Installation
+------------
+
+Install from PyPI::
+
+    pip install python-pptx2
+
+Then in Python::
+
+    from pptx2 import Presentation
+
+``python-pptx2`` imports as ``pptx2`` so it can sit beside upstream
+``python-pptx`` (``pptx``) and the parent fork ``power-pptx``
+(``power_pptx``). To migrate from those packages, replace
+``from pptx import`` / ``from power_pptx import`` with
+``from pptx2 import``.
+
+Optional dependencies:
+
+* ``cairosvg`` — install only if you want ``add_svg_picture(...)`` to
+  auto-rasterise the PNG fallback.
+* ``pyyaml`` — install only if you want ``DesignTokens.from_yaml``.
+* ``python-pptx2[math]`` (``latex2mathml`` + ``mathml2omml``) — required
+  for ``slide.shapes.add_equation(...)`` / ``paragraph.add_math(...)``.
+* ``soffice`` (LibreOffice) on PATH — required for
+  ``Presentation.render_thumbnails()``.
+* ``pdftoppm`` (Poppler) or ``pypdfium2`` — required for the
+  PDF→PNG split path in the thumbnail renderer.
+
+Claude Code skill
+-----------------
+
+python-pptx2 ships a Claude Code skill alongside the library — pip-install
+the package and the skill files are already on disk inside it.  Install
+the skill into your local Claude Code skills directory with::
+
+    python -m pptx2.skill install
+
+This copies ``SKILL.md`` and the ``references/`` directory into
+``~/.claude/skills/python-pptx2/``.  Claude Code (and any compatible
+Claude Agent SDK harness) will pick it up automatically the next time
+it starts.
+
+Other useful commands::
+
+    # Print the skill source path inside the installed package
+    python -m pptx2.skill path
+
+    # Install into a custom directory
+    python -m pptx2.skill install --target /path/to/skills/python-pptx2
+
+    # Refuse to overwrite an existing install
+    python -m pptx2.skill install --no-overwrite
+
+The skill documents the headline space-aware-authoring workflow, the
+``BBox`` value object, the one-call ``add_text`` / ``add_arrow``
+helpers, the diagram recipes (``horizontal_pipeline``,
+``hub_and_spoke``, ``cycle``, ``decision_tree``,
+``comparison_columns``), and 16 focused reference docs covering
+effects, animations, transitions, theming, charts, tables, 3D,
+SmartArt, and rendering.  It also includes an *anti-patterns* section
+calling out the mistakes LLMs commonly make (mis-comparing wrapper
+objects, assuming ``add_connector`` puts an arrowhead on the line,
+sizing a diagram to a broken picture's bbox rather than its enclosing
+card, …).
+
+Quick start
+-----------
+
+A minimal end-to-end deck-generation pattern::
+
+    from pptx2 import Presentation, BBox, audit
+    from pptx2.diagrams import horizontal_pipeline
+    from pptx2.util import Inches
+
+    prs = Presentation()
+    slide = prs.slides.add_slide(prs.slide_layouts[5])
+    slide.shapes.title.text = "Pipeline overview"
+
+    horizontal_pipeline(
+        slide,
+        BBox.from_inches(0.5, 2.5, 9, 2.2),
+        steps=["Extract", "Classify", "Enrich", "Output"],
+        accent="#0B5CFF",
+    )
+
+    slide.shapes.add_text(
+        BBox.from_inches(0.5, 5.5, 9, 1),
+        text="Four-stage data pipeline.",
+        align="center", size_pt=14, color="#666666",
+    )
+
+    # Lint + safe auto-fixes
+    slide.tidy()
+
+    # Optional: full-deck audit
+    print(audit(prs).markdown())
+
+    prs.save("out.pptx")
+
+What's new in the fork
+----------------------
+
+The fork extends the 1.0.2 surface with features the upstream roadmap
+did not cover.  All additions are drop-in compatible — existing
+scripts keep working — and every new feature ships with a round-trip
+regression test.
+
+* **Space-aware authoring** — ``TextFrame.fit_text`` bakes a fitting
+  size before save; ``auto_size`` flags shrink at render time; the
+  layout linter reports text overflow / off-slide shapes /
+  collisions.  Three-tier safety so generated decks look right
+  without manual cleanup.
+
+* **Geometry and convenience helpers (v2.8)** — first-class
+  ``BBox`` value object with ``inset`` / ``split_h`` / ``split_v`` /
+  ``grid`` / ``contains`` / ``intersection``.  One-call
+  ``slide.shapes.add_text(bb, text=..., color="#0B5CFF",
+  align="center")`` collapses the historical seven-line styling
+  ritual.  Hex-string shortcuts (``shape.fill_hex("#0B5CFF")``,
+  ``shape.line_hex(...)``).  ``shape.set_text_preserving_format(new)``
+  for templated placeholders.
+
+* **Real arrows** —
+  ``slide.shapes.add_arrow(start=a, end=b, head="triangle",
+  color="#0B5CFF", inset_pt=6)`` produces a connector with an
+  arrowhead and auto-routed endpoints (mid-edge of target shape,
+  pulled back by ``inset_pt``).  No XML required.
+
+* **Diagram recipes** — ``horizontal_pipeline``, ``vertical_pipeline``,
+  ``hub_and_spoke``, ``cycle``, ``decision_tree``,
+  ``comparison_columns`` from ``pptx2.diagrams`` cover ~80% of
+  architecture-deck patterns.  Each takes a slide, a ``BBox``, and a
+  content spec.
+
+* **Picture and slide helpers** — ``picture.replace_with(builder,
+  padding=...)`` deletes a broken / sub-quality picture and calls a
+  builder in its place.  ``picture.enclosing_container()`` finds the
+  surrounding card so the rebuild fills the right area.
+  ``slide.tidy()`` is the one-call lint + safe auto-fix.
+  ``slide.find_empty_region(...)`` returns an unused area for
+  greenfield placement.
+
+* **Whole-deck audit** — ``pptx2.audit(prs)`` returns an
+  ``AuditReport`` with lint issues, broken pictures, empty slides,
+  uncommon-font warnings, and oversized-picture warnings.  Markdown
+  output for chat replies.
+
+* **Visual effects** — outer shadow, glow, soft edges, blur, and
+  reflection exposed as non-mutating proxies on every shape;
+  alpha-tinted colours (``RGBColor.alpha``); gradient fills with
+  ``linear`` / ``radial`` / ``rectangular`` / ``shape`` kinds and
+  mutable stops; line ends, caps, joins, and compound lines.
+
+* **Animations and transitions** — preset entrance / exit / emphasis
+  effects; motion-path presets; per-paragraph reveal; sequencing
+  context manager; per-slide and deck-wide transitions including
+  Morph and the other ``p14:`` extension transitions.
+
+* **JSON authoring** — ``pptx2.compose.from_spec(...)`` builds a
+  deck from a JSON-shaped spec; ``import_slide`` and
+  ``apply_template`` cover cross-presentation operations.
+
+* **Theme reader and writer** — read theme colours and fonts; write
+  fresh ``<a:srgbClr>`` values into the clrScheme; apply a theme
+  imported from a ``.potx``.
+
+* **Picture effects** — transparency, brightness, contrast, recolor
+  (grayscale, sepia, washout, duotone); native SVG embedding with
+  PNG fallback.
+
+* **Design-system layer** — ``DesignTokens`` (palette, typography,
+  shadows, radii, spacings) loadable from a dict, YAML, or a
+  ``.pptx``; a token-resolving ``shape.style`` facade; ``Grid`` /
+  ``Stack`` layout primitives; opinionated slide recipes
+  (``title``, ``bullet``, ``kpi``, ``quote``, ``image_hero``); a
+  starter pack of three example token sets.
+
+* **Shape-level building blocks** — ``add_kpi_card``,
+  ``add_progress_bar``, ``add_gauge``, ``add_status_pill``,
+  ``add_stat_strip``, ``add_article_card``: token-driven cards that
+  return small dataclasses exposing the constituent shapes for
+  further tweaks.
+
+* **Charting** — chart palette presets independent of
+  ``chart_style``; ten quick-layout presets; per-series gradient
+  and pattern fills.
+
+* **3D primitives and SmartArt text substitution** — bevel and
+  extrusion via ``shape.three_d``;
+  ``slide.smart_art[i].set_text([...])``.
+
+* **Slide thumbnails** — ``Presentation.render_thumbnails()`` or
+  ``pptx2.render.render_slides(prs, slides=[0, 1, 2],
+  name_template="slide-{:02d}.png")`` shells out to LibreOffice for
+  PNG previews.
+
+See ``HISTORY.rst`` for the full changelog and ``ROADMAP.md`` for the
+broader plan.
+
+Attribution
+-----------
+
+This project is a fork of `scanny/python-pptx`_, originally created and
+maintained by Steve Canny under the MIT License. The original
+copyright notice is preserved in ``LICENSE``. Sincere thanks to Steve
+and to all the upstream contributors whose work this project builds
+on.
+
+The fork was created to continue development of features the upstream
+roadmap did not cover (notably effects, transitions, animations, theme
+customization, and a higher-level design layer).  See ``HISTORY.rst``
+for the divergence point and changelog from there forward.
+
+This project is **not** affiliated with or endorsed by Microsoft.
+"PowerPoint" is a trademark of Microsoft Corporation; it is used here
+only descriptively to identify the file format the library reads and
+writes.
+
+Documentation
+-------------
+
+**Project site:** https://github.com/lofcz/python-pptx2 — the
+Astro/React documentation site (source in ``site/``), plus the
+Sphinx docs under ``docs/``.
+
+The Sphinx documentation lives under ``docs/`` and covers both the
+inherited 1.0.2 API and every feature added by the fork.  Browse
+`examples with screenshots`_ to get a quick idea what you can do.
+
+The bundled Claude Code skill (``python -m pptx2.skill install``)
+is the most up-to-date entry point for using the post-fork APIs.
+
+.. _`python-pptx`:
+   https://github.com/scanny/python-pptx
+.. _`scanny/python-pptx`:
+   https://github.com/scanny/python-pptx
+.. _`Steve Canny`:
+   https://github.com/scanny
+.. _`examples with screenshots`:
+   https://python-pptx.readthedocs.org/en/latest/user/quickstart.html