powerpoint-engine-api 2.0.0__py3-none-any.whl

powerpoint_engine/__init__.py

@@ -0,0 +1,30 @@
+"""PowerPoint Engine API Python SDK
+
+A Python client for the PowerPoint Engine API (https://powerpointengine.io):
+generate .pptx from Markdown or a template, edit/merge/replace in existing
+decks, and convert PPTX to PDF.
+"""
+
+__version__ = "2.0.0"
+__author__ = "PowerPoint Engine API"
+__email__ = "support@powerpointengine.io"
+
+from .client import PowerPointEngine
+from .exceptions import (
+    PowerPointEngineError,
+    AuthenticationError,
+    ValidationError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+)
+
+__all__ = [
+    "PowerPointEngine",
+    "PowerPointEngineError",
+    "AuthenticationError",
+    "ValidationError",
+    "NotFoundError",
+    "RateLimitError",
+    "ServerError",
+]

powerpoint_engine/client.py

@@ -0,0 +1,221 @@
+"""PowerPoint Engine API client.
+
+Thin wrapper over the public REST API at https://powerpointengine.io.
+All methods return the parsed JSON response; generated files are fetched
+from the signed ``downloadUrl`` in the result (valid for 24 hours).
+"""
+
+import json
+import mimetypes
+import os
+from typing import Any, Dict, List, Optional
+
+import requests
+
+from .exceptions import (
+    AuthenticationError,
+    NotFoundError,
+    PowerPointEngineError,
+    RateLimitError,
+    ServerError,
+    ValidationError,
+)
+
+DEFAULT_BASE_URL = "https://powerpointengine.io"
+
+PPTX_MIME = (
+    "application/vnd.openxmlformats-officedocument.presentationml.presentation"
+)
+
+
+def _file_part(path):
+    """(filename, handle, mime) tuple so the API sees the right content type."""
+    mime = mimetypes.guess_type(path)[0] or PPTX_MIME
+    return (os.path.basename(path), open(path, "rb"), mime)
+
+
+class PowerPointEngine:
+    """Client for the PowerPoint Engine API.
+
+    Args:
+        session_id: Optional account id (the ``sessionId`` the dashboard
+            shows). Ties generations to your account for credits and history;
+            anonymous calls work but return watermarked files.
+        base_url: API origin (default: https://powerpointengine.io).
+        timeout: Per-request timeout in seconds.
+    """
+
+    def __init__(
+        self,
+        session_id: Optional[str] = None,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: int = 120,
+    ):
+        self.session_id = session_id
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.session = requests.Session()
+        self.session.headers["User-Agent"] = "powerpoint-engine-python/2.0.0"
+
+    # -- generation ---------------------------------------------------------
+
+    def generate(
+        self,
+        markup: Optional[str] = None,
+        template: Optional[Dict[str, Any]] = None,
+        theme: str = "corporate",
+        brand: Optional[Dict[str, str]] = None,
+        font: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Generate a .pptx from markup text or a structured template.
+
+        Exactly one of ``markup`` / ``template`` is required. ``markup`` is
+        the Markdown dialect (``# title``, ``## slide``, bullets, tables,
+        ```` ```chart ```` blocks). ``brand`` is a dict of 6-hex colors like
+        ``{"primary": "#E4002B"}``; ``font`` overrides the theme font.
+        """
+        if not markup and not template:
+            raise ValueError("either markup or template is required")
+        body: Dict[str, Any] = {"theme": theme}
+        if markup:
+            body["markup"] = markup
+        if template:
+            body["template"] = template
+        if brand:
+            body["brand"] = brand
+        if font:
+            body["font"] = font
+        if self.session_id:
+            body["sessionId"] = self.session_id
+        return self._request_json("/api/powerpoint/generate", body)
+
+    # -- operations on an existing .pptx ------------------------------------
+
+    def replace(
+        self,
+        file_path: str,
+        replacements: Dict[str, str],
+        replace_mode: str = "placeholders",
+        images: Optional[Dict[str, str]] = None,
+    ) -> Dict[str, Any]:
+        """Replace text (and optionally images) in your own .pptx in place.
+
+        ``replace_mode`` is ``placeholders`` ({{key}} tokens) or ``objects``
+        (match shapes by name). ``images`` maps a shape name or alt text to a
+        local image path; position, size and effects are kept.
+        """
+        data = {
+            "replacements": json.dumps(replacements),
+            "replaceMode": replace_mode,
+        }
+        files = {"file": _file_part(file_path)}
+        try:
+            if images:
+                for shape_name, image_path in images.items():
+                    files[f"image:{shape_name}"] = _file_part(image_path)
+            return self._request_multipart("/api/powerpoint/replace", data, files)
+        finally:
+            for part in files.values():
+                part[1].close()
+
+    def edit(self, file_path: str, operations: List[Dict[str, Any]]) -> Dict[str, Any]:
+        """Duplicate / delete / move slides in your own .pptx.
+
+        ``operations`` apply sequentially, slide numbers are 1-based, e.g.::
+
+            [{"op": "duplicate", "slide": 2},
+             {"op": "delete", "slide": 5},
+             {"op": "move", "slide": 3, "to": 1}]
+        """
+        data = {"operations": json.dumps(operations)}
+        part = _file_part(file_path)
+        try:
+            return self._request_multipart(
+                "/api/powerpoint/edit", data, {"file": part}
+            )
+        finally:
+            part[1].close()
+
+    def merge(self, file_paths: List[str]) -> Dict[str, Any]:
+        """Merge 2-5 decks into one; each keeps its own design."""
+        if not 2 <= len(file_paths) <= 5:
+            raise ValueError("merge takes 2 to 5 files")
+        parts = [_file_part(p) for p in file_paths]
+        try:
+            files = [("files", part) for part in parts]
+            return self._request_multipart("/api/powerpoint/merge", {}, files)
+        finally:
+            for part in parts:
+                part[1].close()
+
+    def to_pdf(self, file_path: str) -> Dict[str, Any]:
+        """Convert a .pptx to PDF; result has a signed PDF downloadUrl."""
+        part = _file_part(file_path)
+        try:
+            return self._request_multipart(
+                "/api/powerpoint/pdf", {}, {"file": part}
+            )
+        finally:
+            part[1].close()
+
+    def translate(self, file_path: str, target_lang: str) -> Dict[str, Any]:
+        """Translate all text in a .pptx in place (layout preserved)."""
+        data = {"targetLang": target_lang}
+        part = _file_part(file_path)
+        try:
+            return self._request_multipart(
+                "/api/powerpoint/translate", data, {"file": part}
+            )
+        finally:
+            part[1].close()
+
+    # -- helpers -------------------------------------------------------------
+
+    def download(self, result: Dict[str, Any], to_path: str) -> str:
+        """Download the generated file from a response's downloadUrl."""
+        url = (result.get("result") or {}).get("downloadUrl") or result.get(
+            "downloadUrl"
+        )
+        if not url:
+            raise ValueError("response has no downloadUrl")
+        response = requests.get(url, timeout=self.timeout)
+        response.raise_for_status()
+        with open(to_path, "wb") as fh:
+            fh.write(response.content)
+        return to_path
+
+    def _request_json(self, endpoint: str, body: Dict[str, Any]) -> Dict[str, Any]:
+        response = self.session.post(
+            self.base_url + endpoint, json=body, timeout=self.timeout
+        )
+        return self._parse(response)
+
+    def _request_multipart(self, endpoint: str, data, files) -> Dict[str, Any]:
+        if self.session_id:
+            data = dict(data)
+            data["sessionId"] = self.session_id
+        response = self.session.post(
+            self.base_url + endpoint, data=data, files=files, timeout=self.timeout
+        )
+        return self._parse(response)
+
+    def _parse(self, response: requests.Response) -> Dict[str, Any]:
+        try:
+            payload = response.json()
+        except ValueError:
+            payload = {"error": response.text[:500]}
+        if response.ok:
+            return payload
+        message = payload.get("error", "Unknown error")
+        status = response.status_code
+        if status == 401:
+            raise AuthenticationError(message, status)
+        if status == 400:
+            raise ValidationError(message, status)
+        if status == 404:
+            raise NotFoundError(message, status)
+        if status == 429:
+            raise RateLimitError(message, status)
+        if status >= 500:
+            raise ServerError(message, status)
+        raise PowerPointEngineError(message, status)

powerpoint_engine/exceptions.py

@@ -0,0 +1,59 @@
+"""PowerPoint Engine API Exceptions"""
+
+from typing import Optional
+
+
+class PowerPointEngineError(Exception):
+    """Base exception for PowerPoint Engine API errors."""
+    
+    def __init__(
+        self,
+        message: str,
+        status_code: Optional[int] = None,
+        request_id: Optional[str] = None,
+    ):
+        """Initialize the exception.
+        
+        Args:
+            message: Error message
+            status_code: HTTP status code
+            request_id: Request ID for debugging
+        """
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.request_id = request_id
+    
+    def __str__(self) -> str:
+        """String representation of the error."""
+        parts = [self.message]
+        if self.status_code:
+            parts.append(f"Status: {self.status_code}")
+        if self.request_id:
+            parts.append(f"Request ID: {self.request_id}")
+        return " | ".join(parts)
+
+
+class AuthenticationError(PowerPointEngineError):
+    """Raised when API key is invalid or missing."""
+    pass
+
+
+class ValidationError(PowerPointEngineError):
+    """Raised when request data is invalid."""
+    pass
+
+
+class NotFoundError(PowerPointEngineError):
+    """Raised when requested resource is not found."""
+    pass
+
+
+class RateLimitError(PowerPointEngineError):
+    """Raised when rate limit is exceeded."""
+    pass
+
+
+class ServerError(PowerPointEngineError):
+    """Raised when server encounters an error."""
+    pass

powerpoint_engine_api-2.0.0.dist-info/METADATA

@@ -0,0 +1,154 @@
+Metadata-Version: 2.4
+Name: powerpoint-engine-api
+Version: 2.0.0
+Summary: Python SDK for the PowerPoint Engine API - generate, edit, merge and PDF-convert PowerPoint decks over HTTP
+Author-email: PowerPoint Engine API <support@powerpointengine.io>
+License: MIT License
+        
+        Copyright (c) 2024 PowerPoint Engine API
+        
+        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.
+        
+Project-URL: Homepage, https://powerpointengine.io
+Project-URL: Documentation, https://powerpointengine.io/docs
+Project-URL: Repository, https://github.com/powerpoint-engine-api/powerpoint-engine-python
+Project-URL: Bug Tracker, https://github.com/powerpoint-engine-api/powerpoint-engine-python/issues
+Keywords: powerpoint,pptx,presentation,api,sdk,markdown,pdf
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Office/Business :: Office Suites
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.25.0
+Dynamic: license-file
+
+# PowerPoint Engine — Python SDK
+
+Python client for the [PowerPoint Engine API](https://powerpointengine.io): generate `.pptx` from Markdown or a structured template, edit / merge / replace inside existing decks, and convert PPTX to PDF — over plain HTTP, no PowerPoint or LibreOffice install needed.
+
+## Install
+
+Not on PyPI yet — install from GitHub:
+
+```bash
+pip install git+https://github.com/powerpoint-engine-api/powerpoint-engine-python.git
+```
+
+## Quick start
+
+```python
+from powerpoint_engine import PowerPointEngine
+
+engine = PowerPointEngine()  # anonymous: works, but files are watermarked
+
+result = engine.generate(markup="""
+# Q3 Business Review
+
+## Highlights
+- Revenue up 24% QoQ
+- 3 new enterprise customers
+
+## Quarterly Numbers
+| Region | Q1  | Q2  | Q3  |
+|--------|-----|-----|-----|
+| EU     | 1.0 | 1.2 | 1.4 |
+| US     | 2.0 | 2.4 | 2.6 |
+""", theme="corporate")
+
+engine.download(result, "review.pptx")
+```
+
+Markdown tables become native PowerPoint tables. A fenced ```` ```chart ```` block under a `## heading` becomes a real editable chart (col / bar / line / pie / combo with a secondary axis):
+
+```text
+## Revenue vs Margin
+```chart
+type: combo
+categories: Q1, Q2, Q3
+Revenue: 120, 150, 170
+Margin % (line, secondary): 10, 12, 14
+```
+```
+
+## Work with existing decks
+
+```python
+# Replace {{placeholders}} without breaking formatting
+engine.replace("template.pptx", {"client": "ACME", "year": "2026"})
+
+# Duplicate / delete / reorder slides (1-based)
+engine.edit("deck.pptx", [
+    {"op": "duplicate", "slide": 2},
+    {"op": "delete", "slide": 5},
+    {"op": "move", "slide": 3, "to": 1},
+])
+
+# Merge 2-5 decks; each keeps its own design
+engine.merge(["intro.pptx", "results.pptx", "outro.pptx"])
+
+# Convert to PDF
+pdf = engine.to_pdf("deck.pptx")
+engine.download(pdf, "deck.pdf")
+
+# Translate in place (layout preserved)
+engine.translate("deck.pptx", "Spanish")
+```
+
+Every call returns a dict with `result.downloadUrl` — a signed link valid for 24 hours. `engine.download(result, path)` fetches it.
+
+## Branding
+
+```python
+engine.generate(
+    markup="# Deck\n\n## Slide\n- point",
+    brand={"primary": "#E4002B", "secondary": "#111827"},
+    font="Georgia",
+)
+```
+
+## Accounts and credits
+
+Pass your account id to tie calls to your quota and remove the watermark (Pro plan):
+
+```python
+engine = PowerPointEngine(session_id="your-account-id")
+```
+
+Billing is credit-based: 1 credit = up to 10 slides. Free tier: 5 credits/month (watermarked); Pro ($9/mo) removes the watermark. Details: [powerpointengine.io/#pricing](https://powerpointengine.io/#pricing).
+
+## AI agents
+
+The same engine is exposed as a remote [MCP server](https://powerpointengine.io/llms.txt) — one line in Claude Code / any MCP client:
+
+```bash
+claude mcp add --transport http powerpoint-engine https://powerpointengine.io/api/mcp/mcp
+```
+
+## Errors
+
+All errors raise `PowerPointEngineError` subclasses: `ValidationError` (400), `AuthenticationError` (401), `NotFoundError` (404), `RateLimitError` (429), `ServerError` (5xx).
+
+## License
+
+MIT

powerpoint_engine_api-2.0.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+powerpoint_engine/__init__.py,sha256=kCLao6-mM0fgmSm1NAtKGelgg6nuVanf0XFTtaJ9mes,702
+powerpoint_engine/client.py,sha256=qgIxrhqxn2G_JOIGWbhl0qK8SbPqs-43Ookr3hcN1hE,7943
+powerpoint_engine/exceptions.py,sha256=0IRGAw0EObKki60PTpgH-VY111oJqaW1x2xzcraKpxQ,1512
+powerpoint_engine_api-2.0.0.dist-info/licenses/LICENSE,sha256=O-hs3lV0uUmp-mfG-iOHM7Kop2vYkDZMSwA9V0Hc3_Y,1078
+powerpoint_engine_api-2.0.0.dist-info/METADATA,sha256=3Id6q3Y4NxBIxCo_JUZfam6OxIe04VnP1Tb9bn0eOnU,5419
+powerpoint_engine_api-2.0.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+powerpoint_engine_api-2.0.0.dist-info/top_level.txt,sha256=pPivEgmcQq7w7vAR5pzIIkWGzGbHWnij1YpmeR2QJVE,18
+powerpoint_engine_api-2.0.0.dist-info/RECORD,,

powerpoint_engine_api-2.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

powerpoint_engine_api-2.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 PowerPoint Engine API
+
+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.

powerpoint_engine_api-2.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+powerpoint_engine