Metadata-Version: 2.4
Name: athena-python-pptx
Version: 0.1.8
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
