# keynote-parser
<a href="https://travis-ci.org/psobot/keynote-parser"><img src="https://travis-ci.com/psobot/keynote-parser.svg?branch=master" alt="build:" /></a>
`keynote-parser` is a Python module for unpacking and re-packing
[Apple Keynote](https://www.apple.com/keynote/) `.key` files. It supports Keynote
files generated by Keynote version 12.2.1 (current as of December 2022).
Keynote uses a proprietary, compressed binary format to store its presentations.
This format is comprised of a zip file containing images and videos, as well as
[Snappy](https://github.com/google/snappy)-compressed
[Protobuf](https://github.com/protocolbuffers/protobuf) `.iwa` files containing
metadata, text, and all other definitions used in the presentation.
`keynote-parser` unpacks these component files into `.yaml` files in a directory,
making them editable by text editors and/or scripts, then allows re-packing of these
files into a working Keynote archive.
What could you use this for? Well, I use it to allow versioning of Keynote files in Git,
which makes diffs more understandable (rather than binary), as well as modifying text
in Keynote files in response to external scripts.
(e.g.: figures that update from databases before giving a presentation)
## Installation
```bash
pip3 install keynote-parser
```
## Usage
```bash
# Unpack MyPresentation.key into ./MyPresentation/
keynote-parser unpack MyPresentation.key
# Re-pack ./MyPresentation/ into MyPresentation.out.key
keynote-parser pack ./MyPresentation/
# List the files within a Keynote archive
keynote-parser ls MyPresentation.key
# Dump a particular .iwa file into its yaml representation on stdout
keynote-parser cat MyPresentation.key /Index/Slide-00001.iwa
# Replace text within a Keynote file in-place
keynote-parser replace MyPresentation.key --find "hello world" --replace "hello dolly"
```
### Formats
`keynote-parser` supports reading a list of replacements from a JSON file passed in
as `--replacements`. This file must have the form:
```json
{
"replacements": [
{
"find": "regexp to search for",
"replace": "string to replace with"
},
...
]
}
```
This argument can be passed to `keynote-parser replace` to replace text in a Keynote
file in-place. It can also be passed to `keynote-parser pack` to pack a directory
into a Keynote file, replacing text along the way.
#### Replacing Images
The `replacements` json format can also be used to replace images in a Keynote file.
To do so:
* Use the `keynote-parser ls` command to determine the name of the image to replace.
* Set the `find` pattern to the image's name, with the `-\d\d\d` suffix removed.
* Set the `replace` field to the local path to the replacement image.
`keynote-parser` will automatically rescale the replacement image to fit all of the
sizes of the target image.
### Compatibility
Note that between Keynote 10.2 and Keynote 11.2, a number of Protobuf definitions
used by Keynote have changed names. `keynote-parser` does not yet support
backwards compatibility: it can only read `.key` files as the
currently-supported Keynote version would, and will write `.yaml` output with
keys that match the current names of the keys. This means that **`.yaml` files
generated with older versions of `keynote-parser` may not be readable by with
v1.11.2.1 or higher of `keynote-parser`**.
Until this issue is fixed (_if_ it's ever fixed) - to properly read `.yaml` files
created by older versions of `keynote-parser`:
- use an older version of `keynote-parser` to read the file
- write a `.key` (or `.iwa`) file with that older version
- upgrade `keynote-parser`
- read that resulting `.iwa` file in the newer version of `keynote-parser`
## Updates
As `keynote-parser` includes Protobuf definitions extracted from a copy of Keynote,
new versions of Keynote will inevitably create `.key` files that cannot be read by `keynote-parser`.
As new versions of Keynote are released, updates to `keynote-parser` can be made automatically
by running the following on a macOS machine with Keynote installed:
```shell
# protobuf>=3.20.0rc1 must be installed, with the C++ runtime
# on Intel, this can be done with "pip install 'protobuf>=3.20.0rc1'"
# on Apple Silicon, this may require a manual build from source
cd dumper
make clean
make
```
## Troubleshooting
### Unable to complete installation due to snappy-c.h not found.
```bash
snappy/snappymodule.cc:31:10: fatal error: 'snappy-c.h' file not found
```
This means you're missing the Snappy libraries. Install Snappy via whatever method your OS supports. e.g. `brew install snappy`, `sudo apt-get install libsnappy-dev`, etc.
## Credits
`keynote-parser` was built by [Peter Sobot](https://petersobot.com) but heavily based on [prior
work](https://github.com/obriensp/iWorkFileFormat/blob/master/Docs/index.md) by [Sean Patrick O'Brien](http://www.obriensp.com).
A copy of O'Brien's format documentation is included in the `docs` folder for posterity.
## License
All code in this repository is licensed under the MIT License.
```
Copyright 2019-2022 Peter Sobot
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.
```
Raw data
{
"_id": null,
"home_page": "https://github.com/psobot/keynote-parser",
"name": "keynote-parser",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "keynote macOS apple presentation powerpoint",
"author": "Peter Sobot",
"author_email": "github@petersobot.com",
"download_url": "https://files.pythonhosted.org/packages/06/5b/48e7cafa08dee69a028427be6fb62d3078d1d5e34715e81959c2436516a7/keynote-parser-1.13.1.0.tar.gz",
"platform": null,
"description": "# keynote-parser\n\n<a href=\"https://travis-ci.org/psobot/keynote-parser\"><img src=\"https://travis-ci.com/psobot/keynote-parser.svg?branch=master\" alt=\"build:\" /></a>\n\n`keynote-parser` is a Python module for unpacking and re-packing\n[Apple Keynote](https://www.apple.com/keynote/) `.key` files. It supports Keynote\nfiles generated by Keynote version 12.2.1 (current as of December 2022).\n\nKeynote uses a proprietary, compressed binary format to store its presentations.\nThis format is comprised of a zip file containing images and videos, as well as\n[Snappy](https://github.com/google/snappy)-compressed\n[Protobuf](https://github.com/protocolbuffers/protobuf) `.iwa` files containing\nmetadata, text, and all other definitions used in the presentation.\n\n`keynote-parser` unpacks these component files into `.yaml` files in a directory,\nmaking them editable by text editors and/or scripts, then allows re-packing of these\nfiles into a working Keynote archive.\n\nWhat could you use this for? Well, I use it to allow versioning of Keynote files in Git,\nwhich makes diffs more understandable (rather than binary), as well as modifying text\nin Keynote files in response to external scripts.\n(e.g.: figures that update from databases before giving a presentation)\n\n## Installation\n\n```bash\npip3 install keynote-parser\n```\n\n## Usage\n\n```bash\n# Unpack MyPresentation.key into ./MyPresentation/\nkeynote-parser unpack MyPresentation.key\n\n# Re-pack ./MyPresentation/ into MyPresentation.out.key\nkeynote-parser pack ./MyPresentation/\n\n# List the files within a Keynote archive\nkeynote-parser ls MyPresentation.key\n\n# Dump a particular .iwa file into its yaml representation on stdout\nkeynote-parser cat MyPresentation.key /Index/Slide-00001.iwa\n\n# Replace text within a Keynote file in-place\nkeynote-parser replace MyPresentation.key --find \"hello world\" --replace \"hello dolly\"\n```\n\n### Formats\n\n`keynote-parser` supports reading a list of replacements from a JSON file passed in\nas `--replacements`. This file must have the form:\n\n```json\n{\n \"replacements\": [\n {\n \"find\": \"regexp to search for\",\n \"replace\": \"string to replace with\"\n },\n ...\n ]\n}\n```\n\nThis argument can be passed to `keynote-parser replace` to replace text in a Keynote\nfile in-place. It can also be passed to `keynote-parser pack` to pack a directory\ninto a Keynote file, replacing text along the way.\n\n#### Replacing Images\n\nThe `replacements` json format can also be used to replace images in a Keynote file.\nTo do so:\n\n* Use the `keynote-parser ls` command to determine the name of the image to replace.\n* Set the `find` pattern to the image's name, with the `-\\d\\d\\d` suffix removed.\n* Set the `replace` field to the local path to the replacement image.\n\n`keynote-parser` will automatically rescale the replacement image to fit all of the\nsizes of the target image.\n\n### Compatibility\n\nNote that between Keynote 10.2 and Keynote 11.2, a number of Protobuf definitions\nused by Keynote have changed names. `keynote-parser` does not yet support\nbackwards compatibility: it can only read `.key` files as the\ncurrently-supported Keynote version would, and will write `.yaml` output with\nkeys that match the current names of the keys. This means that **`.yaml` files\ngenerated with older versions of `keynote-parser` may not be readable by with\nv1.11.2.1 or higher of `keynote-parser`**.\n\nUntil this issue is fixed (_if_ it's ever fixed) - to properly read `.yaml` files\ncreated by older versions of `keynote-parser`:\n - use an older version of `keynote-parser` to read the file\n - write a `.key` (or `.iwa`) file with that older version\n - upgrade `keynote-parser`\n - read that resulting `.iwa` file in the newer version of `keynote-parser`\n\n## Updates\n\nAs `keynote-parser` includes Protobuf definitions extracted from a copy of Keynote,\nnew versions of Keynote will inevitably create `.key` files that cannot be read by `keynote-parser`.\nAs new versions of Keynote are released, updates to `keynote-parser` can be made automatically\nby running the following on a macOS machine with Keynote installed:\n\n```shell\n# protobuf>=3.20.0rc1 must be installed, with the C++ runtime\n# on Intel, this can be done with \"pip install 'protobuf>=3.20.0rc1'\"\n# on Apple Silicon, this may require a manual build from source\ncd dumper\nmake clean\nmake\n```\n\n## Troubleshooting\n\n### Unable to complete installation due to snappy-c.h not found.\n\n```bash\nsnappy/snappymodule.cc:31:10: fatal error: 'snappy-c.h' file not found\n```\n\nThis means you're missing the Snappy libraries. Install Snappy via whatever method your OS supports. e.g. `brew install snappy`, `sudo apt-get install libsnappy-dev`, etc.\n\n## Credits\n\n`keynote-parser` was built by [Peter Sobot](https://petersobot.com) but heavily based on [prior\nwork](https://github.com/obriensp/iWorkFileFormat/blob/master/Docs/index.md) by [Sean Patrick O'Brien](http://www.obriensp.com).\nA copy of O'Brien's format documentation is included in the `docs` folder for posterity.\n\n## License\n\nAll code in this repository is licensed under the MIT License.\n\n```\nCopyright 2019-2022 Peter Sobot\n\nPermission is hereby granted, free of charge, to any person obtaining a copy of this software\nand associated documentation files (the \"Software\"), to deal in the Software without restriction,\nincluding without limitation the rights to use, copy, modify, merge, publish, distribute,\nsublicense, and/or sell copies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all copies or\nsubstantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING\nBUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND\nNONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,\nDAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\n```\n",
"bugtrack_url": null,
"license": "",
"summary": "A tool for manipulating Apple Keynote presentation files.",
"version": "1.13.1.0",
"project_urls": {
"Bug Reports": "https://github.com/psobot/keynote-parser/issues",
"Homepage": "https://github.com/psobot/keynote-parser",
"Source": "https://github.com/psobot/keynote-parser/"
},
"split_keywords": [
"keynote",
"macos",
"apple",
"presentation",
"powerpoint"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c88e4f2dd0bb294621fcb32d8f5ff09ea1f58c03a17d898b983886e297ea7449",
"md5": "643c9f103df0116bc8c499dec04e3a85",
"sha256": "cf95124ae28f3282798064907e15d05714226b31cdeb2b9231bf1377dd29b076"
},
"downloads": -1,
"filename": "keynote_parser-1.13.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "643c9f103df0116bc8c499dec04e3a85",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 203276,
"upload_time": "2023-06-21T03:40:48",
"upload_time_iso_8601": "2023-06-21T03:40:48.434857Z",
"url": "https://files.pythonhosted.org/packages/c8/8e/4f2dd0bb294621fcb32d8f5ff09ea1f58c03a17d898b983886e297ea7449/keynote_parser-1.13.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "065b48e7cafa08dee69a028427be6fb62d3078d1d5e34715e81959c2436516a7",
"md5": "315b6611a302c8d8130d1fba0a81ffe3",
"sha256": "a8ca27b47affeda30ebcb8938875ce0d98bf235d6ef1595806164004710c47fe"
},
"downloads": -1,
"filename": "keynote-parser-1.13.1.0.tar.gz",
"has_sig": false,
"md5_digest": "315b6611a302c8d8130d1fba0a81ffe3",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 182615,
"upload_time": "2023-06-21T03:40:51",
"upload_time_iso_8601": "2023-06-21T03:40:51.455775Z",
"url": "https://files.pythonhosted.org/packages/06/5b/48e7cafa08dee69a028427be6fb62d3078d1d5e34715e81959c2436516a7/keynote-parser-1.13.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-06-21 03:40:51",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "psobot",
"github_project": "keynote-parser",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"requirements": [
{
"name": "protobuf",
"specs": [
[
">=",
"3.13.0"
]
]
},
{
"name": "tqdm",
"specs": [
[
">=",
"4.14.0"
]
]
},
{
"name": "python-snappy",
"specs": [
[
">=",
"0.5.3"
]
]
},
{
"name": "PyYAML",
"specs": [
[
">=",
"5.3.1"
]
]
},
{
"name": "Pillow",
"specs": [
[
">=",
"7.1.0"
]
]
},
{
"name": "future",
"specs": [
[
">=",
"0.17.1"
]
]
},
{
"name": "colorama",
"specs": [
[
">=",
"0.4.3"
]
]
},
{
"name": "pytest-cov",
"specs": [
[
">=",
"2.6.1"
]
]
}
],
"lcname": "keynote-parser"
}
JSON
