Release v0.62.0 (#1156)

docs/cli.html

@@ -6,7 +6,7 @@
 <link rel="index" title="Index" href="genindex.html" /><link rel="search" title="Search" href="search.html" /><link rel="next" title="OSXPhotos Template System" href="template_help.html" /><link rel="prev" title="OSXPhotos Tutorial" href="tutorial.html" />
 
     <meta name="generator" content="sphinx-5.3.0, furo 2022.09.29"/>
-        <title>OSXPhotos Command Line Interface (CLI) - osxphotos 0.61.0 documentation</title>
+        <title>OSXPhotos Command Line Interface (CLI) - osxphotos 0.62.0 documentation</title>
       <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
     <link rel="stylesheet" type="text/css" href="_static/styles/furo.css?digest=d81277517bee4d6b0349d71bb2661d4890b5617c" />
     <link rel="stylesheet" type="text/css" href="_static/copybutton.css" />
@@ -124,7 +124,7 @@
       </label>
     </div>
     <div class="header-center">
-      <a href="index.html"><div class="brand">osxphotos 0.61.0 documentation</div></a>
+      <a href="index.html"><div class="brand">osxphotos 0.62.0 documentation</div></a>
     </div>
     <div class="header-right">
       <div class="theme-toggle-container theme-toggle-header">
@@ -147,7 +147,7 @@
       <div class="sidebar-sticky"><a class="sidebar-brand" href="index.html">
   
   
-  <span class="sidebar-brand-text">osxphotos 0.61.0 documentation</span>
+  <span class="sidebar-brand-text">osxphotos 0.62.0 documentation</span>
   
 </a><form class="sidebar-search-container" method="get" action="search.html" role="search">
   <input class="sidebar-search" placeholder=Search name="q" aria-label="Search">
@@ -161,6 +161,7 @@
 <li class="toctree-l1 current current-page"><a class="current reference internal" href="#">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>
 
@@ -752,6 +753,18 @@ See <cite>osxphotos help timewarp</cite> for more information.</p>
 <dd><p>Search for photos that are not part of a shared moment</p>
 </dd></dl>
 
+<dl class="std option">
+<dt class="sig sig-object std" id="cmdoption-osxphotos-add-locations-shared-library">
+<span class="sig-name descname"><span class="pre">--shared-library</span></span><span class="sig-prename descclassname"></span><a class="headerlink" href="#cmdoption-osxphotos-add-locations-shared-library" title="Permalink to this definition">#</a></dt>
+<dd><p>Search for photos that are part of a shared library</p>
+</dd></dl>
+
+<dl class="std option">
+<dt class="sig sig-object std" id="cmdoption-osxphotos-add-locations-not-shared-library">
+<span class="sig-name descname"><span class="pre">--not-shared-library</span></span><span class="sig-prename descclassname"></span><a class="headerlink" href="#cmdoption-osxphotos-add-locations-not-shared-library" title="Permalink to this definition">#</a></dt>
+<dd><p>Search for photos that are not part of a shared library</p>
+</dd></dl>
+
 <dl class="std option">
 <dt class="sig sig-object std" id="cmdoption-osxphotos-add-locations-regex">
 <span class="sig-name descname"><span class="pre">--regex</span></span><span class="sig-prename descclassname"> <span class="pre">&lt;REGEX</span> <span class="pre">TEMPLATE&gt;</span></span><a class="headerlink" href="#cmdoption-osxphotos-add-locations-regex" title="Permalink to this definition">#</a></dt>
@@ -1719,6 +1732,18 @@ to modify this behavior.</p>
 <dd><p>Search for photos that are not part of a shared moment</p>
 </dd></dl>
 
+<dl class="std option">
+<dt class="sig sig-object std" id="cmdoption-osxphotos-export-shared-library">
+<span class="sig-name descname"><span class="pre">--shared-library</span></span><span class="sig-prename descclassname"></span><a class="headerlink" href="#cmdoption-osxphotos-export-shared-library" title="Permalink to this definition">#</a></dt>
+<dd><p>Search for photos that are part of a shared library</p>
+</dd></dl>
+
+<dl class="std option">
+<dt class="sig sig-object std" id="cmdoption-osxphotos-export-not-shared-library">
+<span class="sig-name descname"><span class="pre">--not-shared-library</span></span><span class="sig-prename descclassname"></span><a class="headerlink" href="#cmdoption-osxphotos-export-not-shared-library" title="Permalink to this definition">#</a></dt>
+<dd><p>Search for photos that are not part of a shared library</p>
+</dd></dl>
+
 <dl class="std option">
 <dt class="sig sig-object std" id="cmdoption-osxphotos-export-regex">
 <span class="sig-name descname"><span class="pre">--regex</span></span><span class="sig-prename descclassname"> <span class="pre">&lt;REGEX</span> <span class="pre">TEMPLATE&gt;</span></span><a class="headerlink" href="#cmdoption-osxphotos-export-regex" title="Permalink to this definition">#</a></dt>
@@ -1944,8 +1969,8 @@ to modify this behavior.</p>
 
 <dl class="std option">
 <dt class="sig sig-object std" id="cmdoption-osxphotos-export-sidecar-template">
-<span class="sig-name descname"><span class="pre">--sidecar-template</span></span><span class="sig-prename descclassname"> <span class="pre">&lt;MAKO_TEMPLATE_FILE</span> <span class="pre">SIDECAR_FILENAME_TEMPLATE</span> <span class="pre">WRITE_SKIPPED</span> <span class="pre">STRIP_WHITESPACE</span> <span class="pre">STRIP_LINES&gt;</span></span><a class="headerlink" href="#cmdoption-osxphotos-export-sidecar-template" title="Permalink to this definition">#</a></dt>
-<dd><p>Create a custom sidecar file for each photo exported with user provided Mako template (MAKO_TEMPLATE_FILE). MAKO_TEMPLATE_FILE must be a valid Mako template (see <a class="reference external" href="https://www.makotemplates.org/">https://www.makotemplates.org/</a>). The template will passed the following variables: photo (PhotoInfo object for the photo being exported), sidecar_path (pathlib.Path object for the path to the sidecar being written), and photo_path (pathlib.Path object for the path to the exported photo. SIDECAR_FILENAME_TEMPLATE must be a valid template string (see Templating System in help) which will be rendered to generate the filename of the sidecar file. The <cite>{filepath}</cite> template variable may be used in the SIDECAR_FILENAME_TEMPLATE to refer to the filename of the photo being exported. WRITE_SKIPPED is a boolean value (true/false, yes/no, 1/0 are all valid values) and indicates whether or not write the sidecar file even if the photo is skipped during export. If WRITE_SKIPPED is false, the sidecar file will not be written if the photo is skipped during export. If WRITE_SKIPPED is true, the sidecar file will be written even if the photo is skipped during export. STRIP_WHITESPACE and STRIP_LINES are boolean values (true/false, yes/no, 1/0 are all valid values) and indicate whether or not to strip whitespace and blank lines from the resulting sidecar file. For example, to create a sidecar file with extension .xmp using a template file named ‘sidecar.mako’ and write a sidecar for skipped photos and strip blank lines but not whitespace: <cite>–sidecar-template sidecar.mako ‘{filepath}.xmp’ yes no yes</cite>. To do the same but to drop the photo extension from the sidecar filename: <cite>–sidecar-template sidecar.mako ‘{filepath.parent}/{filepath.stem}.xmp’ yes no yes –sidecar-drop-ext</cite>. For an example Mako file see <a class="reference external" href="https://raw.githubusercontent.com/RhetTbull/osxphotos/main/examples/custom_sidecar.mako">https://raw.githubusercontent.com/RhetTbull/osxphotos/main/examples/custom_sidecar.mako</a></p>
+<span class="sig-name descname"><span class="pre">--sidecar-template</span></span><span class="sig-prename descclassname"> <span class="pre">&lt;MAKO_TEMPLATE_FILE</span> <span class="pre">SIDECAR_FILENAME_TEMPLATE</span> <span class="pre">OPTIONS&gt;</span></span><a class="headerlink" href="#cmdoption-osxphotos-export-sidecar-template" title="Permalink to this definition">#</a></dt>
+<dd><p>Create a custom sidecar file for each photo exported with user provided Mako template (MAKO_TEMPLATE_FILE). MAKO_TEMPLATE_FILE must be a valid Mako template (see <a class="reference external" href="https://www.makotemplates.org/">https://www.makotemplates.org/</a>). The template will passed the following variables: photo (PhotoInfo object for the photo being exported), sidecar_path (pathlib.Path object for the path to the sidecar being written), and photo_path (pathlib.Path object for the path to the exported photo. SIDECAR_FILENAME_TEMPLATE must be a valid template string (see Templating System in help) which will be rendered to generate the filename of the sidecar file. The <cite>{filepath}</cite> template variable may be used in the SIDECAR_FILENAME_TEMPLATE to refer to the filename of the photo being exported. OPTIONS is a comma-separated list of strings providing additional options to the template. Valid options are: write_skipped, strip_whitespace, strip_lines, skip_zero, catch_errors, none. write_skipped will cause the sidecar file to be written even if the photo is skipped during export. If write_skipped is not passed as an option, the sidecar file will not be written if the photo is skipped during export. strip_whitespace and strip_lines indicate whether or not to strip whitespace and blank lines, respectively, from the resulting sidecar file. skip_zero causes the sidecar file to be skipped if the rendered template is zero-length. catch_errors causes errors in the template to be caught and logged but not raised. Without catch_errors, osxphotos will abort the export if an error occurs in the template. For example, to create a sidecar file with extension .xmp using a template file named ‘sidecar.mako’ and write a sidecar for skipped photos and strip blank lines but not whitespace: <cite>–sidecar-template sidecar.mako ‘{filepath}.xmp’ write_skipped,strip_lines</cite>. To do the same but to drop the photo extension from the sidecar filename: <cite>–sidecar-template sidecar.mako ‘{filepath.parent}/{filepath.stem}.xmp’ write_skipped,strip_lines</cite>. If you are not passing any options, you must pass ‘none’ as the last argument to –sidecar-template: <cite>–sidecar-template sidecar.mako ‘{filepath}.xmp’ none</cite>. For an example Mako file see <a class="reference external" href="https://raw.githubusercontent.com/RhetTbull/osxphotos/main/examples/custom_sidecar.mako">https://raw.githubusercontent.com/RhetTbull/osxphotos/main/examples/custom_sidecar.mako</a></p>
 </dd></dl>
 
 <dl class="std option">
@@ -2106,13 +2131,13 @@ to modify this behavior.</p>
 <dl class="std option">
 <dt class="sig sig-object std" id="cmdoption-osxphotos-export-cleanup">
 <span class="sig-name descname"><span class="pre">--cleanup</span></span><span class="sig-prename descclassname"></span><a class="headerlink" href="#cmdoption-osxphotos-export-cleanup" title="Permalink to this definition">#</a></dt>
-<dd><p>Cleanup export directory by deleting any files which were not included in this export set. For example, photos which had previously been exported and were subsequently deleted in Photos. WARNING: –cleanup will delete <em>any</em> files in the export directory that were not exported by osxphotos, for example, your own scripts or other files.  Be sure this is what you intend before using –cleanup.  Use –dry-run with –cleanup first if you’re not certain.</p>
+<dd><p>Cleanup export directory by deleting any files which were not included in this export set. For example, photos which had previously been exported and were subsequently deleted in Photos. WARNING: –cleanup will delete <em>any</em> files in the export directory that were not exported by osxphotos, for example, your own scripts or other files.  Be sure this is what you intend before using –cleanup.  Use –dry-run with –cleanup first if you’re not certain. To prevent files not generated by osxphotos from being deleted, you may specify one or more rulesin a file named <cite>.osxphotos_keep</cite> in the export directory. This file uses the same format as a .gitignore file and should contain one rule per line; lines starting with a <cite>#</cite> will be ignored. Reference <a class="reference external" href="https://git-scm.com/docs/gitignore#_pattern_format">https://git-scm.com/docs/gitignore#_pattern_format</a> for details. In addition to the standard .gitignore rules, the rules may also be the absolute path to a file or directory. For example if export destination is <cite>/Volumes/Photos</cite> and you want to keep all <cite>.txt</cite> files, in the top level of the export directory, you can specify <cite>/*.txt”</cite> in the .osxphotos_keep file. If you want to keep all <cite>.txt</cite> files in the export directory and all subdirectories, you can specify <cite>**/*.txt</cite>. If present, the .osxphotos_keep file will be read after the export is completed and any rules found in the file will be added to the list of rules to keep. See also –keep.</p>
 </dd></dl>
 
 <dl class="std option">
 <dt class="sig sig-object std" id="cmdoption-osxphotos-export-keep">
-<span class="sig-name descname"><span class="pre">--keep</span></span><span class="sig-prename descclassname"> <span class="pre">&lt;KEEP_PATH&gt;</span></span><a class="headerlink" href="#cmdoption-osxphotos-export-keep" title="Permalink to this definition">#</a></dt>
-<dd><p>When used with –cleanup, prevents file or directory KEEP_PATH from being deleted when cleanup is run. Use this if there are files in the export directory that you don’t want to be deleted when –cleanup is run. KEEP_PATH may be a file path, e.g. ‘/Volumes/Photos/keep.jpg’, or a file path and wild card, e.g. ‘/Volumes/Photos/<em>.txt’, or a directory, e.g. ‘/Volumes/Photos/KeepMe’. KEEP_PATH may be an absolute path or a relative path. If it is relative, it must be relative to the export destination. For example if export destination is `/Volumes/Photos` and you want to keep all `.txt` files, you can specify `–keep “/Volumes/Photos/</em>.txt”` or <cite>–keep “*.txt”</cite>. If wild card is used, KEEP_PATH must be enclosed in quotes to prevent the shell from expanding the wildcard, e.g. <cite>–keep “/Volumes/Photos/*.txt”</cite>. If KEEP_PATH is a directory, all files and directories contained in KEEP_PATH will be kept. –keep may be repeated to keep additional files/directories.</p>
+<span class="sig-name descname"><span class="pre">--keep</span></span><span class="sig-prename descclassname"> <span class="pre">&lt;KEEP_RULE&gt;</span></span><a class="headerlink" href="#cmdoption-osxphotos-export-keep" title="Permalink to this definition">#</a></dt>
+<dd><p>When used with –cleanup, prevents file or directory matching KEEP_RULE from being deleted when cleanup is run. Use this if there are files in the export directory that you don’t want to be deleted when –cleanup is run. KEEP_RULE follows the same format rules a .gitignore file. Reference <a class="reference external" href="https://git-scm.com/docs/gitignore#_pattern_format">https://git-scm.com/docs/gitignore#_pattern_format</a> for details. In addition to the standard .gitignore rules, KEEP_RULE may also be the absolute path to a file or directory. For example if export destination is <cite>/Volumes/Photos</cite> and you want to keep all <cite>.txt</cite> files, in the top level of the export directory, you can specify <cite>–keep “/*.txt”</cite>. If you want to keep all <cite>.txt</cite> files in the export directory and all subdirectories, you can specify <cite>–keep “**/*.txt”</cite>. If wild card is used, KEEP_RULE must be enclosed in quotes to prevent the shell from expanding the wildcard. –keep may be repeated to keep additional files/directories. Rules may also be included in a file named <cite>.osxphotos_keep</cite> in the export directory. If present, this file will be read after the export is completed and any rules found in the file will be added to the list of rules to keep. This file uses the same format as a .gitignore file and should contain one rule per line; lines starting with a <cite>#</cite> will be ignored.</p>
 </dd></dl>
 
 <dl class="std option">
@@ -2136,7 +2161,18 @@ to modify this behavior.</p>
 <dl class="std option">
 <dt class="sig sig-object std" id="cmdoption-osxphotos-export-post-command">
 <span class="sig-name descname"><span class="pre">--post-command</span></span><span class="sig-prename descclassname"> <span class="pre">&lt;CATEGORY</span> <span class="pre">COMMAND&gt;</span></span><a class="headerlink" href="#cmdoption-osxphotos-export-post-command" title="Permalink to this definition">#</a></dt>
-<dd><p>Run COMMAND on exported files of category CATEGORY.  CATEGORY can be one of: exported, new, updated, skipped, missing, exif_updated, touched, converted_to_jpeg, sidecar_json_written, sidecar_json_skipped, sidecar_exiftool_written, sidecar_exiftool_skipped, sidecar_xmp_written, sidecar_xmp_skipped, error. COMMAND is an osxphotos template string, for example: ‘–post-command exported “echo {filepath|shell_quote} &gt;&gt; {export_dir}/exported.txt”’, which appends the 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 Command below.</p>
+<dd><p>Run COMMAND on exported files of category CATEGORY.  CATEGORY can be one of: exported, new, updated, skipped, missing, exif_updated, touched, converted_to_jpeg, sidecar_json_written, sidecar_json_skipped, sidecar_exiftool_written, sidecar_exiftool_skipped, sidecar_xmp_written, sidecar_xmp_skipped, error. COMMAND is an osxphotos template string, for example: ‘–post-command exported “echo {filepath|shell_quote} &gt;&gt; {export_dir}/exported.txt”’, which appends the 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 also –post-command-error and –post-function.See Post Command below.</p>
+</dd></dl>
+
+<dl class="std option">
+<dt class="sig sig-object std" id="cmdoption-osxphotos-export-post-command-error">
+<span class="sig-name descname"><span class="pre">--post-command-error</span></span><span class="sig-prename descclassname"> <span class="pre">&lt;ACTION&gt;</span></span><a class="headerlink" href="#cmdoption-osxphotos-export-post-command-error" title="Permalink to this definition">#</a></dt>
+<dd><p>Specify either <cite>continue</cite> or <cite>break</cite> for ACTION to control behavior when a post-command fails. If <cite>continue</cite>, osxphotos will log the error and continue processing. If <cite>break</cite>, 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.</p>
+<dl class="field-list simple">
+<dt class="field-odd">Options<span class="colon">:</span></dt>
+<dd class="field-odd"><p>continue | break</p>
+</dd>
+</dl>
 </dd></dl>
 
 <dl class="std option">
@@ -3343,6 +3379,18 @@ If the same query option is provided multiple times, they are treated as
 <dd><p>Search for photos that are not part of a shared moment</p>
 </dd></dl>
 
+<dl class="std option">
+<dt class="sig sig-object std" id="cmdoption-osxphotos-query-shared-library">
+<span class="sig-name descname"><span class="pre">--shared-library</span></span><span class="sig-prename descclassname"></span><a class="headerlink" href="#cmdoption-osxphotos-query-shared-library" title="Permalink to this definition">#</a></dt>
+<dd><p>Search for photos that are part of a shared library</p>
+</dd></dl>
+
+<dl class="std option">
+<dt class="sig sig-object std" id="cmdoption-osxphotos-query-not-shared-library">
+<span class="sig-name descname"><span class="pre">--not-shared-library</span></span><span class="sig-prename descclassname"></span><a class="headerlink" href="#cmdoption-osxphotos-query-not-shared-library" title="Permalink to this definition">#</a></dt>
+<dd><p>Search for photos that are not part of a shared library</p>
+</dd></dl>
+
 <dl class="std option">
 <dt class="sig sig-object std" id="cmdoption-osxphotos-query-regex">
 <span class="sig-name descname"><span class="pre">--regex</span></span><span class="sig-prename descclassname"> <span class="pre">&lt;REGEX</span> <span class="pre">TEMPLATE&gt;</span></span><a class="headerlink" href="#cmdoption-osxphotos-query-regex" title="Permalink to this definition">#</a></dt>
@@ -3916,6 +3964,18 @@ If the same query option is provided multiple times, they are treated as
 <dd><p>Search for photos that are not part of a shared moment</p>
 </dd></dl>
 
+<dl class="std option">
+<dt class="sig sig-object std" id="cmdoption-osxphotos-repl-shared-library">
+<span class="sig-name descname"><span class="pre">--shared-library</span></span><span class="sig-prename descclassname"></span><a class="headerlink" href="#cmdoption-osxphotos-repl-shared-library" title="Permalink to this definition">#</a></dt>
+<dd><p>Search for photos that are part of a shared library</p>
+</dd></dl>
+
+<dl class="std option">
+<dt class="sig sig-object std" id="cmdoption-osxphotos-repl-not-shared-library">
+<span class="sig-name descname"><span class="pre">--not-shared-library</span></span><span class="sig-prename descclassname"></span><a class="headerlink" href="#cmdoption-osxphotos-repl-not-shared-library" title="Permalink to this definition">#</a></dt>
+<dd><p>Search for photos that are not part of a shared library</p>
+</dd></dl>
+
 <dl class="std option">
 <dt class="sig sig-object std" id="cmdoption-osxphotos-repl-regex">
 <span class="sig-name descname"><span class="pre">--regex</span></span><span class="sig-prename descclassname"> <span class="pre">&lt;REGEX</span> <span class="pre">TEMPLATE&gt;</span></span><a class="headerlink" href="#cmdoption-osxphotos-repl-regex" title="Permalink to this definition">#</a></dt>
@@ -4611,6 +4671,18 @@ two different computers, you can export the metadata to a shared folder.</p>
 <dd><p>Search for photos that are not part of a shared moment</p>
 </dd></dl>
 
+<dl class="std option">
+<dt class="sig sig-object std" id="cmdoption-osxphotos-sync-shared-library">
+<span class="sig-name descname"><span class="pre">--shared-library</span></span><span class="sig-prename descclassname"></span><a class="headerlink" href="#cmdoption-osxphotos-sync-shared-library" title="Permalink to this definition">#</a></dt>
+<dd><p>Search for photos that are part of a shared library</p>
+</dd></dl>
+
+<dl class="std option">
+<dt class="sig sig-object std" id="cmdoption-osxphotos-sync-not-shared-library">
+<span class="sig-name descname"><span class="pre">--not-shared-library</span></span><span class="sig-prename descclassname"></span><a class="headerlink" href="#cmdoption-osxphotos-sync-not-shared-library" title="Permalink to this definition">#</a></dt>
+<dd><p>Search for photos that are not part of a shared library</p>
+</dd></dl>
+
 <dl class="std option">
 <dt class="sig sig-object std" id="cmdoption-osxphotos-sync-regex">
 <span class="sig-name descname"><span class="pre">--regex</span></span><span class="sig-prename descclassname"> <span class="pre">&lt;REGEX</span> <span class="pre">TEMPLATE&gt;</span></span><a class="headerlink" href="#cmdoption-osxphotos-sync-regex" title="Permalink to this definition">#</a></dt>