a9843ac60e
* Updated ExportResults docstrings so Sphinx picks them up * Updated API_README so link works in docs * Removed sweep templates
771 lines
63 KiB
HTML
771 lines
63 KiB
HTML
<!doctype html>
|
||
<html class="no-js" lang="en">
|
||
<head><meta charset="utf-8"/>
|
||
<meta name="viewport" content="width=device-width,initial-scale=1"/>
|
||
<meta name="color-scheme" content="light dark"><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />
|
||
<link rel="index" title="Index" href="genindex.html" /><link rel="search" title="Search" href="search.html" /><link rel="next" title="OSXPhotos Python Package Overview" href="package_overview.html" /><link rel="prev" title="OSXPhotos Command Line Interface (CLI)" href="cli.html" />
|
||
|
||
<meta name="generator" content="sphinx-5.3.0, furo 2022.09.29"/>
|
||
<title>OSXPhotos Template System - osxphotos 0.62.1 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" />
|
||
<link rel="stylesheet" type="text/css" href="_static/styles/furo-extensions.css?digest=30d1aed668e5c3a91c3e3bf6a60b675221979f0e" />
|
||
|
||
|
||
|
||
|
||
<style>
|
||
body {
|
||
--color-code-background: #f8f8f8;
|
||
--color-code-foreground: black;
|
||
|
||
}
|
||
@media not print {
|
||
body[data-theme="dark"] {
|
||
--color-code-background: #202020;
|
||
--color-code-foreground: #d0d0d0;
|
||
|
||
}
|
||
@media (prefers-color-scheme: dark) {
|
||
body:not([data-theme="light"]) {
|
||
--color-code-background: #202020;
|
||
--color-code-foreground: #d0d0d0;
|
||
|
||
}
|
||
}
|
||
}
|
||
</style></head>
|
||
<body>
|
||
|
||
<script>
|
||
document.body.dataset.theme = localStorage.getItem("theme") || "auto";
|
||
</script>
|
||
|
||
|
||
<svg xmlns="http://www.w3.org/2000/svg" style="display: none;">
|
||
<symbol id="svg-toc" viewBox="0 0 24 24">
|
||
<title>Contents</title>
|
||
<svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 1024 1024">
|
||
<path d="M408 442h480c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8H408c-4.4 0-8 3.6-8 8v56c0 4.4 3.6 8 8 8zm-8 204c0 4.4 3.6 8 8 8h480c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8H408c-4.4 0-8 3.6-8 8v56zm504-486H120c-4.4 0-8 3.6-8 8v56c0 4.4 3.6 8 8 8h784c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8zm0 632H120c-4.4 0-8 3.6-8 8v56c0 4.4 3.6 8 8 8h784c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8zM115.4 518.9L271.7 642c5.8 4.6 14.4.5 14.4-6.9V388.9c0-7.4-8.5-11.5-14.4-6.9L115.4 505.1a8.74 8.74 0 0 0 0 13.8z"/>
|
||
</svg>
|
||
</symbol>
|
||
<symbol id="svg-menu" viewBox="0 0 24 24">
|
||
<title>Menu</title>
|
||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
|
||
stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather-menu">
|
||
<line x1="3" y1="12" x2="21" y2="12"></line>
|
||
<line x1="3" y1="6" x2="21" y2="6"></line>
|
||
<line x1="3" y1="18" x2="21" y2="18"></line>
|
||
</svg>
|
||
</symbol>
|
||
<symbol id="svg-arrow-right" viewBox="0 0 24 24">
|
||
<title>Expand</title>
|
||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
|
||
stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather-chevron-right">
|
||
<polyline points="9 18 15 12 9 6"></polyline>
|
||
</svg>
|
||
</symbol>
|
||
<symbol id="svg-sun" viewBox="0 0 24 24">
|
||
<title>Light mode</title>
|
||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
|
||
stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" class="feather-sun">
|
||
<circle cx="12" cy="12" r="5"></circle>
|
||
<line x1="12" y1="1" x2="12" y2="3"></line>
|
||
<line x1="12" y1="21" x2="12" y2="23"></line>
|
||
<line x1="4.22" y1="4.22" x2="5.64" y2="5.64"></line>
|
||
<line x1="18.36" y1="18.36" x2="19.78" y2="19.78"></line>
|
||
<line x1="1" y1="12" x2="3" y2="12"></line>
|
||
<line x1="21" y1="12" x2="23" y2="12"></line>
|
||
<line x1="4.22" y1="19.78" x2="5.64" y2="18.36"></line>
|
||
<line x1="18.36" y1="5.64" x2="19.78" y2="4.22"></line>
|
||
</svg>
|
||
</symbol>
|
||
<symbol id="svg-moon" viewBox="0 0 24 24">
|
||
<title>Dark mode</title>
|
||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
|
||
stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" class="icon-tabler-moon">
|
||
<path stroke="none" d="M0 0h24v24H0z" fill="none" />
|
||
<path d="M12 3c.132 0 .263 0 .393 0a7.5 7.5 0 0 0 7.92 12.446a9 9 0 1 1 -8.313 -12.454z" />
|
||
</svg>
|
||
</symbol>
|
||
<symbol id="svg-sun-half" viewBox="0 0 24 24">
|
||
<title>Auto light/dark mode</title>
|
||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
|
||
stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" class="icon-tabler-shadow">
|
||
<path stroke="none" d="M0 0h24v24H0z" fill="none"/>
|
||
<circle cx="12" cy="12" r="9" />
|
||
<path d="M13 12h5" />
|
||
<path d="M13 15h4" />
|
||
<path d="M13 18h1" />
|
||
<path d="M13 9h4" />
|
||
<path d="M13 6h1" />
|
||
</svg>
|
||
</symbol>
|
||
</svg>
|
||
|
||
<input type="checkbox" class="sidebar-toggle" name="__navigation" id="__navigation">
|
||
<input type="checkbox" class="sidebar-toggle" name="__toc" id="__toc">
|
||
<label class="overlay sidebar-overlay" for="__navigation">
|
||
<div class="visually-hidden">Hide navigation sidebar</div>
|
||
</label>
|
||
<label class="overlay toc-overlay" for="__toc">
|
||
<div class="visually-hidden">Hide table of contents sidebar</div>
|
||
</label>
|
||
|
||
|
||
|
||
<div class="page">
|
||
<header class="mobile-header">
|
||
<div class="header-left">
|
||
<label class="nav-overlay-icon" for="__navigation">
|
||
<div class="visually-hidden">Toggle site navigation sidebar</div>
|
||
<i class="icon"><svg><use href="#svg-menu"></use></svg></i>
|
||
</label>
|
||
</div>
|
||
<div class="header-center">
|
||
<a href="index.html"><div class="brand">osxphotos 0.62.1 documentation</div></a>
|
||
</div>
|
||
<div class="header-right">
|
||
<div class="theme-toggle-container theme-toggle-header">
|
||
<button class="theme-toggle">
|
||
<div class="visually-hidden">Toggle Light / Dark / Auto color theme</div>
|
||
<svg class="theme-icon-when-auto"><use href="#svg-sun-half"></use></svg>
|
||
<svg class="theme-icon-when-dark"><use href="#svg-moon"></use></svg>
|
||
<svg class="theme-icon-when-light"><use href="#svg-sun"></use></svg>
|
||
</button>
|
||
</div>
|
||
<label class="toc-overlay-icon toc-header-icon" for="__toc">
|
||
<div class="visually-hidden">Toggle table of contents sidebar</div>
|
||
<i class="icon"><svg><use href="#svg-toc"></use></svg></i>
|
||
</label>
|
||
</div>
|
||
</header>
|
||
<aside class="sidebar-drawer">
|
||
<div class="sidebar-container">
|
||
|
||
<div class="sidebar-sticky"><a class="sidebar-brand" href="index.html">
|
||
|
||
|
||
<span class="sidebar-brand-text">osxphotos 0.62.1 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">
|
||
<input type="hidden" name="check_keywords" value="yes">
|
||
<input type="hidden" name="area" value="default">
|
||
</form>
|
||
<div id="searchbox"></div><div class="sidebar-scroll"><div class="sidebar-tree">
|
||
<ul class="current">
|
||
<li class="toctree-l1"><a class="reference internal" href="overview.html">OSXPhotos</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="tutorial.html">OSXPhotos Tutorial</a></li>
|
||
<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>
|
||
|
||
</div>
|
||
</div>
|
||
|
||
</div>
|
||
|
||
</div>
|
||
</aside>
|
||
<div class="main">
|
||
<div class="content">
|
||
<div class="article-container">
|
||
<a href="#" class="back-to-top muted-link">
|
||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">
|
||
<path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8v12z"></path>
|
||
</svg>
|
||
<span>Back to top</span>
|
||
</a>
|
||
<div class="content-icon-container">
|
||
|
||
<div class="theme-toggle-container theme-toggle-content">
|
||
<button class="theme-toggle">
|
||
<div class="visually-hidden">Toggle Light / Dark / Auto color theme</div>
|
||
<svg class="theme-icon-when-auto"><use href="#svg-sun-half"></use></svg>
|
||
<svg class="theme-icon-when-dark"><use href="#svg-moon"></use></svg>
|
||
<svg class="theme-icon-when-light"><use href="#svg-sun"></use></svg>
|
||
</button>
|
||
</div>
|
||
<label class="toc-overlay-icon toc-content-icon" for="__toc">
|
||
<div class="visually-hidden">Toggle table of contents sidebar</div>
|
||
<i class="icon"><svg><use href="#svg-toc"></use></svg></i>
|
||
</label>
|
||
</div>
|
||
<article role="main">
|
||
<section id="osxphotos-template-system">
|
||
<h1>OSXPhotos Template System<a class="headerlink" href="#osxphotos-template-system" title="Permalink to this heading">#</a></h1>
|
||
<p>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.</p>
|
||
<p>In its simplest form, a template statement has the form: <code class="docutils literal notranslate"><span class="pre">"{template_field}"</span></code>, for example <code class="docutils literal notranslate"><span class="pre">"{title}"</span></code> which would resolve to the title of the photo.</p>
|
||
<p>Template statements may contain one or more modifiers. The full syntax is:</p>
|
||
<p><code class="docutils literal notranslate"><span class="pre">"pretext{delim+template_field:subfield(field_arg)|filter[find,replace]</span> <span class="pre">conditional?bool_value,default}posttext"</span></code></p>
|
||
<p>Template statements are white-space sensitive meaning that white space (spaces, tabs) changes the meaning of the template statement.</p>
|
||
<p><code class="docutils literal notranslate"><span class="pre">pretext</span></code> and <code class="docutils literal notranslate"><span class="pre">posttext</span></code> are free form text. For example, if a photo has title “My Photo Title” the template statement <code class="docutils literal notranslate"><span class="pre">"The</span> <span class="pre">title</span> <span class="pre">of</span> <span class="pre">the</span> <span class="pre">photo</span> <span class="pre">is</span> <span class="pre">{title}"</span></code>, resolves to <code class="docutils literal notranslate"><span class="pre">"The</span> <span class="pre">title</span> <span class="pre">of</span> <span class="pre">the</span> <span class="pre">photo</span> <span class="pre">is</span> <span class="pre">My</span> <span class="pre">Photo</span> <span class="pre">Title"</span></code>. The <code class="docutils literal notranslate"><span class="pre">pretext</span></code> in this example is <code class="docutils literal notranslate"><span class="pre">"The</span> <span class="pre">title</span> <span class="pre">if</span> <span class="pre">the</span> <span class="pre">photo</span> <span class="pre">is</span> <span class="pre">"</span></code> and the template_field is <code class="docutils literal notranslate"><span class="pre">{title}</span></code>.</p>
|
||
<p><code class="docutils literal notranslate"><span class="pre">delim</span></code>: optional delimiter string to use when expanding multi-valued template values in-place</p>
|
||
<p><code class="docutils literal notranslate"><span class="pre">+</span></code>: If present before template <code class="docutils literal notranslate"><span class="pre">name</span></code>, expands the template in place. If <code class="docutils literal notranslate"><span class="pre">delim</span></code> not provided, values are joined with no delimiter.</p>
|
||
<p>e.g. if Photo keywords are <code class="docutils literal notranslate"><span class="pre">["foo","bar"]</span></code>:</p>
|
||
<ul class="simple">
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">"{keyword}"</span></code> renders to <code class="docutils literal notranslate"><span class="pre">"foo",</span> <span class="pre">"bar"</span></code></p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">"{,+keyword}"</span></code> renders to: <code class="docutils literal notranslate"><span class="pre">"foo,bar"</span></code></p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">"{;</span> <span class="pre">+keyword}"</span></code> renders to: <code class="docutils literal notranslate"><span class="pre">"foo;</span> <span class="pre">bar"</span></code></p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">"{+keyword}"</span></code> renders to <code class="docutils literal notranslate"><span class="pre">"foobar"</span></code></p></li>
|
||
</ul>
|
||
<p><code class="docutils literal notranslate"><span class="pre">template_field</span></code>: The template field to resolve. See <a class="reference external" href="#template-substitutions">Template Substitutions</a> for full list of template fields.</p>
|
||
<p><cite>:subfield</cite>: Some templates have sub-fields, For example, <cite>{exiftool:IPTC:Make}`</cite>; the template_field is``exiftool<code class="docutils literal notranslate"><span class="pre">and</span> <span class="pre">the</span> <span class="pre">sub-field</span> <span class="pre">is</span></code>IPTC:Make`.</p>
|
||
<p><code class="docutils literal notranslate"><span class="pre">(field_arg)</span></code>: optional arguments to pass to the field; for example, with <code class="docutils literal notranslate"><span class="pre">{folder_album}</span></code> this is used to pass the path separator used for joining folders and albums when rendering the field (default is “/” for <code class="docutils literal notranslate"><span class="pre">{folder_album}</span></code>).</p>
|
||
<p><cite>|filter</cite>: You may optionally append one or more filter commands to the end of the template field using the vertical pipe (‘|’) symbol. Filters may be combined, separated by ‘|’ as in: <code class="docutils literal notranslate"><span class="pre">{keyword|capitalize|parens}</span></code>.</p>
|
||
<p>Valid filters are:</p>
|
||
<ul class="simple">
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">lower</span></code>: Convert value to lower case, e.g. ‘Value’ => ‘value’.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">upper</span></code>: Convert value to upper case, e.g. ‘Value’ => ‘VALUE’.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">strip</span></code>: Strip whitespace from beginning/end of value, e.g. ‘ Value ‘ => ‘Value’.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">titlecase</span></code>: Convert value to title case, e.g. ‘my value’ => ‘My Value’.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">capitalize</span></code>: Capitalize first word of value and convert other words to lower case, e.g. ‘MY VALUE’ => ‘My value’.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">braces</span></code>: Enclose value in curly braces, e.g. ‘value => ‘{value}’.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">parens</span></code>: Enclose value in parentheses, e.g. ‘value’ => ‘(value’)</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">brackets</span></code>: Enclose value in brackets, e.g. ‘value’ => ‘[value]’</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">shell_quote</span></code>: Quotes the value for safe usage in the shell, e.g. My file.jpeg => ‘My file.jpeg’; only adds quotes if needed.</p></li>
|
||
<li><p><cite>function</cite>: Run custom python function to filter value; use in format ‘function:/path/to/file.py::function_name’. See example at https://github.com/RhetTbull/osxphotos/blob/master/examples/template_filter.py</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">split(x)</span></code>: Split value into a list of values using x as delimiter, e.g. ‘value1;value2’ => [‘value1’, ‘value2’] if used with split(;).</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">autosplit</span></code>: Automatically split delimited string into separate values; will split strings delimited by comma, semicolon, or space, e.g. ‘value1,value2’ => [‘value1’, ‘value2’].</p></li>
|
||
<li><p><cite>chop(x)</cite>: Remove x characters off the end of value, e.g. chop(1): ‘Value’ => ‘Valu’; when applied to a list, chops characters from each list value, e.g. chop(1): [‘travel’, ‘beach’]=> [‘trave’, ‘beac’].</p></li>
|
||
<li><p><cite>chomp(x)</cite>: Remove x characters from the beginning of value, e.g. chomp(1): [‘Value’] => [‘alue’]; when applied to a list, removes characters from each list value, e.g. chomp(1): [‘travel’, ‘beach’]=> [‘ravel’, ‘each’].</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">sort</span></code>: Sort list of values, e.g. [‘c’, ‘b’, ‘a’] => [‘a’, ‘b’, ‘c’].</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">rsort</span></code>: Sort list of values in reverse order, e.g. [‘a’, ‘b’, ‘c’] => [‘c’, ‘b’, ‘a’].</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">reverse</span></code>: Reverse order of values, e.g. [‘a’, ‘b’, ‘c’] => [‘c’, ‘b’, ‘a’].</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">uniq</span></code>: Remove duplicate values, e.g. [‘a’, ‘b’, ‘c’, ‘b’, ‘a’] => [‘a’, ‘b’, ‘c’].</p></li>
|
||
<li><p><cite>join(x)</cite>: 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’.</p></li>
|
||
<li><p><cite>append(x)</cite>: Append x to list of values, e.g. append(d): [‘a’, ‘b’, ‘c’] => [‘a’, ‘b’, ‘c’, ‘d’].</p></li>
|
||
<li><p><cite>prepend(x)</cite>: Prepend x to list of values, e.g. prepend(d): [‘a’, ‘b’, ‘c’] => [‘d’, ‘a’, ‘b’, ‘c’].</p></li>
|
||
<li><p><cite>appends(x)</cite>: Append s[tring] Append x to each value of list of values, e.g. appends(d): [‘a’, ‘b’, ‘c’] => [‘ad’, ‘bd’, ‘cd’].</p></li>
|
||
<li><p><cite>prepends(x)</cite>: Prepend s[tring] x to each value of list of values, e.g. prepends(d): [‘a’, ‘b’, ‘c’] => [‘da’, ‘db’, ‘dc’].</p></li>
|
||
<li><p><cite>remove(x)</cite>: Remove x from list of values, e.g. remove(b): [‘a’, ‘b’, ‘c’] => [‘a’, ‘c’].</p></li>
|
||
<li><p><cite>slice(start:stop:step)</cite>: 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().</p></li>
|
||
<li><p><cite>sslice(start:stop:step)</cite>: [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().</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">filter(x)</span></code>: Filter list of values using predicate x; for example, <code class="docutils literal notranslate"><span class="pre">{folder_album|filter(contains</span> <span class="pre">Events)}</span></code> returns only folders/albums containing the word ‘Events’ in their path.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">int</span></code>: Convert values in list to integer, e.g. 1.0 => 1. If value cannot be converted to integer, remove value from list. [‘1.1’, ‘x’] => [‘1’]. See also float.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">float</span></code>: Convert values in list to floating point number, e.g. 1 => 1.0. If value cannot be converted to float, remove value from list. [‘1’, ‘x’] => [‘1.0’]. See also int.</p></li>
|
||
</ul>
|
||
<p>e.g. if Photo keywords are <code class="docutils literal notranslate"><span class="pre">["FOO","bar"]</span></code>:</p>
|
||
<ul class="simple">
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">"{keyword|lower}"</span></code> renders to <code class="docutils literal notranslate"><span class="pre">"foo",</span> <span class="pre">"bar"</span></code></p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">"{keyword|upper}"</span></code> renders to: <code class="docutils literal notranslate"><span class="pre">"FOO",</span> <span class="pre">"BAR"</span></code></p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">"{keyword|capitalize}"</span></code> renders to: <code class="docutils literal notranslate"><span class="pre">"Foo",</span> <span class="pre">"Bar"</span></code></p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">"{keyword|lower|parens}"</span></code> renders to: <code class="docutils literal notranslate"><span class="pre">"(foo)",</span> <span class="pre">"(bar)"</span></code></p></li>
|
||
</ul>
|
||
<p>e.g. if Photo description is “my description”:</p>
|
||
<ul class="simple">
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">"{descr|titlecase}"</span></code> renders to: <code class="docutils literal notranslate"><span class="pre">"My</span> <span class="pre">Description"</span></code></p></li>
|
||
</ul>
|
||
<p>e.g. If Photo is in <code class="docutils literal notranslate"><span class="pre">Album1</span></code> in <code class="docutils literal notranslate"><span class="pre">Folder1</span></code>:</p>
|
||
<ul class="simple">
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">"{folder_album}"</span></code> renders to <code class="docutils literal notranslate"><span class="pre">["Folder1/Album1"]</span></code></p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">"{folder_album(>)}"</span></code> renders to <code class="docutils literal notranslate"><span class="pre">["Folder1>Album1"]</span></code></p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">"{folder_album()}"</span></code> renders to <code class="docutils literal notranslate"><span class="pre">["Folder1Album1"]</span></code></p></li>
|
||
</ul>
|
||
<p><cite>[find,replace]</cite>: optional text replacement to perform on rendered template value. For example, to replace “/” in an album name, you could use the template <cite>“{album[/,-]}”</cite>. Multiple replacements can be made by appending “|” and adding another find|replace pair. e.g. to replace both “/” and “:” in album name: <code class="docutils literal notranslate"><span class="pre">"{album[/,-|:,-]}"</span></code>. find/replace pairs are not limited to single characters. The “|” character cannot be used in a find/replace pair.</p>
|
||
<p><cite>conditional</cite>: optional conditional expression that is evaluated as boolean (True/False) for use with the <cite>?bool_value</cite> modifier. Conditional expressions take the form ‘<cite>not operator value</cite>’ where <cite>not</cite> is an optional modifier that negates the <cite>operator</cite>. Note: the space before the conditional expression is required if you use a conditional expression. Valid comparison operators are:</p>
|
||
<ul class="simple">
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">contains</span></code>: template field contains value, similar to python’s <code class="docutils literal notranslate"><span class="pre">in</span></code></p></li>
|
||
<li><p><cite>matches</cite>: template field contains exactly value, unlike <cite>contains</cite>: does not match partial matches</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">startswith</span></code>: template field starts with value</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">endswith</span></code>: template field ends with value</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre"><=</span></code>: template field is less than or equal to value</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">>=</span></code>: template field is greater than or equal to value</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre"><</span></code>: template field is less than value</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">></span></code>: template field is greater than value</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">==</span></code>: template field equals value</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">!=</span></code>: template field does not equal value</p></li>
|
||
</ul>
|
||
<p>The <code class="docutils literal notranslate"><span class="pre">value</span></code> part of the conditional expression is treated as a bare (unquoted) word/phrase. Multiple values may be separated by ‘|’ (the pipe symbol). <code class="docutils literal notranslate"><span class="pre">value</span></code> is itself a template statement so you can use one or more template fields in <code class="docutils literal notranslate"><span class="pre">value</span></code> which will be resolved before the comparison occurs.</p>
|
||
<p>For example:</p>
|
||
<ul class="simple">
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">{keyword</span> <span class="pre">matches</span> <span class="pre">Beach}</span></code> resolves to True if ‘Beach’ is a keyword. It would not match keyword ‘BeachDay’.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">{keyword</span> <span class="pre">contains</span> <span class="pre">Beach}</span></code> resolves to True if any keyword contains the word ‘Beach’ so it would match both ‘Beach’ and ‘BeachDay’.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">{photo.score.overall</span> <span class="pre">></span> <span class="pre">0.7}</span></code> resolves to True if the photo’s overall aesthetic score is greater than 0.7.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">{keyword|lower</span> <span class="pre">contains</span> <span class="pre">beach}</span></code> uses the lower case filter to do case-insensitive matching to match any keyword that contains the word ‘beach’.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">{keyword|lower</span> <span class="pre">not</span> <span class="pre">contains</span> <span class="pre">beach}</span></code> uses the <code class="docutils literal notranslate"><span class="pre">not</span></code> modifier to negate the comparison so this resolves to True if there is no keyword that matches ‘beach’.</p></li>
|
||
</ul>
|
||
<p>Examples: to export photos that contain certain keywords with the <code class="docutils literal notranslate"><span class="pre">osxphotos</span> <span class="pre">export</span></code> command’s <code class="docutils literal notranslate"><span class="pre">--directory</span></code> option:</p>
|
||
<p><code class="docutils literal notranslate"><span class="pre">--directory</span> <span class="pre">"{keyword|lower</span> <span class="pre">matches</span> <span class="pre">travel|vacation?Travel-Photos,Not-Travel-Photos}"</span></code></p>
|
||
<p>This exports any photo that has keywords ‘travel’ or ‘vacation’ into a directory ‘Travel-Photos’ and all other photos into directory ‘Not-Travel-Photos’.</p>
|
||
<p>This can be used to rename files as well, for example:
|
||
<code class="docutils literal notranslate"><span class="pre">--filename</span> <span class="pre">"{favorite?Favorite-{original_name},{original_name}}"</span></code></p>
|
||
<p>This renames any photo that is a favorite as ‘Favorite-ImageName.jpg’ (where ‘ImageName.jpg’ is the original name of the photo) and all other photos with the unmodified original name.</p>
|
||
<p><code class="docutils literal notranslate"><span class="pre">?bool_value</span></code>: Template fields may be evaluated as boolean (True/False) by appending “?” after the field name (and following “(field_arg)” or “[find/replace]”. If a field is True (e.g. photo is HDR and field is <code class="docutils literal notranslate"><span class="pre">"{hdr}"</span></code>) or has any value, the value following the “?” will be used to render the template instead of the actual field value. If the template field evaluates to False (e.g. in above example, photo is not HDR) or has no value (e.g. photo has no title and field is <code class="docutils literal notranslate"><span class="pre">"{title}"</span></code>) then the default value following a “,” will be used.</p>
|
||
<p>e.g. if photo is an HDR image,</p>
|
||
<ul class="simple">
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">"{hdr?ISHDR,NOTHDR}"</span></code> renders to <code class="docutils literal notranslate"><span class="pre">"ISHDR"</span></code></p></li>
|
||
</ul>
|
||
<p>and if it is not an HDR image,</p>
|
||
<ul class="simple">
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">"{hdr?ISHDR,NOTHDR}"</span></code> renders to <code class="docutils literal notranslate"><span class="pre">"NOTHDR"</span></code></p></li>
|
||
</ul>
|
||
<p><code class="docutils literal notranslate"><span class="pre">,default</span></code>: optional default value to use if the template name has no value. This modifier is also used for the value if False for boolean-type fields (see above) as well as to hold a sub-template for values like <code class="docutils literal notranslate"><span class="pre">{created.strftime}</span></code>. If no default value provided, “_” is used.</p>
|
||
<p>e.g., if photo has no title set,</p>
|
||
<ul class="simple">
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">"{title}"</span></code> renders to “_”</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">"{title,I</span> <span class="pre">have</span> <span class="pre">no</span> <span class="pre">title}"</span></code> renders to <code class="docutils literal notranslate"><span class="pre">"I</span> <span class="pre">have</span> <span class="pre">no</span> <span class="pre">title"</span></code></p></li>
|
||
</ul>
|
||
<p>Template fields such as <code class="docutils literal notranslate"><span class="pre">created.strftime</span></code> use the default value to pass the template to use for <code class="docutils literal notranslate"><span class="pre">strftime</span></code>.</p>
|
||
<p>e.g., if photo date is 4 February 2020, 19:07:38,</p>
|
||
<ul class="simple">
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">"{created.strftime,%Y-%m-%d-%H%M%S}"</span></code> renders to <code class="docutils literal notranslate"><span class="pre">"2020-02-04-190738"</span></code></p></li>
|
||
</ul>
|
||
<p>Some template fields such as <code class="docutils literal notranslate"><span class="pre">"{media_type}"</span></code> use the default value to allow customization of the output. For example, <code class="docutils literal notranslate"><span class="pre">"{media_type}"</span></code> resolves to the special media type of the photo such as <code class="docutils literal notranslate"><span class="pre">panorama</span></code> or <code class="docutils literal notranslate"><span class="pre">selfie</span></code>. You may use the default value to override these in form: <code class="docutils literal notranslate"><span class="pre">"{media_type,video=vidéo;time_lapse=vidéo_accélérée}"</span></code>. In this example, if photo was a time_lapse photo, <code class="docutils literal notranslate"><span class="pre">media_type</span></code> would resolve to <code class="docutils literal notranslate"><span class="pre">vidéo_accélérée</span></code> instead of <code class="docutils literal notranslate"><span class="pre">time_lapse</span></code>.</p>
|
||
<p>Either or both bool_value or default (False value) may be empty which would result in empty string <code class="docutils literal notranslate"><span class="pre">""</span></code> when rendered.</p>
|
||
<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">"{created.year}/{openbrace}{title}{closebrace}"</span></code> would result in <code class="docutils literal notranslate"><span class="pre">"2020/{Photo</span> <span class="pre">Title}"</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> 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>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">
|
||
<h2>Template Substitutions<a class="headerlink" href="#id1" title="Permalink to this heading">#</a></h2>
|
||
<div class="table-wrapper docutils container">
|
||
<table class="docutils align-default">
|
||
<thead>
|
||
<tr class="row-odd"><th class="head"><p>Field</p></th>
|
||
<th class="head"><p>Description</p></th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr class="row-even"><td><p>{name}</p></td>
|
||
<td><p>Current filename of the photo</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>{original_name}</p></td>
|
||
<td><p>Photo’s original filename when imported to Photos</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>{title}</p></td>
|
||
<td><p>Title of the photo</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>{descr}</p></td>
|
||
<td><p>Description of the photo</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>{media_type}</p></td>
|
||
<td><p>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}’</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>{photo_or_video}</p></td>
|
||
<td><p>‘photo’ or ‘video’ depending on what type the image is. To customize, use default value as in ‘{photo_or_video,photo=fotos;video=videos}’</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>{hdr}</p></td>
|
||
<td><p>Photo is HDR?; True/False value, use in format ‘{hdr?VALUE_IF_TRUE,VALUE_IF_FALSE}’</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>{edited}</p></td>
|
||
<td><p>True if photo has been edited (has adjustments), otherwise False; use in format ‘{edited?VALUE_IF_TRUE,VALUE_IF_FALSE}’</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>{edited_version}</p></td>
|
||
<td><p>True if template is being rendered for the edited version of a photo, otherwise False.</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>{favorite}</p></td>
|
||
<td><p>Photo has been marked as favorite?; True/False value, use in format ‘{favorite?VALUE_IF_TRUE,VALUE_IF_FALSE}’</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>{created}</p></td>
|
||
<td><p>Photo’s creation date in ISO format, e.g. ‘2020-03-22’</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>{created.date}</p></td>
|
||
<td><p>Photo’s creation date in ISO format, e.g. ‘2020-03-22’</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>{created.year}</p></td>
|
||
<td><p>4-digit year of photo creation time</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>{created.yy}</p></td>
|
||
<td><p>2-digit year of photo creation time</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>{created.mm}</p></td>
|
||
<td><p>2-digit month of the photo creation time (zero padded)</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>{created.month}</p></td>
|
||
<td><p>Month name in user’s locale of the photo creation time</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>{created.mon}</p></td>
|
||
<td><p>Month abbreviation in the user’s locale of the photo creation time</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>{created.dd}</p></td>
|
||
<td><p>2-digit day of the month (zero padded) of photo creation time</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>{created.dow}</p></td>
|
||
<td><p>Day of week in user’s locale of the photo creation time</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>{created.doy}</p></td>
|
||
<td><p>3-digit day of year (e.g Julian day) of photo creation time, starting from 1 (zero padded)</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>{created.hour}</p></td>
|
||
<td><p>2-digit hour of the photo creation time</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>{created.min}</p></td>
|
||
<td><p>2-digit minute of the photo creation time</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>{created.sec}</p></td>
|
||
<td><p>2-digit second of the photo creation time</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>{created.strftime}</p></td>
|
||
<td><p>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 <a class="reference external" href="https://strftime.org/">https://strftime.org/</a> for help on strftime templates.</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>{modified}</p></td>
|
||
<td><p>Photo’s modification date in ISO format, e.g. ‘2020-03-22’; uses creation date if photo is not modified</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>{modified.date}</p></td>
|
||
<td><p>Photo’s modification date in ISO format, e.g. ‘2020-03-22’; uses creation date if photo is not modified</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>{modified.year}</p></td>
|
||
<td><p>4-digit year of photo modification time; uses creation date if photo is not modified</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>{modified.yy}</p></td>
|
||
<td><p>2-digit year of photo modification time; uses creation date if photo is not modified</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>{modified.mm}</p></td>
|
||
<td><p>2-digit month of the photo modification time (zero padded); uses creation date if photo is not modified</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>{modified.month}</p></td>
|
||
<td><p>Month name in user’s locale of the photo modification time; uses creation date if photo is not modified</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>{modified.mon}</p></td>
|
||
<td><p>Month abbreviation in the user’s locale of the photo modification time; uses creation date if photo is not modified</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>{modified.dd}</p></td>
|
||
<td><p>2-digit day of the month (zero padded) of the photo modification time; uses creation date if photo is not modified</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>{modified.dow}</p></td>
|
||
<td><p>Day of week in user’s locale of the photo modification time; uses creation date if photo is not modified</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>{modified.doy}</p></td>
|
||
<td><p>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</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>{modified.hour}</p></td>
|
||
<td><p>2-digit hour of the photo modification time; uses creation date if photo is not modified</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>{modified.min}</p></td>
|
||
<td><p>2-digit minute of the photo modification time; uses creation date if photo is not modified</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>{modified.sec}</p></td>
|
||
<td><p>2-digit second of the photo modification time; uses creation date if photo is not modified</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>{modified.strftime}</p></td>
|
||
<td><p>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 <a class="reference external" href="https://strftime.org/">https://strftime.org/</a> for help on strftime templates.</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>{today}</p></td>
|
||
<td><p>Current date in iso format, e.g. ‘2020-03-22’</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>{today.date}</p></td>
|
||
<td><p>Current date in iso format, e.g. ‘2020-03-22’</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>{today.year}</p></td>
|
||
<td><p>4-digit year of current date</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>{today.yy}</p></td>
|
||
<td><p>2-digit year of current date</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>{today.mm}</p></td>
|
||
<td><p>2-digit month of the current date (zero padded)</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>{today.month}</p></td>
|
||
<td><p>Month name in user’s locale of the current date</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>{today.mon}</p></td>
|
||
<td><p>Month abbreviation in the user’s locale of the current date</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>{today.dd}</p></td>
|
||
<td><p>2-digit day of the month (zero padded) of current date</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>{today.dow}</p></td>
|
||
<td><p>Day of week in user’s locale of the current date</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>{today.doy}</p></td>
|
||
<td><p>3-digit day of year (e.g Julian day) of current date, starting from 1 (zero padded)</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>{today.hour}</p></td>
|
||
<td><p>2-digit hour of the current date</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>{today.min}</p></td>
|
||
<td><p>2-digit minute of the current date</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>{today.sec}</p></td>
|
||
<td><p>2-digit second of the current date</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>{today.strftime}</p></td>
|
||
<td><p>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 <a class="reference external" href="https://strftime.org/">https://strftime.org/</a> for help on strftime templates.</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>{place.name}</p></td>
|
||
<td><p>Place name from the photo’s reverse geolocation data, as displayed in Photos</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>{place.country_code}</p></td>
|
||
<td><p>The ISO country code from the photo’s reverse geolocation data</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>{place.name.country}</p></td>
|
||
<td><p>Country name from the photo’s reverse geolocation data</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>{place.name.state_province}</p></td>
|
||
<td><p>State or province name from the photo’s reverse geolocation data</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>{place.name.city}</p></td>
|
||
<td><p>City or locality name from the photo’s reverse geolocation data</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>{place.name.area_of_interest}</p></td>
|
||
<td><p>Area of interest name (e.g. landmark or public place) from the photo’s reverse geolocation data</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>{place.address}</p></td>
|
||
<td><p>Postal address from the photo’s reverse geolocation data, e.g. ‘2007 18th St NW, Washington, DC 20009, United States’</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>{place.address.street}</p></td>
|
||
<td><p>Street part of the postal address, e.g. ‘2007 18th St NW’</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>{place.address.city}</p></td>
|
||
<td><p>City part of the postal address, e.g. ‘Washington’</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>{place.address.state_province}</p></td>
|
||
<td><p>State/province part of the postal address, e.g. ‘DC’</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>{place.address.postal_code}</p></td>
|
||
<td><p>Postal code part of the postal address, e.g. ‘20009’</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>{place.address.country}</p></td>
|
||
<td><p>Country name of the postal address, e.g. ‘United States’</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>{place.address.country_code}</p></td>
|
||
<td><p>ISO country code of the postal address, e.g. ‘US’</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>{searchinfo.season}</p></td>
|
||
<td><p>Season of the year associated with a photo, e.g. ‘Summer’; (Photos 5+ only, applied automatically by Photos’ image categorization algorithms).</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>{exif.camera_make}</p></td>
|
||
<td><p>Camera make from original photo’s EXIF information as imported by Photos, e.g. ‘Apple’</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>{exif.camera_model}</p></td>
|
||
<td><p>Camera model from original photo’s EXIF information as imported by Photos, e.g. ‘iPhone 6s’</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>{exif.lens_model}</p></td>
|
||
<td><p>Lens model from original photo’s EXIF information as imported by Photos, e.g. ‘iPhone 6s back camera 4.15mm f/2.2’</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>{moment}</p></td>
|
||
<td><p>The moment title of the photo</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>{uuid}</p></td>
|
||
<td><p>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’</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>{shortuuid}</p></td>
|
||
<td><p>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’</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>{id}</p></td>
|
||
<td><p>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.</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>{counter}</p></td>
|
||
<td><p>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}.</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>{album_seq}</p></td>
|
||
<td><p>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<em>seq}</em>{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}’.</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>{folder_album_seq}</p></td>
|
||
<td><p>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<em>seq}</em>{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}’.</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>{comma}</p></td>
|
||
<td><p>A comma: ‘,’</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>{semicolon}</p></td>
|
||
<td><p>A semicolon: ‘;’</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>{questionmark}</p></td>
|
||
<td><p>A question mark: ‘?’</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>{pipe}</p></td>
|
||
<td><p>A vertical pipe: ‘|’</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>{openbrace}</p></td>
|
||
<td><p>An open brace: ‘{’</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>{closebrace}</p></td>
|
||
<td><p>A close brace: ‘}’</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>{openparens}</p></td>
|
||
<td><p>An open parentheses: ‘(’</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>{closeparens}</p></td>
|
||
<td><p>A close parentheses: ‘)’</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>{openbracket}</p></td>
|
||
<td><p>An open bracket: ‘[’</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>{closebracket}</p></td>
|
||
<td><p>A close bracket: ‘]’</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>{newline}</p></td>
|
||
<td><p>A newline: ‘n’</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>{lf}</p></td>
|
||
<td><p>A line feed: ‘n’, alias for {newline}</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>{cr}</p></td>
|
||
<td><p>A carriage return: ‘r’</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>{crlf}</p></td>
|
||
<td><p>A carriage return + line feed: ‘rn’</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>{tab}</p></td>
|
||
<td><dl class="field-list simple">
|
||
<dt class="field-odd">A tab<span class="colon">:</span></dt>
|
||
<dd class="field-odd"><p>‘t’</p>
|
||
</dd>
|
||
</dl>
|
||
</td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>{osxphotos_version}</p></td>
|
||
<td><p>The osxphotos version, e.g. ‘0.62.1’</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>{osxphotos_cmd_line}</p></td>
|
||
<td><p>The full command line used to run osxphotos</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>{album}</p></td>
|
||
<td><p>Album(s) photo is contained in</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>{folder_album}</p></td>
|
||
<td><p>Folder path + album photo is contained in. e.g. ‘Folder/Subfolder/Album’ or just ‘Album’ if no enclosing folder</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>{project}</p></td>
|
||
<td><p>Project(s) photo is contained in (such as greeting cards, calendars, slideshows)</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>{album_project}</p></td>
|
||
<td><p>Album(s) and project(s) photo is contained in; treats projects as regular albums</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>{folder_album_project}</p></td>
|
||
<td><p>Folder path + album (includes projects as albums) photo is contained in. e.g. ‘Folder/Subfolder/Album’ or just ‘Album’ if no enclosing folder</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>{keyword}</p></td>
|
||
<td><p>Keyword(s) assigned to photo</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>{person}</p></td>
|
||
<td><p>Person(s) / face(s) in a photo</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>{label}</p></td>
|
||
<td><p>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.</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>{label_normalized}</p></td>
|
||
<td><p>All lower case version of ‘label’ (Photos 5+ only)</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>{comment}</p></td>
|
||
<td><p>Comment(s) on shared Photos; format is ‘Person name: comment text’ (Photos 5+ only)</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>{exiftool}</p></td>
|
||
<td><p>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 <code class="docutils literal notranslate"><span class="pre">exiftool</span> <span class="pre">-G</span></code>. exiftool must be installed in the path to use this template.</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>{searchinfo.holiday}</p></td>
|
||
<td><p>Holiday names associated with a photo, e.g. ‘Christmas Day’; (Photos 5+ only, applied automatically by Photos’ image categorization algorithms).</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>{searchinfo.activity}</p></td>
|
||
<td><p>Activities associated with a photo, e.g. ‘Sporting Event’; (Photos 5+ only, applied automatically by Photos’ image categorization algorithms).</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>{searchinfo.venue}</p></td>
|
||
<td><p>Venues associated with a photo, e.g. name of restaurant; (Photos 5+ only, applied automatically by Photos’ image categorization algorithms).</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>{searchinfo.venue_type}</p></td>
|
||
<td><p>Venue types associated with a photo, e.g. ‘Restaurant’; (Photos 5+ only, applied automatically by Photos’ image categorization algorithms).</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>{photo}</p></td>
|
||
<td><p>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 <a class="reference external" href="https://rhettbull.github.io/osxphotos/">https://rhettbull.github.io/osxphotos/</a> for additional documentation on the PhotoInfo class.</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>{detected_text}</p></td>
|
||
<td><p>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.</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>{shell_quote}</p></td>
|
||
<td><p>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.</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>{strip}</p></td>
|
||
<td><p>Use in form ‘{strip,TEMPLATE}’; strips whitespace from begining and end of rendered TEMPLATE value(s).</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>{format}</p></td>
|
||
<td><p>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’).</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>{function}</p></td>
|
||
<td><p>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.</p></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
</section>
|
||
</section>
|
||
|
||
</article>
|
||
</div>
|
||
<footer>
|
||
|
||
<div class="related-pages">
|
||
<a class="next-page" href="package_overview.html">
|
||
<div class="page-info">
|
||
<div class="context">
|
||
<span>Next</span>
|
||
</div>
|
||
<div class="title">OSXPhotos Python Package Overview</div>
|
||
</div>
|
||
<svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg>
|
||
</a>
|
||
<a class="prev-page" href="cli.html">
|
||
<svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg>
|
||
<div class="page-info">
|
||
<div class="context">
|
||
<span>Previous</span>
|
||
</div>
|
||
|
||
<div class="title">OSXPhotos Command Line Interface (CLI)</div>
|
||
|
||
</div>
|
||
</a>
|
||
</div>
|
||
<div class="bottom-of-page">
|
||
<div class="left-details">
|
||
<div class="copyright">
|
||
Copyright © 2021, Rhet Turnbull
|
||
</div>
|
||
Made with <a href="https://www.sphinx-doc.org/">Sphinx</a> and <a class="muted-link" href="https://pradyunsg.me">@pradyunsg</a>'s
|
||
|
||
<a href="https://github.com/pradyunsg/furo">Furo</a>
|
||
|
||
</div>
|
||
<div class="right-details">
|
||
<div class="icons">
|
||
|
||
</div>
|
||
</div>
|
||
</div>
|
||
|
||
</footer>
|
||
</div>
|
||
<aside class="toc-drawer">
|
||
|
||
|
||
<div class="toc-sticky toc-scroll">
|
||
<div class="toc-title-container">
|
||
<span class="toc-title">
|
||
On this page
|
||
</span>
|
||
</div>
|
||
<div class="toc-tree-container">
|
||
<div class="toc-tree">
|
||
<ul>
|
||
<li><a class="reference internal" href="#">OSXPhotos Template System</a><ul>
|
||
<li><a class="reference internal" href="#id1">Template Substitutions</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
|
||
</div>
|
||
</div>
|
||
</div>
|
||
|
||
|
||
</aside>
|
||
</div>
|
||
</div><script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>
|
||
<script src="_static/jquery.js"></script>
|
||
<script src="_static/underscore.js"></script>
|
||
<script src="_static/_sphinx_javascript_frameworks_compat.js"></script>
|
||
<script src="_static/doctools.js"></script>
|
||
<script src="_static/sphinx_highlight.js"></script>
|
||
<script src="_static/scripts/furo.js"></script>
|
||
<script src="_static/clipboard.min.js"></script>
|
||
<script src="_static/copybutton.js"></script>
|
||
</body>
|
||
</html> |