athena-python-pptx 0.1.0__tar.gz

athena_python_pptx-0.1.0/.gitignore

@@ -0,0 +1,46 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.nox/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Test artifacts
+tests/fixtures/exported_*.pptx
+tests/fixtures/~$*.pptx
+
+# OS
+.DS_Store

athena_python_pptx-0.1.0/PKG-INFO

@@ -0,0 +1,309 @@
+Metadata-Version: 2.4
+Name: athena-python-pptx
+Version: 0.1.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
+Project-URL: Repository, https://github.com/pptx-studio/python-sdk
+Project-URL: Issues, https://github.com/pptx-studio/python-sdk/issues
+Author: PPTX Studio Team
+License-Expression: MIT
+Keywords: api,powerpoint,pptx,presentation,python-pptx,sdk,slides
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business :: Office Suites
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: requests>=2.28.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: responses>=0.23; extra == 'dev'
+Requires-Dist: ruff>=0.1; extra == 'dev'
+Provides-Extra: e2e
+Requires-Dist: pytest>=7.0; extra == 'e2e'
+Requires-Dist: python-pptx>=0.6.21; extra == 'e2e'
+Description-Content-Type: text/markdown
+
+# athena-python-pptx
+
+A **drop-in replacement for [python-pptx](https://python-pptx.readthedocs.io/)** that connects to PPTX Studio for real-time collaboration.
+
+Use the exact same imports and API as python-pptx:
+
+```python
+from pptx import Presentation
+from pptx.util import Inches, Pt
+from pptx.enum.shapes import MSO_SHAPE
+from pptx.dml.color import RGBColor
+```
+
+## Features
+
+- **100% python-pptx compatible imports** - `from pptx import Presentation`
+- **Same API** - Familiar interface for developers and LLMs
+- **Real-time collaboration** - Changes sync instantly with web UI
+- **Remote-first** - Edits apply to live Yjs documents via API
+- **Clear error messages** - Unimplemented features raise helpful errors
+
+## Installation
+
+```bash
+pip install athena-python-pptx
+```
+
+## Quick Start
+
+```python
+from pptx import Presentation
+from pptx.util import Inches
+
+# Connect to an existing deck
+prs = Presentation(
+    deck_id="deck_123",
+    base_url="https://api.pptx-studio.com",
+    api_key="sk_live_..."
+)
+
+# Access slides
+slide = prs.slides[0]
+
+# Add a textbox
+tb = slide.shapes.add_textbox(
+    Inches(1), Inches(1),  # position
+    Inches(8), Inches(1)   # size
+)
+
+# Set text content
+tb.text_frame.text = "Hello from Python!"
+
+# Export to local file
+prs.save("output.pptx")
+```
+
+## Batching Operations
+
+For better performance, batch multiple operations into a single request:
+
+```python
+with prs.batch():
+    tb1 = slide.shapes.add_textbox(Inches(1), Inches(1), Inches(4), Inches(1))
+    tb1.text_frame.text = "First"
+
+    tb2 = slide.shapes.add_textbox(Inches(1), Inches(2), Inches(4), Inches(1))
+    tb2.text_frame.text = "Second"
+    # Both operations sent as one request when context exits
+```
+
+## API Reference
+
+### Presentation
+
+The main entry point for working with a deck.
+
+```python
+# Connect to existing deck
+prs = Presentation(deck_id, base_url, api_key=None)
+
+# Create new deck
+prs = Presentation.create(base_url, api_key=None)
+
+# Properties
+prs.deck_id         # Deck identifier
+prs.slides          # Slides collection
+prs.slide_width     # Width in EMU
+prs.slide_height    # Height in EMU
+
+# Methods
+prs.refresh()              # Sync with server
+prs.save(path)             # Export and download
+prs.save_to_bytes()        # Export as bytes
+prs.render_slide(index)    # Render slide as PNG
+```
+
+### Slides
+
+Collection of slides in the presentation.
+
+```python
+# Access slides
+slide = prs.slides[0]       # By index
+for slide in prs.slides:    # Iterate
+    print(slide.slide_id)
+len(prs.slides)             # Count
+
+# Add new slide
+new_slide = prs.slides.add_slide()
+```
+
+### Shapes
+
+Collection of shapes on a slide.
+
+```python
+# Access shapes
+shape = slide.shapes[0]
+for shape in slide.shapes:
+    print(shape.shape_id)
+
+# Add textbox
+tb = slide.shapes.add_textbox(left, top, width, height)
+```
+
+### Shape
+
+Individual shape on a slide.
+
+```python
+# Properties
+shape.shape_id      # Shape identifier
+shape.shape_type    # "text", "image", etc.
+shape.left          # X position (EMU)
+shape.top           # Y position (EMU)
+shape.width         # Width (EMU)
+shape.height        # Height (EMU)
+shape.rotation      # Rotation (degrees)
+shape.text_frame    # TextFrame (for text shapes)
+
+# Shortcuts
+shape.text          # Same as shape.text_frame.text
+
+# Methods
+shape.delete()      # Remove shape
+```
+
+### TextFrame
+
+Text content container.
+
+```python
+# Get/set text
+tf = shape.text_frame
+tf.text = "Hello"           # Set all text
+text = tf.text              # Get all text
+
+# Paragraphs
+for para in tf.paragraphs:
+    print(para.text)
+
+# Clear text
+tf.clear()
+```
+
+### Units
+
+Unit conversion helpers (python-pptx compatible).
+
+```python
+from pptx.util import Inches, Pt, Cm, Px, Emu
+
+# All return EMU values
+Inches(1)       # 914400 EMU
+Pt(12)          # 152400 EMU (12 points)
+Cm(2.54)        # ~914400 EMU (1 inch)
+Px(96)          # 914400 EMU (at 96 DPI)
+Emu(914400)     # Direct EMU value
+```
+
+## Error Handling
+
+The SDK raises specific exceptions for different error conditions:
+
+```python
+from pptx import (
+    UnsupportedFeatureError,  # Feature not yet implemented
+    RemoteError,              # Server rejected the request
+    ConflictError,            # Stale IDs (concurrent modification)
+    ValidationError,          # Invalid command parameters
+    ConnectionError,          # Network issues
+    AuthenticationError,      # Auth failed
+    ExportError,              # Export job failed
+    RenderError,              # Render job failed
+)
+```
+
+### Handling unsupported features
+
+```python
+try:
+    shape.fill.color = "red"
+except UnsupportedFeatureError as e:
+    print(f"Not yet supported: {e.feature}")
+```
+
+## Phase 1 Limitations
+
+The SDK is in Phase 1 with limited feature support:
+
+### Supported
+- Open deck by ID
+- List and iterate slides
+- Add textbox shapes
+- Set text content
+- Get/set shape position and size
+- Export to PPTX
+- Render slides to PNG
+- Batch operations
+
+### Not Yet Supported
+- Upload local PPTX files
+- Add images, charts, tables
+- Slide layouts and masters
+- Rich text formatting (bold, italic, etc.)
+- Shape fills and lines
+- Placeholder access
+- Notes slides
+
+Unsupported features raise `UnsupportedFeatureError` with a clear message.
+
+## Development
+
+```bash
+# Clone and install dev dependencies
+git clone https://github.com/pptx-studio/python-sdk
+cd python-sdk
+pip install -e ".[dev]"
+
+# Run unit tests
+pytest tests/ -v --ignore=tests/test_e2e_roundtrip.py
+
+# Type checking
+mypy pptx
+
+# Linting
+ruff check pptx
+```
+
+### Running E2E Tests
+
+End-to-end tests require a running PPTX Studio server and the `python-pptx` library.
+
+```bash
+# Install E2E dependencies
+pip install -e ".[e2e]"
+
+# Start the PPTX Studio server (from project root)
+pnpm dev:infra
+pnpm dev
+
+# Run E2E tests (in another terminal)
+PPTX_TEST_BASE_URL=http://localhost:3001 pytest tests/test_e2e_roundtrip.py -v
+```
+
+The E2E tests will:
+1. Create a PPTX file using python-pptx
+2. Upload it to the running server
+3. Modify it using our SDK
+4. Export and verify the changes
+
+## License
+
+MIT

athena_python_pptx-0.1.0/README.md

@@ -0,0 +1,274 @@
+# athena-python-pptx
+
+A **drop-in replacement for [python-pptx](https://python-pptx.readthedocs.io/)** that connects to PPTX Studio for real-time collaboration.
+
+Use the exact same imports and API as python-pptx:
+
+```python
+from pptx import Presentation
+from pptx.util import Inches, Pt
+from pptx.enum.shapes import MSO_SHAPE
+from pptx.dml.color import RGBColor
+```
+
+## Features
+
+- **100% python-pptx compatible imports** - `from pptx import Presentation`
+- **Same API** - Familiar interface for developers and LLMs
+- **Real-time collaboration** - Changes sync instantly with web UI
+- **Remote-first** - Edits apply to live Yjs documents via API
+- **Clear error messages** - Unimplemented features raise helpful errors
+
+## Installation
+
+```bash
+pip install athena-python-pptx
+```
+
+## Quick Start
+
+```python
+from pptx import Presentation
+from pptx.util import Inches
+
+# Connect to an existing deck
+prs = Presentation(
+    deck_id="deck_123",
+    base_url="https://api.pptx-studio.com",
+    api_key="sk_live_..."
+)
+
+# Access slides
+slide = prs.slides[0]
+
+# Add a textbox
+tb = slide.shapes.add_textbox(
+    Inches(1), Inches(1),  # position
+    Inches(8), Inches(1)   # size
+)
+
+# Set text content
+tb.text_frame.text = "Hello from Python!"
+
+# Export to local file
+prs.save("output.pptx")
+```
+
+## Batching Operations
+
+For better performance, batch multiple operations into a single request:
+
+```python
+with prs.batch():
+    tb1 = slide.shapes.add_textbox(Inches(1), Inches(1), Inches(4), Inches(1))
+    tb1.text_frame.text = "First"
+
+    tb2 = slide.shapes.add_textbox(Inches(1), Inches(2), Inches(4), Inches(1))
+    tb2.text_frame.text = "Second"
+    # Both operations sent as one request when context exits
+```
+
+## API Reference
+
+### Presentation
+
+The main entry point for working with a deck.
+
+```python
+# Connect to existing deck
+prs = Presentation(deck_id, base_url, api_key=None)
+
+# Create new deck
+prs = Presentation.create(base_url, api_key=None)
+
+# Properties
+prs.deck_id         # Deck identifier
+prs.slides          # Slides collection
+prs.slide_width     # Width in EMU
+prs.slide_height    # Height in EMU
+
+# Methods
+prs.refresh()              # Sync with server
+prs.save(path)             # Export and download
+prs.save_to_bytes()        # Export as bytes
+prs.render_slide(index)    # Render slide as PNG
+```
+
+### Slides
+
+Collection of slides in the presentation.
+
+```python
+# Access slides
+slide = prs.slides[0]       # By index
+for slide in prs.slides:    # Iterate
+    print(slide.slide_id)
+len(prs.slides)             # Count
+
+# Add new slide
+new_slide = prs.slides.add_slide()
+```
+
+### Shapes
+
+Collection of shapes on a slide.
+
+```python
+# Access shapes
+shape = slide.shapes[0]
+for shape in slide.shapes:
+    print(shape.shape_id)
+
+# Add textbox
+tb = slide.shapes.add_textbox(left, top, width, height)
+```
+
+### Shape
+
+Individual shape on a slide.
+
+```python
+# Properties
+shape.shape_id      # Shape identifier
+shape.shape_type    # "text", "image", etc.
+shape.left          # X position (EMU)
+shape.top           # Y position (EMU)
+shape.width         # Width (EMU)
+shape.height        # Height (EMU)
+shape.rotation      # Rotation (degrees)
+shape.text_frame    # TextFrame (for text shapes)
+
+# Shortcuts
+shape.text          # Same as shape.text_frame.text
+
+# Methods
+shape.delete()      # Remove shape
+```
+
+### TextFrame
+
+Text content container.
+
+```python
+# Get/set text
+tf = shape.text_frame
+tf.text = "Hello"           # Set all text
+text = tf.text              # Get all text
+
+# Paragraphs
+for para in tf.paragraphs:
+    print(para.text)
+
+# Clear text
+tf.clear()
+```
+
+### Units
+
+Unit conversion helpers (python-pptx compatible).
+
+```python
+from pptx.util import Inches, Pt, Cm, Px, Emu
+
+# All return EMU values
+Inches(1)       # 914400 EMU
+Pt(12)          # 152400 EMU (12 points)
+Cm(2.54)        # ~914400 EMU (1 inch)
+Px(96)          # 914400 EMU (at 96 DPI)
+Emu(914400)     # Direct EMU value
+```
+
+## Error Handling
+
+The SDK raises specific exceptions for different error conditions:
+
+```python
+from pptx import (
+    UnsupportedFeatureError,  # Feature not yet implemented
+    RemoteError,              # Server rejected the request
+    ConflictError,            # Stale IDs (concurrent modification)
+    ValidationError,          # Invalid command parameters
+    ConnectionError,          # Network issues
+    AuthenticationError,      # Auth failed
+    ExportError,              # Export job failed
+    RenderError,              # Render job failed
+)
+```
+
+### Handling unsupported features
+
+```python
+try:
+    shape.fill.color = "red"
+except UnsupportedFeatureError as e:
+    print(f"Not yet supported: {e.feature}")
+```
+
+## Phase 1 Limitations
+
+The SDK is in Phase 1 with limited feature support:
+
+### Supported
+- Open deck by ID
+- List and iterate slides
+- Add textbox shapes
+- Set text content
+- Get/set shape position and size
+- Export to PPTX
+- Render slides to PNG
+- Batch operations
+
+### Not Yet Supported
+- Upload local PPTX files
+- Add images, charts, tables
+- Slide layouts and masters
+- Rich text formatting (bold, italic, etc.)
+- Shape fills and lines
+- Placeholder access
+- Notes slides
+
+Unsupported features raise `UnsupportedFeatureError` with a clear message.
+
+## Development
+
+```bash
+# Clone and install dev dependencies
+git clone https://github.com/pptx-studio/python-sdk
+cd python-sdk
+pip install -e ".[dev]"
+
+# Run unit tests
+pytest tests/ -v --ignore=tests/test_e2e_roundtrip.py
+
+# Type checking
+mypy pptx
+
+# Linting
+ruff check pptx
+```
+
+### Running E2E Tests
+
+End-to-end tests require a running PPTX Studio server and the `python-pptx` library.
+
+```bash
+# Install E2E dependencies
+pip install -e ".[e2e]"
+
+# Start the PPTX Studio server (from project root)
+pnpm dev:infra
+pnpm dev
+
+# Run E2E tests (in another terminal)
+PPTX_TEST_BASE_URL=http://localhost:3001 pytest tests/test_e2e_roundtrip.py -v
+```
+
+The E2E tests will:
+1. Create a PPTX file using python-pptx
+2. Upload it to the running server
+3. Modify it using our SDK
+4. Export and verify the changes
+
+## License
+
+MIT