athena-python-pptx 0.1.8

Drop-in replacement for python-pptx that connects to PPTX Studio for real-time collaboration

athena-python-pptx

A drop-in replacement for python-pptx that connects to PPTX Studio for real-time collaboration.

Use the exact same imports and API as python-pptx:

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

pip install athena-python-pptx

Quick Start

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:

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.

# 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.

# 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.

# 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.

# 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.

# 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).

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:

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

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

# 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.

# 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