pykeynote 0.2.0__tar.gz

pykeynote-0.2.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.egg-info/
+.venv/
+dist/
+build/
+.pytest_cache/

pykeynote-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kevin McAleer
+
+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.

pykeynote-0.2.0/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.5
+Name: pykeynote
+Version: 0.2.0
+Summary: Create, read and edit Apple Keynote presentations from Python
+Project-URL: Homepage, https://github.com/kevinmcaleer/pykeynote
+Project-URL: Source, https://github.com/kevinmcaleer/pykeynote
+Project-URL: Issues, https://github.com/kevinmcaleer/pykeynote/issues
+Author: Kevin McAleer
+License-Expression: MIT
+License-File: LICENSE
+Keywords: apple,iwork,keynote,markdown,presentation,slides
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Multimedia :: Graphics :: Presentation
+Classifier: Topic :: Office/Business
+Requires-Python: >=3.9
+Requires-Dist: keynote-parser<2,>=1.14.5
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# pykeynote
+
+Read, and soon write, Apple Keynote presentations from Python. pykeynote
+works on `.key` files directly, so it runs anywhere Python does. You don't
+need Keynote or a Mac.
+
+A `.key` file is a zip of Snappy-compressed protobuf archives (`Index/*.iwa`)
+plus images and media in `Data/`. Decoding comes from
+[keynote-parser](https://github.com/psobot/keynote-parser), which supports
+files saved by Keynote up to 14.5.
+
+## Install
+
+```sh
+pip install pykeynote
+```
+
+For development, clone the repo and run `pip install -e ".[dev]"`.
+
+## Reading a deck
+
+```python
+from pykeynote import Presentation
+
+deck = Presentation.open("talk.key")
+print(deck.theme, deck.size, deck.layouts)
+
+for slide in deck:
+    print(slide.index, slide.layout, slide.title)
+    for para in slide.paragraphs:          # text, indent level, bulleted?
+        print("  " * para.level, para.text)
+    print(slide.notes, slide.transition.effect, slide.skipped)
+
+print(deck.to_markdown())
+```
+
+`title` and `body` are `None` when the slide's layout hides that placeholder.
+
+## Making and changing decks
+
+```python
+from pykeynote import Presentation, Paragraph, from_markdown
+
+deck = Presentation.new()                 # bundled Basic White theme, no slides yet
+deck.add_slide("Title", title="Robots!", body="Kevin McAleer")
+slide = deck.add_slide(
+    "Title & Bullets",
+    title="Why robots?",
+    body=[Paragraph("They're fun"), Paragraph("Mostly", level=1), "They're useful"],
+    notes="Keep this one short.",
+)
+slide.set_transition("dissolve", 1.5)
+deck.save("talk.key")
+
+deck = Presentation.open("talk.key")
+deck[1].title = "Why robots? 🤖"
+deck.duplicate_slide(1)
+deck.move_slide(2, 0)
+deck.delete_slide(-1)
+deck[0].skipped = True
+deck.save()                               # back to talk.key
+
+deck = from_markdown(open("talk.md").read())
+deck.save("from-markdown.key")
+```
+
+`add_slide` copies a slide that already uses the layout, so it keeps the
+theme's look. A deck from `Presentation.new()` has one of every layout to
+copy from, kept out of sight and left out when you save. For a deck you
+opened, at least one slide must already use the layout.
+
+## Markdown
+
+`to_markdown()` writes one block per slide, separated by `---`. Slide
+settings go in HTML comments, and presenter notes follow a `???` line:
+
+```markdown
+<!-- layout: Title & Bullets -->
+<!-- transition: dissolve 1.5s -->
+# Why robots?
+
+- They're fun
+  - Mostly
+- They're useful
+
+???
+Keep this one short.
+```
+
+## Roadmap
+
+1. Read decks and export Markdown. **Done.**
+2. Edit text and notes, then save. **Done.**
+3. Add, duplicate, delete and reorder slides, set transitions and skipping, and build decks from Markdown. **Done.**
+4. More bundled themes, images, and build animations.
+
+## Driving Keynote directly (legacy)
+
+`pykeynote.scripting` controls a running copy of Keynote on a Mac through
+AppleScript and JXA. It can already edit decks, but it will be removed once
+the file-based engine catches up.
+
+## Tests
+
+```sh
+pytest                                    # everything that runs without Keynote
+PYKEYNOTE_INTEGRATION=1 pytest            # also drive real Keynote (macOS)
+```
+
+The sample decks in `tests/fixtures/` were made in Keynote 14.5.

pykeynote-0.2.0/README.md

@@ -0,0 +1,110 @@
+# pykeynote
+
+Read, and soon write, Apple Keynote presentations from Python. pykeynote
+works on `.key` files directly, so it runs anywhere Python does. You don't
+need Keynote or a Mac.
+
+A `.key` file is a zip of Snappy-compressed protobuf archives (`Index/*.iwa`)
+plus images and media in `Data/`. Decoding comes from
+[keynote-parser](https://github.com/psobot/keynote-parser), which supports
+files saved by Keynote up to 14.5.
+
+## Install
+
+```sh
+pip install pykeynote
+```
+
+For development, clone the repo and run `pip install -e ".[dev]"`.
+
+## Reading a deck
+
+```python
+from pykeynote import Presentation
+
+deck = Presentation.open("talk.key")
+print(deck.theme, deck.size, deck.layouts)
+
+for slide in deck:
+    print(slide.index, slide.layout, slide.title)
+    for para in slide.paragraphs:          # text, indent level, bulleted?
+        print("  " * para.level, para.text)
+    print(slide.notes, slide.transition.effect, slide.skipped)
+
+print(deck.to_markdown())
+```
+
+`title` and `body` are `None` when the slide's layout hides that placeholder.
+
+## Making and changing decks
+
+```python
+from pykeynote import Presentation, Paragraph, from_markdown
+
+deck = Presentation.new()                 # bundled Basic White theme, no slides yet
+deck.add_slide("Title", title="Robots!", body="Kevin McAleer")
+slide = deck.add_slide(
+    "Title & Bullets",
+    title="Why robots?",
+    body=[Paragraph("They're fun"), Paragraph("Mostly", level=1), "They're useful"],
+    notes="Keep this one short.",
+)
+slide.set_transition("dissolve", 1.5)
+deck.save("talk.key")
+
+deck = Presentation.open("talk.key")
+deck[1].title = "Why robots? 🤖"
+deck.duplicate_slide(1)
+deck.move_slide(2, 0)
+deck.delete_slide(-1)
+deck[0].skipped = True
+deck.save()                               # back to talk.key
+
+deck = from_markdown(open("talk.md").read())
+deck.save("from-markdown.key")
+```
+
+`add_slide` copies a slide that already uses the layout, so it keeps the
+theme's look. A deck from `Presentation.new()` has one of every layout to
+copy from, kept out of sight and left out when you save. For a deck you
+opened, at least one slide must already use the layout.
+
+## Markdown
+
+`to_markdown()` writes one block per slide, separated by `---`. Slide
+settings go in HTML comments, and presenter notes follow a `???` line:
+
+```markdown
+<!-- layout: Title & Bullets -->
+<!-- transition: dissolve 1.5s -->
+# Why robots?
+
+- They're fun
+  - Mostly
+- They're useful
+
+???
+Keep this one short.
+```
+
+## Roadmap
+
+1. Read decks and export Markdown. **Done.**
+2. Edit text and notes, then save. **Done.**
+3. Add, duplicate, delete and reorder slides, set transitions and skipping, and build decks from Markdown. **Done.**
+4. More bundled themes, images, and build animations.
+
+## Driving Keynote directly (legacy)
+
+`pykeynote.scripting` controls a running copy of Keynote on a Mac through
+AppleScript and JXA. It can already edit decks, but it will be removed once
+the file-based engine catches up.
+
+## Tests
+
+```sh
+pytest                                    # everything that runs without Keynote
+PYKEYNOTE_INTEGRATION=1 pytest            # also drive real Keynote (macOS)
+```
+
+The sample decks in `tests/fixtures/` were made in Keynote 14.5.

pykeynote-0.2.0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pykeynote"
+dynamic = ["version"]
+description = "Create, read and edit Apple Keynote presentations from Python"
+readme = "README.md"
+dependencies = ["keynote-parser>=1.14.5,<2"]
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Kevin McAleer" }]
+keywords = ["keynote", "apple", "presentation", "slides", "markdown", "iwork"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Multimedia :: Graphics :: Presentation",
+    "Topic :: Office/Business",
+]
+
+[project.urls]
+Homepage = "https://github.com/kevinmcaleer/pykeynote"
+Source = "https://github.com/kevinmcaleer/pykeynote"
+Issues = "https://github.com/kevinmcaleer/pykeynote/issues"
+
+[tool.hatch.version]
+path = "src/pykeynote/__init__.py"
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "tests", "README.md", "LICENSE"]
+
+[project.optional-dependencies]
+dev = ["pytest>=7"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = [
+    "keynote: needs macOS with Keynote installed (set PYKEYNOTE_INTEGRATION=1 to run)",
+]

pykeynote-0.2.0/src/pykeynote/__init__.py

@@ -0,0 +1,15 @@
+"""Create, read and edit Apple Keynote presentations from Python.
+
+:class:`Presentation` reads ``.key`` files directly, so Keynote isn't needed.
+The older :mod:`pykeynote.scripting` module drives a running copy of Keynote
+on a Mac instead, and will go once the file-based engine can do everything
+it does.
+"""
+
+from ._osa import KeynoteError
+from .document import Presentation, Slide, Transition, themes
+from .markdown import from_markdown, parse_markdown
+from .text import Paragraph, UnsupportedTextError
+
+__all__ = ["KeynoteError", "Paragraph", "Presentation", "Slide", "Transition", "UnsupportedTextError", "from_markdown", "parse_markdown", "themes"]
+__version__ = "0.2.0"

pykeynote-0.2.0/src/pykeynote/_osa.py

@@ -0,0 +1,56 @@
+"""Low-level bridge to Keynote through ``osascript``.
+
+Values are never pasted into script source. JXA scripts get their arguments
+as one JSON string in ``argv`` and return JSON. AppleScript scripts get plain
+string arguments through ``on run argv``.
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+from typing import Any, Sequence
+
+
+class KeynoteError(RuntimeError):
+    """Raised when Keynote or osascript reports an error."""
+
+
+_JXA_WRAPPER = """
+function run(argv) {
+  const Keynote = Application("Keynote");
+  const args = JSON.parse(argv[0]);
+  const result = main(Keynote, args);
+  return JSON.stringify(result === undefined ? null : result);
+}
+"""
+
+
+def _execute(language: str, script: str, argv: Sequence[str]) -> str:
+    """Run a script with osascript and return its stdout. Tests replace this."""
+    try:
+        proc = subprocess.run(
+            ["osascript", "-l", language, "-", *argv],
+            input=script,
+            capture_output=True,
+            text=True,
+        )
+    except FileNotFoundError as exc:
+        raise KeynoteError(
+            "osascript was not found. pykeynote needs macOS with Keynote installed."
+        ) from exc
+    if proc.returncode != 0:
+        raise KeynoteError(proc.stderr.strip() or f"osascript exited with {proc.returncode}")
+    return proc.stdout
+
+
+def jxa(script: str, **args: Any) -> Any:
+    """Run a JXA script that defines ``function main(Keynote, args)``."""
+    out = _execute("JavaScript", script + _JXA_WRAPPER, [json.dumps(args)])
+    out = out.strip()
+    return json.loads(out) if out else None
+
+
+def applescript(script: str, *args: str) -> str:
+    """Run an AppleScript with an ``on run argv`` handler and return its output."""
+    return _execute("AppleScript", script, [str(a) for a in args]).strip()