athena-python-pptx 0.1.77__tar.gz → 0.2.0__tar.gz

{athena_python_pptx-0.1.77 → athena_python_pptx-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: athena-python-pptx
-Version: 0.1.77
+Version: 0.2.0
 Summary: Drop-in replacement for python-pptx that connects to PPTX Studio for real-time collaboration
 Project-URL: Homepage, https://github.com/pptx-studio/python-sdk
 Project-URL: Documentation, https://docs.pptx-studio.com/sdk/python
@@ -57,6 +57,108 @@ from pptx.shapes.autoshape import Shape
 from pptx.text.text import Font, TextFrame
 ```
 
+---
+
+## ⚠️ Package conflict with `python-pptx`
+
+**`athena-python-pptx` and the upstream `python-pptx` package cannot coexist
+in the same Python environment.** Both distribute files under the top-level
+`pptx` import. `pip install athena-python-pptx` does *not* automatically
+uninstall `python-pptx` — instead, pip silently overwrites the conflicting
+files. Both distributions remain registered as "installed", but the actual
+`pptx` module on disk ends up as a corrupted mix of files from both wheels.
+The result is an environment that imports successfully but raises
+`AttributeError` on calls that exist in one library but not the other.
+
+The only safe configuration is one library per environment; always use an
+isolated virtualenv / venv to keep them apart.
+
+### Why this happens
+
+This SDK is designed to be a drop-in replacement for `python-pptx` — every
+`from pptx import …` statement should resolve to a remote-aware proxy class
+that talks to PPTX Studio instead of a local OOXML adapter. The only way to
+preserve that contract is to shadow the `pptx` top-level package, which
+forces a hard either/or choice at install time. There is no "use both at
+once" mode.
+
+### Workaround: separate virtualenvs
+
+If you need both libraries (for example, to read a stock `.pptx` from disk
+*and* mutate an Athena-hosted deck in the same workflow), put each in its
+own virtualenv and shuttle data between them as bytes / JSON / inline
+arguments — never both in the same `sys.path`.
+
+```bash
+# Venv 1: stock python-pptx for local file I/O
+python -m venv .venv-stock
+source .venv-stock/bin/activate
+pip install python-pptx
+deactivate
+
+# Venv 2: athena-python-pptx for remote authoring
+python -m venv .venv-athena
+source .venv-athena/bin/activate
+pip install athena-python-pptx
+deactivate
+```
+
+### Recipe: "read a stock .pptx, write to Athena"
+
+The most common cross-venv pipeline is to extract content from a local
+`.pptx` with the stock library, then push it into an Athena deck through
+this SDK. Two patterns work:
+
+**Pattern A — upload the file directly.** If the local PPTX is already in
+the shape you want, skip stock python-pptx entirely:
+
+```python
+# In the .venv-athena venv:
+from pptx import Presentation
+prs = Presentation.upload("local_deck.pptx")  # ingests through Athena
+# …mutate via the SDK, then prs.save("out.pptx") to download.
+```
+
+**Pattern B — extract with stock, author with Athena.** When you need to
+read structure (e.g., pull bullet text out of an existing deck) before
+rewriting it, run two scripts:
+
+```python
+# extract.py — runs in .venv-stock
+from pptx import Presentation
+import json
+
+prs = Presentation("local_deck.pptx")
+payload = [
+    {"slide": i, "title": (s.shapes.title.text if s.shapes.title else None)}
+    for i, s in enumerate(prs.slides)
+]
+with open("/tmp/extract.json", "w") as f:
+    json.dump(payload, f)
+```
+
+```python
+# author.py — runs in .venv-athena
+from pptx import Presentation
+import json
+
+with open("/tmp/extract.json") as f:
+    payload = json.load(f)
+
+prs = Presentation.create(name="Imported deck")
+for entry in payload:
+    slide = prs.slides.add_slide()
+    if entry["title"] and slide.shapes.title is not None:
+        slide.shapes.title.text = entry["title"]
+prs.close()
+```
+
+Invoke them from a shell wrapper that activates the right venv for each
+step. Cross-venv state must always travel through a serialized intermediate
+(JSON, pickled bytes, a shared file) — never via shared Python imports.
+
+---
+
 ### Parity status (v0.1.74)
 
 | Dimension | Coverage |

{athena_python_pptx-0.1.77 → athena_python_pptx-0.2.0}/README.md

@@ -17,6 +17,108 @@ from pptx.shapes.autoshape import Shape
 from pptx.text.text import Font, TextFrame
 ```
 
+---
+
+## ⚠️ Package conflict with `python-pptx`
+
+**`athena-python-pptx` and the upstream `python-pptx` package cannot coexist
+in the same Python environment.** Both distribute files under the top-level
+`pptx` import. `pip install athena-python-pptx` does *not* automatically
+uninstall `python-pptx` — instead, pip silently overwrites the conflicting
+files. Both distributions remain registered as "installed", but the actual
+`pptx` module on disk ends up as a corrupted mix of files from both wheels.
+The result is an environment that imports successfully but raises
+`AttributeError` on calls that exist in one library but not the other.
+
+The only safe configuration is one library per environment; always use an
+isolated virtualenv / venv to keep them apart.
+
+### Why this happens
+
+This SDK is designed to be a drop-in replacement for `python-pptx` — every
+`from pptx import …` statement should resolve to a remote-aware proxy class
+that talks to PPTX Studio instead of a local OOXML adapter. The only way to
+preserve that contract is to shadow the `pptx` top-level package, which
+forces a hard either/or choice at install time. There is no "use both at
+once" mode.
+
+### Workaround: separate virtualenvs
+
+If you need both libraries (for example, to read a stock `.pptx` from disk
+*and* mutate an Athena-hosted deck in the same workflow), put each in its
+own virtualenv and shuttle data between them as bytes / JSON / inline
+arguments — never both in the same `sys.path`.
+
+```bash
+# Venv 1: stock python-pptx for local file I/O
+python -m venv .venv-stock
+source .venv-stock/bin/activate
+pip install python-pptx
+deactivate
+
+# Venv 2: athena-python-pptx for remote authoring
+python -m venv .venv-athena
+source .venv-athena/bin/activate
+pip install athena-python-pptx
+deactivate
+```
+
+### Recipe: "read a stock .pptx, write to Athena"
+
+The most common cross-venv pipeline is to extract content from a local
+`.pptx` with the stock library, then push it into an Athena deck through
+this SDK. Two patterns work:
+
+**Pattern A — upload the file directly.** If the local PPTX is already in
+the shape you want, skip stock python-pptx entirely:
+
+```python
+# In the .venv-athena venv:
+from pptx import Presentation
+prs = Presentation.upload("local_deck.pptx")  # ingests through Athena
+# …mutate via the SDK, then prs.save("out.pptx") to download.
+```
+
+**Pattern B — extract with stock, author with Athena.** When you need to
+read structure (e.g., pull bullet text out of an existing deck) before
+rewriting it, run two scripts:
+
+```python
+# extract.py — runs in .venv-stock
+from pptx import Presentation
+import json
+
+prs = Presentation("local_deck.pptx")
+payload = [
+    {"slide": i, "title": (s.shapes.title.text if s.shapes.title else None)}
+    for i, s in enumerate(prs.slides)
+]
+with open("/tmp/extract.json", "w") as f:
+    json.dump(payload, f)
+```
+
+```python
+# author.py — runs in .venv-athena
+from pptx import Presentation
+import json
+
+with open("/tmp/extract.json") as f:
+    payload = json.load(f)
+
+prs = Presentation.create(name="Imported deck")
+for entry in payload:
+    slide = prs.slides.add_slide()
+    if entry["title"] and slide.shapes.title is not None:
+        slide.shapes.title.text = entry["title"]
+prs.close()
+```
+
+Invoke them from a shell wrapper that activates the right venv for each
+step. Cross-venv state must always travel through a serialized intermediate
+(JSON, pickled bytes, a shared file) — never via shared Python imports.
+
+---
+
 ### Parity status (v0.1.74)
 
 | Dimension | Coverage |