extraslide 0.1.0__tar.gz

extraslide-0.1.0/.gitignore

@@ -0,0 +1,45 @@
+# Output directory for manual testing
+output/
+
+# 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/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Testing
+.coverage
+htmlcov/
+.pytest_cache/
+.mypy_cache/
+
+# OS
+.DS_Store
+Thumbs.db

extraslide-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13

extraslide-0.1.0/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+All notable changes to the extraslide library will be documented in this file.
+
+## [0.1.0] - 2026-02-11
+
+### Added
+
+- Initial release (alpha)
+- **Pull**: Download Google Slides to a local folder with SML (Slide Markup Language) format
+  - Per-slide `content.sml` files in minimal XML
+  - `styles.json` - Style definitions (position, fill, stroke, text) per element
+  - `id_mapping.json` - Clean ID to Google object ID mapping
+  - `presentation.json` - Metadata (title, dimensions)
+  - `.pristine/` snapshot for diff comparison
+- **Diff**: Compare edited SML against pristine state and generate `batchUpdate` JSON
+- **Push**: Apply changes to Google Slides via the API
+- **Copy-based workflow**: Duplicate elements by repeating XML with same ID but only x,y coordinates (omit w,h to signal copy)
+  - Cross-slide and same-slide copy detection
+  - Translation-based positioning
+  - Full shape support including images with native dimensions
+  - Unique suffix generation to prevent ID collisions
+- **Supported operations**:
+  - Text replacement and modification
+  - Element copying with position translation
+  - Content alignment extraction and application
+- Async transport-based architecture with `GoogleSlidesTransport` and `LocalFileTransport` for testing
+- Golden file testing infrastructure

extraslide-0.1.0/CLAUDE.md

@@ -0,0 +1,178 @@
+## Overview
+
+Python library that converts Google Slides to/from SML (Slide Markup Language), an XML-based format optimized for LLM editing. Implements the pull/diff/push workflow.
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| `src/extraslide/client.py` | `SlidesClient` - main API with pull/diff/push |
+| `src/extraslide/slide_processor.py` | Builds render trees, extracts styles |
+| `src/extraslide/content_generator.py` | Generates minimal SML from render trees |
+| `src/extraslide/content_parser.py` | Parses SML content files |
+| `src/extraslide/content_diff.py` | Detects copies, calculates translations |
+| `src/extraslide/content_requests.py` | Generates batchUpdate requests |
+| `src/extraslide/style_extractor.py` | Extracts styles to JSON |
+| `src/extraslide/render_tree.py` | Visual containment hierarchy |
+| `src/extraslide/id_manager.py` | Clean ID assignment and mapping |
+| `src/extraslide/transport.py` | `Transport` ABC, `GoogleSlidesTransport`, `LocalFileTransport` |
+| `src/extraslide/classes.py` | Data classes for slide elements (Color, Fill, Stroke, etc.) |
+| `src/extraslide/credentials.py` | `CredentialsManager` for OAuth token handling |
+| `src/extraslide/units.py` | EMU/pt conversion utilities |
+
+## Documentation
+
+- `docs/copy-workflow.md` - Copy-based editing workflow (agent guide)
+- `docs/markup-syntax-design.md` - SML format specification
+- `docs/sml-reconciliation-spec.md` - How diff/push reconciles changes
+
+## CLI Interface
+
+```bash
+# Download a presentation to local folder
+python -m extraslide pull <presentation_url_or_id> [output_dir]
+# Output: ./<presentation_id>/ or specified output_dir
+
+# Options:
+#   --no-raw    Don't save raw API response to .raw/ folder
+
+# Preview changes (dry run)
+python -m extraslide diff <folder>
+# Output: batchUpdate JSON to stdout
+
+# Apply changes to Google Slides
+python -m extraslide push <folder>
+# Output: Success message with change count
+```
+
+Also works via `uvx extraslide pull/diff/push`.
+
+## Folder Structure
+
+After `pull`:
+```
+<presentation_id>/
+  presentation.json       # Metadata (title, presentation ID, dimensions)
+  id_mapping.json         # clean_id -> google_object_id
+  styles.json             # clean_id -> styles (position, fill, stroke, text)
+  slides/
+    01/content.sml        # Slide 1 content (minimal XML)
+    02/content.sml        # Slide 2 content
+    ...
+  .raw/
+    presentation.json     # Raw API response (for debugging)
+  .pristine/
+    presentation.zip      # Zip of entire folder for diff comparison
+```
+
+Edit `slides/NN/content.sml` files. To copy elements, duplicate XML with same ID but only x,y (omit w,h). See `docs/copy-workflow.md`.
+
+## Development
+
+```bash
+cd extraslide
+uv sync --all-extras
+uv run pytest tests/ -v
+uv run ruff check . && uv run ruff format .
+uv run mypy src/extraslide
+```
+
+## Testing
+
+Tests are in `tests/` and focus on:
+- `test_content_diff.py` - Copy detection and diff logic
+- `test_slide_processor.py` - Render tree building and SML generation
+- `test_transport.py` - Transport layer tests
+- `test_classes.py` - Data class conversions
+- `test_units.py` - Unit conversions
+
+### Golden File Testing
+
+Golden files enable testing without mocking or making real API calls:
+
+```
+tests/golden/
+  <presentation_id>/
+    presentation.json    # Raw API response
+```
+
+Use `LocalFileTransport` in tests:
+
+```python
+from extraslide import SlidesClient, LocalFileTransport
+
+@pytest.fixture
+def client():
+    transport = LocalFileTransport(Path("tests/golden"))
+    return SlidesClient(transport)
+
+@pytest.mark.asyncio
+async def test_pull(client, tmp_path):
+    files = await client.pull("simple_presentation", tmp_path)
+    assert (tmp_path / "simple_presentation" / "slides" / "01" / "content.sml").exists()
+```
+
+### Creating New Golden Files
+
+1. Create a Google Slides file with the features to test
+2. Pull it: `python -m extraslide pull <url>` (raw files saved by default)
+3. Copy `.raw/presentation.json` to `tests/golden/<name>/presentation.json`
+4. Verify the output looks correct
+5. Commit the golden files
+
+## Architecture Notes
+
+### Transport-Based Design
+
+```
+┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
+│ SlidesClient    │────▶│ Transport        │────▶│ Google API /    │
+│ (orchestration) │     │ (data fetching)  │     │ Local Files     │
+└─────────────────┘     └──────────────────┘     └─────────────────┘
+```
+
+- `Transport` is an abstract base class with `get_presentation()`, `batch_update()`, `close()`
+- `GoogleSlidesTransport` - Production: makes real API calls via `httpx`
+- `LocalFileTransport` - Testing: reads from local golden files
+- Access token is a transport concern, not a client concern
+
+### Pull Flow
+
+1. **Fetch** - `transport.get_presentation()` gets full presentation JSON
+2. **Process** - `slide_processor.process_presentation()` builds render trees
+3. **Extract styles** - Store styles (fill, stroke, text) in `styles.json`
+4. **Generate SML** - `content_generator` creates minimal XML per slide
+5. **Write** - Save files to `slides/NN/content.sml`
+6. **Save raw** - Optionally save `.raw/presentation.json`
+7. **Pristine copy** - Create `.pristine/presentation.zip` (zip of entire folder)
+
+### Diff/Push Flow
+
+1. **Read pristine** - Extract files from `.pristine/presentation.zip`
+2. **Read current** - Read `slides/NN/content.sml` files
+3. **Parse both** - `content_parser` converts SML to internal structures
+4. **Diff** - `content_diff.diff_presentation()` detects changes and copies
+5. **Generate requests** - `content_requests.generate_batch_requests()` creates API requests
+6. **Push** (if not dry-run) - Send to `transport.batch_update()`
+
+### Copy Detection
+
+The copy-based workflow detects copies by:
+- Same element ID appearing multiple times
+- Copy has x,y but **omits w,h** (signals "copy from original")
+- System duplicates the element and moves to new position
+
+### Key Design Decisions
+
+- **Async-first**: All transport and client methods are async
+- **Single API call for pull**: Slides API returns everything in one call
+- **save_raw=True default**: Always saves raw responses for debugging/testing
+- **No mocking in tests**: Use `LocalFileTransport` with golden files instead
+- **Per-slide files**: Each slide is a separate content.sml for easier editing
+- **Styles in JSON**: Styles stored separately, auto-applied on copy
+
+### Dependencies
+
+- `httpx` - Async HTTP client for API calls
+- `certifi` - SSL certificates
+- `keyring` - OS keyring for token caching (via credentials.py)

extraslide-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Sripathi Krishnan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

extraslide-0.1.0/PKG-INFO

@@ -0,0 +1,272 @@
+Metadata-Version: 2.4
+Name: extraslide
+Version: 0.1.0
+Summary: A Python library that simplifies editing Google Slides through an HTML-like abstraction
+Project-URL: Homepage, https://github.com/think41/extrasuite
+Project-URL: Documentation, https://extrasuite.think41.com
+Project-URL: Repository, https://github.com/think41/extrasuite
+Project-URL: Issues, https://github.com/think41/extrasuite/issues
+Author-email: Sripathi Krishnan <Sripathi.Krishnan@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+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: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: extrasuite>=0.4.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pyfpgrowth>=1.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0.0; extra == 'dev'
+Requires-Dist: pre-commit>=3.0.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# extraslide
+
+A Python library that converts Google Slides to/from SML (Slide Markup Language) - an XML-based format optimized for AI agent editing.
+
+## Overview
+
+extraslide enables AI agents (Claude Code, Codex, etc.) to read and edit Google Slides through a simple workflow:
+
+1. **Pull** - Download a presentation as editable SML files
+2. **Edit** - Agent modifies the SML based on user instructions
+3. **Diff** - Preview changes before applying (dry run)
+4. **Push** - Apply changes to Google Slides
+
+The library handles all the complexity of the Google Slides API - agents just edit XML.
+
+## Installation
+
+```bash
+pip install extraslide
+# or
+uvx extraslide --help
+```
+
+## Authentication
+
+extraslide uses [extrasuite](https://github.com/think41/extrasuite) for authentication. Each user gets a dedicated service account:
+
+```bash
+# One-time login (opens browser)
+uvx extrasuite login
+
+# Share your Google Slides file with the service account email shown after login
+```
+
+## The Pull-Edit-Diff-Push Workflow
+
+### Step 1: Pull
+
+Download a presentation to a local folder:
+
+```bash
+uvx extraslide pull "https://docs.google.com/presentation/d/1abc.../edit"
+```
+
+This creates a folder structure:
+
+```
+1abc.../
+  presentation.json       # Metadata (title, ID, dimensions)
+  id_mapping.json         # clean_id -> google_object_id mapping
+  styles.json             # Styles for each element (position, fill, stroke, text)
+  slides/
+    01/content.sml        # Slide 1 content
+    02/content.sml        # Slide 2 content
+    ...
+  .pristine/
+    presentation.zip      # Original state for diff comparison
+  .raw/
+    presentation.json     # Raw API response (for debugging)
+```
+
+### Step 2: Edit
+
+The agent edits `slides/NN/content.sml` files based on user instructions. SML uses a minimal XML syntax:
+
+```xml
+<Slide>
+  <TextBox id="e1" x="100" y="50" w="500" h="80">
+    <P><T>Quarterly Report</T></P>
+  </TextBox>
+  <Rect id="e2" x="50" y="200" w="300" h="150"/>
+</Slide>
+```
+
+Common edits:
+- Change text content inside `<T>` tags
+- Modify positions (`x`, `y`) or sizes (`w`, `h`)
+- Add/delete elements
+- Copy elements (duplicate with same ID, new position, omit w/h)
+
+See [copy-workflow.md](./docs/copy-workflow.md) for the copy-based editing guide.
+
+### Step 3: Diff (Preview)
+
+See what changes will be applied without modifying the original:
+
+```bash
+uvx extraslide diff 1abc.../
+```
+
+This compares the current `slides/` content against the `.pristine/` copy and outputs the Google Slides API requests that would be generated. No API calls are made.
+
+### Step 4: Push
+
+Apply the changes to Google Slides:
+
+```bash
+uvx extraslide push 1abc.../
+```
+
+The library sends a `batchUpdate` request to the Google Slides API. All edits appear in Google Drive version history with proper attribution.
+
+## SML Format
+
+Each slide is stored as a separate `content.sml` file with minimal XML:
+
+```xml
+<Slide>
+  <TextBox id="e1" x="100" y="50" w="500" h="80">
+    <P><T>Title text</T></P>
+  </TextBox>
+  <Rect id="e2" x="50" y="200" w="300" h="150"/>
+  <Group id="g1" x="400" y="100">
+    <Ellipse id="e3" x="0" y="0" w="50" h="50"/>
+    <Ellipse id="e4" x="60" y="0" w="50" h="50"/>
+  </Group>
+</Slide>
+```
+
+### Elements
+
+| Element | Description |
+|---------|-------------|
+| `<TextBox>` | Text container with paragraphs |
+| `<Rect>`, `<Ellipse>`, `<RoundRect>` | Basic shapes |
+| `<Line>` | Lines and connectors |
+| `<Image>` | Images |
+| `<Table>` | Tables with `<Row>` and `<Cell>` |
+| `<Group>` | Grouped elements (children use relative positions) |
+| `<Video>` | Embedded videos |
+| `<SheetsChart>` | Linked Google Sheets charts |
+
+### Text Content
+
+Text uses a paragraph (`<P>`) and text run (`<T>`) structure:
+
+```xml
+<TextBox id="e1" x="50" y="100" w="400" h="200">
+  <P><T>Regular text </T><T>more text</T></P>
+  <P><T>Second paragraph</T></P>
+</TextBox>
+```
+
+### Positions and Sizes
+
+All positions (`x`, `y`) and sizes (`w`, `h`) are in points:
+
+```xml
+<Rect id="e1" x="100" y="200" w="300" h="150"/>
+```
+
+For elements inside groups, positions are relative to the group's origin.
+
+### Copying Elements
+
+To copy an element, duplicate its XML with:
+- Same `id` as the source element
+- New `x`, `y` position
+- **Omit `w` and `h`** (this signals a copy)
+
+```xml
+<!-- Original -->
+<Rect id="e1" x="100" y="100" w="200" h="100"/>
+
+<!-- Copy (omit w/h to signal copy) -->
+<Rect id="e1" x="400" y="100"/>
+```
+
+See [copy-workflow.md](./docs/copy-workflow.md) for details.
+
+## CLI Reference
+
+```bash
+# Pull a presentation
+uvx extraslide pull <url_or_id> [output_dir]
+uvx extraslide pull "https://docs.google.com/presentation/d/1abc.../edit"
+uvx extraslide pull "https://docs.google.com/presentation/d/1abc.../edit" ./my-folder
+
+# Preview changes (dry run)
+uvx extraslide diff <folder>
+uvx extraslide diff ./1abc.../
+
+# Apply changes
+uvx extraslide push <folder>
+uvx extraslide push ./1abc.../
+```
+
+Also works as a Python module:
+```bash
+python -m extraslide pull ...
+python -m extraslide diff ...
+python -m extraslide push ...
+```
+
+## Important Notes
+
+### Re-pull After Push
+
+After pushing changes, the local SML becomes stale. Always re-pull before making more edits:
+
+```bash
+uvx extraslide push ./1abc.../
+uvx extraslide pull "https://docs.google.com/presentation/d/1abc.../edit"  # Re-pull!
+# Now safe to edit again
+```
+
+### What Can Be Edited
+
+- Text content and styling
+- Shape properties (fill, stroke, position, size)
+- Add/delete slides
+- Add/delete elements
+- Copy existing elements
+- Tables (content and basic styling)
+- Images (can reference existing, limited creation support)
+- Charts (read-only, linked to source spreadsheet)
+
+### Styles
+
+Element styles (fill, stroke, text formatting) are stored in `styles.json` and automatically applied when copying elements. You don't need to specify styles in the SML - just copy an element and modify the text/position.
+
+## Documentation
+
+- [Copy-Based Editing Guide](./docs/copy-workflow.md) - How to copy and modify elements
+- [SML Syntax Specification](./docs/markup-syntax-design.md) - Full format reference
+
+## Requirements
+
+- Python 3.10+
+- Google Slides file shared with your service account
+
+## Project Status
+
+**Alpha** - The library is functional but still evolving. SML format and CLI may change.
+
+## License
+
+[MIT License](LICENSE)