photoscript


Namephotoscript JSON
Version 0.3.1 PyPI version JSON
download
home_pagehttps://github.com/RhetTbull/photoscript
SummaryPython wrapper around Apple Photos applescript interface
upload_time2023-10-22 14:49:43
maintainer
docs_urlNone
authorRhet Turnbull
requires_python>=3.8,<4.0
licenseMIT
keywords photos mac macos applescript apple
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage
            # PhotoScript

[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/python/black)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
<!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->
[![All Contributors](https://img.shields.io/badge/all_contributors-2-orange.svg?style=flat-square)](#contributors-)
<!-- ALL-CONTRIBUTORS-BADGE:END -->

## What is PhotoScript

PhotoScript provides a python wrapper around Apple Photos applescript interface.  With PhotoScript you can interact with Photos using python.  Runs only on MacOS.  Tested on MacOS Catalina.

PhotosScript is limited by Photos' very limited AppleScript dictionary.

## Compatibility

Designed for MacOS Catalina/Photos 5.  Preliminary testing on Big Sur/Photos 6 beta shows this should work on Big Sur as well.  Photos' AppleScript interface has changed very little since Photos 2 (the earliest version I have access to).  This package should work with most versions of Photos but some methods may not function correctly on versions earlier than Photos 5.  If you find compatibility issues, open an issue or send a PR.

## Installation

PhotoScript uses [poetry](https://python-poetry.org/) for dependency management.  To install, clone the repo and run `poetry install`. If you don't have poetry already installed, follow the [installation instructions](https://python-poetry.org/docs/#installation). To enter the virtual environment, run `poetry shell`.

Or you can install via pip:

`python3 -m pip install photoscript`

## Example

```python
""" Simple example showing use of photoscript """

import photoscript

photoslib = photoscript.PhotosLibrary()

photoslib.activate()
print(f"Running Photos version: {photoslib.version}")

album = photoslib.album("Album1")
photos = album.photos()

for photo in photos:
    photo.keywords = ["travel", "vacation"]
    print(f"{photo.title}, {photo.description}, {photo.keywords}")

new_album = photoslib.create_album("New Album")
photoslib.import_photos(["/Users/rhet/Downloads/test.jpeg"], album=new_album)

photoslib.quit()
```

## Documentation

Full documentation [here](https://rhettbull.github.io/PhotoScript/).

Additional documentation about Photos and AppleScript available on the [wiki](https://github.com/RhetTbull/PhotoScript/wiki/Welcome-to-the-PhotoScript-Wiki).

## Testing

Tested on MacOS Catalina, Photos 5 with 100% coverage.

## Limitations

Photos' AppleScript interface is very limited.  For example, it cannot access information on faces in photos nor can it delete a photo.  PhotoScript is thus limited.  PhotoScript works by executing AppleScript through an Objective-C bridge from python.  Every method call has to do a python->Objective C->AppleScript round trip; this makes the interface much slower than native python code.  This is particularly noticeable when dealing with Folders which requires significant work arounds.

Where possible, PhotoScript attempts to provide work-arounds to Photos' limitations. For example, Photos does not provide a way to remove a photo from an album.  PhotoScript does provide a `Album.remove()` method but in order to do this, it creates a new album with the same name as the original, copies all but the removed photos to the new album then deletes the original album.  This simulates removing photos and produces the desired effect but is not the same thing as removing a photo from an album.

## Related Projects

- [osxphotos](https://github.com/RhetTbull/osxphotos): Python package that provides read-only access to the Photos library including all associated metadata.

## Dependencies

- [py-applescript](https://github.com/rdhyee/py-applescript)
- [PyObjC](https://github.com/ronaldoussoren/pyobjc)

## Contributors ✨

Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):

<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
<!-- prettier-ignore-start -->
<!-- markdownlint-disable -->
<table>
  <tbody>
    <tr>
      <td align="center" valign="top" width="14.28%"><a href="http://davidhaberthür.ch"><img src="https://avatars.githubusercontent.com/u/1651235?v=4?s=100" width="100px;" alt="David Haberthür"/><br /><sub><b>David Haberthür</b></sub></a><br /><a href="https://github.com/RhetTbull/PhotoScript/commits?author=habi" title="Documentation">📖</a></td>
      <td align="center" valign="top" width="14.28%"><a href="https://anjos.ai"><img src="https://avatars.githubusercontent.com/u/46305?v=4?s=100" width="100px;" alt="André Anjos"/><br /><sub><b>André Anjos</b></sub></a><br /><a href="#ideas-anjos" title="Ideas, Planning, & Feedback">🤔</a> <a href="https://github.com/RhetTbull/PhotoScript/issues?q=author%3Aanjos" title="Bug reports">🐛</a></td>
    </tr>
  </tbody>
</table>

<!-- markdownlint-restore -->
<!-- prettier-ignore-end -->

<!-- ALL-CONTRIBUTORS-LIST:END -->

This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!

## See Also

For a more comprehensive python interface for Mac automation, see [PyXA](https://github.com/SKaplanOfficial/PyXA)
which provides a python interface to Photos and many other Mac applications.


            

Raw data

            {
    "_id": null,
    "home_page": "https://github.com/RhetTbull/photoscript",
    "name": "photoscript",
    "maintainer": "",
    "docs_url": null,
    "requires_python": ">=3.8,<4.0",
    "maintainer_email": "",
    "keywords": "photos,mac,macos,applescript,apple",
    "author": "Rhet Turnbull",
    "author_email": "rturnbull+git@gmail.com",
    "download_url": "https://files.pythonhosted.org/packages/4b/e9/cb0dabdfb32092f41f06774b8b0ec4c4ef48977ac631ff47dd758700f1ca/photoscript-0.3.1.tar.gz",
    "platform": null,
    "description": "# PhotoScript\n\n[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/python/black)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n<!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->\n[![All Contributors](https://img.shields.io/badge/all_contributors-2-orange.svg?style=flat-square)](#contributors-)\n<!-- ALL-CONTRIBUTORS-BADGE:END -->\n\n## What is PhotoScript\n\nPhotoScript provides a python wrapper around Apple Photos applescript interface.  With PhotoScript you can interact with Photos using python.  Runs only on MacOS.  Tested on MacOS Catalina.\n\nPhotosScript is limited by Photos' very limited AppleScript dictionary.\n\n## Compatibility\n\nDesigned for MacOS Catalina/Photos 5.  Preliminary testing on Big Sur/Photos 6 beta shows this should work on Big Sur as well.  Photos' AppleScript interface has changed very little since Photos 2 (the earliest version I have access to).  This package should work with most versions of Photos but some methods may not function correctly on versions earlier than Photos 5.  If you find compatibility issues, open an issue or send a PR.\n\n## Installation\n\nPhotoScript uses [poetry](https://python-poetry.org/) for dependency management.  To install, clone the repo and run `poetry install`. If you don't have poetry already installed, follow the [installation instructions](https://python-poetry.org/docs/#installation). To enter the virtual environment, run `poetry shell`.\n\nOr you can install via pip:\n\n`python3 -m pip install photoscript`\n\n## Example\n\n```python\n\"\"\" Simple example showing use of photoscript \"\"\"\n\nimport photoscript\n\nphotoslib = photoscript.PhotosLibrary()\n\nphotoslib.activate()\nprint(f\"Running Photos version: {photoslib.version}\")\n\nalbum = photoslib.album(\"Album1\")\nphotos = album.photos()\n\nfor photo in photos:\n    photo.keywords = [\"travel\", \"vacation\"]\n    print(f\"{photo.title}, {photo.description}, {photo.keywords}\")\n\nnew_album = photoslib.create_album(\"New Album\")\nphotoslib.import_photos([\"/Users/rhet/Downloads/test.jpeg\"], album=new_album)\n\nphotoslib.quit()\n```\n\n## Documentation\n\nFull documentation [here](https://rhettbull.github.io/PhotoScript/).\n\nAdditional documentation about Photos and AppleScript available on the [wiki](https://github.com/RhetTbull/PhotoScript/wiki/Welcome-to-the-PhotoScript-Wiki).\n\n## Testing\n\nTested on MacOS Catalina, Photos 5 with 100% coverage.\n\n## Limitations\n\nPhotos' AppleScript interface is very limited.  For example, it cannot access information on faces in photos nor can it delete a photo.  PhotoScript is thus limited.  PhotoScript works by executing AppleScript through an Objective-C bridge from python.  Every method call has to do a python->Objective C->AppleScript round trip; this makes the interface much slower than native python code.  This is particularly noticeable when dealing with Folders which requires significant work arounds.\n\nWhere possible, PhotoScript attempts to provide work-arounds to Photos' limitations. For example, Photos does not provide a way to remove a photo from an album.  PhotoScript does provide a `Album.remove()` method but in order to do this, it creates a new album with the same name as the original, copies all but the removed photos to the new album then deletes the original album.  This simulates removing photos and produces the desired effect but is not the same thing as removing a photo from an album.\n\n## Related Projects\n\n- [osxphotos](https://github.com/RhetTbull/osxphotos): Python package that provides read-only access to the Photos library including all associated metadata.\n\n## Dependencies\n\n- [py-applescript](https://github.com/rdhyee/py-applescript)\n- [PyObjC](https://github.com/ronaldoussoren/pyobjc)\n\n## Contributors \u2728\n\nThanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):\n\n<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->\n<!-- prettier-ignore-start -->\n<!-- markdownlint-disable -->\n<table>\n  <tbody>\n    <tr>\n      <td align=\"center\" valign=\"top\" width=\"14.28%\"><a href=\"http://davidhaberth\u00fcr.ch\"><img src=\"https://avatars.githubusercontent.com/u/1651235?v=4?s=100\" width=\"100px;\" alt=\"David Haberth\u00fcr\"/><br /><sub><b>David Haberth\u00fcr</b></sub></a><br /><a href=\"https://github.com/RhetTbull/PhotoScript/commits?author=habi\" title=\"Documentation\">\ud83d\udcd6</a></td>\n      <td align=\"center\" valign=\"top\" width=\"14.28%\"><a href=\"https://anjos.ai\"><img src=\"https://avatars.githubusercontent.com/u/46305?v=4?s=100\" width=\"100px;\" alt=\"Andr\u00e9 Anjos\"/><br /><sub><b>Andr\u00e9 Anjos</b></sub></a><br /><a href=\"#ideas-anjos\" title=\"Ideas, Planning, & Feedback\">\ud83e\udd14</a> <a href=\"https://github.com/RhetTbull/PhotoScript/issues?q=author%3Aanjos\" title=\"Bug reports\">\ud83d\udc1b</a></td>\n    </tr>\n  </tbody>\n</table>\n\n<!-- markdownlint-restore -->\n<!-- prettier-ignore-end -->\n\n<!-- ALL-CONTRIBUTORS-LIST:END -->\n\nThis project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!\n\n## See Also\n\nFor a more comprehensive python interface for Mac automation, see [PyXA](https://github.com/SKaplanOfficial/PyXA)\nwhich provides a python interface to Photos and many other Mac applications.\n\n",
    "bugtrack_url": null,
    "license": "MIT",
    "summary": "Python wrapper around Apple Photos applescript interface",
    "version": "0.3.1",
    "project_urls": {
        "Homepage": "https://github.com/RhetTbull/photoscript",
        "Repository": "https://github.com/RhetTbull/photoscript"
    },
    "split_keywords": [
        "photos",
        "mac",
        "macos",
        "applescript",
        "apple"
    ],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "73f7cda3ac022bf79bd18bbb5cdfd7ff17c13f235f4678b1ed96975f764c92fc",
                "md5": "873b465aa5efe76c82087a200a62a413",
                "sha256": "250881e307f7649f0dd3c816b668558ec2ca3a30c98074f97d867e9b24e9856a"
            },
            "downloads": -1,
            "filename": "photoscript-0.3.1-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "873b465aa5efe76c82087a200a62a413",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.8,<4.0",
            "size": 23883,
            "upload_time": "2023-10-22T14:49:41",
            "upload_time_iso_8601": "2023-10-22T14:49:41.471546Z",
            "url": "https://files.pythonhosted.org/packages/73/f7/cda3ac022bf79bd18bbb5cdfd7ff17c13f235f4678b1ed96975f764c92fc/photoscript-0.3.1-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "4be9cb0dabdfb32092f41f06774b8b0ec4c4ef48977ac631ff47dd758700f1ca",
                "md5": "afd80a3b81bf083526f6079dcd4905aa",
                "sha256": "fbd07e7d64467ffd0498b5fa09208c125024f8960641b15ca1e5ae65af33edab"
            },
            "downloads": -1,
            "filename": "photoscript-0.3.1.tar.gz",
            "has_sig": false,
            "md5_digest": "afd80a3b81bf083526f6079dcd4905aa",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.8,<4.0",
            "size": 24728,
            "upload_time": "2023-10-22T14:49:43",
            "upload_time_iso_8601": "2023-10-22T14:49:43.117946Z",
            "url": "https://files.pythonhosted.org/packages/4b/e9/cb0dabdfb32092f41f06774b8b0ec4c4ef48977ac631ff47dd758700f1ca/photoscript-0.3.1.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2023-10-22 14:49:43",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "RhetTbull",
    "github_project": "photoscript",
    "travis_ci": false,
    "coveralls": true,
    "github_actions": false,
    "lcname": "photoscript"
}
        
Elapsed time: 0.14727s