athena-python-pptx 0.1.62__tar.gz → 0.1.74__tar.gz

{athena_python_pptx-0.1.62 → athena_python_pptx-0.1.74}/.gitignore

@@ -12,7 +12,10 @@ eggs/
 .eggs/
 lib/
 lib64/
+# Top-level "parts/" is a setuptools artifact, but ``pptx/parts/`` is
+# our public package mirroring python-pptx's parts module — keep it.
 parts/
+!pptx/parts/
 sdist/
 var/
 wheels/

athena_python_pptx-0.1.74/API_PARITY_REPORT.md

@@ -0,0 +1,141 @@
+# API Parity Report: athena-python-pptx vs python-pptx
+
+**Generated:** 2026-05-11
+**athena-python-pptx version:** 0.1.74
+**python-pptx version:** 1.0.2
+**Test scripts:**
+  - `tests/test_python_pptx_api_parity.py` — 150 classes + 14 enums
+  - `tests/test_parity_class_hierarchy.py` — 70 behavioural smoke tests
+  - `tests/test_canonical_import_paths.py` — 57 docs-canonical import paths
+**Coverage:** 100% of upstream public classes + 100% of upstream enum members & values + 100% of canonical `from pptx.X import Y` paths from the python-pptx docs.
+
+---
+
+## Summary
+
+**0 unexpected missing, 0 unexpected extras, 0 param mismatches across all 147 tested classes — and 0 uncovered upstream public classes.** Every public class in `python-pptx` 1.0.2 has an importable counterpart at the matching module path in athena-python-pptx.
+
+v0.1.69 added 25 classes (Tranches A–E); v0.1.70 added another 18
+classes via Tranches F–I; v0.1.71 added another 22 classes via
+Tranches J–P; v0.1.72 closes the remaining 37 REST-internal classes
+via Tranches R–W:
+
+- **Tranche A** — units (Length / Pt / Cm / etc.), chart data
+  (CategoryChartData / XyChartData / BubbleChartData / Categories /
+  Category), GraphicFrame.
+- **Tranche B** — promoted chart sub-adapters (AxisTitle /
+  MajorGridlines / TickLabels / ChartFormat / Legend) from underscored
+  internal names to python-pptx-canonical public names.
+- **Tranche C** — ShadowFormat.
+- **Tranche D** — per-type Plot subclasses (BarPlot / LinePlot / etc.)
+  and Series subclasses (BarSeries / LineSeries / etc.) +
+  SeriesCollection.
+- **Tranche E** — DataLabels / DataLabel / Marker / Point /
+  CategoryPoints / XyPoints / BubblePoints.
+- **Tranche F** — Adjustment / AdjustmentCollection / AutoShapeType.
+- **Tranche G** — Movie / Video / _MediaFormat.
+- **Tranche H** — Placeholder subclasses (BasePlaceholder /
+  _BaseSlidePlaceholder / SlidePlaceholder / ChartPlaceholder /
+  PicturePlaceholder / TablePlaceholder / LayoutPlaceholder /
+  MasterPlaceholder / NotesSlidePlaceholder / PlaceholderGraphicFrame /
+  PlaceholderPicture).
+- **Tranche I** — FreeformBuilder drawing API.
+- **Tranche J** — shape collection containers (LayoutShapes /
+  MasterShapes / NotesSlideShapes / GroupShapes).
+- **Tranche K** — placeholder collection containers (BasePlaceholders /
+  LayoutPlaceholders / MasterPlaceholders / NotesSlidePlaceholders) +
+  SlidePlaceholders parity-test entry.
+- **Tranche L** — NotesMaster adapter + NotesSlide parity-test entry.
+- **Tranche M** — chart data points (CategoryDataPoint / XyDataPoint /
+  BubbleDataPoint) + CategoryLevel.
+- **Tranche N** — ChartData (alias) / ChartTitle (public name) /
+  DateAxis / Area3DPlot.
+- **Tranche O** — `BaseShape = Shape` alias for upstream's two-level
+  shape hierarchy.
+- **Tranche P** — SlideLayouts / SlideMasters parity-test entries
+  (`SlideLayouts.get_by_name` gains a `default` kwarg).
+- **Tranche R** — exception classes (`pptx.exc.PythonPptxError` /
+  `PackageNotFoundError` / `InvalidXmlError`).
+- **Tranche S** — XML proxy bases (`pptx.shared.ElementProxy` /
+  `ParentedElementProxy` / `PartElementProxy`), `pptx.types`
+  Protocols (`ProvidesExtents`, `ProvidesPart`), and
+  `pptx.shapes.Subshape`.
+- **Tranche T** — `pptx/parts/` package: 15 Part stubs at the
+  upstream-canonical paths (BaseSlidePart / SlidePart /
+  SlideLayoutPart / SlideMasterPart / NotesSlidePart /
+  NotesMasterPart / PresentationPart / CorePropertiesPart /
+  ImagePart / EmbeddedPackagePart / EmbeddedDocxPart /
+  EmbeddedPptxPart / EmbeddedXlsxPart / MediaPart / ChartPart).
+- **Tranche U** — Image (with real from_blob / sha1 / ext / size),
+  Package (raises on `.open()`), ChartWorkbook (no-op),
+  FontFiles / TextFitter (auto-fit stubs), PlotTypeInspector
+  (delegates to plot.chart_type), ShapeSpec TypedDict.
+- **Tranche V** — chart series-data classes (CategorySeriesData /
+  XySeriesData / BubbleSeriesData) + workbook writers
+  (CategoryWorkbookWriter / XyWorkbookWriter / BubbleWorkbookWriter).
+- **Tranche W** — `pptx.shapes.autoshape.Shape` parity entry.
+
+| Class | Status |
+|-------|--------|
+| FillFormat | PASS |
+| LineFormat | PASS |
+| RGBColor | PASS |
+| ColorFormat | PASS |
+| Font | PASS (`language_id` + `MSO_LANGUAGE_ID` enum added in v0.1.68) |
+| TextFrame | PASS (+47 SDK convenience extras, allowlisted) |
+| Paragraph | PASS (+30 SDK convenience extras, allowlisted) |
+| Run | PASS (+20 SDK convenience extras, allowlisted) |
+| Presentation | PASS (+SDK REST helpers: `upload`, `from_url`, `find_text`, etc.) |
+| Slide | PASS (+SDK REST helpers: `clone`, `notes`, `render`, etc.) |
+| Slides | PASS (+SDK REST helpers: `delete`, `get_by_id`, `find_by_title`, etc.) |
+| SlideLayout | PASS (+`index`) |
+| SlideMaster | PASS |
+| SlideShapes | PASS (+SDK REST helpers; `add_connector` accepts optional `begin_shape`/`end_shape`) |
+| Table | PASS (+SDK REST helpers + inherited `Shape.element` proxy) |
+| `_Cell` | PASS (+SDK REST helpers) |
+| PlaceholderFormat | PASS (+convenience type-check booleans + custom-prompt/transform fields) |
+| Chart | PASS (`category_axis` / `value_axis` / `legend` / `font` / `chart_style` added in v0.1.68; replaces `UnsupportedFeatureError` stubs) |
+| CategoryAxis | PASS (added v0.1.68 — local-state adapter; chart-axis round-trip patches are a follow-up) |
+| ValueAxis | PASS (added v0.1.68 — local-state adapter) |
+| Picture | PASS (added v0.1.68 — Shape subclass for `isinstance(shape, Picture)`) |
+| Connector | PASS (added v0.1.68 — Shape subclass; `begin_connect` / `end_connect` methods) |
+| GroupShape | PASS (added v0.1.68 — Shape subclass; `.shapes` is empty pending child-parenting) |
+| ActionSetting | PASS (real adapter in v0.1.68 over the SDK's `ClickAction`; replaces `UnsupportedFeatureError` stub) |
+| Hyperlink | PASS |
+
+## Intentionally Omitted (REST SDK Limitations)
+
+| Member | Reason |
+|--------|--------|
+| `*.element`, `*.part`, `*.ln`, `*.get_or_add_ln` | XML element / OPC package / direct DML XML access — REST SDK has no local XML or packages |
+| `FillFormat.from_fill_parent()` | Internal XML constructor |
+| `ColorFormat.from_colorchoice_parent()` | Internal XML constructor |
+| `Font.fill` | Font fill format (uncommon) |
+| `SlideLayout.background`, `SlideMaster.background` | Not yet exposed at layout / master level |
+| `SlideLayout.iter_cloneable_placeholders`, `SlideLayout.used_by_slides` | Placeholder cloning is server-side |
+| `SlideShapes.add_movie`, `add_ole_object`, `build_freeform` | Not implemented (uncommon) |
+| `Slide.follow_master_background` | XML-level inheritance flag — REST SDK abstracts this |
+| `Picture.image.blob` | Image bytes live in the studio's asset store — not materialized into Python |
+
+## SDK Additions (Documented Deviations)
+
+See `docs/API_PARITY_EXCEPTIONS.md` for the full list. Highlights:
+
+- **`Font.strike`, `Font.subscript`, `Font.superscript`** — real OOXML run properties python-pptx doesn't surface, useful for fidelity.
+- **`TableCell.font_bold`, `font_color_rgb`, `fill_color_rgb`** — agent-friendly RGB-tuple aliases.
+- **`GraphicFrame.cell()`, `.rows`, `.cols`** — passthroughs that delegate to `.table` for agent ergonomics.
+- **SDK-specific REST helpers** on `Presentation`, `Slide`, `Slides`, `SlideShapes`, `Table`, `_Cell` (e.g. `from_url`, `clone`, `render`, `delete`, `to_csv`).
+- **`Table.first_row` / `Table.last_row`** are booleans (look flags) per python-pptx; cell-list accessors are renamed to `get_first_row_cells()` etc.
+
+## Non-Standard Convenience Extras (Candidates for Future Cleanup)
+
+**Core classes** (FillFormat, LineFormat, RGBColor, ColorFormat, Font): clean — only OOXML-surface extras (`strike`, `subscript`, `superscript`).
+
+**TextFrame, Paragraph, Run, Table**: large blocks of string-manipulation / aggregation helpers (`to_dict()`, `word_count`, `capitalize()`, `to_csv()`, etc.). Additive, but candidates for future removal pass to tighten the drop-in contract.
+
+## How to Run
+
+```bash
+pip install python-pptx --target /tmp/pptx-standard
+python -m pytest tests/test_python_pptx_api_parity.py -v -s
+```