Added API_README to docs (#1146)

API_README.md

@@ -57,11 +57,12 @@ osxphotos provides several useful helper functions to make it easy to build simp
 Here's a simple example showing how to use the `query_command` decorator to implement a simple command line tool. The `query_command` decorator turns your function into a full-fledged [Click](https://palletsprojects.com/p/click/) command line app that can be run via `osxphotos run example.py` or `python example.py` if you have pip installed osxphotos.  Your command will include all the query options available in `osxphotos query` as command line options as well as `--verbose` and other convenient options.
 
 <!--[[[cog
-cog.out("```python\n")
+cog.out("\n```python\n")
 with open("examples/cli_example_1.py", "r") as f:
     cog.out(f.read())
 cog.out("```\n")
 ]]]-->
+
 ```python
 """Sample query command for osxphotos
 
@@ -136,11 +137,12 @@ if __name__ == "__main__":
 Here is a more advanced example that shows how to implement a script with a "dry run" and "resume" capability that preserves state between runs. Using the built-in helpers allows you to implement complex behavior in just a few lines of code.
 
 <!--[[[cog
-cog.out("```python\n")
+cog.out("\n```python\n")
 with open("examples/cli_example_2.py", "r") as f:
     cog.out(f.read())
 cog.out("```\n")
 ]]]-->
+
 ```python
 """Sample query command for osxphotos
 
@@ -308,11 +310,12 @@ if __name__ == "__main__":
 In addition to the `query_command` decorator, you can also use the `selection_command` decorator to implement a command that operates on the current selection in Photos.
 
 <!--[[[cog
-cog.out("```python\n")
+cog.out("\n```python\n")
 with open("examples/cli_example_3.py", "r") as f:
     cog.out(f.read())
 cog.out("```\n")
 ]]]-->
+
 ```python
 """Sample query command for osxphotos
 
@@ -2242,8 +2245,9 @@ To get the path of every raw photo, whether it's a single raw photo or a raw+JPE
 
 <!--[[[cog
 from osxphotos.phototemplate import get_template_help
-cog.out(get_template_help())
+cog.out("\n"+get_template_help())
 ]]]-->
+
 <!-- Generated by cog: see phototemplate.cog.md -->
 
 The templating system converts one or template statements, written in osxphotos metadata templating language, to one or more rendered values using information from the photo being processed.
@@ -2408,8 +2412,9 @@ The following template field substitutions are availabe for use the templating s
 
 <!--[[[cog
 from osxphotos.phototemplate import get_template_field_table
-cog.out(get_template_field_table())
+cog.out("\n"+get_template_field_table()+"\n")
 ]]]-->
+
 | Field | Description |
 |--------------|-------------|
 |{name}|Current filename of the photo|

README.md

@@ -1448,8 +1448,18 @@ Options:
                                   full path of all exported files to the file
                                   'exported.txt'. You can run more than one
                                   command by repeating the '--post-command'
-                                  option with different arguments. See Post
+                                  option with different arguments. See also
-                                  Command below.
+                                  --post-command-error and --post-function.See
+                                  Post Command below.
+  --post-command-error ACTION     Specify either `continue` or `break` for
+                                  ACTION to control behavior when a post-command
+                                  fails. If `continue`, osxphotos will log the
+                                  error and continue processing. If `break`,
+                                  osxphotos will stop processing any additional
+                                  --post-command commands for the current photo
+                                  but will continue with the export. Without
+                                  --post-command-error, osxphotos will abort the
+                                  export if a post-command encounters an error.
   --post-function filename.py::function
                                   Run function on exported files. Use this in
                                   format: --post-function filename.py::function

build.sh

@@ -30,6 +30,12 @@ python3 utils/generate_template_docs.py
 m2r2 docsrc/source/template_help.md
 rm docsrc/source/template_help.md
 
+echo "Copying API_README.md to docsrc/source/api_readme.md"
+rm docsrc/source/api_readme.rst
+cp API_README.md docsrc/source/api_readme.md
+m2r2 docsrc/source/api_readme.md
+rm docsrc/source/api_readme.md
+
 # build docs
 echo "Building docs"
 (cd docsrc && make github && make pdf)

docs/_modules/index.html

@@ -160,6 +160,7 @@
 <li class="toctree-l1"><a class="reference internal" href="../cli.html">OSXPhotos Command Line Interface (CLI)</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../template_help.html">OSXPhotos Template System</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../package_overview.html">OSXPhotos Python Package Overview</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../api_readme.html">OSXPhotos Python API</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../reference.html">OSXPhotos Python Reference</a></li>
 </ul>
 

docs/_modules/osxphotos/photoexporter.html

@@ -489,6 +489,7 @@
         <span class="s2">&quot;sidecar_xmp_written&quot;</span><span class="p">,</span>
         <span class="s2">&quot;sidecar_user_written&quot;</span><span class="p">,</span>
         <span class="s2">&quot;sidecar_user_skipped&quot;</span><span class="p">,</span>
+        <span class="s2">&quot;sidecar_user_error&quot;</span><span class="p">,</span>
         <span class="s2">&quot;skipped&quot;</span><span class="p">,</span>
         <span class="s2">&quot;skipped_album&quot;</span><span class="p">,</span>
         <span class="s2">&quot;to_touch&quot;</span><span class="p">,</span>
@@ -522,6 +523,7 @@
         <span class="n">sidecar_xmp_written</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span>
         <span class="n">sidecar_user_written</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span>
         <span class="n">sidecar_user_skipped</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span>
+        <span class="n">sidecar_user_error</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span>
         <span class="n">skipped</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span>
         <span class="n">skipped_album</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span>
         <span class="n">to_touch</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span>
@@ -569,6 +571,7 @@
         <span class="n">files</span> <span class="o">+=</span> <span class="p">[</span><span class="n">x</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span> <span class="k">for</span> <span class="n">x</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">exiftool_warning</span><span class="p">]</span>
         <span class="n">files</span> <span class="o">+=</span> <span class="p">[</span><span class="n">x</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span> <span class="k">for</span> <span class="n">x</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">exiftool_error</span><span class="p">]</span>
         <span class="n">files</span> <span class="o">+=</span> <span class="p">[</span><span class="n">x</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span> <span class="k">for</span> <span class="n">x</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">error</span><span class="p">]</span>
+        <span class="n">files</span> <span class="o">+=</span> <span class="p">[</span><span class="n">x</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span> <span class="k">for</span> <span class="n">x</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">sidecar_user_error</span><span class="p">]</span>
 
         <span class="k">return</span> <span class="nb">list</span><span class="p">(</span><span class="nb">set</span><span class="p">(</span><span class="n">files</span><span class="p">))</span></div>
 
@@ -1636,7 +1639,8 @@
         <span class="k">if</span> <span class="n">options</span><span class="o">.</span><span class="n">export_as_hardlink</span><span class="p">:</span>
             <span class="k">try</span><span class="p">:</span>
                 <span class="k">if</span> <span class="n">aae_dest</span><span class="o">.</span><span class="n">exists</span><span class="p">()</span> <span class="ow">and</span> <span class="nb">any</span><span class="p">(</span>
-                    <span class="p">[</span><span class="n">options</span><span class="o">.</span><span class="n">overwrite</span><span class="p">,</span> <span class="n">options</span><span class="o">.</span><span class="n">update</span><span class="p">,</span> <span class="n">options</span><span class="o">.</span><span class="n">force_update</span><span class="p">]):</span>
+                    <span class="p">[</span><span class="n">options</span><span class="o">.</span><span class="n">overwrite</span><span class="p">,</span> <span class="n">options</span><span class="o">.</span><span class="n">update</span><span class="p">,</span> <span class="n">options</span><span class="o">.</span><span class="n">force_update</span><span class="p">]</span>
+                <span class="p">):</span>
                     <span class="k">try</span><span class="p">:</span>
                         <span class="n">options</span><span class="o">.</span><span class="n">fileutil</span><span class="o">.</span><span class="n">unlink</span><span class="p">(</span><span class="n">aae_dest</span><span class="p">)</span>
                     <span class="k">except</span> <span class="ne">Exception</span> <span class="k">as</span> <span class="n">e</span><span class="p">:</span>

docs/_sources/API_README.rst.txt

@@ -31,6 +31,7 @@ Table of Contents
   * `CommentInfo <#commentinfo>`_
   * `LikeInfo <#likeinfo>`_
   * `AdjustmentsInfo <#adjustmentsinfo>`_
+  * `PhotoTables <#phototables>`_
   * `Raw Photos <#raw-photos>`_
   * `Template System <#template-system>`_
   * `ExifTool <#exiftoolExifTool>`_
@@ -70,12 +71,16 @@ Here's a simple example showing how to use the ``query_command`` decorator to im
 .. raw:: html
 
    <!--[[[cog
-   cog.out("```python\n")
+   cog.out("\n```python\n")
    with open("examples/cli_example_1.py", "r") as f:
        cog.out(f.read())
    cog.out("```\n")
    ]]]-->
-   ```python
+
+
+
+.. code-block:: python
+
    """Sample query command for osxphotos
 
    This shows how simple it is to create a command line tool using osxphotos to process your photos.
@@ -143,7 +148,10 @@ Here's a simple example showing how to use the ``query_command`` decorator to im
        # you do not need to pass any arguments to the function
        # as the decorator will handle parsing the command line arguments
        example()
-   ```
+
+
+.. raw:: html
+
    <!--[[[end]]]-->
 
 
@@ -154,12 +162,16 @@ Here is a more advanced example that shows how to implement a script with a "dry
 .. raw:: html
 
    <!--[[[cog
-   cog.out("```python\n")
+   cog.out("\n```python\n")
    with open("examples/cli_example_2.py", "r") as f:
        cog.out(f.read())
    cog.out("```\n")
    ]]]-->
-   ```python
+
+
+
+.. code-block:: python
+
    """Sample query command for osxphotos
 
    This shows how simple it is to create a command line tool using osxphotos to process your photos.
@@ -320,7 +332,10 @@ Here is a more advanced example that shows how to implement a script with a "dry
        # you do not need to pass any arguments to the function
        # as the decorator will handle parsing the command line arguments
        example()
-   ```
+
+
+.. raw:: html
+
    <!--[[[end]]]-->
 
 
@@ -331,12 +346,16 @@ In addition to the ``query_command`` decorator, you can also use the ``selection
 .. raw:: html
 
    <!--[[[cog
-   cog.out("```python\n")
+   cog.out("\n```python\n")
    with open("examples/cli_example_3.py", "r") as f:
        cog.out(f.read())
    cog.out("```\n")
    ]]]-->
-   ```python
+
+
+
+.. code-block:: python
+
    """Sample query command for osxphotos
 
    This shows how simple it is to create a command line tool using osxphotos to process your photos.
@@ -362,10 +381,7 @@ In addition to the ``query_command`` decorator, you can also use the ``selection
    from __future__ import annotations
 
    import osxphotos
-   from osxphotos.cli import (
+   from osxphotos.cli import selection_command, verbose
-       selection_command,
-       verbose,
-   )
 
 
    @selection_command
@@ -397,11 +413,81 @@ In addition to the ``query_command`` decorator, you can also use the ``selection
        # you do not need to pass any arguments to the function
        # as the decorator will handle parsing the command line arguments
        example()
-   ```
+
+
+.. raw:: html
+
    <!--[[[end]]]-->
 
 
 
+Concurrency
+-----------
+
+OSXPhotos is not currently compatible with multiprocessing as the ``PhotosDB`` class cannot be pickled which required
+when sharing data between processes. Photos can be exported concurrently using separate threads, however, this is
+only compatible with Python 3.11 and later.  See `issue #999 <https://github.com/RhetTbull/osxphotos/issues/999>`_.
+The reason for this is that internally, ``PhotoExporter`` uses a sqlite ``ExportDB`` database for managing the export,
+even if you don't specify an export database. (In the case where you don't specify an export database, a temporary
+in-memory database is created and then discard.) The python implementation of sqlite3 is not fully thread safe on
+Python < 3.11.
+
+For example, the following code will work on Python >= 3.11. This code is available in the ``examples`` directory as
+`concurrent_export.py <https://github.com/RhetTbull/osxphotos/blob/main/examples/concurrent_export.py>`_.
+
+.. code-block:: python
+
+   """Example for concurrent export of photos using osxphotos.PhotoExporter.export()
+
+   Note: concurrent export can only be used on Python 3.11 and later due to the way
+   python's sqlite3 module is implemented. See https://docs.python.org/3/library/sqlite3.html#sqlite3.threadsafety
+   for more information.
+   """
+
+   import concurrent.futures
+   import os
+   import time
+
+   import click
+
+   import osxphotos
+   from osxphotos.cli import echo, query_command, verbose
+
+
+   @query_command()
+   @click.option(
+       "--workers",
+       metavar="WORKERS",
+       help="Maximum number of worker threads to use for export. "
+       "If not specified, it will default to the number of processors on the machine, multiplied by 5.",
+       type=int,
+   )
+   @click.argument(
+       "export_dir",
+       type=click.Path(exists=True, file_okay=False, dir_okay=True, writable=True),
+   )
+   def export(workers, export_dir, photos: list[osxphotos.PhotoInfo], **kwargs):
+       """Export photos"""
+       workers = workers or os.cpu_count() * 5
+       echo(f"Exporting {len(photos)} photos to {export_dir} using {workers} workers")
+       start_t = time.perf_counter()
+       with concurrent.futures.ThreadPoolExecutor(max_workers=workers) as executor:
+           futures = [
+               executor.submit(p.export, export_dir, f"{p.uuid}_{p.original_filename}")
+               for p in photos
+           ]
+           exported = []
+           for future in concurrent.futures.as_completed(futures):
+               exported.extend(future.result())
+       end_t = time.perf_counter()
+       echo(
+           f"Exported {len(exported)} photos to {export_dir} in {end_t-start_t:.4f} seconds"
+       )
+
+
+   if __name__ == "__main__":
+       export()
+
 Package Interface
 -----------------
 
@@ -1232,6 +1318,22 @@ Returns True if photo is a `cloud asset <#iscloudasset>`_ and is synched to iClo
 
 **Note**\ : Applies to master (original) photo only.  It's possible for the master to be in iCloud but a local edited version is not yet synched to iCloud. ``incloud`` provides status of only the master photo.  osxphotos does not yet provide a means to determine if the edited version is in iCloud.  If you need this feature, please open an `issue <https://github.com/RhetTbull/osxphotos/issues>`_.
 
+``syndicated``
+~~~~~~~~~~~~~~~~~~
+
+Return true if photo was shared via syndication (e.g. via Messages, etc.); these are photos that appear in "Shared with you" album. Photos 7+ only; returns None if not Photos 7+.
+
+``saved_to_library``
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Return True if syndicated photo has been saved to library; returns False if photo is not syndicated or has not been saved to the library.
+Syndicated photos are photos that appear in "Shared with you" album. Photos 7+ only; returns None if not Photos 7+.
+
+``shared_moment``
+^^^^^^^^^^^^^^^^^^^^^
+
+Return True if photo is part of a shared moment, otherwise False.  Shared moments are created when multiple photos are shared via iCloud. (e.g. in Messages)
+
 ``uti``
 ~~~~~~~~~~~
 
@@ -1459,6 +1561,16 @@ Returns a `ScoreInfo <#scoreinfo>`_ data class object which provides access to t
 
 Returns list of PhotoInfo objects for *possible* duplicates or empty list if no matching duplicates.  Photos are considered possible duplicates if the photo's original file size, date created, height, and width match another those of another photo.  This does not do a byte-for-byte comparison or compute a hash which makes it fast and allows for identification of possible duplicates even if originals are not downloaded from iCloud.  The signature-based approach should be robust enough to match duplicates created either through the "duplicate photo" menu item or imported twice into the library but you should not rely on this 100% for identification of all duplicates.
 
+``cloud_guid``
+~~~~~~~~~~~~~~~~~~
+
+For photos in iCloud, returns the cloud GUID for the photo.  This is the unique identifier for the photo in iCloud.  For photos not in iCloud, returns None.
+
+``cloud_owner_hashed_id``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For shared photos, returns the hashed ID of the owner of the shared photo.  For photos not shared, returns None.
+
 ``fingerprint``
 ~~~~~~~~~~~~~~~~~~~
 
@@ -1469,6 +1581,13 @@ Returns a unique fingerprint for the original photo file.  This is a hash of the
 
 Returns a unique digest of the photo's properties and metadata; useful for detecting changes in any property/metadata of the photo.
 
+``tables()``
+~~~~~~~~~~~~~~~~
+
+Returns a PhotoTables object which provides access to the underlying SQLite database tables for the photo.
+See `PhotoTables <#phototables>`_ for more details. This is useful for debugging or developing new features but
+is not intended for general use.
+
 ``json()``
 ~~~~~~~~~~~~~~
 
@@ -1685,13 +1804,16 @@ Returns full name of the album owner (person who shared the album) for shared al
 
 **Note**\ : *Only valid on Photos 5 / MacOS 10.15+; on Photos <= 4, returns None.
 
+``asdict()``
+~~~~~~~~~~~~~~~~
+
+Returns a dictionary representation of the AlbumInfo object.
+
 ImportInfo
 ^^^^^^^^^^
 
 PhotosDB.import_info returns a list of ImportInfo objects.  Each ImportInfo object represents an import session in the library.  PhotoInfo.import_info returns a single ImportInfo object representing the import session for the photo (or ``None`` if no associated import session).
 
-**Note**\ : Photos 5+ only.  Not implemented for Photos version <= 4.
-
 ``uuid``
 ~~~~~~~~~~~~
 
@@ -1710,13 +1832,20 @@ Returns the creation date as a timezone aware datetime.datetime object of the im
 ``start_date``
 ~~~~~~~~~~~~~~~~~~
 
-Returns the start date as a timezone aware datetime.datetime object for when the import session bega.
+Returns the start date as a timezone aware datetime.datetime object for when the import session began.
 
 ``end_date``
 ~~~~~~~~~~~~~~~~
 
 Returns the end date as a timezone aware datetime.datetime object for when the import session completed.
 
+**Note**\ : On Photos <=4, ``start_date`` and ``end_date`` will be the same as ``creation_date``.
+
+``asdict()``
+~~~~~~~~~~~~~~~~
+
+Returns a dictionary representation of the import session.
+
 ProjectInfo
 ^^^^^^^^^^^
 
@@ -1744,6 +1873,11 @@ Returns a list of `PhotoInfo <#photoinfo>`_ objects representing each photo cont
 
 Returns the creation date as a timezone aware datetime.datetime object of the project.
 
+``asdict()``
+~~~~~~~~~~~~~~~~
+
+Returns a dictionary representation of the ProjectInfo object.
+
 MomentInfo
 ^^^^^^^^^^
 
@@ -1855,6 +1989,11 @@ Returns album sort order (as ``AlbumSortOrder`` enum).  On Photos <=4, always re
 
 Returns index of photo in album (based on album sort order).
 
+``asdict()``
+~~~~~~~~~~~~~~~~
+
+Returns a dictionary representation of the FolderInfo object.
+
 **Note**\ : FolderInfo and AlbumInfo objects effectively work as a linked list.  The children of a folder are contained in ``subfolders`` and ``album_info`` and the parent object of both ``AlbumInfo`` and ``FolderInfo`` is represented by ``parent``.  For example:
 
 .. code-block:: pycon
@@ -2339,6 +2478,39 @@ AdjustmentsInfo
 * ``adj_version_info``\ : version info for the application which made the adjustments to the photo decoded from the adjustments data.
 * ``asdict()``\ : dict representation of the AdjustmentsInfo object; contains all properties with exception of ``plist``.
 
+PhotoTables
+^^^^^^^^^^^
+
+`PhotoInfo.tables <#tables>`_ returns a PhotoTables object that contains information about the tables in the Photos database that contain information about the photo.
+The following properties are available:
+
+
+* ``ZASSET``
+* ``ZADDITIONALASSETATTRIBUTES``
+* ``ZDETECTEDFACE``
+* ``ZPERSON``
+
+Each of these properties returns a ``Table`` object that provides access to the row(s) in the table that correspond to the photo.
+
+The Table object has dynamically created properties that correspond to the associated column in the table and return a tuple of values for that column.
+
+.. code-block:: pycon
+
+   >>> photo.tables().ZADDITIONALASSETATTRIBUTES.ZTITLE
+   ("St. James's Park",)
+
+The Table object also provides a ``rows()`` method which returns a list a of tuples for the matching rows in the table
+and a ``rows_dict()`` method which returns a list of dicts for the matching rows in the table.
+
+.. code-block:: pycon
+
+
+   >>> photo.tables().ZASSET.rows()
+   [(6, 3, 35, 0, 0, 0, 0, 0, 0, None, None, None, None, None, 0, 0, 1, 0, 0, 0, 0, -100, 0, 1, 0, 1356, 0, 0, 0, 0, 0, 0, 0, 1, 6192599813128215, 1, 2814835671629878, 1, 0, 3, 0, 0, 5, 0, 0, 0, 0, 0, 0, 0, 2047, 7, None, 8, None, None, None, None, None, None, None, None, 3, 6, 6, 6, None, 6, 4, None, None, 8, 4, None, 2, None, 3, None, 3, None, None, 585926209.859624, 596906868.198932, 689981763.374756, None, None, None, 0.5, 561129492.501, 0.0, 596906868.198932, None, 0.03816793893129771, None, 51.50357167, -0.1318055, 689982854.802854, 0.6494140625, 0.0, 561129492.501, None, None, None, None, None, None, None, 'D', 'DC99FBDD-7A52-4100-A5BB-344131646C30.jpeg', None, 'sRGB IEC61966-2.1', 'public.jpeg', 'DC99FBDD-7A52-4100-A5BB-344131646C30', b'Ki\t@\x01\x00\x00\x00\td\tH\x01\x00\x00\x00\x93\\\tL\x01\x00\x00\x00\x1aK\x0c\x03\x0c\xa8q\x92\x00\x12C\x0c\x03\x0c"\r\x90\x00\x00<\x0c\x03\x08"\x19\x80\x00', b'\xca\xebV\tu\xc0I@/j\xf7\xab\x00\xdf\xc0\xbf\xcd\xcc\xcc\xcc\xcc\xcc\x04@\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00')]
+
+   >>> photo.tables().ZASSET.rows_dict()
+   [{'Z_PK': 6, 'Z_ENT': 3, 'Z_OPT': 35, 'ZACTIVELIBRARYSCOPEPARTICIPATIONSTATE': 0, 'ZAVALANCHEPICKTYPE': 0, 'ZBUNDLESCOPE': 0, 'ZCAMERAPROCESSINGADJUSTMENTSTATE': 0, 'ZCLOUDDELETESTATE': 0, 'ZCLOUDDOWNLOADREQUESTS': 0, 'ZCLOUDHASCOMMENTSBYME': None, 'ZCLOUDHASCOMMENTSCONVERSATION': None, 'ZCLOUDHASUNSEENCOMMENTS': None, 'ZCLOUDISDELETABLE': None, 'ZCLOUDISMYASSET': None, 'ZCLOUDLOCALSTATE': 0, 'ZCLOUDPLACEHOLDERKIND': 0, 'ZCOMPLETE': 1, 'ZDEFERREDPROCESSINGNEEDED': 0, 'ZDEPTHTYPE': 0, 'ZDERIVEDCAMERACAPTUREDEVICE': 0, 'ZDUPLICATEASSETVISIBILITYSTATE': 0, 'ZFACEAREAPOINTS': -100, 'ZFAVORITE': 0, 'ZHASADJUSTMENTS': 1, 'ZHDRTYPE': 0, 'ZHEIGHT': 1356, 'ZHIDDEN': 0, 'ZHIGHFRAMERATESTATE': 0, 'ZISMAGICCARPET': 0, 'ZKIND': 0, 'ZKINDSUBTYPE': 0, 'ZLIBRARYSCOPESHARESTATE': 0, 'ZMONOSKITYPE': 0, 'ZORIENTATION': 1, 'ZPACKEDACCEPTABLECROPRECT': 6192599813128215, 'ZPACKEDBADGEATTRIBUTES': 1, 'ZPACKEDPREFERREDCROPRECT': 2814835671629878, 'ZPLAYBACKSTYLE': 1, 'ZPLAYBACKVARIATION': 0, 'ZSAVEDASSETTYPE': 3, 'ZSEARCHINDEXREBUILDSTATE': 0, 'ZSYNDICATIONSTATE': 0, 'ZTHUMBNAILINDEX': 5, 'ZTRASHEDSTATE': 0, 'ZVIDEOCPDURATIONVALUE': 0, 'ZVIDEOCPVISIBILITYSTATE': 0, 'ZVIDEODEFERREDPROCESSINGNEEDED': 0, 'ZVIDEOKEYFRAMETIMESCALE': 0, 'ZVIDEOKEYFRAMEVALUE': 0, 'ZVISIBILITYSTATE': 0, 'ZWIDTH': 2047, 'ZADDITIONALATTRIBUTES': 7, 'ZCLOUDFEEDASSETSENTRY': None, 'ZCOMPUTEDATTRIBUTES': 8, 'ZCONVERSATION': None, 'ZDAYGROUPHIGHLIGHTBEINGASSETS': None, 'ZDAYGROUPHIGHLIGHTBEINGEXTENDEDASSETS': None, 'ZDAYGROUPHIGHLIGHTBEINGKEYASSETPRIVATE': None, 'ZDAYGROUPHIGHLIGHTBEINGKEYASSETSHARED': None, 'ZDAYGROUPHIGHLIGHTBEINGSUMMARYASSETS': None, 'ZDUPLICATEMETADATAMATCHINGALBUM': None, 'ZDUPLICATEPERCEPTUALMATCHINGALBUM': None, 'ZEXTENDEDATTRIBUTES': 3, 'ZHIGHLIGHTBEINGASSETS': 6, 'ZHIGHLIGHTBEINGEXTENDEDASSETS': 6, 'ZHIGHLIGHTBEINGKEYASSETPRIVATE': 6, 'ZHIGHLIGHTBEINGKEYASSETSHARED': None, 'ZHIGHLIGHTBEINGSUMMARYASSETS': 6, 'ZIMPORTSESSION': 4, 'ZLIBRARYSCOPE': None, 'ZMASTER': None, 'ZMEDIAANALYSISATTRIBUTES': 8, 'ZMOMENT': 4, 'ZMOMENTSHARE': None, 'ZMONTHHIGHLIGHTBEINGKEYASSETPRIVATE': 2, 'ZMONTHHIGHLIGHTBEINGKEYASSETSHARED': None, 'ZPHOTOANALYSISATTRIBUTES': 3, 'ZTRASHEDBYPARTICIPANT': None, 'ZYEARHIGHLIGHTBEINGKEYASSETPRIVATE': 3, 'ZYEARHIGHLIGHTBEINGKEYASSETSHARED': None, 'Z_FOK_CLOUDFEEDASSETSENTRY': None, 'ZADDEDDATE': 585926209.859624, 'ZADJUSTMENTTIMESTAMP': 596906868.198932, 'ZANALYSISSTATEMODIFICATIONDATE': 689981763.374756, 'ZCLOUDBATCHPUBLISHDATE': None, 'ZCLOUDLASTVIEWEDCOMMENTDATE': None, 'ZCLOUDSERVERPUBLISHDATE': None, 'ZCURATIONSCORE': 0.5, 'ZDATECREATED': 561129492.501, 'ZDURATION': 0.0, 'ZFACEADJUSTMENTVERSION': 596906868.198932, 'ZHDRGAIN': None, 'ZHIGHLIGHTVISIBILITYSCORE': 0.03816793893129771, 'ZLASTSHAREDDATE': None, 'ZLATITUDE': 51.50357167, 'ZLONGITUDE': -0.1318055, 'ZMODIFICATIONDATE': 689982854.802854, 'ZOVERALLAESTHETICSCORE': 0.6494140625, 'ZPROMOTIONSCORE': 0.0, 'ZSORTTOKEN': 561129492.501, 'ZTRASHEDDATE': None, 'ZAVALANCHEUUID': None, 'ZCLOUDASSETGUID': None, 'ZCLOUDBATCHID': None, 'ZCLOUDCOLLECTIONGUID': None, 'ZCLOUDOWNERHASHEDPERSONID': None, 'ZDELETEREASON': None, 'ZDIRECTORY': 'D', 'ZFILENAME': 'DC99FBDD-7A52-4100-A5BB-344131646C30.jpeg', 'ZMEDIAGROUPUUID': None, 'ZORIGINALCOLORSPACE': 'sRGB IEC61966-2.1', 'ZUNIFORMTYPEIDENTIFIER': 'public.jpeg', 'ZUUID': 'DC99FBDD-7A52-4100-A5BB-344131646C30', 'ZIMAGEREQUESTHINTS': b'Ki\t@\x01\x00\x00\x00\td\tH\x01\x00\x00\x00\x93\\\tL\x01\x00\x00\x00\x1aK\x0c\x03\x0c\xa8q\x92\x00\x12C\x0c\x03\x0c"\r\x90\x00\x00<\x0c\x03\x08"\x19\x80\x00', 'ZLOCATIONDATA': b'\xca\xebV\tu\xc0I@/j\xf7\xab\x00\xdf\xc0\xbf\xcd\xcc\xcc\xcc\xcc\xcc\x04@\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00'}]
+
 Raw Photos
 ^^^^^^^^^^
 
@@ -2411,8 +2583,14 @@ Template System
 
    <!--[[[cog
    from osxphotos.phototemplate import get_template_help
-   cog.out(get_template_help())
+   cog.out("\n"+get_template_help())
    ]]]-->
+
+
+
+
+.. raw:: html
+
    <!-- Generated by cog: see phototemplate.cog.md -->
 
 
@@ -2473,6 +2651,8 @@ Valid filters are:
 * `join(x)`: Join list of values with delimiter x, e.g. join(,): ['a', 'b', 'c'] => 'a,b,c'; the DELIM option functions similar to join(x) but with DELIM, the join happens before being passed to any filters.May optionally be used without an argument, that is 'join()' which joins values together with no delimiter. e.g. join(): ['a', 'b', 'c'] => 'abc'.
 * `append(x)`: Append x to list of values, e.g. append(d): ['a', 'b', 'c'] => ['a', 'b', 'c', 'd'].
 * `prepend(x)`: Prepend x to list of values, e.g. prepend(d): ['a', 'b', 'c'] => ['d', 'a', 'b', 'c'].
+* `appends(x)`: Append s[tring] Append x to each value of list of values, e.g. appends(d): ['a', 'b', 'c'] => ['ad', 'bd', 'cd'].
+* `prepends(x)`: Prepend s[tring] x to each value of list of values, e.g. prepends(d): ['a', 'b', 'c'] => ['da', 'db', 'dc'].
 * `remove(x)`: Remove x from list of values, e.g. remove(b): ['a', 'b', 'c'] => ['a', 'c'].
 * `slice(start:stop:step)`: Slice list using same semantics as Python's list slicing, e.g. slice(1:3): ['a', 'b', 'c', 'd'] => ['b', 'c']; slice(1:4:2): ['a', 'b', 'c', 'd'] => ['b', 'd']; slice(1:): ['a', 'b', 'c', 'd'] => ['b', 'c', 'd']; slice(:-1): ['a', 'b', 'c', 'd'] => ['a', 'b', 'c']; slice(::-1): ['a', 'b', 'c', 'd'] => ['d', 'c', 'b', 'a']. See also sslice().
 * `sslice(start:stop:step)`: [s(tring) slice] Slice values in a list using same semantics as Python's string slicing, e.g. sslice(1:3):'abcd => 'bc'; sslice(1:4:2): 'abcd' => 'bd', etc. See also slice().
@@ -2575,9 +2755,9 @@ e.g. ``"{created.year}/{openbrace}{title}{closebrace}"`` would result in ``"2020
 
 **Variables**
 
-You can define variables for later use in the template string using the format ``{var:NAME,VALUE}``.  Variables may then be referenced using the format ``%NAME``. For example: ``{var:foo,bar}`` defines the variable ``%foo`` to have value ``bar``. This can be useful if you want to re-use a complex template value in multiple places within your template string or for allowing the use of characters that would otherwise be prohibited in a template string. For example, the "pipe" (\ ``|``\ ) character is not allowed in a find/replace pair but you can get around this limitation like so: ``{var:pipe,{pipe}}{title[-,%pipe]}`` which replaces the ``-`` character with ``|`` (the value of ``%pipe``\ ).  
+You can define variables for later use in the template string using the format ``{var:NAME,VALUE}`` where ``VALUE`` is a template statement.  Variables may then be referenced using the format ``%NAME``. For example: ``{var:foo,bar}`` defines the variable ``%foo`` to have value ``bar``. This can be useful if you want to re-use a complex template value in multiple places within your template string or for allowing the use of characters that would otherwise be prohibited in a template string. For example, the "pipe" (\ ``|``\ ) character is not allowed in a find/replace pair but you can get around this limitation like so: ``{var:pipe,{pipe}}{title[-,%pipe]}`` which replaces the ``-`` character with ``|`` (the value of ``%pipe``\ ).  
 
-Variables can also be referenced as fields in the template string, for example: ``{var:year,created.year}{original_name}-{%year}``. In some cases, use of variables can make your template string more readable.  Variables can be used as template fields, as values for filters, as values for conditional operations, or as default values.  When used as a conditional value or default value, variables should be treated like any other field and enclosed in braces as conditional and default values are evaluated as template strings. For example: ``{var:name,Katie}{person contains {%name}?{%name},Not-{%name}}``.
+Variables can also be referenced as fields in the template string, for example: ``{var:year,{created.year}}{original_name}-{%year}``. In some cases, use of variables can make your template string more readable.  Variables can be used as template fields, as values for filters, as values for conditional operations, or as default values.  When used as a conditional value or default value, variables should be treated like any other field and enclosed in braces as conditional and default values are evaluated as template strings. For example: ``{var:name,Katie}{person contains {%name}?{%name},Not-{%name}}``.
 
 If you need to use a ``%`` (percent sign character), you can escape the percent sign by using ``%%``.  You can also use the ``{percent}`` template field where a template field is required. For example:
 
@@ -2591,124 +2771,249 @@ The following template field substitutions are availabe for use the templating s
 
    <!--[[[cog
    from osxphotos.phototemplate import get_template_field_table
-   cog.out(get_template_field_table())
+   cog.out("\n"+get_template_field_table()+"\n")
    ]]]-->
-   | Field | Description |
+
-   |--------------|-------------|
+
-   |{name}|Current filename of the photo|
+
-   |{original_name}|Photo's original filename when imported to Photos|
+.. list-table::
-   |{title}|Title of the photo|
+   :header-rows: 1
-   |{descr}|Description of the photo|
+
-   |{media_type}|Special media type resolved in this precedence: selfie, time_lapse, panorama, slow_mo, screenshot, portrait, live_photo, burst, photo, video. Defaults to 'photo' or 'video' if no special type. Customize one or more media types using format: '{media_type,video=vidéo;time_lapse=vidéo_accélérée}'|
+   * - Field
-   |{photo_or_video}|'photo' or 'video' depending on what type the image is. To customize, use default value as in '{photo_or_video,photo=fotos;video=videos}'|
+     - Description
-   |{hdr}|Photo is HDR?; True/False value, use in format '{hdr?VALUE_IF_TRUE,VALUE_IF_FALSE}'|
+   * - {name}
-   |{edited}|True if photo has been edited (has adjustments), otherwise False; use in format '{edited?VALUE_IF_TRUE,VALUE_IF_FALSE}'|
+     - Current filename of the photo
-   |{edited_version}|True if template is being rendered for the edited version of a photo, otherwise False. |
+   * - {original_name}
-   |{favorite}|Photo has been marked as favorite?; True/False value, use in format '{favorite?VALUE_IF_TRUE,VALUE_IF_FALSE}'|
+     - Photo's original filename when imported to Photos
-   |{created}|Photo's creation date in ISO format, e.g. '2020-03-22'|
+   * - {title}
-   |{created.date}|Photo's creation date in ISO format, e.g. '2020-03-22'|
+     - Title of the photo
-   |{created.year}|4-digit year of photo creation time|
+   * - {descr}
-   |{created.yy}|2-digit year of photo creation time|
+     - Description of the photo
-   |{created.mm}|2-digit month of the photo creation time (zero padded)|
+   * - {media_type}
-   |{created.month}|Month name in user's locale of the photo creation time|
+     - Special media type resolved in this precedence: selfie, time_lapse, panorama, slow_mo, screenshot, portrait, live_photo, burst, photo, video. Defaults to 'photo' or 'video' if no special type. Customize one or more media types using format: '{media_type,video=vidéo;time_lapse=vidéo_accélérée}'
-   |{created.mon}|Month abbreviation in the user's locale of the photo creation time|
+   * - {photo_or_video}
-   |{created.dd}|2-digit day of the month (zero padded) of photo creation time|
+     - 'photo' or 'video' depending on what type the image is. To customize, use default value as in '{photo_or_video,photo=fotos;video=videos}'
-   |{created.dow}|Day of week in user's locale of the photo creation time|
+   * - {hdr}
-   |{created.doy}|3-digit day of year (e.g Julian day) of photo creation time, starting from 1 (zero padded)|
+     - Photo is HDR?; True/False value, use in format '{hdr?VALUE_IF_TRUE,VALUE_IF_FALSE}'
-   |{created.hour}|2-digit hour of the photo creation time|
+   * - {edited}
-   |{created.min}|2-digit minute of the photo creation time|
+     - True if photo has been edited (has adjustments), otherwise False; use in format '{edited?VALUE_IF_TRUE,VALUE_IF_FALSE}'
-   |{created.sec}|2-digit second of the photo creation time|
+   * - {edited_version}
-   |{created.strftime}|Apply strftime template to file creation date/time. Should be used in form {created.strftime,TEMPLATE} where TEMPLATE is a valid strftime template, e.g. {created.strftime,%Y-%U} would result in year-week number of year: '2020-23'. If used with no template will return null value. See https://strftime.org/ for help on strftime templates.|
+     - True if template is being rendered for the edited version of a photo, otherwise False.
-   |{modified}|Photo's modification date in ISO format, e.g. '2020-03-22'; uses creation date if photo is not modified|
+   * - {favorite}
-   |{modified.date}|Photo's modification date in ISO format, e.g. '2020-03-22'; uses creation date if photo is not modified|
+     - Photo has been marked as favorite?; True/False value, use in format '{favorite?VALUE_IF_TRUE,VALUE_IF_FALSE}'
-   |{modified.year}|4-digit year of photo modification time; uses creation date if photo is not modified|
+   * - {created}
-   |{modified.yy}|2-digit year of photo modification time; uses creation date if photo is not modified|
+     - Photo's creation date in ISO format, e.g. '2020-03-22'
-   |{modified.mm}|2-digit month of the photo modification time (zero padded); uses creation date if photo is not modified|
+   * - {created.date}
-   |{modified.month}|Month name in user's locale of the photo modification time; uses creation date if photo is not modified|
+     - Photo's creation date in ISO format, e.g. '2020-03-22'
-   |{modified.mon}|Month abbreviation in the user's locale of the photo modification time; uses creation date if photo is not modified|
+   * - {created.year}
-   |{modified.dd}|2-digit day of the month (zero padded) of the photo modification time; uses creation date if photo is not modified|
+     - 4-digit year of photo creation time
-   |{modified.dow}|Day of week in user's locale of the photo modification time; uses creation date if photo is not modified|
+   * - {created.yy}
-   |{modified.doy}|3-digit day of year (e.g Julian day) of photo modification time, starting from 1 (zero padded); uses creation date if photo is not modified|
+     - 2-digit year of photo creation time
-   |{modified.hour}|2-digit hour of the photo modification time; uses creation date if photo is not modified|
+   * - {created.mm}
-   |{modified.min}|2-digit minute of the photo modification time; uses creation date if photo is not modified|
+     - 2-digit month of the photo creation time (zero padded)
-   |{modified.sec}|2-digit second of the photo modification time; uses creation date if photo is not modified|
+   * - {created.month}
-   |{modified.strftime}|Apply strftime template to file modification date/time. Should be used in form {modified.strftime,TEMPLATE} where TEMPLATE is a valid strftime template, e.g. {modified.strftime,%Y-%U} would result in year-week number of year: '2020-23'. If used with no template will return null value. Uses creation date if photo is not modified. See https://strftime.org/ for help on strftime templates.|
+     - Month name in user's locale of the photo creation time
-   |{today}|Current date in iso format, e.g. '2020-03-22'|
+   * - {created.mon}
-   |{today.date}|Current date in iso format, e.g. '2020-03-22'|
+     - Month abbreviation in the user's locale of the photo creation time
-   |{today.year}|4-digit year of current date|
+   * - {created.dd}
-   |{today.yy}|2-digit year of current date|
+     - 2-digit day of the month (zero padded) of photo creation time
-   |{today.mm}|2-digit month of the current date (zero padded)|
+   * - {created.dow}
-   |{today.month}|Month name in user's locale of the current date|
+     - Day of week in user's locale of the photo creation time
-   |{today.mon}|Month abbreviation in the user's locale of the current date|
+   * - {created.doy}
-   |{today.dd}|2-digit day of the month (zero padded) of current date|
+     - 3-digit day of year (e.g Julian day) of photo creation time, starting from 1 (zero padded)
-   |{today.dow}|Day of week in user's locale of the current date|
+   * - {created.hour}
-   |{today.doy}|3-digit day of year (e.g Julian day) of current date, starting from 1 (zero padded)|
+     - 2-digit hour of the photo creation time
-   |{today.hour}|2-digit hour of the current date|
+   * - {created.min}
-   |{today.min}|2-digit minute of the current date|
+     - 2-digit minute of the photo creation time
-   |{today.sec}|2-digit second of the current date|
+   * - {created.sec}
-   |{today.strftime}|Apply strftime template to current date/time. Should be used in form {today.strftime,TEMPLATE} where TEMPLATE is a valid strftime template, e.g. {today.strftime,%Y-%U} would result in year-week number of year: '2020-23'. If used with no template will return null value. See https://strftime.org/ for help on strftime templates.|
+     - 2-digit second of the photo creation time
-   |{place.name}|Place name from the photo's reverse geolocation data, as displayed in Photos|
+   * - {created.strftime}
-   |{place.country_code}|The ISO country code from the photo's reverse geolocation data|
+     - Apply strftime template to file creation date/time. Should be used in form {created.strftime,TEMPLATE} where TEMPLATE is a valid strftime template, e.g. {created.strftime,%Y-%U} would result in year-week number of year: '2020-23'. If used with no template will return null value. See https://strftime.org/ for help on strftime templates.
-   |{place.name.country}|Country name from the photo's reverse geolocation data|
+   * - {modified}
-   |{place.name.state_province}|State or province name from the photo's reverse geolocation data|
+     - Photo's modification date in ISO format, e.g. '2020-03-22'; uses creation date if photo is not modified
-   |{place.name.city}|City or locality name from the photo's reverse geolocation data|
+   * - {modified.date}
-   |{place.name.area_of_interest}|Area of interest name (e.g. landmark or public place) from the photo's reverse geolocation data|
+     - Photo's modification date in ISO format, e.g. '2020-03-22'; uses creation date if photo is not modified
-   |{place.address}|Postal address from the photo's reverse geolocation data, e.g. '2007 18th St NW, Washington, DC 20009, United States'|
+   * - {modified.year}
-   |{place.address.street}|Street part of the postal address, e.g. '2007 18th St NW'|
+     - 4-digit year of photo modification time; uses creation date if photo is not modified
-   |{place.address.city}|City part of the postal address, e.g. 'Washington'|
+   * - {modified.yy}
-   |{place.address.state_province}|State/province part of the postal address, e.g. 'DC'|
+     - 2-digit year of photo modification time; uses creation date if photo is not modified
-   |{place.address.postal_code}|Postal code part of the postal address, e.g. '20009'|
+   * - {modified.mm}
-   |{place.address.country}|Country name of the postal address, e.g. 'United States'|
+     - 2-digit month of the photo modification time (zero padded); uses creation date if photo is not modified
-   |{place.address.country_code}|ISO country code of the postal address, e.g. 'US'|
+   * - {modified.month}
-   |{searchinfo.season}|Season of the year associated with a photo, e.g. 'Summer'; (Photos 5+ only, applied automatically by Photos' image categorization algorithms).|
+     - Month name in user's locale of the photo modification time; uses creation date if photo is not modified
-   |{exif.camera_make}|Camera make from original photo's EXIF information as imported by Photos, e.g. 'Apple'|
+   * - {modified.mon}
-   |{exif.camera_model}|Camera model from original photo's EXIF information as imported by Photos, e.g. 'iPhone 6s'|
+     - Month abbreviation in the user's locale of the photo modification time; uses creation date if photo is not modified
-   |{exif.lens_model}|Lens model from original photo's EXIF information as imported by Photos, e.g. 'iPhone 6s back camera 4.15mm f/2.2'|
+   * - {modified.dd}
-   |{moment}|The moment title of the photo|
+     - 2-digit day of the month (zero padded) of the photo modification time; uses creation date if photo is not modified
-   |{uuid}|Photo's internal universally unique identifier (UUID) for the photo, a 36-character string unique to the photo, e.g. '128FB4C6-0B16-4E7D-9108-FB2E90DA1546'|
+   * - {modified.dow}
-   |{shortuuid}|A shorter representation of photo's internal universally unique identifier (UUID) for the photo, a 22-character string unique to the photo, e.g. 'JYsxugP9UjetmCbBCHXcmu'|
+     - Day of week in user's locale of the photo modification time; uses creation date if photo is not modified
-   |{id}|A unique number for the photo based on its primary key in the Photos database. A sequential integer, e.g. 1, 2, 3...etc.  Each asset associated with a photo (e.g. an image and Live Photo preview) will share the same id. May be formatted using a python string format code. For example, to format as a 5-digit integer and pad with zeros, use '{id:05d}' which results in 00001, 00002, 00003...etc. |
+   * - {modified.doy}
-   |{counter}|A sequential counter, starting at 0, that increments each time it is evaluated.To start counting at a value other than 0, append append '(starting_value)' to the field name.For example, to start counting at 1 instead of 0: '{counter(1)}'.May be formatted using a python string format code.For example, to format as a 5-digit integer and pad with zeros, use '{counter:05d(1)}'which results in 00001, 00002, 00003...etc.You may also specify a stop value which causes the counter to reset to the starting valuewhen the stop value is reached and a step size which causes the counter to increment bythe specified value instead of 1. Use the format '{counter(start,stop,step)}' where start,stop, and step are integers. For example, to count from 1 to 10 by 2, use '{counter(1,11,2)}'.Note that the counter stops counting when the stop value is reached and does not return thestop value. Start, stop, and step are optional and may be omitted. For example, to countfrom 0 by 2s, use '{counter(,,2)}'.You may create an arbitrary number of counters by appending a unique name to the field namepreceded by a period: '{counter.a}', '{counter.b}', etc. Each counter will have its own stateand will start at 0 and increment by 1 unless otherwise specified. Note: {counter} is not suitable for use with 'export' and '--update' as the counter associated with a photo may change between export sessions. See also {id}.|
+     - 3-digit day of year (e.g Julian day) of photo modification time, starting from 1 (zero padded); uses creation date if photo is not modified
-   |{album_seq}|An integer, starting at 0, indicating the photo's index (sequence) in the containing album. Only valid when used in a '--filename' template and only when '{album}' or '{folder_album}' is used in the '--directory' template. For example '--directory "{folder_album}" --filename "{album_seq}_{original_name}"'. To start counting at a value other than 0, append append '(starting_value)' to the field name.  For example, to start counting at 1 instead of 0: '{album_seq(1)}'. May be formatted using a python string format code. For example, to format as a 5-digit integer and pad with zeros, use '{album_seq:05d}' which results in 00000, 00001, 00002...etc. To format while also using a starting value: '{album_seq:05d(1)}' which results in 0001, 00002...etc.This may result in incorrect sequences if you have duplicate albums with the same name; see also '{folder_album_seq}'.|
+   * - {modified.hour}
-   |{folder_album_seq}|An integer, starting at 0, indicating the photo's index (sequence) in the containing album and folder path. Only valid when used in a '--filename' template and only when '{folder_album}' is used in the '--directory' template. For example '--directory "{folder_album}" --filename "{folder_album_seq}_{original_name}"'. To start counting at a value other than 0, append '(starting_value)' to the field name. For example, to start counting at 1 instead of 0: '{folder_album_seq(1)}' May be formatted using a python string format code. For example, to format as a 5-digit integer and pad with zeros, use '{folder_album_seq:05d}' which results in 00000, 00001, 00002...etc. To format while also using a starting value: '{folder_album_seq:05d(1)}' which results in 0001, 00002...etc.This may result in incorrect sequences if you have duplicate albums with the same name in the same folder; see also '{album_seq}'. |
+     - 2-digit hour of the photo modification time; uses creation date if photo is not modified
-   |{comma}|A comma: ','|
+   * - {modified.min}
-   |{semicolon}|A semicolon: ';'|
+     - 2-digit minute of the photo modification time; uses creation date if photo is not modified
-   |{questionmark}|A question mark: '?'|
+   * - {modified.sec}
-   |{pipe}|A vertical pipe: '\|'|
+     - 2-digit second of the photo modification time; uses creation date if photo is not modified
-   |{openbrace}|An open brace: '{'|
+   * - {modified.strftime}
-   |{closebrace}|A close brace: '}'|
+     - Apply strftime template to file modification date/time. Should be used in form {modified.strftime,TEMPLATE} where TEMPLATE is a valid strftime template, e.g. {modified.strftime,%Y-%U} would result in year-week number of year: '2020-23'. If used with no template will return null value. Uses creation date if photo is not modified. See https://strftime.org/ for help on strftime templates.
-   |{openparens}|An open parentheses: '('|
+   * - {today}
-   |{closeparens}|A close parentheses: ')'|
+     - Current date in iso format, e.g. '2020-03-22'
-   |{openbracket}|An open bracket: '['|
+   * - {today.date}
-   |{closebracket}|A close bracket: ']'|
+     - Current date in iso format, e.g. '2020-03-22'
-   |{newline}|A newline: '\n'|
+   * - {today.year}
-   |{lf}|A line feed: '\n', alias for {newline}|
+     - 4-digit year of current date
-   |{cr}|A carriage return: '\r'|
+   * - {today.yy}
-   |{crlf}|A carriage return + line feed: '\r\n'|
+     - 2-digit year of current date
-   |{tab}|:A tab: '\t'|
+   * - {today.mm}
-   |{osxphotos_version}|The osxphotos version, e.g. '0.57.1'|
+     - 2-digit month of the current date (zero padded)
-   |{osxphotos_cmd_line}|The full command line used to run osxphotos|
+   * - {today.month}
-   |{album}|Album(s) photo is contained in|
+     - Month name in user's locale of the current date
-   |{folder_album}|Folder path + album photo is contained in. e.g. 'Folder/Subfolder/Album' or just 'Album' if no enclosing folder|
+   * - {today.mon}
-   |{project}|Project(s) photo is contained in (such as greeting cards, calendars, slideshows)|
+     - Month abbreviation in the user's locale of the current date
-   |{album_project}|Album(s) and project(s) photo is contained in; treats projects as regular albums|
+   * - {today.dd}
-   |{folder_album_project}|Folder path + album (includes projects as albums) photo is contained in. e.g. 'Folder/Subfolder/Album' or just 'Album' if no enclosing folder|
+     - 2-digit day of the month (zero padded) of current date
-   |{keyword}|Keyword(s) assigned to photo|
+   * - {today.dow}
-   |{person}|Person(s) / face(s) in a photo|
+     - Day of week in user's locale of the current date
-   |{label}|Image categorization label associated with a photo (Photos 5+ only). Labels are added automatically by Photos using machine learning algorithms to categorize images. These are not the same as {keyword} which refers to the user-defined keywords/tags applied in Photos.|
+   * - {today.doy}
-   |{label_normalized}|All lower case version of 'label' (Photos 5+ only)|
+     - 3-digit day of year (e.g Julian day) of current date, starting from 1 (zero padded)
-   |{comment}|Comment(s) on shared Photos; format is 'Person name: comment text' (Photos 5+ only)|
+   * - {today.hour}
-   |{exiftool}|Format: '{exiftool:GROUP:TAGNAME}'; use exiftool (https://exiftool.org) to extract metadata, in form GROUP:TAGNAME, from image.  E.g. '{exiftool:EXIF:Make}' to get camera make, or {exiftool:IPTC:Keywords} to extract keywords. See https://exiftool.org/TagNames/ for list of valid tag names.  You must specify group (e.g. EXIF, IPTC, etc) as used in `exiftool -G`. exiftool must be installed in the path to use this template.|
+     - 2-digit hour of the current date
-   |{searchinfo.holiday}|Holiday names associated with a photo, e.g. 'Christmas Day'; (Photos 5+ only, applied automatically by Photos' image categorization algorithms).|
+   * - {today.min}
-   |{searchinfo.activity}|Activities associated with a photo, e.g. 'Sporting Event'; (Photos 5+ only, applied automatically by Photos' image categorization algorithms).|
+     - 2-digit minute of the current date
-   |{searchinfo.venue}|Venues associated with a photo, e.g. name of restaurant; (Photos 5+ only, applied automatically by Photos' image categorization algorithms).|
+   * - {today.sec}
-   |{searchinfo.venue_type}|Venue types associated with a photo, e.g. 'Restaurant'; (Photos 5+ only, applied automatically by Photos' image categorization algorithms).|
+     - 2-digit second of the current date
-   |{photo}|Provides direct access to the PhotoInfo object for the photo. Must be used in format '{photo.property}' where 'property' represents a PhotoInfo property. For example: '{photo.favorite}' is the same as '{favorite}' and '{photo.place.name}' is the same as '{place.name}'. '{photo}' provides access to properties that are not available as separate template fields but it assumes some knowledge of the underlying PhotoInfo class.  See https://rhettbull.github.io/osxphotos/ for additional documentation on the PhotoInfo class.|
+   * - {today.strftime}
-   |{detected_text}|List of text strings found in the image after performing text detection. Using '{detected_text}' will cause osxphotos to perform text detection on your photos using the built-in macOS text detection algorithms which will slow down your export. The results for each photo will be cached in the export database so that future exports with '--update' do not need to reprocess each photo. You may pass a confidence threshold value between 0.0 and 1.0 after a colon as in '{detected_text:0.5}'; The default confidence threshold is 0.75. '{detected_text}' works only on macOS Catalina (10.15) or later. Note: this feature is not the same thing as Live Text in macOS Monterey, which osxphotos does not yet support.|
+     - Apply strftime template to current date/time. Should be used in form {today.strftime,TEMPLATE} where TEMPLATE is a valid strftime template, e.g. {today.strftime,%Y-%U} would result in year-week number of year: '2020-23'. If used with no template will return null value. See https://strftime.org/ for help on strftime templates.
-   |{shell_quote}|Use in form '{shell_quote,TEMPLATE}'; quotes the rendered TEMPLATE value(s) for safe usage in the shell, e.g. My file.jpeg => 'My file.jpeg'; only adds quotes if needed.|
+   * - {place.name}
-   |{strip}|Use in form '{strip,TEMPLATE}'; strips whitespace from begining and end of rendered TEMPLATE value(s).|
+     - Place name from the photo's reverse geolocation data, as displayed in Photos
-   |{format}|Use in form, '{format:TYPE:FORMAT,TEMPLATE}'; converts TEMPLATE value to TYPE then formats the value using Python string formatting codes specified by FORMAT; TYPE is one of: 'int', 'float', or 'str'. For example, '{format:float:.1f,{exiftool:EXIF:FocalLength}}' will format focal length to 1 decimal place (e.g. '100.0'). |
+   * - {place.country_code}
-   |{function}|Execute a python function from an external file and use return value as template substitution. Use in format: {function:file.py::function_name} where 'file.py' is the name of the python file and 'function_name' is the name of the function to call. The function will be passed the PhotoInfo object for the photo. See https://github.com/RhetTbull/osxphotos/blob/master/examples/template_function.py for an example of how to implement a template function.|
+     - The ISO country code from the photo's reverse geolocation data
+   * - {place.name.country}
+     - Country name from the photo's reverse geolocation data
+   * - {place.name.state_province}
+     - State or province name from the photo's reverse geolocation data
+   * - {place.name.city}
+     - City or locality name from the photo's reverse geolocation data
+   * - {place.name.area_of_interest}
+     - Area of interest name (e.g. landmark or public place) from the photo's reverse geolocation data
+   * - {place.address}
+     - Postal address from the photo's reverse geolocation data, e.g. '2007 18th St NW, Washington, DC 20009, United States'
+   * - {place.address.street}
+     - Street part of the postal address, e.g. '2007 18th St NW'
+   * - {place.address.city}
+     - City part of the postal address, e.g. 'Washington'
+   * - {place.address.state_province}
+     - State/province part of the postal address, e.g. 'DC'
+   * - {place.address.postal_code}
+     - Postal code part of the postal address, e.g. '20009'
+   * - {place.address.country}
+     - Country name of the postal address, e.g. 'United States'
+   * - {place.address.country_code}
+     - ISO country code of the postal address, e.g. 'US'
+   * - {searchinfo.season}
+     - Season of the year associated with a photo, e.g. 'Summer'; (Photos 5+ only, applied automatically by Photos' image categorization algorithms).
+   * - {exif.camera_make}
+     - Camera make from original photo's EXIF information as imported by Photos, e.g. 'Apple'
+   * - {exif.camera_model}
+     - Camera model from original photo's EXIF information as imported by Photos, e.g. 'iPhone 6s'
+   * - {exif.lens_model}
+     - Lens model from original photo's EXIF information as imported by Photos, e.g. 'iPhone 6s back camera 4.15mm f/2.2'
+   * - {moment}
+     - The moment title of the photo
+   * - {uuid}
+     - Photo's internal universally unique identifier (UUID) for the photo, a 36-character string unique to the photo, e.g. '128FB4C6-0B16-4E7D-9108-FB2E90DA1546'
+   * - {shortuuid}
+     - A shorter representation of photo's internal universally unique identifier (UUID) for the photo, a 22-character string unique to the photo, e.g. 'JYsxugP9UjetmCbBCHXcmu'
+   * - {id}
+     - A unique number for the photo based on its primary key in the Photos database. A sequential integer, e.g. 1, 2, 3...etc.  Each asset associated with a photo (e.g. an image and Live Photo preview) will share the same id. May be formatted using a python string format code. For example, to format as a 5-digit integer and pad with zeros, use '{id:05d}' which results in 00001, 00002, 00003...etc.
+   * - {counter}
+     - A sequential counter, starting at 0, that increments each time it is evaluated.To start counting at a value other than 0, append append '(starting_value)' to the field name.For example, to start counting at 1 instead of 0: '{counter(1)}'.May be formatted using a python string format code.For example, to format as a 5-digit integer and pad with zeros, use '{counter:05d(1)}'which results in 00001, 00002, 00003...etc.You may also specify a stop value which causes the counter to reset to the starting valuewhen the stop value is reached and a step size which causes the counter to increment bythe specified value instead of 1. Use the format '{counter(start,stop,step)}' where start,stop, and step are integers. For example, to count from 1 to 10 by 2, use '{counter(1,11,2)}'.Note that the counter stops counting when the stop value is reached and does not return thestop value. Start, stop, and step are optional and may be omitted. For example, to countfrom 0 by 2s, use '{counter(,,2)}'.You may create an arbitrary number of counters by appending a unique name to the field namepreceded by a period: '{counter.a}', '{counter.b}', etc. Each counter will have its own stateand will start at 0 and increment by 1 unless otherwise specified. Note: {counter} is not suitable for use with 'export' and '--update' as the counter associated with a photo may change between export sessions. See also {id}.
+   * - {album_seq}
+     - An integer, starting at 0, indicating the photo's index (sequence) in the containing album. Only valid when used in a '--filename' template and only when '{album}' or '{folder_album}' is used in the '--directory' template. For example '--directory "{folder_album}" --filename "{album\ *seq}*\ {original_name}"'. To start counting at a value other than 0, append append '(starting_value)' to the field name.  For example, to start counting at 1 instead of 0: '{album_seq(1)}'. May be formatted using a python string format code. For example, to format as a 5-digit integer and pad with zeros, use '{album_seq:05d}' which results in 00000, 00001, 00002...etc. To format while also using a starting value: '{album_seq:05d(1)}' which results in 0001, 00002...etc.This may result in incorrect sequences if you have duplicate albums with the same name; see also '{folder_album_seq}'.
+   * - {folder_album_seq}
+     - An integer, starting at 0, indicating the photo's index (sequence) in the containing album and folder path. Only valid when used in a '--filename' template and only when '{folder_album}' is used in the '--directory' template. For example '--directory "{folder_album}" --filename "{folder_album\ *seq}*\ {original_name}"'. To start counting at a value other than 0, append '(starting_value)' to the field name. For example, to start counting at 1 instead of 0: '{folder_album_seq(1)}' May be formatted using a python string format code. For example, to format as a 5-digit integer and pad with zeros, use '{folder_album_seq:05d}' which results in 00000, 00001, 00002...etc. To format while also using a starting value: '{folder_album_seq:05d(1)}' which results in 0001, 00002...etc.This may result in incorrect sequences if you have duplicate albums with the same name in the same folder; see also '{album_seq}'.
+   * - {comma}
+     - A comma: ','
+   * - {semicolon}
+     - A semicolon: ';'
+   * - {questionmark}
+     - A question mark: '?'
+   * - {pipe}
+     - A vertical pipe: '|'
+   * - {openbrace}
+     - An open brace: '{'
+   * - {closebrace}
+     - A close brace: '}'
+   * - {openparens}
+     - An open parentheses: '('
+   * - {closeparens}
+     - A close parentheses: ')'
+   * - {openbracket}
+     - An open bracket: '['
+   * - {closebracket}
+     - A close bracket: ']'
+   * - {newline}
+     - A newline: '\n'
+   * - {lf}
+     - A line feed: '\n', alias for {newline}
+   * - {cr}
+     - A carriage return: '\r'
+   * - {crlf}
+     - A carriage return + line feed: '\r\n'
+   * - {tab}
+     - :A tab: '\t'
+   * - {osxphotos_version}
+     - The osxphotos version, e.g. '0.61.0'
+   * - {osxphotos_cmd_line}
+     - The full command line used to run osxphotos
+   * - {album}
+     - Album(s) photo is contained in
+   * - {folder_album}
+     - Folder path + album photo is contained in. e.g. 'Folder/Subfolder/Album' or just 'Album' if no enclosing folder
+   * - {project}
+     - Project(s) photo is contained in (such as greeting cards, calendars, slideshows)
+   * - {album_project}
+     - Album(s) and project(s) photo is contained in; treats projects as regular albums
+   * - {folder_album_project}
+     - Folder path + album (includes projects as albums) photo is contained in. e.g. 'Folder/Subfolder/Album' or just 'Album' if no enclosing folder
+   * - {keyword}
+     - Keyword(s) assigned to photo
+   * - {person}
+     - Person(s) / face(s) in a photo
+   * - {label}
+     - Image categorization label associated with a photo (Photos 5+ only). Labels are added automatically by Photos using machine learning algorithms to categorize images. These are not the same as {keyword} which refers to the user-defined keywords/tags applied in Photos.
+   * - {label_normalized}
+     - All lower case version of 'label' (Photos 5+ only)
+   * - {comment}
+     - Comment(s) on shared Photos; format is 'Person name: comment text' (Photos 5+ only)
+   * - {exiftool}
+     - Format: '{exiftool:GROUP:TAGNAME}'; use exiftool (https://exiftool.org) to extract metadata, in form GROUP:TAGNAME, from image.  E.g. '{exiftool:EXIF:Make}' to get camera make, or {exiftool:IPTC:Keywords} to extract keywords. See https://exiftool.org/TagNames/ for list of valid tag names.  You must specify group (e.g. EXIF, IPTC, etc) as used in ``exiftool -G``. exiftool must be installed in the path to use this template.
+   * - {searchinfo.holiday}
+     - Holiday names associated with a photo, e.g. 'Christmas Day'; (Photos 5+ only, applied automatically by Photos' image categorization algorithms).
+   * - {searchinfo.activity}
+     - Activities associated with a photo, e.g. 'Sporting Event'; (Photos 5+ only, applied automatically by Photos' image categorization algorithms).
+   * - {searchinfo.venue}
+     - Venues associated with a photo, e.g. name of restaurant; (Photos 5+ only, applied automatically by Photos' image categorization algorithms).
+   * - {searchinfo.venue_type}
+     - Venue types associated with a photo, e.g. 'Restaurant'; (Photos 5+ only, applied automatically by Photos' image categorization algorithms).
+   * - {photo}
+     - Provides direct access to the PhotoInfo object for the photo. Must be used in format '{photo.property}' where 'property' represents a PhotoInfo property. For example: '{photo.favorite}' is the same as '{favorite}' and '{photo.place.name}' is the same as '{place.name}'. '{photo}' provides access to properties that are not available as separate template fields but it assumes some knowledge of the underlying PhotoInfo class.  See https://rhettbull.github.io/osxphotos/ for additional documentation on the PhotoInfo class.
+   * - {detected_text}
+     - List of text strings found in the image after performing text detection. Using '{detected_text}' will cause osxphotos to perform text detection on your photos using the built-in macOS text detection algorithms which will slow down your export. The results for each photo will be cached in the export database so that future exports with '--update' do not need to reprocess each photo. You may pass a confidence threshold value between 0.0 and 1.0 after a colon as in '{detected_text:0.5}'; The default confidence threshold is 0.75. '{detected_text}' works only on macOS Catalina (10.15) or later. Note: this feature is not the same thing as Live Text in macOS Monterey, which osxphotos does not yet support.
+   * - {shell_quote}
+     - Use in form '{shell_quote,TEMPLATE}'; quotes the rendered TEMPLATE value(s) for safe usage in the shell, e.g. My file.jpeg => 'My file.jpeg'; only adds quotes if needed.
+   * - {strip}
+     - Use in form '{strip,TEMPLATE}'; strips whitespace from begining and end of rendered TEMPLATE value(s).
+   * - {format}
+     - Use in form, '{format:TYPE:FORMAT,TEMPLATE}'; converts TEMPLATE value to TYPE then formats the value using Python string formatting codes specified by FORMAT; TYPE is one of: 'int', 'float', or 'str'. For example, '{format:float:.1f,{exiftool:EXIF:FocalLength}}' will format focal length to 1 decimal place (e.g. '100.0').
+   * - {function}
+     - Execute a python function from an external file and use return value as template substitution. Use in format: {function:file.py::function_name} where 'file.py' is the name of the python file and 'function_name' is the name of the function to call. The function will be passed the PhotoInfo object for the photo. See https://github.com/RhetTbull/osxphotos/blob/master/examples/template_function.py for an example of how to implement a template function.
+
+
+
+.. raw:: html
+
    <!--[[[end]]] -->
 
 

docs/_sources/index.rst.txt

@@ -14,6 +14,7 @@ Welcome to OSXPhotos's documentation!
    cli
    template_help
    package_overview
+   api_readme
    reference
 
 

docs/_sources/template_help.rst.txt

@@ -162,9 +162,9 @@ e.g. ``"{created.year}/{openbrace}{title}{closebrace}"`` would result in ``"2020
 
 **Variables**
 
-You can define variables for later use in the template string using the format ``{var:NAME,VALUE}``.  Variables may then be referenced using the format ``%NAME``. For example: ``{var:foo,bar}`` defines the variable ``%foo`` to have value ``bar``. This can be useful if you want to re-use a complex template value in multiple places within your template string or for allowing the use of characters that would otherwise be prohibited in a template string. For example, the "pipe" (\ ``|``\ ) character is not allowed in a find/replace pair but you can get around this limitation like so: ``{var:pipe,{pipe}}{title[-,%pipe]}`` which replaces the ``-`` character with ``|`` (the value of ``%pipe``\ ).  
+You can define variables for later use in the template string using the format ``{var:NAME,VALUE}`` where ``VALUE`` is a template statement.  Variables may then be referenced using the format ``%NAME``. For example: ``{var:foo,bar}`` defines the variable ``%foo`` to have value ``bar``. This can be useful if you want to re-use a complex template value in multiple places within your template string or for allowing the use of characters that would otherwise be prohibited in a template string. For example, the "pipe" (\ ``|``\ ) character is not allowed in a find/replace pair but you can get around this limitation like so: ``{var:pipe,{pipe}}{title[-,%pipe]}`` which replaces the ``-`` character with ``|`` (the value of ``%pipe``\ ).  
 
-Variables can also be referenced as fields in the template string, for example: ``{var:year,created.year}{original_name}-{%year}``. In some cases, use of variables can make your template string more readable.  Variables can be used as template fields, as values for filters, as values for conditional operations, or as default values.  When used as a conditional value or default value, variables should be treated like any other field and enclosed in braces as conditional and default values are evaluated as template strings. For example: ``{var:name,Katie}{person contains {%name}?{%name},Not-{%name}}``.
+Variables can also be referenced as fields in the template string, for example: ``{var:year,{created.year}}{original_name}-{%year}``. In some cases, use of variables can make your template string more readable.  Variables can be used as template fields, as values for filters, as values for conditional operations, or as default values.  When used as a conditional value or default value, variables should be treated like any other field and enclosed in braces as conditional and default values are evaluated as template strings. For example: ``{var:name,Katie}{person contains {%name}?{%name},Not-{%name}}``.
 
 If you need to use a ``%`` (percent sign character), you can escape the percent sign by using ``%%``.  You can also use the ``{percent}`` template field where a template field is required. For example:
 

docs/genindex.html

@@ -159,6 +159,7 @@
 <li class="toctree-l1"><a class="reference internal" href="cli.html">OSXPhotos Command Line Interface (CLI)</a></li>
 <li class="toctree-l1"><a class="reference internal" href="template_help.html">OSXPhotos Template System</a></li>
 <li class="toctree-l1"><a class="reference internal" href="package_overview.html">OSXPhotos Python Package Overview</a></li>
+<li class="toctree-l1"><a class="reference internal" href="api_readme.html">OSXPhotos Python API</a></li>
 <li class="toctree-l1"><a class="reference internal" href="reference.html">OSXPhotos Python Reference</a></li>
 </ul>
 

docs/index.html

@@ -161,6 +161,7 @@
 <li class="toctree-l1"><a class="reference internal" href="cli.html">OSXPhotos Command Line Interface (CLI)</a></li>
 <li class="toctree-l1"><a class="reference internal" href="template_help.html">OSXPhotos Template System</a></li>
 <li class="toctree-l1"><a class="reference internal" href="package_overview.html">OSXPhotos Python Package Overview</a></li>
+<li class="toctree-l1"><a class="reference internal" href="api_readme.html">OSXPhotos Python API</a></li>
 <li class="toctree-l1"><a class="reference internal" href="reference.html">OSXPhotos Python Reference</a></li>
 </ul>
 
@@ -282,6 +283,307 @@
 <li class="toctree-l2"><a class="reference internal" href="package_overview.html#using-the-osxphotos-cli-to-run-python-code">Using the osxphotos CLI to run python code</a></li>
 </ul>
 </li>
+<li class="toctree-l1"><a class="reference internal" href="api_readme.html">OSXPhotos Python API</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="api_readme.html#table-of-contents">Table of Contents</a></li>
+<li class="toctree-l2"><a class="reference internal" href="api_readme.html#id1">Example uses of the Python package</a><ul>
+<li class="toctree-l3"><a class="reference internal" href="api_readme.html#print-filename-date-created-title-and-keywords-for-all-photos-in-a-library">Print filename, date created, title, and keywords for all photos in a library</a></li>
+<li class="toctree-l3"><a class="reference internal" href="api_readme.html#building-simple-command-line-tools">Building simple command line tools</a></li>
+</ul>
+</li>
+<li class="toctree-l2"><a class="reference internal" href="api_readme.html#concurrency">Concurrency</a></li>
+<li class="toctree-l2"><a class="reference internal" href="api_readme.html#id6">Package Interface</a><ul>
+<li class="toctree-l3"><a class="reference internal" href="api_readme.html#id7">PhotosDB</a><ul>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#read-a-photos-library-database">Read a Photos library database</a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#open-the-default-last-opened-photos-library">Open the default (last opened) Photos library</a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#open-system-photos-library">Open System Photos library</a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#open-a-specific-photos-library">Open a specific Photos library</a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#a-name-photosdbphotos-photos-keywords-none-uuid-none-persons-none-albums-none-images-true-movies-true-from-date-none-to-date-none-intrash-false-a"><span class="raw-html-m2r"><A name="photosdbphotos"></span><code class="docutils literal notranslate"><span class="pre">photos(keywords=None,</span> <span class="pre">uuid=None,</span> <span class="pre">persons=None,</span> <span class="pre">albums=None,</span> <span class="pre">images=True,</span> <span class="pre">movies=True,</span> <span class="pre">from_date=None,</span> <span class="pre">to_date=None,</span> <span class="pre">intrash=False)</span></code>&lt;/a&gt;</a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#a-name-getphoto-get-photo-uuid-a"><span class="raw-html-m2r"><a name="getphoto"></span><code class="docutils literal notranslate"><span class="pre">get_photo(uuid)</span></code>&lt;/A&gt;</a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#a-name-photosdbquery-query-options-queryoptions-list-photoinfo-a"><span class="raw-html-m2r"><A name="photosdbquery"></span><code class="docutils literal notranslate"><span class="pre">query(options:</span> <span class="pre">QueryOptions)</span> <span class="pre">-&gt;</span> <span class="pre">List[PhotoInfo]:</span></code>&lt;/a&gt;</a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#keywords"><code class="docutils literal notranslate"><span class="pre">keywords</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#a-name-photosdbalbuminfo-album-info-a"><span class="raw-html-m2r"><a name="photosdbalbuminfo">`album_info`</a></span></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#id14"><code class="docutils literal notranslate"><span class="pre">albums</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#albums-shared"><code class="docutils literal notranslate"><span class="pre">albums_shared</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#import-info"><code class="docutils literal notranslate"><span class="pre">import_info</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#project-info"><code class="docutils literal notranslate"><span class="pre">project_info</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#moment-info"><code class="docutils literal notranslate"><span class="pre">moment_info</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#folder-info"><code class="docutils literal notranslate"><span class="pre">folder_info</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#id19"><code class="docutils literal notranslate"><span class="pre">folders</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#persons"><code class="docutils literal notranslate"><span class="pre">persons</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#a-name-dbpersoninfo-person-info-a"><span class="raw-html-m2r"><a name="dbpersoninfo">`person_info`</a></span></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#keywords-as-dict"><code class="docutils literal notranslate"><span class="pre">keywords_as_dict</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#persons-as-dict"><code class="docutils literal notranslate"><span class="pre">persons_as_dict</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#albums-as-dict"><code class="docutils literal notranslate"><span class="pre">albums_as_dict</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#albums-shared-as-dict"><code class="docutils literal notranslate"><span class="pre">albums_shared_as_dict</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#labels"><code class="docutils literal notranslate"><span class="pre">labels</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#id22"><code class="docutils literal notranslate"><span class="pre">labels_normalized</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#labels-as-dict"><code class="docutils literal notranslate"><span class="pre">labels_as_dict</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#id24"><code class="docutils literal notranslate"><span class="pre">labels_normalized_as_dict</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#library-path"><code class="docutils literal notranslate"><span class="pre">library_path</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#db-path"><code class="docutils literal notranslate"><span class="pre">db_path</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#db-version"><code class="docutils literal notranslate"><span class="pre">db_version</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#photos-version"><code class="docutils literal notranslate"><span class="pre">photos_version</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#get-db-connection"><code class="docutils literal notranslate"><span class="pre">get_db_connection()</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#execute-sql"><code class="docutils literal notranslate"><span class="pre">execute(sql)</span></code></a></li>
+</ul>
+</li>
+<li class="toctree-l3"><a class="reference internal" href="api_readme.html#id26">QueryOptions</a><ul>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#attributes">Attributes</a></li>
+</ul>
+</li>
+<li class="toctree-l3"><a class="reference internal" href="api_readme.html#id27">PhotoInfo</a><ul>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#uuid"><code class="docutils literal notranslate"><span class="pre">uuid</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#filename"><code class="docutils literal notranslate"><span class="pre">filename</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#id28"><code class="docutils literal notranslate"><span class="pre">original_filename</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#date"><code class="docutils literal notranslate"><span class="pre">date</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#date-added"><code class="docutils literal notranslate"><span class="pre">date_added</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#date-modified"><code class="docutils literal notranslate"><span class="pre">date_modified</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#description"><code class="docutils literal notranslate"><span class="pre">description</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#title"><code class="docutils literal notranslate"><span class="pre">title</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#id30"><code class="docutils literal notranslate"><span class="pre">keywords</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#id31"><code class="docutils literal notranslate"><span class="pre">albums</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#id33"><code class="docutils literal notranslate"><span class="pre">album_info</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#id36"><code class="docutils literal notranslate"><span class="pre">import_info</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#id38"><code class="docutils literal notranslate"><span class="pre">project_info</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#id40"><code class="docutils literal notranslate"><span class="pre">persons</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#a-name-photopersoninfo-person-info-a"><span class="raw-html-m2r"><a name="photopersoninfo">`person_info`</a></span></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#a-name-photofaceinfo-face-info-a"><span class="raw-html-m2r"><a name="photofaceinfo">`face_info`</a></span></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#path"><code class="docutils literal notranslate"><span class="pre">path</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#path-edited"><code class="docutils literal notranslate"><span class="pre">path_edited</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#path-derivatives"><code class="docutils literal notranslate"><span class="pre">path_derivatives</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#path-raw"><code class="docutils literal notranslate"><span class="pre">path_raw</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#has-raw"><code class="docutils literal notranslate"><span class="pre">has_raw</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#israw"><code class="docutils literal notranslate"><span class="pre">israw</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#raw-original"><code class="docutils literal notranslate"><span class="pre">raw_original</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#height"><code class="docutils literal notranslate"><span class="pre">height</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#width"><code class="docutils literal notranslate"><span class="pre">width</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#orientation"><code class="docutils literal notranslate"><span class="pre">orientation</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#id48"><code class="docutils literal notranslate"><span class="pre">original_height</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#id50"><code class="docutils literal notranslate"><span class="pre">original_width</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#id52"><code class="docutils literal notranslate"><span class="pre">original_orientation</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#original-filesize"><code class="docutils literal notranslate"><span class="pre">original_filesize</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#id54"><code class="docutils literal notranslate"><span class="pre">ismissing</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#id56"><code class="docutils literal notranslate"><span class="pre">hasadjustments</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#adjustments"><code class="docutils literal notranslate"><span class="pre">adjustments</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#external-edit"><code class="docutils literal notranslate"><span class="pre">external_edit</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#favorite"><code class="docutils literal notranslate"><span class="pre">favorite</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#id58"><code class="docutils literal notranslate"><span class="pre">hidden</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#visible"><code class="docutils literal notranslate"><span class="pre">visible</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#intrash"><code class="docutils literal notranslate"><span class="pre">intrash</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#date-trashed"><code class="docutils literal notranslate"><span class="pre">date_trashed</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#location"><code class="docutils literal notranslate"><span class="pre">location</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#place"><code class="docutils literal notranslate"><span class="pre">place</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#id60"><code class="docutils literal notranslate"><span class="pre">shared</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#owner"><code class="docutils literal notranslate"><span class="pre">owner</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#comments"><code class="docutils literal notranslate"><span class="pre">comments</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#likes"><code class="docutils literal notranslate"><span class="pre">likes</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#isreference"><code class="docutils literal notranslate"><span class="pre">isreference</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#isphoto"><code class="docutils literal notranslate"><span class="pre">isphoto</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#ismovie"><code class="docutils literal notranslate"><span class="pre">ismovie</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#iscloudasset"><code class="docutils literal notranslate"><span class="pre">iscloudasset</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#id71"><code class="docutils literal notranslate"><span class="pre">incloud</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#syndicated"><code class="docutils literal notranslate"><span class="pre">syndicated</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#saved-to-library"><code class="docutils literal notranslate"><span class="pre">saved_to_library</span></code></a></li>
+</ul>
+</li>
+<li class="toctree-l3"><a class="reference internal" href="api_readme.html#shared-moment"><code class="docutils literal notranslate"><span class="pre">shared_moment</span></code></a><ul>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#uti"><code class="docutils literal notranslate"><span class="pre">uti</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#uti-original"><code class="docutils literal notranslate"><span class="pre">uti_original</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#uti-edited"><code class="docutils literal notranslate"><span class="pre">uti_edited</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#uti-raw"><code class="docutils literal notranslate"><span class="pre">uti_raw</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#id74"><code class="docutils literal notranslate"><span class="pre">burst</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#burst-selected"><code class="docutils literal notranslate"><span class="pre">burst_selected</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#burst-key"><code class="docutils literal notranslate"><span class="pre">burst_key</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#burst-default-pick"><code class="docutils literal notranslate"><span class="pre">burst_default_pick</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#id75"><code class="docutils literal notranslate"><span class="pre">burst_photos</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#id77"><code class="docutils literal notranslate"><span class="pre">burst_albums</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#id80"><code class="docutils literal notranslate"><span class="pre">burst_album_info</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#live-photo"><code class="docutils literal notranslate"><span class="pre">live_photo</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#id84"><code class="docutils literal notranslate"><span class="pre">path_live_photo</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#path-edited-live-photo"><code class="docutils literal notranslate"><span class="pre">path_edited_live_photo</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#portrait"><code class="docutils literal notranslate"><span class="pre">portrait</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#hdr"><code class="docutils literal notranslate"><span class="pre">hdr</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#selfie"><code class="docutils literal notranslate"><span class="pre">selfie</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#time-lapse"><code class="docutils literal notranslate"><span class="pre">time_lapse</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#panorama"><code class="docutils literal notranslate"><span class="pre">panorama</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#slow-mo"><code class="docutils literal notranslate"><span class="pre">slow_mo</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#id88"><code class="docutils literal notranslate"><span class="pre">labels</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#id90"><code class="docutils literal notranslate"><span class="pre">labels_normalized</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#a-name-photosearchinfo-search-info-a"><span class="raw-html-m2r"><a name="photosearchinfo">`search_info`</a></span></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#a-name-photosearchinfo-normalized-search-info-normalized-a"><span class="raw-html-m2r"><a name="photosearchinfo-normalized">`search_info_normalized`</a></span></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#exif-info"><code class="docutils literal notranslate"><span class="pre">exif_info</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#id96"><code class="docutils literal notranslate"><span class="pre">exiftool</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#score"><code class="docutils literal notranslate"><span class="pre">score</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#duplicates"><code class="docutils literal notranslate"><span class="pre">duplicates</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#cloud-guid"><code class="docutils literal notranslate"><span class="pre">cloud_guid</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#cloud-owner-hashed-id"><code class="docutils literal notranslate"><span class="pre">cloud_owner_hashed_id</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#fingerprint"><code class="docutils literal notranslate"><span class="pre">fingerprint</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#hexdigest"><code class="docutils literal notranslate"><span class="pre">hexdigest</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#tables"><code class="docutils literal notranslate"><span class="pre">tables()</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#json"><code class="docutils literal notranslate"><span class="pre">json()</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#asdict"><code class="docutils literal notranslate"><span class="pre">asdict()</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#export"><code class="docutils literal notranslate"><span class="pre">export()</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#a-name-rendertemplate-render-template-template-str-options-none-a"><span class="raw-html-m2r"><a name="rendertemplate">`render_template(template_str, options=None)`</a></span></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#a-name-detected-text-method-detected-text-confidence-threshold-text-detection-confidence-threshold-a"><span class="raw-html-m2r"><a name="detected_text_method">`detected_text(confidence_threshold=TEXT_DETECTION_CONFIDENCE_THRESHOLD)`</a></span></a></li>
+</ul>
+</li>
+<li class="toctree-l3"><a class="reference internal" href="api_readme.html#id106">ExifInfo</a></li>
+<li class="toctree-l3"><a class="reference internal" href="api_readme.html#id107">AlbumInfo</a><ul>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#id108"><code class="docutils literal notranslate"><span class="pre">uuid</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#id109"><code class="docutils literal notranslate"><span class="pre">title</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#a-name-albumphotos-photos-a"><span class="raw-html-m2r"><a name="albumphotos">`photos`</a></span></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#creation-date"><code class="docutils literal notranslate"><span class="pre">creation_date</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#start-date"><code class="docutils literal notranslate"><span class="pre">start_date</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#end-date"><code class="docutils literal notranslate"><span class="pre">end_date</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#folder-list"><code class="docutils literal notranslate"><span class="pre">folder_list</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#folder-names"><code class="docutils literal notranslate"><span class="pre">folder_names</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#parent"><code class="docutils literal notranslate"><span class="pre">parent</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#id113"><code class="docutils literal notranslate"><span class="pre">owner</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#id116"><code class="docutils literal notranslate"><span class="pre">asdict()</span></code></a></li>
+</ul>
+</li>
+<li class="toctree-l3"><a class="reference internal" href="api_readme.html#id117">ImportInfo</a><ul>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#id118"><code class="docutils literal notranslate"><span class="pre">uuid</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#a-name-importphotos-photos-a"><span class="raw-html-m2r"><a name="importphotos">`photos`</a></span></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#id120"><code class="docutils literal notranslate"><span class="pre">creation_date</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#id121"><code class="docutils literal notranslate"><span class="pre">start_date</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#id122"><code class="docutils literal notranslate"><span class="pre">end_date</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#id123"><code class="docutils literal notranslate"><span class="pre">asdict()</span></code></a></li>
+</ul>
+</li>
+<li class="toctree-l3"><a class="reference internal" href="api_readme.html#id124">ProjectInfo</a><ul>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#id125"><code class="docutils literal notranslate"><span class="pre">uuid</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#id126"><code class="docutils literal notranslate"><span class="pre">title</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#a-name-projectphotos-photos-a"><span class="raw-html-m2r"><a name="projectphotos">`photos`</a></span></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#id128"><code class="docutils literal notranslate"><span class="pre">creation_date</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#id129"><code class="docutils literal notranslate"><span class="pre">asdict()</span></code></a></li>
+</ul>
+</li>
+<li class="toctree-l3"><a class="reference internal" href="api_readme.html#id130">MomentInfo</a><ul>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#pk"><code class="docutils literal notranslate"><span class="pre">pk</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#id131"><code class="docutils literal notranslate"><span class="pre">location</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#id132"><code class="docutils literal notranslate"><span class="pre">title</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#subtitle"><code class="docutils literal notranslate"><span class="pre">subtitle</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#id133"><code class="docutils literal notranslate"><span class="pre">start_date</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#id134"><code class="docutils literal notranslate"><span class="pre">end_date</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#id135"><code class="docutils literal notranslate"><span class="pre">date</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#modification-date"><code class="docutils literal notranslate"><span class="pre">modification_date</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#id136"><code class="docutils literal notranslate"><span class="pre">photos</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#id137"><code class="docutils literal notranslate"><span class="pre">asdict()</span></code></a></li>
+</ul>
+</li>
+<li class="toctree-l3"><a class="reference internal" href="api_readme.html#id138">FolderInfo</a><ul>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#id139"><code class="docutils literal notranslate"><span class="pre">uuid</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#id140"><code class="docutils literal notranslate"><span class="pre">title</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#id141"><code class="docutils literal notranslate"><span class="pre">album_info</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#album-info-shared"><code class="docutils literal notranslate"><span class="pre">album_info_shared</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#subfolders"><code class="docutils literal notranslate"><span class="pre">subfolders</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#id145"><code class="docutils literal notranslate"><span class="pre">parent</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#sort-order"><code class="docutils literal notranslate"><span class="pre">sort_order</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#photo-index-photo"><code class="docutils literal notranslate"><span class="pre">photo_index(photo)</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#id147"><code class="docutils literal notranslate"><span class="pre">asdict()</span></code></a></li>
+</ul>
+</li>
+<li class="toctree-l3"><a class="reference internal" href="api_readme.html#id148">PlaceInfo</a><ul>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#ishome"><code class="docutils literal notranslate"><span class="pre">ishome</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#name"><code class="docutils literal notranslate"><span class="pre">name</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#names"><code class="docutils literal notranslate"><span class="pre">names</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#country-code"><code class="docutils literal notranslate"><span class="pre">country_code</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#address-str"><code class="docutils literal notranslate"><span class="pre">address_str</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#address"><code class="docutils literal notranslate"><span class="pre">address</span></code></a></li>
+</ul>
+</li>
+<li class="toctree-l3"><a class="reference internal" href="api_readme.html#id149">ScoreInfo</a></li>
+<li class="toctree-l3"><a class="reference internal" href="api_readme.html#id150">SearchInfo</a><ul>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#id151"><code class="docutils literal notranslate"><span class="pre">labels</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#place-names"><code class="docutils literal notranslate"><span class="pre">place_names</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#streets"><code class="docutils literal notranslate"><span class="pre">streets</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#neighborhoods"><code class="docutils literal notranslate"><span class="pre">neighborhoods</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#locality-names"><code class="docutils literal notranslate"><span class="pre">locality_names</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#city"><code class="docutils literal notranslate"><span class="pre">city</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#state"><code class="docutils literal notranslate"><span class="pre">state</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#state-abbreviation"><code class="docutils literal notranslate"><span class="pre">state_abbreviation</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#country"><code class="docutils literal notranslate"><span class="pre">country</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#month"><code class="docutils literal notranslate"><span class="pre">month</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#year"><code class="docutils literal notranslate"><span class="pre">year</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#bodies-of-water"><code class="docutils literal notranslate"><span class="pre">bodies_of_water</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#holidays"><code class="docutils literal notranslate"><span class="pre">holidays</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#activities"><code class="docutils literal notranslate"><span class="pre">activities</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#season"><code class="docutils literal notranslate"><span class="pre">season</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#venues"><code class="docutils literal notranslate"><span class="pre">venues</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#venue-types"><code class="docutils literal notranslate"><span class="pre">venue_types</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#media-types"><code class="docutils literal notranslate"><span class="pre">media_types</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#all"><code class="docutils literal notranslate"><span class="pre">all</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#id152"><code class="docutils literal notranslate"><span class="pre">asdict()</span></code></a></li>
+</ul>
+</li>
+<li class="toctree-l3"><a class="reference internal" href="api_readme.html#id153">PersonInfo</a><ul>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#id154"><code class="docutils literal notranslate"><span class="pre">name</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#display-name"><code class="docutils literal notranslate"><span class="pre">display_name</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#id155"><code class="docutils literal notranslate"><span class="pre">uuid</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#keyphoto"><code class="docutils literal notranslate"><span class="pre">keyphoto</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#facecount"><code class="docutils literal notranslate"><span class="pre">facecount</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#a-name-personphotos-photos-a"><span class="raw-html-m2r"><a name="personphotos">`photos`</a></span></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#a-name-personfaceinfo-face-info-a"><span class="raw-html-m2r"><a name="personfaceinfo">`face_info`</a></span></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#a-name-personfavorite-favorite-a"><span class="raw-html-m2r"><a name="personfavorite">`favorite`</a></span></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#a-name-personsortorder-sort-order-a"><span class="raw-html-m2r"><a name="personsortorder">`sort_order`</a></span></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#id157"><code class="docutils literal notranslate"><span class="pre">json()</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#id158"><code class="docutils literal notranslate"><span class="pre">asdict()</span></code></a></li>
+</ul>
+</li>
+<li class="toctree-l3"><a class="reference internal" href="api_readme.html#id159">FaceInfo</a><ul>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#id160"><code class="docutils literal notranslate"><span class="pre">uuid</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#id161"><code class="docutils literal notranslate"><span class="pre">name</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#asset-uuid"><code class="docutils literal notranslate"><span class="pre">asset_uuid</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#id162"><code class="docutils literal notranslate"><span class="pre">person_info</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#photo"><code class="docutils literal notranslate"><span class="pre">photo</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#mwg-rs-area"><code class="docutils literal notranslate"><span class="pre">mwg_rs_area</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#mpri-reg-rect"><code class="docutils literal notranslate"><span class="pre">mpri_reg_rect</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#face-rect"><code class="docutils literal notranslate"><span class="pre">face_rect()</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#center"><code class="docutils literal notranslate"><span class="pre">center</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#size-pixels"><code class="docutils literal notranslate"><span class="pre">size_pixels</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#roll-pitch-yaw"><code class="docutils literal notranslate"><span class="pre">roll_pitch_yaw()</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#roll">roll</a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#pitch">pitch</a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#yaw">yaw</a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#additional-properties"><code class="docutils literal notranslate"><span class="pre">Additional</span> <span class="pre">properties</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#id165"><code class="docutils literal notranslate"><span class="pre">asdict()</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#id166"><code class="docutils literal notranslate"><span class="pre">json()</span></code></a></li>
+</ul>
+</li>
+<li class="toctree-l3"><a class="reference internal" href="api_readme.html#id167">CommentInfo</a></li>
+<li class="toctree-l3"><a class="reference internal" href="api_readme.html#id168">LikeInfo</a></li>
+<li class="toctree-l3"><a class="reference internal" href="api_readme.html#id169">AdjustmentsInfo</a></li>
+<li class="toctree-l3"><a class="reference internal" href="api_readme.html#id170">PhotoTables</a></li>
+<li class="toctree-l3"><a class="reference internal" href="api_readme.html#id171">Raw Photos</a><ul>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#raw-related-attributes">Raw-Related Attributes</a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#example">Example</a></li>
+</ul>
+</li>
+<li class="toctree-l3"><a class="reference internal" href="api_readme.html#id180">Template System</a></li>
+<li class="toctree-l3"><a class="reference internal" href="api_readme.html#a-name-exiftoolexiftool-exiftool-a"><span class="raw-html-m2r"><a name="exiftoolExifTool">ExifTool</a></span></a><ul>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#exiftool-methods">ExifTool methods</a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#implementation-note">Implementation Note</a></li>
+</ul>
+</li>
+<li class="toctree-l3"><a class="reference internal" href="api_readme.html#a-name-photoexporter-photoexporter-a"><span class="raw-html-m2r"><a name="photoexporter">PhotoExporter</a></span></a><ul>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#export-dest-filename-none-options-optional-exportoptions-none-exportresults"><code class="docutils literal notranslate"><span class="pre">export(dest,</span> <span class="pre">filename=None,</span> <span class="pre">options:</span> <span class="pre">Optional[ExportOptions]=None)</span> <span class="pre">-&gt;</span> <span class="pre">ExportResults</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#exportoptions"><code class="docutils literal notranslate"><span class="pre">ExportOptions</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#exportresults"><code class="docutils literal notranslate"><span class="pre">ExportResults</span></code></a></li>
+</ul>
+</li>
+<li class="toctree-l3"><a class="reference internal" href="api_readme.html#a-name-textdetection-text-detection-a"><span class="raw-html-m2r"><a name="textdetection">Text Detection</a></span></a></li>
+<li class="toctree-l3"><a class="reference internal" href="api_readme.html#id183">Utility Functions</a><ul>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#id184"><code class="docutils literal notranslate"><span class="pre">get_system_library_path()</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#id185"><code class="docutils literal notranslate"><span class="pre">get_last_library_path()</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api_readme.html#list-photo-libraries"><code class="docutils literal notranslate"><span class="pre">list_photo_libraries()</span></code></a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li class="toctree-l2"><a class="reference internal" href="api_readme.html#id186">Additional Examples</a></li>
+</ul>
+</li>
 <li class="toctree-l1"><a class="reference internal" href="reference.html">OSXPhotos Python Reference</a><ul>
 <li class="toctree-l2"><a class="reference internal" href="reference.html#osxphotos.AlbumInfo"><code class="docutils literal notranslate"><span class="pre">AlbumInfo</span></code></a><ul>
 <li class="toctree-l3"><a class="reference internal" href="reference.html#osxphotos.AlbumInfo.asdict"><code class="docutils literal notranslate"><span class="pre">AlbumInfo.asdict()</span></code></a></li>

docs/py-modindex.html

@@ -159,6 +159,7 @@
 <li class="toctree-l1"><a class="reference internal" href="cli.html">OSXPhotos Command Line Interface (CLI)</a></li>
 <li class="toctree-l1"><a class="reference internal" href="template_help.html">OSXPhotos Template System</a></li>
 <li class="toctree-l1"><a class="reference internal" href="package_overview.html">OSXPhotos Python Package Overview</a></li>
+<li class="toctree-l1"><a class="reference internal" href="api_readme.html">OSXPhotos Python API</a></li>
 <li class="toctree-l1"><a class="reference internal" href="reference.html">OSXPhotos Python Reference</a></li>
 </ul>
 

docs/search.html

@@ -158,6 +158,7 @@
 <li class="toctree-l1"><a class="reference internal" href="cli.html">OSXPhotos Command Line Interface (CLI)</a></li>
 <li class="toctree-l1"><a class="reference internal" href="template_help.html">OSXPhotos Template System</a></li>
 <li class="toctree-l1"><a class="reference internal" href="package_overview.html">OSXPhotos Python Package Overview</a></li>
+<li class="toctree-l1"><a class="reference internal" href="api_readme.html">OSXPhotos Python API</a></li>
 <li class="toctree-l1"><a class="reference internal" href="reference.html">OSXPhotos Python Reference</a></li>
 </ul>
 

docs/template_help.html

@@ -161,6 +161,7 @@
 <li class="toctree-l1"><a class="reference internal" href="cli.html">OSXPhotos Command Line Interface (CLI)</a></li>
 <li class="toctree-l1 current current-page"><a class="current reference internal" href="#">OSXPhotos Template System</a></li>
 <li class="toctree-l1"><a class="reference internal" href="package_overview.html">OSXPhotos Python Package Overview</a></li>
+<li class="toctree-l1"><a class="reference internal" href="api_readme.html">OSXPhotos Python API</a></li>
 <li class="toctree-l1"><a class="reference internal" href="reference.html">OSXPhotos Python Reference</a></li>
 </ul>
 
@@ -320,8 +321,8 @@
 <p>If you want to include “{” or “}” in the output, use “{openbrace}” or “{closebrace}” template substitution.</p>
 <p>e.g. <code class="docutils literal notranslate"><span class="pre">&quot;{created.year}/{openbrace}{title}{closebrace}&quot;</span></code> would result in <code class="docutils literal notranslate"><span class="pre">&quot;2020/{Photo</span> <span class="pre">Title}&quot;</span></code>.</p>
 <p><strong>Variables</strong></p>
-<p>You can define variables for later use in the template string using the format <code class="docutils literal notranslate"><span class="pre">{var:NAME,VALUE}</span></code>.  Variables may then be referenced using the format <code class="docutils literal notranslate"><span class="pre">%NAME</span></code>. For example: <code class="docutils literal notranslate"><span class="pre">{var:foo,bar}</span></code> defines the variable <code class="docutils literal notranslate"><span class="pre">%foo</span></code> to have value <code class="docutils literal notranslate"><span class="pre">bar</span></code>. This can be useful if you want to re-use a complex template value in multiple places within your template string or for allowing the use of characters that would otherwise be prohibited in a template string. For example, the “pipe” (<code class="docutils literal notranslate"><span class="pre">|</span></code>) character is not allowed in a find/replace pair but you can get around this limitation like so: <code class="docutils literal notranslate"><span class="pre">{var:pipe,{pipe}}{title[-,%pipe]}</span></code> which replaces the <code class="docutils literal notranslate"><span class="pre">-</span></code> character with <code class="docutils literal notranslate"><span class="pre">|</span></code> (the value of <code class="docutils literal notranslate"><span class="pre">%pipe</span></code>).</p>
+<p>You can define variables for later use in the template string using the format <code class="docutils literal notranslate"><span class="pre">{var:NAME,VALUE}</span></code> where <code class="docutils literal notranslate"><span class="pre">VALUE</span></code> is a template statement.  Variables may then be referenced using the format <code class="docutils literal notranslate"><span class="pre">%NAME</span></code>. For example: <code class="docutils literal notranslate"><span class="pre">{var:foo,bar}</span></code> defines the variable <code class="docutils literal notranslate"><span class="pre">%foo</span></code> to have value <code class="docutils literal notranslate"><span class="pre">bar</span></code>. This can be useful if you want to re-use a complex template value in multiple places within your template string or for allowing the use of characters that would otherwise be prohibited in a template string. For example, the “pipe” (<code class="docutils literal notranslate"><span class="pre">|</span></code>) character is not allowed in a find/replace pair but you can get around this limitation like so: <code class="docutils literal notranslate"><span class="pre">{var:pipe,{pipe}}{title[-,%pipe]}</span></code> which replaces the <code class="docutils literal notranslate"><span class="pre">-</span></code> character with <code class="docutils literal notranslate"><span class="pre">|</span></code> (the value of <code class="docutils literal notranslate"><span class="pre">%pipe</span></code>).</p>
-<p>Variables can also be referenced as fields in the template string, for example: <code class="docutils literal notranslate"><span class="pre">{var:year,created.year}{original_name}-{%year}</span></code>. In some cases, use of variables can make your template string more readable.  Variables can be used as template fields, as values for filters, as values for conditional operations, or as default values.  When used as a conditional value or default value, variables should be treated like any other field and enclosed in braces as conditional and default values are evaluated as template strings. For example: <code class="docutils literal notranslate"><span class="pre">{var:name,Katie}{person</span> <span class="pre">contains</span> <span class="pre">{%name}?{%name},Not-{%name}}</span></code>.</p>
+<p>Variables can also be referenced as fields in the template string, for example: <code class="docutils literal notranslate"><span class="pre">{var:year,{created.year}}{original_name}-{%year}</span></code>. In some cases, use of variables can make your template string more readable.  Variables can be used as template fields, as values for filters, as values for conditional operations, or as default values.  When used as a conditional value or default value, variables should be treated like any other field and enclosed in braces as conditional and default values are evaluated as template strings. For example: <code class="docutils literal notranslate"><span class="pre">{var:name,Katie}{person</span> <span class="pre">contains</span> <span class="pre">{%name}?{%name},Not-{%name}}</span></code>.</p>
 <p>If you need to use a <code class="docutils literal notranslate"><span class="pre">%</span></code> (percent sign character), you can escape the percent sign by using <code class="docutils literal notranslate"><span class="pre">%%</span></code>.  You can also use the <code class="docutils literal notranslate"><span class="pre">{percent}</span></code> template field where a template field is required. For example:</p>
 <p><code class="docutils literal notranslate"><span class="pre">{title[:,%%]}</span></code> replaces the <code class="docutils literal notranslate"><span class="pre">:</span></code> with <code class="docutils literal notranslate"><span class="pre">%</span></code> and <code class="docutils literal notranslate"><span class="pre">{title</span> <span class="pre">contains</span> <span class="pre">Foo?{title}{percent},{title}}</span></code> adds <code class="docutils literal notranslate"><span class="pre">%</span></code> to the  title if it contains <code class="docutils literal notranslate"><span class="pre">Foo</span></code>.</p>
 <section id="id1">

docs/tutorial.html

@@ -161,6 +161,7 @@
 <li class="toctree-l1"><a class="reference internal" href="cli.html">OSXPhotos Command Line Interface (CLI)</a></li>
 <li class="toctree-l1"><a class="reference internal" href="template_help.html">OSXPhotos Template System</a></li>
 <li class="toctree-l1"><a class="reference internal" href="package_overview.html">OSXPhotos Python Package Overview</a></li>
+<li class="toctree-l1"><a class="reference internal" href="api_readme.html">OSXPhotos Python API</a></li>
 <li class="toctree-l1"><a class="reference internal" href="reference.html">OSXPhotos Python Reference</a></li>
 </ul>
 

docsrc/source/index.rst

@@ -14,6 +14,7 @@ Welcome to OSXPhotos's documentation!
    cli
    template_help
    package_overview
+   api_readme
    reference
 
 

docsrc/source/template_help.rst

@@ -162,9 +162,9 @@ e.g. ``"{created.year}/{openbrace}{title}{closebrace}"`` would result in ``"2020
 
 **Variables**
 
-You can define variables for later use in the template string using the format ``{var:NAME,VALUE}``.  Variables may then be referenced using the format ``%NAME``. For example: ``{var:foo,bar}`` defines the variable ``%foo`` to have value ``bar``. This can be useful if you want to re-use a complex template value in multiple places within your template string or for allowing the use of characters that would otherwise be prohibited in a template string. For example, the "pipe" (\ ``|``\ ) character is not allowed in a find/replace pair but you can get around this limitation like so: ``{var:pipe,{pipe}}{title[-,%pipe]}`` which replaces the ``-`` character with ``|`` (the value of ``%pipe``\ ).  
+You can define variables for later use in the template string using the format ``{var:NAME,VALUE}`` where ``VALUE`` is a template statement.  Variables may then be referenced using the format ``%NAME``. For example: ``{var:foo,bar}`` defines the variable ``%foo`` to have value ``bar``. This can be useful if you want to re-use a complex template value in multiple places within your template string or for allowing the use of characters that would otherwise be prohibited in a template string. For example, the "pipe" (\ ``|``\ ) character is not allowed in a find/replace pair but you can get around this limitation like so: ``{var:pipe,{pipe}}{title[-,%pipe]}`` which replaces the ``-`` character with ``|`` (the value of ``%pipe``\ ).  
 
-Variables can also be referenced as fields in the template string, for example: ``{var:year,created.year}{original_name}-{%year}``. In some cases, use of variables can make your template string more readable.  Variables can be used as template fields, as values for filters, as values for conditional operations, or as default values.  When used as a conditional value or default value, variables should be treated like any other field and enclosed in braces as conditional and default values are evaluated as template strings. For example: ``{var:name,Katie}{person contains {%name}?{%name},Not-{%name}}``.
+Variables can also be referenced as fields in the template string, for example: ``{var:year,{created.year}}{original_name}-{%year}``. In some cases, use of variables can make your template string more readable.  Variables can be used as template fields, as values for filters, as values for conditional operations, or as default values.  When used as a conditional value or default value, variables should be treated like any other field and enclosed in braces as conditional and default values are evaluated as template strings. For example: ``{var:name,Katie}{person contains {%name}?{%name},Not-{%name}}``.
 
 If you need to use a ``%`` (percent sign character), you can escape the percent sign by using ``%%``.  You can also use the ``{percent}`` template field where a template field is required. For example: