Added a few more methods

docs/README.md

@@ -0,0 +1,17 @@
+# Building the documentation
+
+I'm still trying to learn sphinx and come up with a workflow for building docs.  Right now it's 
+pretty kludgy.
+
+- `brew install sphinx-doc` or `conda install sphinx`
+- `pip install sphinx-rtd-theme`
+- `pip install m2r2`
+- Download and install [MacTeX](https://tug.org/mactex/)
+- Add `/Library/TeX/texbin` to your `$PATH`
+- Convert README to rst.  I tried using plug-ins to do this and ran into errors with LaTeX to PDF due to the black and MIT license images.  
+- `m2r2 README.md`
+- Move the README.rst that's generated to `docs/source` and edit it to remove the images
+- `cd docs`
+- `make html`
+- `make latexpdf`
+- copy `docs/build/latex/photoscript.pdf` to the project root directory

docs/source/README.rst

@@ -0,0 +1,46 @@
+
+PhotoScript
+===========
+
+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.
+
+Installation
+------------
+
+PhotoScript uses setuptools, thus simply run:
+
+``python3 setup.py install``
+
+Example
+-------
+
+.. code-block:: 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:
+       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()
+
+See Also
+--------
+
+
+* `osxphotos <https://github.com/RhetTbull/osxphotos>`_\ : Python package that provides read-only access to the Photos library including all associated metadata. 

docs/source/conf.py

@@ -11,6 +11,7 @@
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
 import os
+import pathlib
 import sys
 
 import sphinx_rtd_theme
@@ -24,16 +25,25 @@
 copyright = "2020, Rhet Turnbull"
 author = "Rhet Turnbull"
 
-# The full version, including alpha/beta/rc tags
-release = "0.0.1"
+# holds config info read from disk
+about = {}
+this_directory = pathlib.Path(__file__).parent
+version_file = this_directory.parent.parent / "photoscript" / "_version.py"
+# get version info from _version
+with open(
+   version_file, mode="r", encoding="utf-8"
+) as f:
+    exec(f.read(), about)
 
+# The full version, including alpha/beta/rc tags
+release = about["__version__"]
 
 # -- General configuration ---------------------------------------------------
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ["sphinx.ext.autodoc", "sphinx.ext.napoleon", "sphinx.ext.viewcode", "sphinx.ext.intersphinx", "recommonmark"]
+extensions = ["sphinx.ext.autodoc", "sphinx.ext.napoleon", "sphinx.ext.viewcode", "sphinx.ext.intersphinx", "m2r2"] 
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
@@ -56,3 +66,5 @@
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ["_static"]
+
+source_suffix = ['.rst', '.md']

docs/source/index.rst

@@ -6,42 +6,8 @@
 Welcome to PhotoScript's documentation!
 =======================================
 
-What is PhotoScript
--------------------
+.. include:: README.rst
 
-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.
-
-Installation
-------------
-
-PhotoScript uses setuptools, thus simply run:
-
-`python3 setup.py install`
-
-Example
--------
-
-.. code-block:: 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:
-      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
 =============

photoscript/_version.py

@@ -1,3 +1,3 @@
 """ version info """
 
-__version__ = "0.0.1"
+__version__ = "0.0.2"

photoscript/photoscript.applescript

@@ -1,3 +1,5 @@
+-- TODO: Variable names are not very consistent throughout this
+
 ---------- PhotoLibrary ----------
 on _activate()
 	(* activate Photos app *)
@@ -35,6 +37,7 @@ on _photoslibrary_frontmost()
 end _photoslibrary_frontmost
 
 on _photoslibrary_get_all_photos()
+	(* return all photos in the library *)
 	set ids to {}
 	tell application "Photos"
 		repeat with _item in every media item
@@ -45,6 +48,7 @@ on _photoslibrary_get_all_photos()
 end _photoslibrary_get_all_photos
 
 on _photoslibrary_search_photos(search_str)
+	(* search for photos by text string *)
 	set ids to {}
 	tell application "Photos"
 		set _items to search for search_str
@@ -150,6 +154,7 @@ on _get_albums_folders()
 end _get_albums_folders
 
 on _get_album_folder_names()
+	(* return names of albums and folders *)
 	set albums_folders to _get_albums_folders()
 	set allalbums to _albums of albums_folders
 	set allfolders to _folders of albums_folders
@@ -203,6 +208,40 @@ on _create_album(albumName)
 	end tell
 end _create_album
 
+on _get_selection()
+	(* return ids of selected items *)
+	set item_ids_ to {}
+	tell application "Photos"
+		set items_ to selection
+		repeat with item_ in items_
+			copy id of item_ to end of item_ids_
+		end repeat
+	end tell
+	return item_ids_
+end _get_selection
+
+on _photoslib_favorites()
+	(* return favorites album *)
+	tell application "Photos"
+		return id of favorites album
+	end tell
+end _photoslib_favorites
+
+on _photoslib_recently_deleted()
+	(* return recently deleted album *)
+	tell application "Photos"
+		return id of recently deleted album
+	end tell
+end _photoslib_recently_deleted
+
+on _photoslib_delete_album(id_)
+	(* delete album with id_ *)
+	tell application "Photos"
+		set album_ to album id (id_)
+		delete album_
+	end tell
+end _photoslib_delete_album
+
 ---------- Album ----------
 
 on _album_name(_id)
@@ -270,6 +309,22 @@ on _album_len(id_)
 	end tell
 end _album_len
 
+on _album_add(id_, items_)
+	(* add media items to album
+	    Args:
+		id_: id of album
+	       items_: list of media item ids
+	*)
+	tell application "Photos"
+		set media_list_ to {}
+		repeat with item_ in items_
+			copy media item id (item_) to end of media_list_
+		end repeat
+		set album_ to album id (id_)
+		add media_list_ to album_
+	end tell
+end _album_add
+
 ---------- Photo ----------
 on _photo_exists(_id)
 	(* return true if media item with _id exists otherwise false *)
@@ -285,30 +340,42 @@ on _photo_exists(_id)
 end _photo_exists
 
 on _photo_name(_id)
+	(* name or title of photo *)
 	tell application "Photos"
 		return name of media item id (_id)
 	end tell
 end _photo_name
 
 on _photo_description(_id)
+	(* description of photo *)
 	tell application "Photos"
 		return description of media item id (_id)
 	end tell
 end _photo_description
 
 on _photo_keywords(_id)
+	(* keywords of photo *)
 	tell application "Photos"
 		return keywords of media item id (_id)
 	end tell
 end _photo_keywords
 
 on _photo_date(_id)
+	(* date of photo *)
 	tell application "Photos"
 		return date of media item id (_id)
 	end tell
 end _photo_date
 
 on _photo_export(theUUID, thePath, original, edited, theTimeOut)
+	(* export photo
+	   Args:
+	      theUUID: id of the photo to export
+		  thePath: path to export to as POSIX path string
+		  original: boolean, if true, exports original photo
+		  edited: boolean, if true, exports edited photo
+		  theTimeOut: how long to wait in case Photos timesout
+	*)
 	tell application "Photos"
 		set thePath to thePath
 		set theItem to media item id theUUID
@@ -333,20 +400,15 @@ on _photo_export(theUUID, thePath, original, edited, theTimeOut)
 end _photo_export
 
 on _photo_filename(id_)
+	(* original filename of the photo *)
 	tell application "Photos"
-		return filename of media item id (id_)	
+		return filename of media item id (id_)
 	end tell
 end _photo_filename
 
-
-#_album_by_name("People")
-#_album_exists("8245D1B5-1B26-4858-B16E-279591641EB4/L0/040")
-#_album_exists("FOO8245D1B5-1B26-4858-B16E-279591641EB4/L0/040")
-#_album_ids(false)
-#_album_parent("7E59016E-92D0-47FB-B71D-DCD6C6BBB1EE/L0/040")
-#_photoslibrary_version()
-#_photoslibrary_name()
-#_photoslibrary_frontmost()
-#_photoslibrary_get_all_photos()
-
-# _photoslibrary_search_photos("bride")
+on _photo_duplicate(id_)
+	tell application "Photos"
+		set _new_photo to duplicate media item id (id_)
+		return id of _new_photo
+	end tell
+end _photo_duplicate