diff --git a/README.md b/README.md
index 34fc25b7c..d17d2eb54 100644
--- a/README.md
+++ b/README.md
@@ -61,7 +61,7 @@ Limited support is also provided for exporting photos and metadata from iPhoto l
This package will read Photos databases for any supported version on any supported macOS version. E.g. you can read a database created with Photos 5.0 on MacOS 10.15 on a machine running macOS 10.12 and vice versa.
-Requires python >= `3.9`, <= `3.12`. Reading iPhoto libraries requires python >= `3.10`.
+Requires python >= `3.10`, <= `3.13`.
For macOS 15.0 / Sequoia developer preview, alpha support is provided (very preliminary, not guaranteed to work). Not all features of osxphotos have been tested and some features may not work. If you encounter issues, please open an issue on GitHub.
@@ -357,7 +357,7 @@ If your photos are organized in folders and albums in Photos you can preserve th
`osxphotos export /path/to/export --directory "{folder_album}"`
-Photos can belong to more than one album. In this case, the template field `{folder_album}` will expand to all the album names that the photo belongs to. For example, if a photo belongs to the albums `Vacation` and `Travel`, the template field `{folder_album}` would expand to `Vacation`, `Travel`. If the photo belongs to no albums, the template field `{folder_album}` would expand to "_" (the default value).
+Photos can belong to more than one album. In this case, the template field `{folder_album}` will expand to all the album names that the photo belongs to. For example, if a photo belongs to the albums `Vacation` and `Travel`, the template field `{folder_album}` would expand to `Vacation`, `Travel`. If the photo belongs to no albums, the template field `{folder_album}` would expand to "_" (the default value).
All template fields including `{folder_album}` can be further filtered using a number of different filters. To convert all directory names to lower case for example, use the `lower` filter:
@@ -378,8 +378,8 @@ By default, osxphotos will use the original filename of the photo when exporting
The above command will export photos using the title. Note that you don't need to specify the extension as part of the `--filename` template as osxphotos will automatically add the correct file extension. Some photos might not have a title so in this case, you could use the default value feature to specify a different name for these photos. For example, to use the title as the filename, but if no title is specified, use the original filename instead:
osxphotos export /path/to/export --filename "{title,{original_name}}"
- │ ││ │
- │ ││ │
+ │ ││ │
+ │ ││ │
Use photo's title as the filename <──────┘ ││ │
││ │
Value after comma will be used <───────┘│ │
@@ -393,8 +393,8 @@ The above command will export photos using the title. Note that you don't need
The osxphotos template system also allows for limited conditional logic of the type "If a condition is true then do one thing, otherwise, do a different thing". For example, you can use the `--filename` option to name files that are marked as "Favorites" in Photos differently than other files. For example, to add a "#" to the name of every photo that's a favorite:
osxphotos export /path/to/export --filename "{original_name}{favorite?#,}"
- │ │ │││
- │ │ │││
+ │ │ │││
+ │ │ │││
Use photo's original name as filename <──┘ │ │││
│ │││
'favorite' is True if photo is a Favorite, <───────┘ │││
@@ -450,7 +450,7 @@ All the above commands operate on the default Photos library. Most users only u
#### Missing photos
-osxphotos works by copying photos out of the Photos library folder to export them. You may see osxphotos report that one or more photos are missing and thus could not be exported. One possible reason for this is that you are using iCloud to synch your Photos library and Photos either hasn't yet synched the cloud library to the local Mac or you have Photos configured to "Optimize Mac Storage" in Photos Preferences. Another reason is that even if you have Photos configured to download originals to the Mac, Photos does not always download photos from shared albums or original screenshots to the Mac.
+osxphotos works by copying photos out of the Photos library folder to export them. You may see osxphotos report that one or more photos are missing and thus could not be exported. One possible reason for this is that you are using iCloud to synch your Photos library and Photos either hasn't yet synched the cloud library to the local Mac or you have Photos configured to "Optimize Mac Storage" in Photos Preferences. Another reason is that even if you have Photos configured to download originals to the Mac, Photos does not always download photos from shared albums or original screenshots to the Mac.
If you encounter missing photos you can tell osxphotos to download the missing photos from iCloud using the `--download-missing` option. `--download-missing` uses AppleScript to communicate with Photos and tell it to download the missing photos. Photos' AppleScript interface is somewhat buggy and you may find that Photos crashes. In this case, osxphotos will attempt to restart Photos to resume the download process. There's also an experimental `--use-photokit` option that will communicate with Photos using a different "PhotoKit" interface. This option must be used together with `--download-missing`:
@@ -480,12 +480,12 @@ This will write basic metadata such as keywords, persons, and GPS location to th
osxphotos export /path/to/export --exiftool --keyword-template "{folder_album(>)}"
│ │
- │ │
- folder_album results in the folder(s) <──┘ │
- and album a photo is contained in │
- │
- The value in () is used as the path separator <───────┘
- for joining the folders and albums. For example,
+ │ │
+ folder_album results in the folder(s) <──┘ │
+ and album a photo is contained in │
+ │
+ The value in () is used as the path separator <───────┘
+ for joining the folders and albums. For example,
if photo is in Folder1/Folder2/Album, (>) produces
"Folder1>Folder2>Album" which some programs, such as
Lightroom Classic, treat as hierarchical keywords
@@ -514,7 +514,7 @@ Another way to export metadata about your photos is through the use of sidecar f
`osxphotos export /path/to/export --sidecar XMP`
-Unlike `--exiftool`, you do not need to install exiftool to use the `--sidecar` feature. Many of the same configuration options that apply to `--exiftool` to modify metadata, for example, `--keyword-template` can also be used with `--sidecar`.
+Unlike `--exiftool`, you do not need to install exiftool to use the `--sidecar` feature. Many of the same configuration options that apply to `--exiftool` to modify metadata, for example, `--keyword-template` can also be used with `--sidecar`.
Sidecar files are named "photoname.ext.sidecar_ext". For example, if the photo is named `IMG_1234.JPG` and the sidecar format is XMP, the sidecar would be named `IMG_1234.JPG.XMP`. Some applications expect the sidecar in this case to be named `IMG_1234.XMP`. You can use the `--sidecar-drop-ext` option to force osxphotos to name the sidecar files in this manner:
@@ -621,21 +621,21 @@ In the template string above, `{newline}` instructs osxphotos to insert a new li
Explanation of the template string:
{title,}{title?{descr?{newline},},}{descr,}
- │ │ │ │ │ │ │
- │ │ │ │ │ │ │
- └──> insert title (or nothing if no title)
+ │ │ │ │ │ │ │
+ │ │ │ │ │ │ │
+ └──> insert title (or nothing if no title)
│ │ │ │ │ │
└───> is there a title?
│ │ │ │ │
- └───> if so, is there a description?
+ └───> if so, is there a description?
│ │ │ │
- └───> if so, insert new line
+ └───> if so, insert new line
│ │ │
└───> if descr is blank, insert nothing
- │ │
+ │ │
└───> if title is blank, insert nothing
│
- └───> finally, insert description
+ └───> finally, insert description
(or nothing if no description)
In this example, `title?` demonstrates use of the boolean (True/False) feature of the template system. `title?` is read as "Is the title True (or not blank/empty)? If so, then the value immediately following the `?` is used in place of `title`. If `title` is blank, then the value immediately following the comma is used instead. The format for boolean fields is `field?value if true,value if false`. Either `value if true` or `value if false` may be blank, in which case a blank string ("") is used for the value and both may also be an entirely new template string as seen in the above example. Using this format, template strings may be nested inside each other to form complex `if-then-else` statements.
@@ -660,13 +660,13 @@ The configuration file is a plain text file in [TOML](https://toml.io/en/) forma
#### Run commands on exported photos for post-processing
-You can use the `--post-command` option to run one or more commands against exported files. The `--post-command` option takes two arguments: CATEGORY and COMMAND. CATEGORY is a string that describes which category of file to run the command against. The available categories are described in the help text available via: `osxphotos help export`. For example, the `exported` category includes all exported photos and the `skipped` category includes all photos that were skipped when running export with `--update`. COMMAND is an osxphotos template string which will be rendered then passed to the shell for execution.
+You can use the `--post-command` option to run one or more commands against exported files. The `--post-command` option takes two arguments: CATEGORY and COMMAND. CATEGORY is a string that describes which category of file to run the command against. The available categories are described in the help text available via: `osxphotos help export`. For example, the `exported` category includes all exported photos and the `skipped` category includes all photos that were skipped when running export with `--update`. COMMAND is an osxphotos template string which will be rendered then passed to the shell for execution.
For example, the following command generates a log of all exported files and their associated keywords:
`osxphotos export /path/to/export --post-command exported "echo {shell_quote,{filepath}{comma}{,+keyword,}} >> {shell_quote,{export_dir}/exported.txt}"`
-The special template field `{shell_quote}` ensures a string is properly quoted for execution in the shell. For example, it's possible that a file path or keyword in this example has a space in the value and if not properly quoted, this would cause an error in the execution of the command. When running commands, the template `{filepath}` is set to the full path of the exported file and `{export_dir}` is set to the full path of the base export directory.
+The special template field `{shell_quote}` ensures a string is properly quoted for execution in the shell. For example, it's possible that a file path or keyword in this example has a space in the value and if not properly quoted, this would cause an error in the execution of the command. When running commands, the template `{filepath}` is set to the full path of the exported file and `{export_dir}` is set to the full path of the base export directory.
Explanation of the template string:
@@ -677,7 +677,7 @@ Explanation of the template string:
│ │ │ │
└───> filepath of the exported file
│ │ │
- └───> insert a comma
+ └───> insert a comma
│ │
└───> join the list of keywords together with a ","
│
@@ -1659,7 +1659,7 @@ Options:
depending on system dark mode setting.
-h, --help Show this message and exit.
- Export
+ Export
When exporting photos, osxphotos creates a database in the top-level export
folder called '.osxphotos_export.db'. This database preserves state
@@ -1691,7 +1691,7 @@ option to re-export the entire library thus rebuilding the
'.osxphotos_export.db' database.
- Extended Attributes
+ Extended Attributes
Some options (currently '--finder-tag-template', '--finder-tag-keywords',
'-xattr-template') write additional metadata accessible by Spotlight
@@ -1759,300 +1759,300 @@ For additional information on extended attributes see: https://developer.apple
_keys
- Templating System
+ Templating System
-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.
+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.
-In its simplest form, a template statement has the form: "{template_field}",
-for example "{title}" which would resolve to the title of the photo.
+In its simplest form, a template statement has the form: "{template_field}",
+for example "{title}" which would resolve to the title of the photo.
-Template statements may contain one or more modifiers. The full syntax is:
+Template statements may contain one or more modifiers. The full syntax is:
-"pretext{delim+template_field:subfield(field_arg)|filter[find,replace]
-conditional&combine_value?bool_value,default}posttext"
+"pretext{delim+template_field:subfield(field_arg)|filter[find,replace]
+conditional&combine_value?bool_value,default}posttext"
-Template statements are white-space sensitive meaning that white space
-(spaces, tabs) changes the meaning of the template statement.
+Template statements are white-space sensitive meaning that white space
+(spaces, tabs) changes the meaning of the template statement.
-pretext and posttext are free form text. For example, if a photo has title
-"My Photo Title" the template statement "The title of the photo is {title}",
-resolves to "The title of the photo is My Photo Title". The pretext in this
-example is "The title if the photo is " and the template_field is {title}.
+pretext and posttext are free form text. For example, if a photo has title
+"My Photo Title" the template statement "The title of the photo is {title}",
+resolves to "The title of the photo is My Photo Title". The pretext in this
+example is "The title if the photo is " and the template_field is {title}.
-delim: optional delimiter string to use when expanding multi-valued template
-values in-place
+delim: optional delimiter string to use when expanding multi-valued template
+values in-place
-+: If present before template name, expands the template in place. If delim
-not provided, values are joined with no delimiter.
++: If present before template name, expands the template in place. If delim
+not provided, values are joined with no delimiter.
-e.g. if Photo keywords are ["foo","bar"]:
+e.g. if Photo keywords are ["foo","bar"]:
- • "{keyword}" renders to "foo", "bar"
- • "{,+keyword}" renders to: "foo,bar"
- • "{; +keyword}" renders to: "foo; bar"
- • "{+keyword}" renders to "foobar"
+ • "{keyword}" renders to "foo", "bar"
+ • "{,+keyword}" renders to: "foo,bar"
+ • "{; +keyword}" renders to: "foo; bar"
+ • "{+keyword}" renders to "foobar"
template_field: The template field to resolve. See Template Substitutions for
-full list of template fields.
+full list of template fields.
-:subfield: Some templates have sub-fields, For example, {exiftool:IPTC:Make};
-the template_field is exiftool and the sub-field is IPTC:Make.
+:subfield: Some templates have sub-fields, For example, {exiftool:IPTC:Make};
+the template_field is exiftool and the sub-field is IPTC:Make.
-(field_arg): optional arguments to pass to the field; for example, with
-{folder_album} this is used to pass the path separator used for joining
-folders and albums when rendering the field (default is "/" for
-{folder_album}).
+(field_arg): optional arguments to pass to the field; for example, with
+{folder_album} this is used to pass the path separator used for joining
+folders and albums when rendering the field (default is "/" for
+{folder_album}).
-|filter: 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: {keyword|capitalize|parens}.
+|filter: 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: {keyword|capitalize|parens}.
-Valid filters are:
+Valid filters are:
- • lower: Convert value to lower case, e.g. 'Value' => 'value'.
- • upper: Convert value to upper case, e.g. 'Value' => 'VALUE'.
- • strip: Strip whitespace from beginning/end of value, e.g. ' Value ' =>
- 'Value'.
- • titlecase: Convert value to title case, e.g. 'my value' => 'My Value'.
+ • lower: Convert value to lower case, e.g. 'Value' => 'value'.
+ • upper: Convert value to upper case, e.g. 'Value' => 'VALUE'.
+ • strip: Strip whitespace from beginning/end of value, e.g. ' Value ' =>
+ 'Value'.
+ • titlecase: Convert value to title case, e.g. 'my value' => 'My Value'.
• capitalize: Capitalize first word of value and convert other words to lower
- case, e.g. 'MY VALUE' => 'My value'.
- • braces: Enclose value in curly braces, e.g. 'value => '{value}'.
- • parens: Enclose value in parentheses, e.g. 'value' => '(value')
- • brackets: Enclose value in brackets, e.g. 'value' => '[value]'
- • shell_quote: Quotes the value for safe usage in the shell, e.g. My
- file.jpeg => 'My file.jpeg'; only adds quotes if needed.
- • function: Run custom python function to filter value; use in format
- 'function:/path/to/file.py::function_name'. See example at
+ case, e.g. 'MY VALUE' => 'My value'.
+ • braces: Enclose value in curly braces, e.g. 'value => '{value}'.
+ • parens: Enclose value in parentheses, e.g. 'value' => '(value')
+ • brackets: Enclose value in brackets, e.g. 'value' => '[value]'
+ • shell_quote: Quotes the value for safe usage in the shell, e.g. My
+ file.jpeg => 'My file.jpeg'; only adds quotes if needed.
+ • function: 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
- • split(x): Split value into a list of values using x as delimiter, e.g.
- 'value1;value2' => ['value1', 'value2'] if used with split(;).
- • autosplit: Automatically split delimited string into separate values; will
+ .py
+ • split(x): Split value into a list of values using x as delimiter, e.g.
+ 'value1;value2' => ['value1', 'value2'] if used with split(;).
+ • autosplit: Automatically split delimited string into separate values; will
split strings delimited by comma, semicolon, or space, e.g. 'value1,value2'
- => ['value1', 'value2'].
+ => ['value1', 'value2'].
• chop(x): 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'].
- • chomp(x): Remove x characters from the beginning of value, e.g. chomp(1):
+ chop(1): ['travel', 'beach']=> ['trave', 'beac'].
+ • chomp(x): 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'].
- • sort: Sort list of values, e.g. ['c', 'b', 'a'] => ['a', 'b', 'c'].
- • rsort: Sort list of values in reverse order, e.g. ['a', 'b', 'c'] => ['c',
- 'b', 'a'].
- • reverse: Reverse order of values, e.g. ['a', 'b', 'c'] => ['c', 'b', 'a'].
+ list value, e.g. chomp(1): ['travel', 'beach']=> ['ravel', 'each'].
+ • sort: Sort list of values, e.g. ['c', 'b', 'a'] => ['a', 'b', 'c'].
+ • rsort: Sort list of values in reverse order, e.g. ['a', 'b', 'c'] => ['c',
+ 'b', 'a'].
+ • reverse: Reverse order of values, e.g. ['a', 'b', 'c'] => ['c', 'b', 'a'].
• uniq: Remove duplicate values, e.g. ['a', 'b', 'c', 'b', 'a'] => ['a', 'b',
- 'c'].
- • 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'].
+ 'c'].
+ • 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
+ ['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().
+ ['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().
- • filter(x): Filter list of values using predicate x; for example,
- {folder_album|filter(contains Events)} returns only folders/albums
- containing the word 'Events' in their path.
- • int: 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.
- • float: 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.
-
-e.g. if Photo keywords are ["FOO","bar"]:
-
- • "{keyword|lower}" renders to "foo", "bar"
- • "{keyword|upper}" renders to: "FOO", "BAR"
- • "{keyword|capitalize}" renders to: "Foo", "Bar"
- • "{keyword|lower|parens}" renders to: "(foo)", "(bar)"
-
-e.g. if Photo description is "my description":
-
- • "{descr|titlecase}" renders to: "My Description"
-
-e.g. If Photo is in Album1 in Folder1:
-
- • "{folder_album}" renders to ["Folder1/Album1"]
- • "{folder_album(>)}" renders to ["Folder1>Album1"]
- • "{folder_album()}" renders to ["Folder1Album1"]
-
-[find,replace]: optional text replacement to perform on rendered template
-value. For example, to replace "/" in an album name, you could use the
-template "{album[/,-]}". Multiple replacements can be made by appending "|"
-and adding another find|replace pair. e.g. to replace both "/" and ":" in
-album name: "{album[/,-|:,-]}". find/replace pairs are not limited to single
-characters. The "|" character cannot be used in a find/replace pair.
-
-conditional: optional conditional expression that is evaluated as boolean
-(True/False) for use with the ?bool_value modifier. Conditional expressions
-take the form 'not operator value' where not is an optional modifier that
-negates the operator. Note: the space before the conditional expression is
+ semantics as Python's string slicing, e.g. sslice(1:3):'abcd => 'bc';
+ sslice(1:4:2): 'abcd' => 'bd', etc. See also slice().
+ • filter(x): Filter list of values using predicate x; for example,
+ {folder_album|filter(contains Events)} returns only folders/albums
+ containing the word 'Events' in their path.
+ • int: 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.
+ • float: 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.
+
+e.g. if Photo keywords are ["FOO","bar"]:
+
+ • "{keyword|lower}" renders to "foo", "bar"
+ • "{keyword|upper}" renders to: "FOO", "BAR"
+ • "{keyword|capitalize}" renders to: "Foo", "Bar"
+ • "{keyword|lower|parens}" renders to: "(foo)", "(bar)"
+
+e.g. if Photo description is "my description":
+
+ • "{descr|titlecase}" renders to: "My Description"
+
+e.g. If Photo is in Album1 in Folder1:
+
+ • "{folder_album}" renders to ["Folder1/Album1"]
+ • "{folder_album(>)}" renders to ["Folder1>Album1"]
+ • "{folder_album()}" renders to ["Folder1Album1"]
+
+[find,replace]: optional text replacement to perform on rendered template
+value. For example, to replace "/" in an album name, you could use the
+template "{album[/,-]}". Multiple replacements can be made by appending "|"
+and adding another find|replace pair. e.g. to replace both "/" and ":" in
+album name: "{album[/,-|:,-]}". find/replace pairs are not limited to single
+characters. The "|" character cannot be used in a find/replace pair.
+
+conditional: optional conditional expression that is evaluated as boolean
+(True/False) for use with the ?bool_value modifier. Conditional expressions
+take the form 'not operator value' where not is an optional modifier that
+negates the operator. Note: the space before the conditional expression is
required if you use a conditional expression. Valid comparison operators are:
- • contains: template field contains value, similar to python's in
- • matches: template field contains exactly value, unlike contains: does not
- match partial matches
- • startswith: template field starts with value
- • endswith: template field ends with value
- • <=: template field is less than or equal to value
- • >=: template field is greater than or equal to value
- • <: template field is less than value
- • >: template field is greater than value
- • ==: template field equals value
- • !=: template field does not equal value
-
-The value part of the conditional expression is treated as a bare (unquoted)
-word/phrase. Multiple values may be separated by '|' (the pipe symbol).
-value is itself a template statement so you can use one or more template
-fields in value which will be resolved before the comparison occurs.
-
-For example:
-
- • {keyword matches Beach} resolves to True if 'Beach' is a keyword. It would
- not match keyword 'BeachDay'.
- • {keyword contains Beach} resolves to True if any keyword contains the word
- 'Beach' so it would match both 'Beach' and 'BeachDay'.
- • {photo.score.overall > 0.7} resolves to True if the photo's overall
- aesthetic score is greater than 0.7.
- • {keyword|lower contains beach} uses the lower case filter to do
- case-insensitive matching to match any keyword that contains the word
- 'beach'.
- • {keyword|lower not contains beach} uses the not modifier to negate the
- comparison so this resolves to True if there is no keyword that matches
- 'beach'.
-
-Examples: to export photos that contain certain keywords with the osxphotos
-export command's --directory option:
-
---directory "{keyword|lower matches
-travel|vacation?Travel-Photos,Not-Travel-Photos}"
-
-This exports any photo that has keywords 'travel' or 'vacation' into a
-directory 'Travel-Photos' and all other photos into directory
-'Not-Travel-Photos'.
-
-This can be used to rename files as well, for example: --filename
-"{favorite?Favorite-{original_name},{original_name}}"
-
-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.
-
-&combine_value: Template fields may be combined with another template
-statement to return multiple values. The combine_value is another template
-statement. For example, the template {created.year&{folder_album,}} would
-resolve to ["1999", "Vacation"] if the photo was created in 1999 and was in
-the album Vacation. Because the combine_value is a template statement,
-multiple templates may be combined together by nesting the combine operator:
-{template1&{template2&{template3,},},}. In this example, a null default value
-is used to prevent the default value from being combined if any of the nested
-templates does not resolve to a value
-
-?bool_value: Template fields may be evaluated as boolean (True/False) by
-appending "?" after the field name (and following "(field_arg)" or
+ • contains: template field contains value, similar to python's in
+ • matches: template field contains exactly value, unlike contains: does not
+ match partial matches
+ • startswith: template field starts with value
+ • endswith: template field ends with value
+ • <=: template field is less than or equal to value
+ • >=: template field is greater than or equal to value
+ • <: template field is less than value
+ • >: template field is greater than value
+ • ==: template field equals value
+ • !=: template field does not equal value
+
+The value part of the conditional expression is treated as a bare (unquoted)
+word/phrase. Multiple values may be separated by '|' (the pipe symbol).
+value is itself a template statement so you can use one or more template
+fields in value which will be resolved before the comparison occurs.
+
+For example:
+
+ • {keyword matches Beach} resolves to True if 'Beach' is a keyword. It would
+ not match keyword 'BeachDay'.
+ • {keyword contains Beach} resolves to True if any keyword contains the word
+ 'Beach' so it would match both 'Beach' and 'BeachDay'.
+ • {photo.score.overall > 0.7} resolves to True if the photo's overall
+ aesthetic score is greater than 0.7.
+ • {keyword|lower contains beach} uses the lower case filter to do
+ case-insensitive matching to match any keyword that contains the word
+ 'beach'.
+ • {keyword|lower not contains beach} uses the not modifier to negate the
+ comparison so this resolves to True if there is no keyword that matches
+ 'beach'.
+
+Examples: to export photos that contain certain keywords with the osxphotos
+export command's --directory option:
+
+--directory "{keyword|lower matches
+travel|vacation?Travel-Photos,Not-Travel-Photos}"
+
+This exports any photo that has keywords 'travel' or 'vacation' into a
+directory 'Travel-Photos' and all other photos into directory
+'Not-Travel-Photos'.
+
+This can be used to rename files as well, for example: --filename
+"{favorite?Favorite-{original_name},{original_name}}"
+
+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.
+
+&combine_value: Template fields may be combined with another template
+statement to return multiple values. The combine_value is another template
+statement. For example, the template {created.year&{folder_album,}} would
+resolve to ["1999", "Vacation"] if the photo was created in 1999 and was in
+the album Vacation. Because the combine_value is a template statement,
+multiple templates may be combined together by nesting the combine operator:
+{template1&{template2&{template3,},},}. In this example, a null default value
+is used to prevent the default value from being combined if any of the nested
+templates does not resolve to a value
+
+?bool_value: 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 "{hdr}")
-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
+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 "{title}") then the default value following a ","
-will be used.
+has no title and field is "{title}") then the default value following a ","
+will be used.
-e.g. if photo is an HDR image,
+e.g. if photo is an HDR image,
- • "{hdr?ISHDR,NOTHDR}" renders to "ISHDR"
+ • "{hdr?ISHDR,NOTHDR}" renders to "ISHDR"
-and if it is not an HDR image,
+and if it is not an HDR image,
- • "{hdr?ISHDR,NOTHDR}" renders to "NOTHDR"
+ • "{hdr?ISHDR,NOTHDR}" renders to "NOTHDR"
-,default: optional default value to use if the template name has no value.
+,default: 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 {created.strftime}.
-If no default value provided, "_" is used.
+above) as well as to hold a sub-template for values like {created.strftime}.
+If no default value provided, "_" is used.
-e.g., if photo has no title set,
+e.g., if photo has no title set,
- • "{title}" renders to "_"
- • "{title,I have no title}" renders to "I have no title"
+ • "{title}" renders to "_"
+ • "{title,I have no title}" renders to "I have no title"
-Template fields such as created.strftime use the default value to pass the
-template to use for strftime.
+Template fields such as created.strftime use the default value to pass the
+template to use for strftime.
-e.g., if photo date is 4 February 2020, 19:07:38,
+e.g., if photo date is 4 February 2020, 19:07:38,
- • "{created.strftime,%Y-%m-%d-%H%M%S}" renders to "2020-02-04-190738"
+ • "{created.strftime,%Y-%m-%d-%H%M%S}" renders to "2020-02-04-190738"
-Some template fields such as "{media_type}" use the default value to allow
-customization of the output. For example, "{media_type}" resolves to the
-special media type of the photo such as panorama or selfie. You may use the
-default value to override these in form:
-"{media_type,video=vidéo;time_lapse=vidéo_accélérée}". In this example, if
-photo was a time_lapse photo, media_type would resolve to vidéo_accélérée
-instead of time_lapse.
+Some template fields such as "{media_type}" use the default value to allow
+customization of the output. For example, "{media_type}" resolves to the
+special media type of the photo such as panorama or selfie. You may use the
+default value to override these in form:
+"{media_type,video=vidéo;time_lapse=vidéo_accélérée}". In this example, if
+photo was a time_lapse photo, media_type would resolve to vidéo_accélérée
+instead of time_lapse.
-Either or both bool_value or default (False value) may be empty which would
-result in empty string "" when rendered.
+Either or both bool_value or default (False value) may be empty which would
+result in empty string "" when rendered.
-If you want to include "{" or "}" in the output, use "{openbrace}" or
-"{closebrace}" template substitution.
+If you want to include "{" or "}" in the output, use "{openbrace}" or
+"{closebrace}" template substitution.
-e.g. "{created.year}/{openbrace}{title}{closebrace}" would result in
-"2020/{Photo Title}".
+e.g. "{created.year}/{openbrace}{title}{closebrace}" would result in
+"2020/{Photo Title}".
-Variables
+Variables
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).
-
-Another use case for variables is filtering combined template values. For
-example, using the &combine_value mechanism to combine two template values
-that might result in duplicate values, you could do the following:
+{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).
+
+Another use case for variables is filtering combined template values. For
+example, using the &combine_value mechanism to combine two template values
+that might result in duplicate values, you could do the following:
{var:myvar,{template1&{template2,},}}{%myvar|uniq} which allows the use of the
-uniq filter against the combined template values.
+uniq filter against the combined template values.
-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
+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}}.
+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:
+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:
-{title[:,%%]} replaces the : with % and {title contains
-Foo?{title}{percent},{title}} adds % to the title if it contains Foo.
+{title[:,%%]} replaces the : with % and {title contains
+Foo?{title}{percent},{title}} adds % to the title if it contains Foo.
With the --directory and --filename options you may specify a template for the
export directory or filename, respectively. The directory will be appended to
@@ -2074,7 +2074,7 @@ corresponding value from the table below. Invalid substitutions will result
in a an error and the script will abort.
- Template Substitutions
+ Template Substitutions
Substitution Description
{name} Current filename of the photo
@@ -2504,7 +2504,7 @@ Substitution Description
{filepath} The full path to the exported file
- Post Command
+ Post Command
You can run commands on the exported photos for post-processing using the '--
post-command' option. '--post-command' is passed a CATEGORY and a COMMAND.
@@ -2569,7 +2569,7 @@ first to ensure your commands are as expected. This will not actually run the
commands but will print out the exact command string which would be executed.
- Post Function
+ Post Function
You can run your own python functions on the exported photos for post-
processing using the '--post-function' option. '--post-function' is passed the
diff --git a/dev_requirements.txt b/dev_requirements.txt
index 7656bc1b2..80c0c08d2 100644
--- a/dev_requirements.txt
+++ b/dev_requirements.txt
@@ -6,11 +6,11 @@ furo
isort
m2r2==0.3.3.post2
pdbpp
-pyinstaller==5.13.2
+pyinstaller>=6.11.1
pytest-cov==4.0.0
pytest-mock
-pytest==7.4.0
-ruff==0.7.2
+pytest>=7.4.0,<8.0.0
+ruff==0.8.1
Sphinx
sphinx_click
sphinx_rtd_theme
diff --git a/docs/.buildinfo b/docs/.buildinfo
index fa00444ca..6d382f48a 100644
--- a/docs/.buildinfo
+++ b/docs/.buildinfo
@@ -1,4 +1,4 @@
# Sphinx build info version 1
-# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: a02785b8a9b27357a3304c5646993811
+# This file records the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: 453689a36d886f59523b5b58791e91e0
tags: 645f666f9bcd5a90fca523b33c5a78b7
diff --git a/docs/API_README.html b/docs/API_README.html
index eaa8a8146..aec215206 100644
--- a/docs/API_README.html
+++ b/docs/API_README.html
@@ -5,12 +5,12 @@
-
+
OSXPhotos Python API - osxphotos 0.68.6 documentation
-
+
-
+
@@ -69,7 +69,7 @@
Light mode
@@ -113,6 +154,8 @@
In addition to a command line interface, OSXPhotos provides a access to a Python API that allows you to easily access a Photos library, often with just a few lines of code.
Returns the original creation date of the photo as a timezone aware datetime.datetime object.
+If user changed the photo’s date in Photos, this will return the original date Photos assigned
+as the creation date at the time of import. The original date is stored by Photos at import time
+from the date in the photo’s EXIF data. If this is not set (photo had no EXIF date or photo was
+imported on an older version of macOS that did not store original date) then date_original
+returns the same value as date.
+
Photos 5+ only; on Photos < 5.0, this will return the same value as date.
Returns the date the photo was added to the Photos library as a timezone aware datetime.datetime object, or None if the data added cannot be determined
+
Returns the date the photo was added to the Photos library as a timezone aware datetime.datetime object in the local timezone, or None if the data added cannot be determined
Returns the date the photo was placed in the trash as a datetime.datetime object or None if photo is not in the trash
+
Returns the date the photo was placed in the trash as a timezone aware datetime.datetime object in the local timezone or None if photo is not in the trash