forked/osxphotos
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Updated docs build to use cog

Browse Source
This commit is contained in:
Rhet Turnbull 2022-04-23 08:16:47 -07:00
parent ee6e4602e4
commit b8b4c15784
60 changed files with 561 additions and 433 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

102
API_README.md
View File

@ -1719,6 +1719,8 @@ To get the path of every raw photo, whether it's a single raw photo or a raw+JPE
from osxphotos.phototemplate import get_template_help
cog.out(get_template_help())
]]]-->
<!-- Generated by cog: see phototemplate.cog.md -->
The templating system converts one or template statements, written in osxphotos metadata templating language, to one or more rendered values using information from the photo being processed.
In its simplest form, a template statement has the form: `"{template_field}"`, for example `"{title}"` which would resolve to the title of the photo.
@ -1737,10 +1739,10 @@ Template statements are white-space sensitive meaning that white space (spaces,
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](#template-substitutions) for full list of template fields.
@ -1750,62 +1752,60 @@ e.g. if Photo keywords are `["foo","bar"]`:
Valid filters are:
<!-- OSXPHOTOS-FILTER-TABLE:START - Do not remove or modify this section -->
* `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 <https://github.com/RhetTbull/osxphotos/blob/master/examples/template_filter.py>
<!-- OSXPHOTOS-FILTER-TABLE:END -->
- `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 https://github.com/RhetTbull/osxphotos/blob/master/examples/template_filter.py
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)"`
- `"{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"`
- `"{descr|titlecase}"` renders to: `"My Description"`
`(path_sep)`: optional path separator to use when joining path-like fields, for example `{folder_album}`. Default is "/".
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"]`
- `"{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
- `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'.
- `{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:
@ -1822,24 +1822,24 @@ This renames any photo that is a favorite as 'Favorite-ImageName.jpg' (where 'Im
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,
* `"{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. 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.
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`.
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`.
@ -1856,7 +1856,7 @@ The following template field substitutions are availabe for use the templating s
from osxphotos.phototemplate import get_template_field_table
cog.out(get_template_field_table())
]]]-->
| Substitution | Description |
| Field | Description |
|--------------|-------------|
|{name}|Current filename of the photo|
|{original_name}|Photo's original filename when imported to Photos|
@ -1880,7 +1880,7 @@ cog.out(get_template_field_table())
|{created.hour}|2-digit hour of the photo creation time|
|{created.min}|2-digit minute of the photo creation time|
|{created.sec}|2-digit second of the photo creation time|
|{created.strftime}|Apply strftime template to file creation date/time. Should be used in form {created.strftime,TEMPLATE} where TEMPLATE is a valid strftime template, e.g. {created.strftime,%Y-%U} would result in year-week number of year: '2020-23'. If used with no template will return null value. See <https://strftime.org/> for help on strftime templates.|
|{created.strftime}|Apply strftime template to file creation date/time. Should be used in form {created.strftime,TEMPLATE} where TEMPLATE is a valid strftime template, e.g. {created.strftime,%Y-%U} would result in year-week number of year: '2020-23'. If used with no template will return null value. See https://strftime.org/ for help on strftime templates.|
|{modified.date}|Photo's modification date in ISO format, e.g. '2020-03-22'; uses creation date if photo is not modified|
|{modified.year}|4-digit year of photo modification time; uses creation date if photo is not modified|
|{modified.yy}|2-digit year of photo modification time; uses creation date if photo is not modified|
@ -1893,7 +1893,7 @@ cog.out(get_template_field_table())
|{modified.hour}|2-digit hour of the photo modification time; uses creation date if photo is not modified|
|{modified.min}|2-digit minute of the photo modification time; uses creation date if photo is not modified|
|{modified.sec}|2-digit second of the photo modification time; uses creation date if photo is not modified|
|{modified.strftime}|Apply strftime template to file modification date/time. Should be used in form {modified.strftime,TEMPLATE} where TEMPLATE is a valid strftime template, e.g. {modified.strftime,%Y-%U} would result in year-week number of year: '2020-23'. If used with no template will return null value. Uses creation date if photo is not modified. See <https://strftime.org/> for help on strftime templates.|
|{modified.strftime}|Apply strftime template to file modification date/time. Should be used in form {modified.strftime,TEMPLATE} where TEMPLATE is a valid strftime template, e.g. {modified.strftime,%Y-%U} would result in year-week number of year: '2020-23'. If used with no template will return null value. Uses creation date if photo is not modified. See https://strftime.org/ for help on strftime templates.|
|{today.date}|Current date in iso format, e.g. '2020-03-22'|
|{today.year}|4-digit year of current date|
|{today.yy}|2-digit year of current date|
@ -1906,7 +1906,7 @@ cog.out(get_template_field_table())
|{today.hour}|2-digit hour of the current date|
|{today.min}|2-digit minute of the current date|
|{today.sec}|2-digit second of the current date|
|{today.strftime}|Apply strftime template to current date/time. Should be used in form {today.strftime,TEMPLATE} where TEMPLATE is a valid strftime template, e.g. {today.strftime,%Y-%U} would result in year-week number of year: '2020-23'. If used with no template will return null value. See <https://strftime.org/> for help on strftime templates.|
|{today.strftime}|Apply strftime template to current date/time. Should be used in form {today.strftime,TEMPLATE} where TEMPLATE is a valid strftime template, e.g. {today.strftime,%Y-%U} would result in year-week number of year: '2020-23'. If used with no template will return null value. See https://strftime.org/ for help on strftime templates.|
|{place.name}|Place name from the photo's reverse geolocation data, as displayed in Photos|
|{place.country_code}|The ISO country code from the photo's reverse geolocation data|
|{place.name.country}|Country name from the photo's reverse geolocation data|
@ -1954,14 +1954,16 @@ cog.out(get_template_field_table())
|{label}|Image categorization label associated with a photo (Photos 5+ only). Labels are added automatically by Photos using machine learning algorithms to categorize images. These are not the same as {keyword} which refers to the user-defined keywords/tags applied in Photos.|
|{label_normalized}|All lower case version of 'label' (Photos 5+ only)|
|{comment}|Comment(s) on shared Photos; format is 'Person name: comment text' (Photos 5+ only)|
|{exiftool}|Format: '{exiftool:GROUP:TAGNAME}'; use exiftool (<https://exiftool.org>) to extract metadata, in form GROUP:TAGNAME, from image. E.g. '{exiftool:EXIF:Make}' to get camera make, or {exiftool:IPTC:Keywords} to extract keywords. See <https://exiftool.org/TagNames/> for list of valid tag names. You must specify group (e.g. EXIF, IPTC, etc) as used in `exiftool -G`. exiftool must be installed in the path to use this template.|
|{exiftool}|Format: '{exiftool:GROUP:TAGNAME}'; use exiftool (https://exiftool.org) to extract metadata, in form GROUP:TAGNAME, from image. E.g. '{exiftool:EXIF:Make}' to get camera make, or {exiftool:IPTC:Keywords} to extract keywords. See https://exiftool.org/TagNames/ for list of valid tag names. You must specify group (e.g. EXIF, IPTC, etc) as used in `exiftool -G`. exiftool must be installed in the path to use this template.|
|{searchinfo.holiday}|Holiday names associated with a photo, e.g. 'Christmas Day'; (Photos 5+ only, applied automatically by Photos' image categorization algorithms).|
|{searchinfo.activity}|Activities associated with a photo, e.g. 'Sporting Event'; (Photos 5+ only, applied automatically by Photos' image categorization algorithms).|
|{searchinfo.venue}|Venues associated with a photo, e.g. name of restaurant; (Photos 5+ only, applied automatically by Photos' image categorization algorithms).|
|{searchinfo.venue_type}|Venue types associated with a photo, e.g. 'Restaurant'; (Photos 5+ only, applied automatically by Photos' image categorization algorithms).|
|{photo}|Provides direct access to the PhotoInfo object for the photo. Must be used in format '{photo.property}' where 'property' represents a PhotoInfo property. For example: '{photo.favorite}' is the same as '{favorite}' and '{photo.place.name}' is the same as '{place.name}'. '{photo}' provides access to properties that are not available as separate template fields but it assumes some knowledge of the underlying PhotoInfo class. See <https://rhettbull.github.io/osxphotos/> for additional documentation on the PhotoInfo class.|
|{photo}|Provides direct access to the PhotoInfo object for the photo. Must be used in format '{photo.property}' where 'property' represents a PhotoInfo property. For example: '{photo.favorite}' is the same as '{favorite}' and '{photo.place.name}' is the same as '{place.name}'. '{photo}' provides access to properties that are not available as separate template fields but it assumes some knowledge of the underlying PhotoInfo class. See https://rhettbull.github.io/osxphotos/ for additional documentation on the PhotoInfo class.|
|{detected_text}|List of text strings found in the image after performing text detection. Using '{detected_text}' will cause osxphotos to perform text detection on your photos using the built-in macOS text detection algorithms which will slow down your export. The results for each photo will be cached in the export database so that future exports with '--update' do not need to reprocess each photo. You may pass a confidence threshold value between 0.0 and 1.0 after a colon as in '{detected_text:0.5}'; The default confidence threshold is 0.75. '{detected_text}' works only on macOS Catalina (10.15) or later. Note: this feature is not the same thing as Live Text in macOS Monterey, which osxphotos does not yet support.|
|{shell_quote}|Use in form '{shell_quote,TEMPLATE}'; quotes the rendered TEMPLATE value(s) for safe usage in the shell, e.g. My file.jpeg => 'My file.jpeg'; only adds quotes if needed.|
|{strip}|Use in form '{strip,TEMPLATE}'; strips whitespace from begining and end of rendered TEMPLATE value(s).|
|{function}|Execute a python function from an external file and use return value as template substitution. Use in format: {function:file.py::function_name} where 'file.py' is the name of the python file and 'function_name' is the name of the function to call. The function will be passed the PhotoInfo object for the photo. See https://github.com/RhetTbull/osxphotos/blob/master/examples/template_function.py for an example of how to implement a template function.|
<!--[[[end]]] -->
### <a name="exiftoolExifTool">ExifTool</a>

24
README.md
View File

@ -304,7 +304,7 @@ The osxphotos template system also allows for limited conditional logic of the t
Value immediately following comma will be used if <──────┘
template field is False or blank (null); in this case
no value is specified so a blank string "" will be used
Like with `--directory`, using a multi-valued template field such as `{keyword}` may result in more than one copy of a photo being exported. For example, if `IMG_1234.JPG` has keywords `Travel`, and `Vacation` and you run the following command:
`osxphotos export /path/to/export --filename "{keyword}-{original_name}"`
@ -385,7 +385,7 @@ This will write basic metadata such as keywords, persons, and GPS location to th
if photo is in Folder1/Folder2/Album, (>) produces
"Folder1>Folder2>Album" which some programs, such as
Lightroom Classic, treat as hierarchal keywords
The above command will write all the regular metadata that `--exiftool` normally writes to the file upon export but will also add an additional keyword in the exported metadata in the form "Folder1>Folder2>Album". If you did not include the `(>)` in the template string (e.g. `{folder_album}`), folder_album would render in form "Folder1/Folder2/Album".
A powerful feature of Photos is that it uses machine learning algorithms to automatically classify or label photos. These labels are used when you search for images in Photos but are not otherwise available to the user. osxphotos is able to read all the labels associated with a photo and makes those available through the template system via the `{label}`. Think of these as automatic keywords as opposed to the keywords you assign manually in Photos. One common use case is to use the automatic labels to create new keywords when exporting images so that these labels are embedded in the image's metadata:
@ -1440,7 +1440,7 @@ 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
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:
@ -3495,7 +3495,9 @@ To get the path of every raw photo, whether it's a single raw photo or a raw+JPE
### Template System
<!-- OSXPHOTOS-TEMPLATE-HELP:START - Do not remove or modify this section -->
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.
<!-- Generated by cog: see phototemplate.cog.md -->
The templating system converts one or template statements, written in osxphotos metadata templating language, to one or more rendered values using information from the photo being processed.
In its simplest form, a template statement has the form: `"{template_field}"`, for example `"{title}"` which would resolve to the title of the photo.
@ -3507,7 +3509,6 @@ Template statements are white-space sensitive meaning that white space (spaces,
`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
`+`: If present before template `name`, expands the template in place. If `delim` not provided, values are joined with no delimiter.
@ -3519,7 +3520,7 @@ e.g. if Photo keywords are `["foo","bar"]`:
- `"{; +keyword}"` renders to: `"foo; bar"`
- `"{+keyword}"` renders to `"foobar"`
`template_field`: The template field to resolve. See [Template Substitutions](#template-substitutions) for full list of template fields.
`template_field`: The template field to resolve. See [Template Substitutions](#template-substitutions) for 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`.
@ -3527,7 +3528,6 @@ e.g. if Photo keywords are `["foo","bar"]`:
Valid filters are:
<!-- OSXPHOTOS-FILTER-TABLE:START - Do not remove or modify this section -->
- `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'.
@ -3538,7 +3538,6 @@ Valid filters are:
- `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
<!-- OSXPHOTOS-FILTER-TABLE:END -->
e.g. if Photo keywords are `["FOO","bar"]`:
@ -3561,7 +3560,7 @@ e.g. If Photo is in `Album1` in `Folder1`:
`[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:
`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
@ -3605,7 +3604,7 @@ and if it is not an HDR image,
- `"{hdr?ISHDR,NOTHDR}"` renders to `"NOTHDR"`
`,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.
`,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.
e.g., if photo has no title set,
@ -3618,19 +3617,20 @@ 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"`
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.
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}"`.
<!-- OSXPHOTOS-TEMPLATE-HELP:END -->
The following template field substitutions are availabe for use the templating system.
<!-- OSXPHOTOS-TEMPLATE-TABLE:START - Do not remove or modify this section -->
| Substitution | Description |
| Field | Description |
|--------------|-------------|
|{name}|Current filename of the photo|
|{original_name}|Photo's original filename when imported to Photos|

15
build.sh
View File

@ -3,9 +3,19 @@
# script to help build osxphotos release
# this is unique to my own dev setup
rm -rf dist; rm -rf build
echo "Cleaning old build and dist directories"
rm -rf dist
rm -rf build
echo "Updated phototemplate.md"
cog -d -o osxphotos/phototemplate.md osxphotos/phototemplate.cog.md
echo "Updating README.md"
python3 utils/update_readme.py
echo "Updating API_README.md"
cog -r API_README.md
# stage and convert markdown to rst
echo "Copying osxphotos/tutorial.md to docsrc/source/tutorial.md"
cp osxphotos/tutorial.md docsrc/source/tutorial.md
@ -20,10 +30,13 @@ m2r2 docsrc/source/template_help.md
rm docsrc/source/template_help.md
# build docs
echo "Building docs"
(cd docsrc && make github && make docs && make pdf)
# build the package
echo "Building package"
python3 -m build
# build CLI executable
echo "Building CLI executable"
./make_cli_exe.sh

1
dev_requirements.txt
View File

@ -1,4 +1,5 @@
build
cogapp>=3.3.0,<4.0.0
furo
m2r2
pdbpp

12
docs/_modules/index.html
View File

@ -155,12 +155,12 @@
</form>
<div id="searchbox"></div><div class="sidebar-scroll"><div class="sidebar-tree">
<ul>
<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"><a class="reference internal" href="../template_help.html">osxphotos Template System</a></li>
<li class="toctree-l1"><a class="reference internal" href="../package_overview.html">Example uses of the python package</a></li>
<li class="toctree-l1"><a class="reference internal" href="../reference.html">osxphotos python API</a></li>
<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"><a class="reference internal" href="../template_help.html">OSXPhotos Template System</a></li>
<li class="toctree-l1"><a class="reference internal" href="../package_overview.html">Example uses of the OSXPhotos python package</a></li>
<li class="toctree-l1"><a class="reference internal" href="../reference.html">OSXPhotos python API</a></li>
</ul>
</div>

14
docs/_modules/osxphotos/phototemplate.html
View File

@ -158,6 +158,7 @@
<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"><a class="reference internal" href="../../template_help.html">osxphotos Template System</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../package_overview.html">Example uses of the python package</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../reference.html">osxphotos python API</a></li>
</ul>
@ -1590,6 +1591,19 @@
<span class="k">return</span> <span class="n">md</span>
<span class="k">def</span> <span class="nf">get_template_field_table</span><span class="p">():</span>
<span class="sd">"""Return markdown table of template field substitutions"""</span>
<span class="n">template_table</span> <span class="o">=</span> <span class="s2">"| Field | Description |"</span> <span class="o">+</span> <span class="s2">"</span><span class="se">\n</span><span class="s2">|--------------|-------------|"</span>
<span class="k">for</span> <span class="n">subst</span><span class="p">,</span> <span class="n">descr</span> <span class="ow">in</span> <span class="p">[</span>
<span class="o">*</span><span class="n">TEMPLATE_SUBSTITUTIONS</span><span class="o">.</span><span class="n">items</span><span class="p">(),</span>
<span class="o">*</span><span class="n">TEMPLATE_SUBSTITUTIONS_MULTI_VALUED</span><span class="o">.</span><span class="n">items</span><span class="p">(),</span>
<span class="p">]:</span>
<span class="c1"># replace '|' with '\|' to avoid markdown parsing issues (e.g. in {pipe} description)</span>
<span class="n">descr</span> <span class="o">=</span> <span class="n">descr</span><span class="o">.</span><span class="n">replace</span><span class="p">(</span><span class="s2">"'|'"</span><span class="p">,</span> <span class="s2">"'\|'"</span><span class="p">)</span>
<span class="n">template_table</span> <span class="o">+=</span> <span class="sa">f</span><span class="s2">"</span><span class="se">\n</span><span class="s2">|</span><span class="si">{</span><span class="n">subst</span><span class="si">}</span><span class="s2">|</span><span class="si">{</span><span class="n">descr</span><span class="si">}</span><span class="s2">|"</span>
<span class="k">return</span> <span class="n">template_table</span>
<span class="k">def</span> <span class="nf">_get_pathlib_value</span><span class="p">(</span><span class="n">field</span><span class="p">,</span> <span class="n">value</span><span class="p">,</span> <span class="n">quote</span><span class="p">):</span>
<span class="sd">"""Get the value for a pathlib.Path type template</span>

2
docs/_sources/cli.rst.txt
View File

@ -1,4 +1,4 @@
osxphotos Command Line Interface (CLI)
OSXPhotos Command Line Interface (CLI)
======================================
.. click:: osxphotos.cli:cli_main

2
docs/_sources/index.rst.txt
View File

@ -3,7 +3,7 @@
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Welcome to osxphotos's documentation!
Welcome to OSXPhotos's documentation!
=====================================
.. toctree::

6
docs/_sources/overview.rst.txt
View File

@ -1,10 +1,10 @@
osxphotos
OSXPhotos
=========
What is osxphotos?
What is OSXPhotos?
------------------
osxphotos provides both the ability to interact with and query Apple's Photos.app library on macOS directly from your python code
OSXPhotos provides both the ability to interact with and query Apple's Photos.app library on macOS directly from your python code
as well as a very flexible command line interface (CLI) app for exporting photos.
You can query the Photos library database -- for example, file name, file path, and metadata such as keywords/tags, persons/faces, albums, etc.
You can also easily export both the original and edited photos.

2
docs/_sources/package_overview.rst.txt
View File

@ -1,5 +1,5 @@
Example uses of the python package
Example uses of the OSXPhotos python package
----------------------------------
.. code-block:: python

2
docs/_sources/reference.rst.txt
View File

@ -1,4 +1,4 @@
osxphotos python API
OSXPhotos python API
====================
.. automodule:: osxphotos

14
docs/_sources/template_help.rst.txt
View File

@ -1,8 +1,8 @@
osxphotos Template System
OSXPhotos Template 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.
@ -26,7 +26,7 @@ e.g. if Photo keywords are ``["foo","bar"]``\ :
* ``"{; +keyword}"`` renders to: ``"foo; bar"``
* ``"{+keyword}"`` renders to ``"foobar"``
``template_field``\ : The template field to resolve. See `Template Substitutions <#template-substitutions>`_ for full list of template fields.
``template_field``\ : The template field to resolve. See `Template Substitutions <#template-substitutions>`_ for 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`.
@ -70,7 +70,7 @@ e.g. If Photo is in ``Album1`` in ``Folder1``\ :
`[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:
`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``
@ -118,7 +118,7 @@ and if it is not an HDR image,
* ``"{hdr?ISHDR,NOTHDR}"`` renders to ``"NOTHDR"``
``,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.
``,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.
e.g., if photo has no title set,
@ -133,7 +133,7 @@ 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"``
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.
@ -147,7 +147,7 @@ Template Substitutions
.. list-table::
:header-rows: 1
* - Substitution
* - Field
- Description
* - {name}
- Current filename of the photo

2
docs/_sources/tutorial.rst.txt
View File

@ -9,7 +9,7 @@
osxphotos Tutorial
OSXPhotos Tutorial
==================
Overview

23
docs/cli.html
View File

@ -3,10 +3,10 @@
<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.17.1: http://docutils.sourceforge.net/" />
<link rel="index" title="Index" href="genindex.html" /><link rel="search" title="Search" href="search.html" /><link rel="next" title="Example uses of the python package" href="package_overview.html" /><link rel="prev" title="osxphotos Tutorial" href="tutorial.html" />
<link rel="index" title="Index" href="genindex.html" /><link rel="search" title="Search" href="search.html" /><link rel="next" title="OSXPhotos Template System" href="template_help.html" /><link rel="prev" title="OSXPhotos Tutorial" href="tutorial.html" />
<meta name="generator" content="sphinx-4.4.0, furo 2022.04.07"/>
<title>osxphotos Command Line Interface (CLI) - osxphotos 0.47.10 documentation</title>
<title>OSXPhotos Command Line Interface (CLI) - osxphotos 0.47.10 documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css" />
<link rel="stylesheet" type="text/css" href="_static/styles/furo.css?digest=68f4518137b9aefe99b631505a2064c3c42c9852" />
<link rel="stylesheet" type="text/css" href="_static/copybutton.css" />
@ -157,10 +157,11 @@
<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 current current-page"><a class="current reference internal" href="#">osxphotos Command Line Interface (CLI)</a></li>
<li class="toctree-l1"><a class="reference internal" href="package_overview.html">Example uses of the python package</a></li>
<li class="toctree-l1"><a class="reference internal" href="reference.html">osxphotos python API</a></li>
<li class="toctree-l1"><a class="reference internal" href="tutorial.html">OSXPhotos Tutorial</a></li>
<li class="toctree-l1 current current-page"><a class="current reference internal" href="#">OSXPhotos Command Line Interface (CLI)</a></li>
<li class="toctree-l1"><a class="reference internal" href="template_help.html">OSXPhotos Template System</a></li>
<li class="toctree-l1"><a class="reference internal" href="package_overview.html">Example uses of the OSXPhotos python package</a></li>
<li class="toctree-l1"><a class="reference internal" href="reference.html">OSXPhotos python API</a></li>
</ul>
</div>
@ -194,7 +195,7 @@
</div>
<article role="main">
<section id="osxphotos-command-line-interface-cli">
<h1>osxphotos Command Line Interface (CLI)<a class="headerlink" href="#osxphotos-command-line-interface-cli" title="Permalink to this headline">#</a></h1>
<h1>OSXPhotos Command Line Interface (CLI)<a class="headerlink" href="#osxphotos-command-line-interface-cli" title="Permalink to this headline">#</a></h1>
<section id="osxphotos">
<h2>osxphotos<a class="headerlink" href="#osxphotos" title="Permalink to this headline">#</a></h2>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>osxphotos <span class="o">[</span>OPTIONS<span class="o">]</span> COMMAND <span class="o">[</span>ARGS<span class="o">]</span>...
@ -2201,12 +2202,12 @@ Commands:
<footer>
<div class="related-pages">
<a class="next-page" href="package_overview.html">
<a class="next-page" href="template_help.html">
<div class="page-info">
<div class="context">
<span>Next</span>
</div>
<div class="title">Example uses of the python package</div>
<div class="title">OSXPhotos Template System</div>
</div>
<svg><use href="#svg-arrow-right"></use></svg>
</a>
@ -2217,7 +2218,7 @@ Commands:
<span>Previous</span>
</div>
<div class="title">osxphotos Tutorial</div>
<div class="title">OSXPhotos Tutorial</div>
</div>
</a>
@ -2253,7 +2254,7 @@ Commands:
<div class="toc-tree-container">
<div class="toc-tree">
<ul>
<li><a class="reference internal" href="#">osxphotos Command Line Interface (CLI)</a><ul>
<li><a class="reference internal" href="#">OSXPhotos Command Line Interface (CLI)</a><ul>
<li><a class="reference internal" href="#osxphotos">osxphotos</a><ul>
<li><a class="reference internal" href="#osxphotos-about">about</a></li>
<li><a class="reference internal" href="#osxphotos-albums">albums</a></li>

12
docs/genindex.html
View File

@ -154,12 +154,12 @@
</form>
<div id="searchbox"></div><div class="sidebar-scroll"><div class="sidebar-tree">
<ul>
<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"><a class="reference internal" href="template_help.html">osxphotos Template System</a></li>
<li class="toctree-l1"><a class="reference internal" href="package_overview.html">Example uses of the python package</a></li>
<li class="toctree-l1"><a class="reference internal" href="reference.html">osxphotos python API</a></li>
<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"><a class="reference internal" href="template_help.html">OSXPhotos Template System</a></li>
<li class="toctree-l1"><a class="reference internal" href="package_overview.html">Example uses of the OSXPhotos python package</a></li>
<li class="toctree-l1"><a class="reference internal" href="reference.html">OSXPhotos python API</a></li>
</ul>
</div>

34
docs/index.html
View File

@ -3,7 +3,7 @@
<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.17.1: http://docutils.sourceforge.net/" />
<link rel="index" title="Index" href="genindex.html" /><link rel="search" title="Search" href="search.html" /><link rel="next" title="osxphotos" href="overview.html" />
<link rel="index" title="Index" href="genindex.html" /><link rel="search" title="Search" href="search.html" /><link rel="next" title="OSXPhotos" href="overview.html" />
<meta name="generator" content="sphinx-4.4.0, furo 2022.04.07"/>
<title>osxphotos 0.47.10 documentation</title>
@ -156,12 +156,12 @@
</form>
<div id="searchbox"></div><div class="sidebar-scroll"><div class="sidebar-tree">
<ul>
<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"><a class="reference internal" href="template_help.html">osxphotos Template System</a></li>
<li class="toctree-l1"><a class="reference internal" href="package_overview.html">Example uses of the python package</a></li>
<li class="toctree-l1"><a class="reference internal" href="reference.html">osxphotos python API</a></li>
<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"><a class="reference internal" href="template_help.html">OSXPhotos Template System</a></li>
<li class="toctree-l1"><a class="reference internal" href="package_overview.html">Example uses of the OSXPhotos python package</a></li>
<li class="toctree-l1"><a class="reference internal" href="reference.html">OSXPhotos python API</a></li>
</ul>
</div>
@ -195,17 +195,17 @@
</div>
<article role="main">
<section id="welcome-to-osxphotos-s-documentation">
<h1>Welcome to osxphotos’s documentation!<a class="headerlink" href="#welcome-to-osxphotos-s-documentation" title="Permalink to this headline">#</a></h1>
<h1>Welcome to OSXPhotos’s documentation!<a class="headerlink" href="#welcome-to-osxphotos-s-documentation" title="Permalink to this headline">#</a></h1>
<div class="toctree-wrapper compound">
<ul>
<li class="toctree-l1"><a class="reference internal" href="overview.html">osxphotos</a><ul>
<li class="toctree-l2"><a class="reference internal" href="overview.html#what-is-osxphotos">What is osxphotos?</a></li>
<li class="toctree-l1"><a class="reference internal" href="overview.html">OSXPhotos</a><ul>
<li class="toctree-l2"><a class="reference internal" href="overview.html#what-is-osxphotos">What is OSXPhotos?</a></li>
<li class="toctree-l2"><a class="reference internal" href="overview.html#supported-operating-systems">Supported operating systems</a></li>
<li class="toctree-l2"><a class="reference internal" href="overview.html#installation">Installation</a></li>
<li class="toctree-l2"><a class="reference internal" href="overview.html#command-line-usage">Command Line Usage</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="tutorial.html">osxphotos Tutorial</a><ul>
<li class="toctree-l1"><a class="reference internal" href="tutorial.html">OSXPhotos Tutorial</a><ul>
<li class="toctree-l2"><a class="reference internal" href="tutorial.html#overview">Overview</a></li>
<li class="toctree-l2"><a class="reference internal" href="tutorial.html#export-your-photos">Export your photos</a></li>
<li class="toctree-l2"><a class="reference internal" href="tutorial.html#export-by-date">Export by date</a></li>
@ -230,7 +230,7 @@
<li class="toctree-l2"><a class="reference internal" href="tutorial.html#conclusion">Conclusion</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="cli.html">osxphotos Command Line Interface (CLI)</a><ul>
<li class="toctree-l1"><a class="reference internal" href="cli.html">OSXPhotos Command Line Interface (CLI)</a><ul>
<li class="toctree-l2"><a class="reference internal" href="cli.html#osxphotos">osxphotos</a><ul>
<li class="toctree-l3"><a class="reference internal" href="cli.html#osxphotos-about">about</a></li>
<li class="toctree-l3"><a class="reference internal" href="cli.html#osxphotos-albums">albums</a></li>
@ -258,12 +258,12 @@
</li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="template_help.html">osxphotos Template System</a><ul>
<li class="toctree-l1"><a class="reference internal" href="template_help.html">OSXPhotos Template System</a><ul>
<li class="toctree-l2"><a class="reference internal" href="template_help.html#id1">Template Substitutions</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="package_overview.html">Example uses of the python package</a></li>
<li class="toctree-l1"><a class="reference internal" href="reference.html">osxphotos python API</a></li>
<li class="toctree-l1"><a class="reference internal" href="package_overview.html">Example uses of the OSXPhotos python package</a></li>
<li class="toctree-l1"><a class="reference internal" href="reference.html">OSXPhotos python API</a></li>
</ul>
</div>
</section>
@ -286,7 +286,7 @@
<div class="context">
<span>Next</span>
</div>
<div class="title">osxphotos</div>
<div class="title">OSXPhotos</div>
</div>
<svg><use href="#svg-arrow-right"></use></svg>
</a>
@ -323,7 +323,7 @@
<div class="toc-tree-container">
<div class="toc-tree">
<ul>
<li><a class="reference internal" href="#">Welcome to osxphotos’s documentation!</a></li>
<li><a class="reference internal" href="#">Welcome to OSXPhotos’s documentation!</a></li>
<li><a class="reference internal" href="#indices-and-tables">Indices and tables</a></li>
</ul>

BIN
docs/objects.inv
View File

Binary file not shown.

27
docs/overview.html
View File

@ -3,10 +3,10 @@
<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.17.1: http://docutils.sourceforge.net/" />
<link rel="index" title="Index" href="genindex.html" /><link rel="search" title="Search" href="search.html" /><link rel="next" title="osxphotos Tutorial" href="tutorial.html" /><link rel="prev" title="Welcome to osxphotos’s documentation!" href="index.html" />
<link rel="index" title="Index" href="genindex.html" /><link rel="search" title="Search" href="search.html" /><link rel="next" title="OSXPhotos Tutorial" href="tutorial.html" /><link rel="prev" title="Welcome to OSXPhotos’s documentation!" href="index.html" />
<meta name="generator" content="sphinx-4.4.0, furo 2022.04.07"/>
<title>osxphotos - osxphotos 0.47.10 documentation</title>
<title>OSXPhotos - osxphotos 0.47.10 documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css" />
<link rel="stylesheet" type="text/css" href="_static/styles/furo.css?digest=68f4518137b9aefe99b631505a2064c3c42c9852" />
<link rel="stylesheet" type="text/css" href="_static/copybutton.css" />
@ -156,11 +156,12 @@
</form>
<div id="searchbox"></div><div class="sidebar-scroll"><div class="sidebar-tree">
<ul class="current">
<li class="toctree-l1 current current-page"><a class="current reference internal" href="#">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"><a class="reference internal" href="package_overview.html">Example uses of the python package</a></li>
<li class="toctree-l1"><a class="reference internal" href="reference.html">osxphotos python API</a></li>
<li class="toctree-l1 current current-page"><a class="current reference internal" href="#">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"><a class="reference internal" href="template_help.html">OSXPhotos Template System</a></li>
<li class="toctree-l1"><a class="reference internal" href="package_overview.html">Example uses of the OSXPhotos python package</a></li>
<li class="toctree-l1"><a class="reference internal" href="reference.html">OSXPhotos python API</a></li>
</ul>
</div>
@ -194,10 +195,10 @@
</div>
<article role="main">
<section id="osxphotos">
<h1>osxphotos<a class="headerlink" href="#osxphotos" title="Permalink to this headline">#</a></h1>
<h1>OSXPhotos<a class="headerlink" href="#osxphotos" title="Permalink to this headline">#</a></h1>
<section id="what-is-osxphotos">
<h2>What is osxphotos?<a class="headerlink" href="#what-is-osxphotos" title="Permalink to this headline">#</a></h2>
<p>osxphotos provides both the ability to interact with and query Apple’s Photos.app library on macOS directly from your python code
<h2>What is OSXPhotos?<a class="headerlink" href="#what-is-osxphotos" title="Permalink to this headline">#</a></h2>
<p>OSXPhotos provides both the ability to interact with and query Apple’s Photos.app library on macOS directly from your python code
as well as a very flexible command line interface (CLI) app for exporting photos.
You can query the Photos library database – for example, file name, file path, and metadata such as keywords/tags, persons/faces, albums, etc.
You can also easily export both the original and edited photos.</p>
@ -278,7 +279,7 @@ E.g. you can read a database created with Photos 5.0 on MacOS 10.15 on a machine
<div class="context">
<span>Next</span>
</div>
<div class="title">osxphotos Tutorial</div>
<div class="title">OSXPhotos Tutorial</div>
</div>
<svg><use href="#svg-arrow-right"></use></svg>
</a>
@ -325,8 +326,8 @@ E.g. you can read a database created with Photos 5.0 on MacOS 10.15 on a machine
<div class="toc-tree-container">
<div class="toc-tree">
<ul>
<li><a class="reference internal" href="#">osxphotos</a><ul>
<li><a class="reference internal" href="#what-is-osxphotos">What is osxphotos?</a></li>
<li><a class="reference internal" href="#">OSXPhotos</a><ul>
<li><a class="reference internal" href="#what-is-osxphotos">What is OSXPhotos?</a></li>
<li><a class="reference internal" href="#supported-operating-systems">Supported operating systems</a></li>
<li><a class="reference internal" href="#installation">Installation</a></li>
<li><a class="reference internal" href="#command-line-usage">Command Line Usage</a></li>

23
docs/package_overview.html
View File

@ -3,10 +3,10 @@
<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.17.1: http://docutils.sourceforge.net/" />
<link rel="index" title="Index" href="genindex.html" /><link rel="search" title="Search" href="search.html" /><link rel="next" title="osxphotos python API" href="reference.html" /><link rel="prev" title="osxphotos Command Line Interface (CLI)" href="cli.html" />
<link rel="index" title="Index" href="genindex.html" /><link rel="search" title="Search" href="search.html" /><link rel="next" title="OSXPhotos python API" href="reference.html" /><link rel="prev" title="OSXPhotos Template System" href="template_help.html" />
<meta name="generator" content="sphinx-4.4.0, furo 2022.04.07"/>
<title>Example uses of the python package - osxphotos 0.47.10 documentation</title>
<title>Example uses of the OSXPhotos python package - osxphotos 0.47.10 documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css" />
<link rel="stylesheet" type="text/css" href="_static/styles/furo.css?digest=68f4518137b9aefe99b631505a2064c3c42c9852" />
<link rel="stylesheet" type="text/css" href="_static/copybutton.css" />
@ -157,10 +157,11 @@
<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="#">Example uses of the python package</a></li>
<li class="toctree-l1"><a class="reference internal" href="reference.html">osxphotos python API</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"><a class="reference internal" href="template_help.html">OSXPhotos Template System</a></li>
<li class="toctree-l1 current current-page"><a class="current reference internal" href="#">Example uses of the OSXPhotos python package</a></li>
<li class="toctree-l1"><a class="reference internal" href="reference.html">OSXPhotos python API</a></li>
</ul>
</div>
@ -193,8 +194,8 @@
</label>
</div>
<article role="main">
<section id="example-uses-of-the-python-package">
<h1>Example uses of the python package<a class="headerlink" href="#example-uses-of-the-python-package" title="Permalink to this headline">#</a></h1>
<section id="example-uses-of-the-osxphotos-python-package">
<h1>Example uses of the OSXPhotos python package<a class="headerlink" href="#example-uses-of-the-osxphotos-python-package" title="Permalink to this headline">#</a></h1>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="sd">""" Simple usage of the package """</span>
<span class="kn">import</span> <span class="nn">osxphotos</span>
@ -321,18 +322,18 @@
<div class="context">
<span>Next</span>
</div>
<div class="title">osxphotos python API</div>
<div class="title">OSXPhotos python API</div>
</div>
<svg><use href="#svg-arrow-right"></use></svg>
</a>
<a class="prev-page" href="cli.html">
<a class="prev-page" href="template_help.html">
<svg><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 class="title">OSXPhotos Template System</div>
</div>
</a>

12
docs/py-modindex.html
View File

@ -154,12 +154,12 @@
</form>
<div id="searchbox"></div><div class="sidebar-scroll"><div class="sidebar-tree">
<ul>
<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"><a class="reference internal" href="template_help.html">osxphotos Template System</a></li>
<li class="toctree-l1"><a class="reference internal" href="package_overview.html">Example uses of the python package</a></li>
<li class="toctree-l1"><a class="reference internal" href="reference.html">osxphotos python API</a></li>
<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"><a class="reference internal" href="template_help.html">OSXPhotos Template System</a></li>
<li class="toctree-l1"><a class="reference internal" href="package_overview.html">Example uses of the OSXPhotos python package</a></li>
<li class="toctree-l1"><a class="reference internal" href="reference.html">OSXPhotos python API</a></li>
</ul>
</div>

17
docs/reference.html
View File

@ -3,10 +3,10 @@
<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.17.1: http://docutils.sourceforge.net/" />
<link rel="index" title="Index" href="genindex.html" /><link rel="search" title="Search" href="search.html" /><link rel="prev" title="Example uses of the python package" href="package_overview.html" />
<link rel="index" title="Index" href="genindex.html" /><link rel="search" title="Search" href="search.html" /><link rel="prev" title="Example uses of the OSXPhotos python package" href="package_overview.html" />
<meta name="generator" content="sphinx-4.4.0, furo 2022.04.07"/>
<title>osxphotos python API - osxphotos 0.47.10 documentation</title>
<title>OSXPhotos python API - osxphotos 0.47.10 documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css" />
<link rel="stylesheet" type="text/css" href="_static/styles/furo.css?digest=68f4518137b9aefe99b631505a2064c3c42c9852" />
<link rel="stylesheet" type="text/css" href="_static/copybutton.css" />
@ -157,10 +157,11 @@
<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"><a class="reference internal" href="package_overview.html">Example uses of the python package</a></li>
<li class="toctree-l1 current current-page"><a class="current reference internal" href="#">osxphotos python API</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"><a class="reference internal" href="template_help.html">OSXPhotos Template System</a></li>
<li class="toctree-l1"><a class="reference internal" href="package_overview.html">Example uses of the OSXPhotos python package</a></li>
<li class="toctree-l1 current current-page"><a class="current reference internal" href="#">OSXPhotos python API</a></li>
</ul>
</div>
@ -194,7 +195,7 @@
</div>
<article role="main">
<section id="module-osxphotos">
<span id="osxphotos-python-api"></span><h1>osxphotos python API<a class="headerlink" href="#module-osxphotos" title="Permalink to this headline">#</a></h1>
<span id="osxphotos-python-api"></span><h1>OSXPhotos python API<a class="headerlink" href="#module-osxphotos" title="Permalink to this headline">#</a></h1>
<dl class="py class">
<dt class="sig sig-object py" id="osxphotos.AlbumInfo">
<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">osxphotos.</span></span><span class="sig-name descname"><span class="pre">AlbumInfo</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">db</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">uuid</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/osxphotos/albuminfo.html#AlbumInfo"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#osxphotos.AlbumInfo" title="Permalink to this definition">#</a></dt>
@ -2894,7 +2895,7 @@ Projects are cards, calendars, slideshows, etc.</p>
<span>Previous</span>
</div>
<div class="title">Example uses of the python package</div>
<div class="title">Example uses of the OSXPhotos python package</div>
</div>
</a>

12
docs/search.html
View File

@ -153,12 +153,12 @@
</form>
<div id="searchbox"></div><div class="sidebar-scroll"><div class="sidebar-tree">
<ul>
<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"><a class="reference internal" href="template_help.html">osxphotos Template System</a></li>
<li class="toctree-l1"><a class="reference internal" href="package_overview.html">Example uses of the python package</a></li>
<li class="toctree-l1"><a class="reference internal" href="reference.html">osxphotos python API</a></li>
<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"><a class="reference internal" href="template_help.html">OSXPhotos Template System</a></li>
<li class="toctree-l1"><a class="reference internal" href="package_overview.html">Example uses of the OSXPhotos python package</a></li>
<li class="toctree-l1"><a class="reference internal" href="reference.html">OSXPhotos python API</a></li>
</ul>
</div>

2
docs/searchindex.js
View File

File diff suppressed because one or more lines are too long

28
docs/template_help.html
View File

@ -3,10 +3,10 @@
<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.17.1: http://docutils.sourceforge.net/" />
<link rel="index" title="Index" href="genindex.html" /><link rel="search" title="Search" href="search.html" /><link rel="next" title="Example uses of the python package" href="package_overview.html" /><link rel="prev" title="osxphotos Command Line Interface (CLI)" href="cli.html" />
<link rel="index" title="Index" href="genindex.html" /><link rel="search" title="Search" href="search.html" /><link rel="next" title="Example uses of the OSXPhotos python package" href="package_overview.html" /><link rel="prev" title="OSXPhotos Command Line Interface (CLI)" href="cli.html" />
<meta name="generator" content="sphinx-4.4.0, furo 2022.04.07"/>
<title>osxphotos Template System - osxphotos 0.47.10 documentation</title>
<title>OSXPhotos Template System - osxphotos 0.47.10 documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css" />
<link rel="stylesheet" type="text/css" href="_static/styles/furo.css?digest=68f4518137b9aefe99b631505a2064c3c42c9852" />
<link rel="stylesheet" type="text/css" href="_static/copybutton.css" />
@ -156,12 +156,12 @@
</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">Example uses of the python package</a></li>
<li class="toctree-l1"><a class="reference internal" href="reference.html">osxphotos python API</a></li>
<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">Example uses of the OSXPhotos python package</a></li>
<li class="toctree-l1"><a class="reference internal" href="reference.html">OSXPhotos python API</a></li>
</ul>
</div>
@ -195,7 +195,7 @@
</div>
<article role="main">
<section id="osxphotos-template-system">
<h1>osxphotos Template System<a class="headerlink" href="#osxphotos-template-system" title="Permalink to this headline">#</a></h1>
<h1>OSXPhotos Template System<a class="headerlink" href="#osxphotos-template-system" title="Permalink to this headline">#</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>
@ -246,7 +246,7 @@
<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 ‘` not operator value`’ 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>
<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>
@ -306,7 +306,7 @@
<col style="width: 50%"/>
</colgroup>
<thead>
<tr class="row-odd"><th class="head"><p>Substitution</p></th>
<tr class="row-odd"><th class="head"><p>Field</p></th>
<th class="head"><p>Description</p></th>
</tr>
</thead>
@ -644,7 +644,7 @@
<div class="context">
<span>Next</span>
</div>
<div class="title">Example uses of the python package</div>
<div class="title">Example uses of the OSXPhotos python package</div>
</div>
<svg><use href="#svg-arrow-right"></use></svg>
</a>
@ -655,7 +655,7 @@
<span>Previous</span>
</div>
<div class="title">osxphotos Command Line Interface (CLI)</div>
<div class="title">OSXPhotos Command Line Interface (CLI)</div>
</div>
</a>
@ -691,7 +691,7 @@
<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="#">OSXPhotos Template System</a><ul>
<li><a class="reference internal" href="#id1">Template Substitutions</a></li>
</ul>
</li>

24
docs/tutorial.html
View File

@ -3,10 +3,10 @@
<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.17.1: http://docutils.sourceforge.net/" />
<link rel="index" title="Index" href="genindex.html" /><link rel="search" title="Search" href="search.html" /><link rel="next" title="osxphotos Command Line Interface (CLI)" href="cli.html" /><link rel="prev" title="osxphotos" href="overview.html" />
<link rel="index" title="Index" href="genindex.html" /><link rel="search" title="Search" href="search.html" /><link rel="next" title="OSXPhotos Command Line Interface (CLI)" href="cli.html" /><link rel="prev" title="OSXPhotos" href="overview.html" />
<meta name="generator" content="sphinx-4.4.0, furo 2022.04.07"/>
<title>osxphotos Tutorial - osxphotos 0.47.10 documentation</title>
<title>OSXPhotos Tutorial - osxphotos 0.47.10 documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css" />
<link rel="stylesheet" type="text/css" href="_static/styles/furo.css?digest=68f4518137b9aefe99b631505a2064c3c42c9852" />
<link rel="stylesheet" type="text/css" href="_static/copybutton.css" />
@ -156,12 +156,12 @@
</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 current current-page"><a class="current reference internal" href="#">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"><a class="reference internal" href="template_help.html">osxphotos Template System</a></li>
<li class="toctree-l1"><a class="reference internal" href="package_overview.html">Example uses of the python package</a></li>
<li class="toctree-l1"><a class="reference internal" href="reference.html">osxphotos python API</a></li>
<li class="toctree-l1"><a class="reference internal" href="overview.html">OSXPhotos</a></li>
<li class="toctree-l1 current current-page"><a class="current reference internal" href="#">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"><a class="reference internal" href="template_help.html">OSXPhotos Template System</a></li>
<li class="toctree-l1"><a class="reference internal" href="package_overview.html">Example uses of the OSXPhotos python package</a></li>
<li class="toctree-l1"><a class="reference internal" href="reference.html">OSXPhotos python API</a></li>
</ul>
</div>
@ -195,7 +195,7 @@
</div>
<article role="main">
<!-- OSXPHOTOS-TUTORIAL-HEADER:START --><section id="osxphotos-tutorial">
<h1>osxphotos Tutorial<a class="headerlink" href="#osxphotos-tutorial" title="Permalink to this headline">#</a></h1>
<h1>OSXPhotos Tutorial<a class="headerlink" href="#osxphotos-tutorial" title="Permalink to this headline">#</a></h1>
<section id="overview">
<h2>Overview<a class="headerlink" href="#overview" title="Permalink to this headline">#</a></h2>
<!-- OSXPHOTOS-TUTORIAL-HEADER:END --><p>The design philosophy for osxphotos is “make the easy things easy and make the hard things possible”. To “make the hard things possible”, osxphotos is very flexible and has many, many configuration options – the <code class="docutils literal notranslate"><span class="pre">export</span></code> command for example, has over 100 command line options. Thus, osxphotos may seem daunting at first. The purpose of this tutorial is to explain a number of common use cases with examples and, hopefully, make osxphotos less daunting to use. osxphotos includes several commands for retrieving information from your Photos library but the one most users are interested in is the <code class="docutils literal notranslate"><span class="pre">export</span></code> command which exports photos from the library so that’s the focus of this tutorial.</p>
@ -508,7 +508,7 @@ template fields.
<div class="context">
<span>Next</span>
</div>
<div class="title">osxphotos Command Line Interface (CLI)</div>
<div class="title">OSXPhotos Command Line Interface (CLI)</div>
</div>
<svg><use href="#svg-arrow-right"></use></svg>
</a>
@ -519,7 +519,7 @@ template fields.
<span>Previous</span>
</div>
<div class="title">osxphotos</div>
<div class="title">OSXPhotos</div>
</div>
</a>
@ -555,7 +555,7 @@ template fields.
<div class="toc-tree-container">
<div class="toc-tree">
<ul>
<li><a class="reference internal" href="#">osxphotos Tutorial</a><ul>
<li><a class="reference internal" href="#">OSXPhotos Tutorial</a><ul>
<li><a class="reference internal" href="#overview">Overview</a></li>
<li><a class="reference internal" href="#export-your-photos">Export your photos</a></li>
<li><a class="reference internal" href="#export-by-date">Export by date</a></li>

11
docsrc/README.md
View File

@ -2,12 +2,17 @@
I'm still trying to learn sphinx and come up with a workflow for building docs. Right now it's pretty kludgy.
- `pip install sphinx`
- `pip install sphinx-rtd-theme`
- `pip install m2r2`
- `python3 -m pip -r dev_requirements.txt`
- Download and install [MacTeX](https://tug.org/mactex/)
- Add `/Library/TeX/texbin` to your `$PATH`
- `cd docs`
- `make html`
- `make latexpdf`
- `cp _build/latex/osxphotos.pdf .`
The `build.sh` script in the main repo directory will build the documents for you and is the preferred way to build the docs.
The following files are generated by `build.sh` and should not be directly edited:
- source/template_help.rst
- source/tutorial.rst

2
docsrc/source/cli.rst
View File

@ -1,4 +1,4 @@
osxphotos Command Line Interface (CLI)
OSXPhotos Command Line Interface (CLI)
======================================
.. click:: osxphotos.cli:cli_main

2
docsrc/source/index.rst
View File

@ -3,7 +3,7 @@
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Welcome to osxphotos's documentation!
Welcome to OSXPhotos's documentation!
=====================================
.. toctree::

6
docsrc/source/overview.rst
View File

@ -1,10 +1,10 @@
osxphotos
OSXPhotos
=========
What is osxphotos?
What is OSXPhotos?
------------------
osxphotos provides both the ability to interact with and query Apple's Photos.app library on macOS directly from your python code
OSXPhotos provides both the ability to interact with and query Apple's Photos.app library on macOS directly from your python code
as well as a very flexible command line interface (CLI) app for exporting photos.
You can query the Photos library database -- for example, file name, file path, and metadata such as keywords/tags, persons/faces, albums, etc.
You can also easily export both the original and edited photos.

2
docsrc/source/package_overview.rst
View File

@ -1,5 +1,5 @@
Example uses of the python package
Example uses of the OSXPhotos python package
----------------------------------
.. code-block:: python

2
docsrc/source/reference.rst
View File

@ -1,4 +1,4 @@
osxphotos python API
OSXPhotos python API
====================
.. automodule:: osxphotos

14
docsrc/source/template_help.rst
View File

@ -1,8 +1,8 @@
osxphotos Template System
OSXPhotos Template 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.
@ -26,7 +26,7 @@ e.g. if Photo keywords are ``["foo","bar"]``\ :
* ``"{; +keyword}"`` renders to: ``"foo; bar"``
* ``"{+keyword}"`` renders to ``"foobar"``
``template_field``\ : The template field to resolve. See `Template Substitutions <#template-substitutions>`_ for full list of template fields.
``template_field``\ : The template field to resolve. See `Template Substitutions <#template-substitutions>`_ for 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`.
@ -70,7 +70,7 @@ e.g. If Photo is in ``Album1`` in ``Folder1``\ :
`[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:
`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``
@ -118,7 +118,7 @@ and if it is not an HDR image,
* ``"{hdr?ISHDR,NOTHDR}"`` renders to ``"NOTHDR"``
``,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.
``,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.
e.g., if photo has no title set,
@ -133,7 +133,7 @@ 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"``
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.
@ -147,7 +147,7 @@ Template Substitutions
.. list-table::
:header-rows: 1
* - Substitution
* - Field
- Description
* - {name}
- Current filename of the photo

2
docsrc/source/tutorial.rst
View File

@ -9,7 +9,7 @@
osxphotos Tutorial
OSXPhotos Tutorial
==================
Overview

12
osxphotos/docs/_modules/index.html
View File

@ -155,12 +155,12 @@
</form>
<div id="searchbox"></div><div class="sidebar-scroll"><div class="sidebar-tree">
<ul>
<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"><a class="reference internal" href="../template_help.html">osxphotos Template System</a></li>
<li class="toctree-l1"><a class="reference internal" href="../package_overview.html">Example uses of the python package</a></li>
<li class="toctree-l1"><a class="reference internal" href="../reference.html">osxphotos python API</a></li>
<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"><a class="reference internal" href="../template_help.html">OSXPhotos Template System</a></li>
<li class="toctree-l1"><a class="reference internal" href="../package_overview.html">Example uses of the OSXPhotos python package</a></li>
<li class="toctree-l1"><a class="reference internal" href="../reference.html">OSXPhotos python API</a></li>
</ul>
</div>

14
osxphotos/docs/_modules/osxphotos/phototemplate.html
View File

@ -158,6 +158,7 @@
<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"><a class="reference internal" href="../../template_help.html">osxphotos Template System</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../package_overview.html">Example uses of the python package</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../reference.html">osxphotos python API</a></li>
</ul>
@ -1590,6 +1591,19 @@
<span class="k">return</span> <span class="n">md</span>
<span class="k">def</span> <span class="nf">get_template_field_table</span><span class="p">():</span>
<span class="sd">"""Return markdown table of template field substitutions"""</span>
<span class="n">template_table</span> <span class="o">=</span> <span class="s2">"| Field | Description |"</span> <span class="o">+</span> <span class="s2">"</span><span class="se">\n</span><span class="s2">|--------------|-------------|"</span>
<span class="k">for</span> <span class="n">subst</span><span class="p">,</span> <span class="n">descr</span> <span class="ow">in</span> <span class="p">[</span>
<span class="o">*</span><span class="n">TEMPLATE_SUBSTITUTIONS</span><span class="o">.</span><span class="n">items</span><span class="p">(),</span>
<span class="o">*</span><span class="n">TEMPLATE_SUBSTITUTIONS_MULTI_VALUED</span><span class="o">.</span><span class="n">items</span><span class="p">(),</span>
<span class="p">]:</span>
<span class="c1"># replace '|' with '\|' to avoid markdown parsing issues (e.g. in {pipe} description)</span>
<span class="n">descr</span> <span class="o">=</span> <span class="n">descr</span><span class="o">.</span><span class="n">replace</span><span class="p">(</span><span class="s2">"'|'"</span><span class="p">,</span> <span class="s2">"'\|'"</span><span class="p">)</span>
<span class="n">template_table</span> <span class="o">+=</span> <span class="sa">f</span><span class="s2">"</span><span class="se">\n</span><span class="s2">|</span><span class="si">{</span><span class="n">subst</span><span class="si">}</span><span class="s2">|</span><span class="si">{</span><span class="n">descr</span><span class="si">}</span><span class="s2">|"</span>
<span class="k">return</span> <span class="n">template_table</span>
<span class="k">def</span> <span class="nf">_get_pathlib_value</span><span class="p">(</span><span class="n">field</span><span class="p">,</span> <span class="n">value</span><span class="p">,</span> <span class="n">quote</span><span class="p">):</span>
<span class="sd">"""Get the value for a pathlib.Path type template</span>

2
osxphotos/docs/_sources/cli.rst.txt
View File

@ -1,4 +1,4 @@
osxphotos Command Line Interface (CLI)
OSXPhotos Command Line Interface (CLI)
======================================
.. click:: osxphotos.cli:cli_main

2
osxphotos/docs/_sources/index.rst.txt
View File

@ -3,7 +3,7 @@
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Welcome to osxphotos's documentation!
Welcome to OSXPhotos's documentation!
=====================================
.. toctree::

6
osxphotos/docs/_sources/overview.rst.txt
View File

@ -1,10 +1,10 @@
osxphotos
OSXPhotos
=========
What is osxphotos?
What is OSXPhotos?
------------------
osxphotos provides both the ability to interact with and query Apple's Photos.app library on macOS directly from your python code
OSXPhotos provides both the ability to interact with and query Apple's Photos.app library on macOS directly from your python code
as well as a very flexible command line interface (CLI) app for exporting photos.
You can query the Photos library database -- for example, file name, file path, and metadata such as keywords/tags, persons/faces, albums, etc.
You can also easily export both the original and edited photos.

2
osxphotos/docs/_sources/package_overview.rst.txt
View File

@ -1,5 +1,5 @@
Example uses of the python package
Example uses of the OSXPhotos python package
----------------------------------
.. code-block:: python

2
osxphotos/docs/_sources/reference.rst.txt
View File

@ -1,4 +1,4 @@
osxphotos python API
OSXPhotos python API
====================
.. automodule:: osxphotos

14
osxphotos/docs/_sources/template_help.rst.txt
View File

@ -1,8 +1,8 @@
osxphotos Template System
OSXPhotos Template 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.
@ -26,7 +26,7 @@ e.g. if Photo keywords are ``["foo","bar"]``\ :
* ``"{; +keyword}"`` renders to: ``"foo; bar"``
* ``"{+keyword}"`` renders to ``"foobar"``
``template_field``\ : The template field to resolve. See `Template Substitutions <#template-substitutions>`_ for full list of template fields.
``template_field``\ : The template field to resolve. See `Template Substitutions <#template-substitutions>`_ for 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`.
@ -70,7 +70,7 @@ e.g. If Photo is in ``Album1`` in ``Folder1``\ :
`[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:
`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``
@ -118,7 +118,7 @@ and if it is not an HDR image,
* ``"{hdr?ISHDR,NOTHDR}"`` renders to ``"NOTHDR"``
``,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.
``,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.
e.g., if photo has no title set,
@ -133,7 +133,7 @@ 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"``
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.
@ -147,7 +147,7 @@ Template Substitutions
.. list-table::
:header-rows: 1
* - Substitution
* - Field
- Description
* - {name}
- Current filename of the photo

2
osxphotos/docs/_sources/tutorial.rst.txt
View File

@ -9,7 +9,7 @@
osxphotos Tutorial
OSXPhotos Tutorial
==================
Overview

23
osxphotos/docs/cli.html
View File

@ -3,10 +3,10 @@
<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.17.1: http://docutils.sourceforge.net/" />
<link rel="index" title="Index" href="genindex.html" /><link rel="search" title="Search" href="search.html" /><link rel="next" title="Example uses of the python package" href="package_overview.html" /><link rel="prev" title="osxphotos Tutorial" href="tutorial.html" />
<link rel="index" title="Index" href="genindex.html" /><link rel="search" title="Search" href="search.html" /><link rel="next" title="OSXPhotos Template System" href="template_help.html" /><link rel="prev" title="OSXPhotos Tutorial" href="tutorial.html" />
<meta name="generator" content="sphinx-4.4.0, furo 2022.04.07"/>
<title>osxphotos Command Line Interface (CLI) - osxphotos 0.47.10 documentation</title>
<title>OSXPhotos Command Line Interface (CLI) - osxphotos 0.47.10 documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css" />
<link rel="stylesheet" type="text/css" href="_static/styles/furo.css?digest=68f4518137b9aefe99b631505a2064c3c42c9852" />
<link rel="stylesheet" type="text/css" href="_static/copybutton.css" />
@ -157,10 +157,11 @@
<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 current current-page"><a class="current reference internal" href="#">osxphotos Command Line Interface (CLI)</a></li>
<li class="toctree-l1"><a class="reference internal" href="package_overview.html">Example uses of the python package</a></li>
<li class="toctree-l1"><a class="reference internal" href="reference.html">osxphotos python API</a></li>
<li class="toctree-l1"><a class="reference internal" href="tutorial.html">OSXPhotos Tutorial</a></li>
<li class="toctree-l1 current current-page"><a class="current reference internal" href="#">OSXPhotos Command Line Interface (CLI)</a></li>
<li class="toctree-l1"><a class="reference internal" href="template_help.html">OSXPhotos Template System</a></li>
<li class="toctree-l1"><a class="reference internal" href="package_overview.html">Example uses of the OSXPhotos python package</a></li>
<li class="toctree-l1"><a class="reference internal" href="reference.html">OSXPhotos python API</a></li>
</ul>
</div>
@ -194,7 +195,7 @@
</div>
<article role="main">
<section id="osxphotos-command-line-interface-cli">
<h1>osxphotos Command Line Interface (CLI)<a class="headerlink" href="#osxphotos-command-line-interface-cli" title="Permalink to this headline">#</a></h1>
<h1>OSXPhotos Command Line Interface (CLI)<a class="headerlink" href="#osxphotos-command-line-interface-cli" title="Permalink to this headline">#</a></h1>
<section id="osxphotos">
<h2>osxphotos<a class="headerlink" href="#osxphotos" title="Permalink to this headline">#</a></h2>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>osxphotos <span class="o">[</span>OPTIONS<span class="o">]</span> COMMAND <span class="o">[</span>ARGS<span class="o">]</span>...
@ -2201,12 +2202,12 @@ Commands:
<footer>
<div class="related-pages">
<a class="next-page" href="package_overview.html">
<a class="next-page" href="template_help.html">
<div class="page-info">
<div class="context">
<span>Next</span>
</div>
<div class="title">Example uses of the python package</div>
<div class="title">OSXPhotos Template System</div>
</div>
<svg><use href="#svg-arrow-right"></use></svg>
</a>
@ -2217,7 +2218,7 @@ Commands:
<span>Previous</span>
</div>
<div class="title">osxphotos Tutorial</div>
<div class="title">OSXPhotos Tutorial</div>
</div>
</a>
@ -2253,7 +2254,7 @@ Commands:
<div class="toc-tree-container">
<div class="toc-tree">
<ul>
<li><a class="reference internal" href="#">osxphotos Command Line Interface (CLI)</a><ul>
<li><a class="reference internal" href="#">OSXPhotos Command Line Interface (CLI)</a><ul>
<li><a class="reference internal" href="#osxphotos">osxphotos</a><ul>
<li><a class="reference internal" href="#osxphotos-about">about</a></li>
<li><a class="reference internal" href="#osxphotos-albums">albums</a></li>

12
osxphotos/docs/genindex.html
View File

@ -154,12 +154,12 @@
</form>
<div id="searchbox"></div><div class="sidebar-scroll"><div class="sidebar-tree">
<ul>
<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"><a class="reference internal" href="template_help.html">osxphotos Template System</a></li>
<li class="toctree-l1"><a class="reference internal" href="package_overview.html">Example uses of the python package</a></li>
<li class="toctree-l1"><a class="reference internal" href="reference.html">osxphotos python API</a></li>
<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"><a class="reference internal" href="template_help.html">OSXPhotos Template System</a></li>
<li class="toctree-l1"><a class="reference internal" href="package_overview.html">Example uses of the OSXPhotos python package</a></li>
<li class="toctree-l1"><a class="reference internal" href="reference.html">OSXPhotos python API</a></li>
</ul>
</div>

34
osxphotos/docs/index.html
View File

@ -3,7 +3,7 @@
<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.17.1: http://docutils.sourceforge.net/" />
<link rel="index" title="Index" href="genindex.html" /><link rel="search" title="Search" href="search.html" /><link rel="next" title="osxphotos" href="overview.html" />
<link rel="index" title="Index" href="genindex.html" /><link rel="search" title="Search" href="search.html" /><link rel="next" title="OSXPhotos" href="overview.html" />
<meta name="generator" content="sphinx-4.4.0, furo 2022.04.07"/>
<title>osxphotos 0.47.10 documentation</title>
@ -156,12 +156,12 @@
</form>
<div id="searchbox"></div><div class="sidebar-scroll"><div class="sidebar-tree">
<ul>
<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"><a class="reference internal" href="template_help.html">osxphotos Template System</a></li>
<li class="toctree-l1"><a class="reference internal" href="package_overview.html">Example uses of the python package</a></li>
<li class="toctree-l1"><a class="reference internal" href="reference.html">osxphotos python API</a></li>
<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"><a class="reference internal" href="template_help.html">OSXPhotos Template System</a></li>
<li class="toctree-l1"><a class="reference internal" href="package_overview.html">Example uses of the OSXPhotos python package</a></li>
<li class="toctree-l1"><a class="reference internal" href="reference.html">OSXPhotos python API</a></li>
</ul>
</div>
@ -195,17 +195,17 @@
</div>
<article role="main">
<section id="welcome-to-osxphotos-s-documentation">
<h1>Welcome to osxphotos’s documentation!<a class="headerlink" href="#welcome-to-osxphotos-s-documentation" title="Permalink to this headline">#</a></h1>
<h1>Welcome to OSXPhotos’s documentation!<a class="headerlink" href="#welcome-to-osxphotos-s-documentation" title="Permalink to this headline">#</a></h1>
<div class="toctree-wrapper compound">
<ul>
<li class="toctree-l1"><a class="reference internal" href="overview.html">osxphotos</a><ul>
<li class="toctree-l2"><a class="reference internal" href="overview.html#what-is-osxphotos">What is osxphotos?</a></li>
<li class="toctree-l1"><a class="reference internal" href="overview.html">OSXPhotos</a><ul>
<li class="toctree-l2"><a class="reference internal" href="overview.html#what-is-osxphotos">What is OSXPhotos?</a></li>
<li class="toctree-l2"><a class="reference internal" href="overview.html#supported-operating-systems">Supported operating systems</a></li>
<li class="toctree-l2"><a class="reference internal" href="overview.html#installation">Installation</a></li>
<li class="toctree-l2"><a class="reference internal" href="overview.html#command-line-usage">Command Line Usage</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="tutorial.html">osxphotos Tutorial</a><ul>
<li class="toctree-l1"><a class="reference internal" href="tutorial.html">OSXPhotos Tutorial</a><ul>
<li class="toctree-l2"><a class="reference internal" href="tutorial.html#overview">Overview</a></li>
<li class="toctree-l2"><a class="reference internal" href="tutorial.html#export-your-photos">Export your photos</a></li>
<li class="toctree-l2"><a class="reference internal" href="tutorial.html#export-by-date">Export by date</a></li>
@ -230,7 +230,7 @@
<li class="toctree-l2"><a class="reference internal" href="tutorial.html#conclusion">Conclusion</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="cli.html">osxphotos Command Line Interface (CLI)</a><ul>
<li class="toctree-l1"><a class="reference internal" href="cli.html">OSXPhotos Command Line Interface (CLI)</a><ul>
<li class="toctree-l2"><a class="reference internal" href="cli.html#osxphotos">osxphotos</a><ul>
<li class="toctree-l3"><a class="reference internal" href="cli.html#osxphotos-about">about</a></li>
<li class="toctree-l3"><a class="reference internal" href="cli.html#osxphotos-albums">albums</a></li>
@ -258,12 +258,12 @@
</li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="template_help.html">osxphotos Template System</a><ul>
<li class="toctree-l1"><a class="reference internal" href="template_help.html">OSXPhotos Template System</a><ul>
<li class="toctree-l2"><a class="reference internal" href="template_help.html#id1">Template Substitutions</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="package_overview.html">Example uses of the python package</a></li>
<li class="toctree-l1"><a class="reference internal" href="reference.html">osxphotos python API</a></li>
<li class="toctree-l1"><a class="reference internal" href="package_overview.html">Example uses of the OSXPhotos python package</a></li>
<li class="toctree-l1"><a class="reference internal" href="reference.html">OSXPhotos python API</a></li>
</ul>
</div>
</section>
@ -286,7 +286,7 @@
<div class="context">
<span>Next</span>
</div>
<div class="title">osxphotos</div>
<div class="title">OSXPhotos</div>
</div>
<svg><use href="#svg-arrow-right"></use></svg>
</a>
@ -323,7 +323,7 @@
<div class="toc-tree-container">
<div class="toc-tree">
<ul>
<li><a class="reference internal" href="#">Welcome to osxphotos’s documentation!</a></li>
<li><a class="reference internal" href="#">Welcome to OSXPhotos’s documentation!</a></li>
<li><a class="reference internal" href="#indices-and-tables">Indices and tables</a></li>
</ul>

BIN
osxphotos/docs/objects.inv
View File

Binary file not shown.

27
osxphotos/docs/overview.html
View File

@ -3,10 +3,10 @@
<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.17.1: http://docutils.sourceforge.net/" />
<link rel="index" title="Index" href="genindex.html" /><link rel="search" title="Search" href="search.html" /><link rel="next" title="osxphotos Tutorial" href="tutorial.html" /><link rel="prev" title="Welcome to osxphotos’s documentation!" href="index.html" />
<link rel="index" title="Index" href="genindex.html" /><link rel="search" title="Search" href="search.html" /><link rel="next" title="OSXPhotos Tutorial" href="tutorial.html" /><link rel="prev" title="Welcome to OSXPhotos’s documentation!" href="index.html" />
<meta name="generator" content="sphinx-4.4.0, furo 2022.04.07"/>
<title>osxphotos - osxphotos 0.47.10 documentation</title>
<title>OSXPhotos - osxphotos 0.47.10 documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css" />
<link rel="stylesheet" type="text/css" href="_static/styles/furo.css?digest=68f4518137b9aefe99b631505a2064c3c42c9852" />
<link rel="stylesheet" type="text/css" href="_static/copybutton.css" />
@ -156,11 +156,12 @@
</form>
<div id="searchbox"></div><div class="sidebar-scroll"><div class="sidebar-tree">
<ul class="current">
<li class="toctree-l1 current current-page"><a class="current reference internal" href="#">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"><a class="reference internal" href="package_overview.html">Example uses of the python package</a></li>
<li class="toctree-l1"><a class="reference internal" href="reference.html">osxphotos python API</a></li>
<li class="toctree-l1 current current-page"><a class="current reference internal" href="#">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"><a class="reference internal" href="template_help.html">OSXPhotos Template System</a></li>
<li class="toctree-l1"><a class="reference internal" href="package_overview.html">Example uses of the OSXPhotos python package</a></li>
<li class="toctree-l1"><a class="reference internal" href="reference.html">OSXPhotos python API</a></li>
</ul>
</div>
@ -194,10 +195,10 @@
</div>
<article role="main">
<section id="osxphotos">
<h1>osxphotos<a class="headerlink" href="#osxphotos" title="Permalink to this headline">#</a></h1>
<h1>OSXPhotos<a class="headerlink" href="#osxphotos" title="Permalink to this headline">#</a></h1>
<section id="what-is-osxphotos">
<h2>What is osxphotos?<a class="headerlink" href="#what-is-osxphotos" title="Permalink to this headline">#</a></h2>
<p>osxphotos provides both the ability to interact with and query Apple’s Photos.app library on macOS directly from your python code
<h2>What is OSXPhotos?<a class="headerlink" href="#what-is-osxphotos" title="Permalink to this headline">#</a></h2>
<p>OSXPhotos provides both the ability to interact with and query Apple’s Photos.app library on macOS directly from your python code
as well as a very flexible command line interface (CLI) app for exporting photos.
You can query the Photos library database – for example, file name, file path, and metadata such as keywords/tags, persons/faces, albums, etc.
You can also easily export both the original and edited photos.</p>
@ -278,7 +279,7 @@ E.g. you can read a database created with Photos 5.0 on MacOS 10.15 on a machine
<div class="context">
<span>Next</span>
</div>
<div class="title">osxphotos Tutorial</div>
<div class="title">OSXPhotos Tutorial</div>
</div>
<svg><use href="#svg-arrow-right"></use></svg>
</a>
@ -325,8 +326,8 @@ E.g. you can read a database created with Photos 5.0 on MacOS 10.15 on a machine
<div class="toc-tree-container">
<div class="toc-tree">
<ul>
<li><a class="reference internal" href="#">osxphotos</a><ul>
<li><a class="reference internal" href="#what-is-osxphotos">What is osxphotos?</a></li>
<li><a class="reference internal" href="#">OSXPhotos</a><ul>
<li><a class="reference internal" href="#what-is-osxphotos">What is OSXPhotos?</a></li>
<li><a class="reference internal" href="#supported-operating-systems">Supported operating systems</a></li>
<li><a class="reference internal" href="#installation">Installation</a></li>
<li><a class="reference internal" href="#command-line-usage">Command Line Usage</a></li>

23
osxphotos/docs/package_overview.html
View File

@ -3,10 +3,10 @@
<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.17.1: http://docutils.sourceforge.net/" />
<link rel="index" title="Index" href="genindex.html" /><link rel="search" title="Search" href="search.html" /><link rel="next" title="osxphotos python API" href="reference.html" /><link rel="prev" title="osxphotos Command Line Interface (CLI)" href="cli.html" />
<link rel="index" title="Index" href="genindex.html" /><link rel="search" title="Search" href="search.html" /><link rel="next" title="OSXPhotos python API" href="reference.html" /><link rel="prev" title="OSXPhotos Template System" href="template_help.html" />
<meta name="generator" content="sphinx-4.4.0, furo 2022.04.07"/>
<title>Example uses of the python package - osxphotos 0.47.10 documentation</title>
<title>Example uses of the OSXPhotos python package - osxphotos 0.47.10 documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css" />
<link rel="stylesheet" type="text/css" href="_static/styles/furo.css?digest=68f4518137b9aefe99b631505a2064c3c42c9852" />
<link rel="stylesheet" type="text/css" href="_static/copybutton.css" />
@ -157,10 +157,11 @@
<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="#">Example uses of the python package</a></li>
<li class="toctree-l1"><a class="reference internal" href="reference.html">osxphotos python API</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"><a class="reference internal" href="template_help.html">OSXPhotos Template System</a></li>
<li class="toctree-l1 current current-page"><a class="current reference internal" href="#">Example uses of the OSXPhotos python package</a></li>
<li class="toctree-l1"><a class="reference internal" href="reference.html">OSXPhotos python API</a></li>
</ul>
</div>
@ -193,8 +194,8 @@
</label>
</div>
<article role="main">
<section id="example-uses-of-the-python-package">
<h1>Example uses of the python package<a class="headerlink" href="#example-uses-of-the-python-package" title="Permalink to this headline">#</a></h1>
<section id="example-uses-of-the-osxphotos-python-package">
<h1>Example uses of the OSXPhotos python package<a class="headerlink" href="#example-uses-of-the-osxphotos-python-package" title="Permalink to this headline">#</a></h1>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="sd">""" Simple usage of the package """</span>
<span class="kn">import</span> <span class="nn">osxphotos</span>
@ -321,18 +322,18 @@
<div class="context">
<span>Next</span>
</div>
<div class="title">osxphotos python API</div>
<div class="title">OSXPhotos python API</div>
</div>
<svg><use href="#svg-arrow-right"></use></svg>
</a>
<a class="prev-page" href="cli.html">
<a class="prev-page" href="template_help.html">
<svg><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 class="title">OSXPhotos Template System</div>
</div>
</a>

12
osxphotos/docs/py-modindex.html
View File

@ -154,12 +154,12 @@
</form>
<div id="searchbox"></div><div class="sidebar-scroll"><div class="sidebar-tree">
<ul>
<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"><a class="reference internal" href="template_help.html">osxphotos Template System</a></li>
<li class="toctree-l1"><a class="reference internal" href="package_overview.html">Example uses of the python package</a></li>
<li class="toctree-l1"><a class="reference internal" href="reference.html">osxphotos python API</a></li>
<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"><a class="reference internal" href="template_help.html">OSXPhotos Template System</a></li>
<li class="toctree-l1"><a class="reference internal" href="package_overview.html">Example uses of the OSXPhotos python package</a></li>
<li class="toctree-l1"><a class="reference internal" href="reference.html">OSXPhotos python API</a></li>
</ul>
</div>

17
osxphotos/docs/reference.html
View File

@ -3,10 +3,10 @@
<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.17.1: http://docutils.sourceforge.net/" />
<link rel="index" title="Index" href="genindex.html" /><link rel="search" title="Search" href="search.html" /><link rel="prev" title="Example uses of the python package" href="package_overview.html" />
<link rel="index" title="Index" href="genindex.html" /><link rel="search" title="Search" href="search.html" /><link rel="prev" title="Example uses of the OSXPhotos python package" href="package_overview.html" />
<meta name="generator" content="sphinx-4.4.0, furo 2022.04.07"/>
<title>osxphotos python API - osxphotos 0.47.10 documentation</title>
<title>OSXPhotos python API - osxphotos 0.47.10 documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css" />
<link rel="stylesheet" type="text/css" href="_static/styles/furo.css?digest=68f4518137b9aefe99b631505a2064c3c42c9852" />
<link rel="stylesheet" type="text/css" href="_static/copybutton.css" />
@ -157,10 +157,11 @@
<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"><a class="reference internal" href="package_overview.html">Example uses of the python package</a></li>
<li class="toctree-l1 current current-page"><a class="current reference internal" href="#">osxphotos python API</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"><a class="reference internal" href="template_help.html">OSXPhotos Template System</a></li>
<li class="toctree-l1"><a class="reference internal" href="package_overview.html">Example uses of the OSXPhotos python package</a></li>
<li class="toctree-l1 current current-page"><a class="current reference internal" href="#">OSXPhotos python API</a></li>
</ul>
</div>
@ -194,7 +195,7 @@
</div>
<article role="main">
<section id="module-osxphotos">
<span id="osxphotos-python-api"></span><h1>osxphotos python API<a class="headerlink" href="#module-osxphotos" title="Permalink to this headline">#</a></h1>
<span id="osxphotos-python-api"></span><h1>OSXPhotos python API<a class="headerlink" href="#module-osxphotos" title="Permalink to this headline">#</a></h1>
<dl class="py class">
<dt class="sig sig-object py" id="osxphotos.AlbumInfo">
<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">osxphotos.</span></span><span class="sig-name descname"><span class="pre">AlbumInfo</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">db</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">uuid</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/osxphotos/albuminfo.html#AlbumInfo"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#osxphotos.AlbumInfo" title="Permalink to this definition">#</a></dt>
@ -2894,7 +2895,7 @@ Projects are cards, calendars, slideshows, etc.</p>
<span>Previous</span>
</div>
<div class="title">Example uses of the python package</div>
<div class="title">Example uses of the OSXPhotos python package</div>
</div>
</a>

12
osxphotos/docs/search.html
View File

@ -153,12 +153,12 @@
</form>
<div id="searchbox"></div><div class="sidebar-scroll"><div class="sidebar-tree">
<ul>
<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"><a class="reference internal" href="template_help.html">osxphotos Template System</a></li>
<li class="toctree-l1"><a class="reference internal" href="package_overview.html">Example uses of the python package</a></li>
<li class="toctree-l1"><a class="reference internal" href="reference.html">osxphotos python API</a></li>
<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"><a class="reference internal" href="template_help.html">OSXPhotos Template System</a></li>
<li class="toctree-l1"><a class="reference internal" href="package_overview.html">Example uses of the OSXPhotos python package</a></li>
<li class="toctree-l1"><a class="reference internal" href="reference.html">OSXPhotos python API</a></li>
</ul>
</div>

2
osxphotos/docs/searchindex.js
View File

File diff suppressed because one or more lines are too long

28
osxphotos/docs/template_help.html
View File

@ -3,10 +3,10 @@
<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.17.1: http://docutils.sourceforge.net/" />
<link rel="index" title="Index" href="genindex.html" /><link rel="search" title="Search" href="search.html" /><link rel="next" title="Example uses of the python package" href="package_overview.html" /><link rel="prev" title="osxphotos Command Line Interface (CLI)" href="cli.html" />
<link rel="index" title="Index" href="genindex.html" /><link rel="search" title="Search" href="search.html" /><link rel="next" title="Example uses of the OSXPhotos python package" href="package_overview.html" /><link rel="prev" title="OSXPhotos Command Line Interface (CLI)" href="cli.html" />
<meta name="generator" content="sphinx-4.4.0, furo 2022.04.07"/>
<title>osxphotos Template System - osxphotos 0.47.10 documentation</title>
<title>OSXPhotos Template System - osxphotos 0.47.10 documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css" />
<link rel="stylesheet" type="text/css" href="_static/styles/furo.css?digest=68f4518137b9aefe99b631505a2064c3c42c9852" />
<link rel="stylesheet" type="text/css" href="_static/copybutton.css" />
@ -156,12 +156,12 @@
</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">Example uses of the python package</a></li>
<li class="toctree-l1"><a class="reference internal" href="reference.html">osxphotos python API</a></li>
<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">Example uses of the OSXPhotos python package</a></li>
<li class="toctree-l1"><a class="reference internal" href="reference.html">OSXPhotos python API</a></li>
</ul>
</div>
@ -195,7 +195,7 @@
</div>
<article role="main">
<section id="osxphotos-template-system">
<h1>osxphotos Template System<a class="headerlink" href="#osxphotos-template-system" title="Permalink to this headline">#</a></h1>
<h1>OSXPhotos Template System<a class="headerlink" href="#osxphotos-template-system" title="Permalink to this headline">#</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>
@ -246,7 +246,7 @@
<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 ‘` not operator value`’ 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>
<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>
@ -306,7 +306,7 @@
<col style="width: 50%"/>
</colgroup>
<thead>
<tr class="row-odd"><th class="head"><p>Substitution</p></th>
<tr class="row-odd"><th class="head"><p>Field</p></th>
<th class="head"><p>Description</p></th>
</tr>
</thead>
@ -644,7 +644,7 @@
<div class="context">
<span>Next</span>
</div>
<div class="title">Example uses of the python package</div>
<div class="title">Example uses of the OSXPhotos python package</div>
</div>
<svg><use href="#svg-arrow-right"></use></svg>
</a>
@ -655,7 +655,7 @@
<span>Previous</span>
</div>
<div class="title">osxphotos Command Line Interface (CLI)</div>
<div class="title">OSXPhotos Command Line Interface (CLI)</div>
</div>
</a>
@ -691,7 +691,7 @@
<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="#">OSXPhotos Template System</a><ul>
<li><a class="reference internal" href="#id1">Template Substitutions</a></li>
</ul>
</li>

24
osxphotos/docs/tutorial.html
View File

@ -3,10 +3,10 @@
<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.17.1: http://docutils.sourceforge.net/" />
<link rel="index" title="Index" href="genindex.html" /><link rel="search" title="Search" href="search.html" /><link rel="next" title="osxphotos Command Line Interface (CLI)" href="cli.html" /><link rel="prev" title="osxphotos" href="overview.html" />
<link rel="index" title="Index" href="genindex.html" /><link rel="search" title="Search" href="search.html" /><link rel="next" title="OSXPhotos Command Line Interface (CLI)" href="cli.html" /><link rel="prev" title="OSXPhotos" href="overview.html" />
<meta name="generator" content="sphinx-4.4.0, furo 2022.04.07"/>
<title>osxphotos Tutorial - osxphotos 0.47.10 documentation</title>
<title>OSXPhotos Tutorial - osxphotos 0.47.10 documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css" />
<link rel="stylesheet" type="text/css" href="_static/styles/furo.css?digest=68f4518137b9aefe99b631505a2064c3c42c9852" />
<link rel="stylesheet" type="text/css" href="_static/copybutton.css" />
@ -156,12 +156,12 @@
</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 current current-page"><a class="current reference internal" href="#">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"><a class="reference internal" href="template_help.html">osxphotos Template System</a></li>
<li class="toctree-l1"><a class="reference internal" href="package_overview.html">Example uses of the python package</a></li>
<li class="toctree-l1"><a class="reference internal" href="reference.html">osxphotos python API</a></li>
<li class="toctree-l1"><a class="reference internal" href="overview.html">OSXPhotos</a></li>
<li class="toctree-l1 current current-page"><a class="current reference internal" href="#">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"><a class="reference internal" href="template_help.html">OSXPhotos Template System</a></li>
<li class="toctree-l1"><a class="reference internal" href="package_overview.html">Example uses of the OSXPhotos python package</a></li>
<li class="toctree-l1"><a class="reference internal" href="reference.html">OSXPhotos python API</a></li>
</ul>
</div>
@ -195,7 +195,7 @@
</div>
<article role="main">
<!-- OSXPHOTOS-TUTORIAL-HEADER:START --><section id="osxphotos-tutorial">
<h1>osxphotos Tutorial<a class="headerlink" href="#osxphotos-tutorial" title="Permalink to this headline">#</a></h1>
<h1>OSXPhotos Tutorial<a class="headerlink" href="#osxphotos-tutorial" title="Permalink to this headline">#</a></h1>
<section id="overview">
<h2>Overview<a class="headerlink" href="#overview" title="Permalink to this headline">#</a></h2>
<!-- OSXPHOTOS-TUTORIAL-HEADER:END --><p>The design philosophy for osxphotos is “make the easy things easy and make the hard things possible”. To “make the hard things possible”, osxphotos is very flexible and has many, many configuration options – the <code class="docutils literal notranslate"><span class="pre">export</span></code> command for example, has over 100 command line options. Thus, osxphotos may seem daunting at first. The purpose of this tutorial is to explain a number of common use cases with examples and, hopefully, make osxphotos less daunting to use. osxphotos includes several commands for retrieving information from your Photos library but the one most users are interested in is the <code class="docutils literal notranslate"><span class="pre">export</span></code> command which exports photos from the library so that’s the focus of this tutorial.</p>
@ -508,7 +508,7 @@ template fields.
<div class="context">
<span>Next</span>
</div>
<div class="title">osxphotos Command Line Interface (CLI)</div>
<div class="title">OSXPhotos Command Line Interface (CLI)</div>
</div>
<svg><use href="#svg-arrow-right"></use></svg>
</a>
@ -519,7 +519,7 @@ template fields.
<span>Previous</span>
</div>
<div class="title">osxphotos</div>
<div class="title">OSXPhotos</div>
</div>
</a>
@ -555,7 +555,7 @@ template fields.
<div class="toc-tree-container">
<div class="toc-tree">
<ul>
<li><a class="reference internal" href="#">osxphotos Tutorial</a><ul>
<li><a class="reference internal" href="#">OSXPhotos Tutorial</a><ul>
<li><a class="reference internal" href="#overview">Overview</a></li>
<li><a class="reference internal" href="#export-your-photos">Export your photos</a></li>
<li><a class="reference internal" href="#export-by-date">Export by date</a></li>

139
osxphotos/phototemplate.cog.md Normal file
View File

@ -0,0 +1,139 @@
<!--[[[cog
# This file must be processed with `cog` to produce phototemplate.md
cog.out("<!" + "-- Generated by cog: see phototemplate.cog.md --" + ">\n")
]]]-->
<!--[[[end]]]-->
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.
Template statements may contain one or more modifiers. The full syntax is:
`"pretext{delim+template_field:subfield|filter(path_sep)[find,replace] conditional?bool_value,default}posttext"`
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}`.
`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.
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"`
`template_field`: The template field to resolve. See [Template Substitutions](#template-substitutions) for 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`.
`|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:
<!--[[[cog
from osxphotos.phototemplate import FILTER_VALUES
filter_help = "\n".join(f"- `{f}`: {descr}" for f, descr in FILTER_VALUES.items())
cog.out(filter_help)
]]]-->
- `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 <https://github.com/RhetTbull/osxphotos/blob/master/examples/template_filter.py>
<!--[[[end]]]-->
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"`
`(path_sep)`: optional path separator to use when joining path-like fields, for example `{folder_album}`. Default is "/".
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.
`?bool_value`: Template fields may be evaluated as boolean (True/False) by appending "?" after the field name (and following "(path_sep)" 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 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.
e.g. if photo is an HDR image,
- `"{hdr?ISHDR,NOTHDR}"` renders to `"ISHDR"`
and if it is not an HDR image,
- `"{hdr?ISHDR,NOTHDR}"` renders to `"NOTHDR"`
`,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.
e.g., if photo has no title set,
- `"{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`.
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"`
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.
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}"`.

17
osxphotos/phototemplate.md
View File

@ -1,4 +1,6 @@
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.
<!-- Generated by cog: see phototemplate.cog.md -->
The templating system converts one or template statements, written in osxphotos metadata templating language, to one or more rendered values using information from the photo being processed.
In its simplest form, a template statement has the form: `"{template_field}"`, for example `"{title}"` which would resolve to the title of the photo.
@ -10,7 +12,6 @@ Template statements are white-space sensitive meaning that white space (spaces,
`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
`+`: If present before template `name`, expands the template in place. If `delim` not provided, values are joined with no delimiter.
@ -22,7 +23,7 @@ e.g. if Photo keywords are `["foo","bar"]`:
- `"{; +keyword}"` renders to: `"foo; bar"`
- `"{+keyword}"` renders to `"foobar"`
`template_field`: The template field to resolve. See [Template Substitutions](#template-substitutions) for full list of template fields.
`template_field`: The template field to resolve. See [Template Substitutions](#template-substitutions) for 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`.
@ -30,7 +31,6 @@ e.g. if Photo keywords are `["foo","bar"]`:
Valid filters are:
<!-- OSXPHOTOS-FILTER-TABLE:START - Do not remove or modify this section -->
- `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'.
@ -41,7 +41,6 @@ Valid filters are:
- `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
<!-- OSXPHOTOS-FILTER-TABLE:END -->
e.g. if Photo keywords are `["FOO","bar"]`:
@ -64,7 +63,7 @@ e.g. If Photo is in `Album1` in `Folder1`:
`[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:
`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
@ -108,7 +107,7 @@ and if it is not an HDR image,
- `"{hdr?ISHDR,NOTHDR}"` renders to `"NOTHDR"`
`,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.
`,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.
e.g., if photo has no title set,
@ -121,10 +120,10 @@ 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"`
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.
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}"`.

13
osxphotos/phototemplate.py
View File

@ -1395,6 +1395,19 @@ def get_template_help():
return md
def get_template_field_table():
"""Return markdown table of template field substitutions"""
template_table = "| Field | Description |" + "\n|--------------|-------------|"
for subst, descr in [
*TEMPLATE_SUBSTITUTIONS.items(),
*TEMPLATE_SUBSTITUTIONS_MULTI_VALUED.items(),
]:
# replace '|' with '\|' to avoid markdown parsing issues (e.g. in {pipe} description)
descr = descr.replace("'|'", "'\|'")
template_table += f"\n|{subst}|{descr}|"
return template_table
def _get_pathlib_value(field, value, quote):
"""Get the value for a pathlib.Path type template

6
osxphotos/tutorial.md
View File

@ -1,6 +1,6 @@
<!-- OSXPHOTOS-TUTORIAL-HEADER:START -->
# osxphotos Tutorial
# OSXPhotos Tutorial
## Overview
@ -90,7 +90,7 @@ The osxphotos template system also allows for limited conditional logic of the t
Value immediately following comma will be used if <──────┘
template field is False or blank (null); in this case
no value is specified so a blank string "" will be used
Like with `--directory`, using a multi-valued template field such as `{keyword}` may result in more than one copy of a photo being exported. For example, if `IMG_1234.JPG` has keywords `Travel`, and `Vacation` and you run the following command:
`osxphotos export /path/to/export --filename "{keyword}-{original_name}"`
@ -171,7 +171,7 @@ This will write basic metadata such as keywords, persons, and GPS location to th
if photo is in Folder1/Folder2/Album, (>) produces
"Folder1>Folder2>Album" which some programs, such as
Lightroom Classic, treat as hierarchal keywords
The above command will write all the regular metadata that `--exiftool` normally writes to the file upon export but will also add an additional keyword in the exported metadata in the form "Folder1>Folder2>Album". If you did not include the `(>)` in the template string (e.g. `{folder_album}`), folder_album would render in form "Folder1/Folder2/Album".
A powerful feature of Photos is that it uses machine learning algorithms to automatically classify or label photos. These labels are used when you search for images in Photos but are not otherwise available to the user. osxphotos is able to read all the labels associated with a photo and makes those available through the template system via the `{label}`. Think of these as automatic keywords as opposed to the keywords you assign manually in Photos. One common use case is to use the automatic labels to create new keywords when exporting images so that these labels are embedded in the image's metadata:

46
utils/generate_template_docs.py
View File

@ -5,13 +5,8 @@ from click.testing import CliRunner
from osxphotos.cli import cli_main
from osxphotos.cli.help import strip_html_comments
from osxphotos.phototemplate import (
FILTER_VALUES,
TEMPLATE_SUBSTITUTIONS,
TEMPLATE_SUBSTITUTIONS_MULTI_VALUED,
)
from osxphotos.phototemplate import get_template_field_table, get_template_help
TEMPLATE_HELP = "osxphotos/phototemplate.md"
TUTORIAL_HELP = "osxphotos/tutorial.md"
TEMPLATE_HELP_DOC = "docsrc/source/template_help.md"
@ -25,26 +20,6 @@ TEMPLATE_HELP_START = (
)
TEMPLATE_HELP_STOP = "<!-- OSXPHOTOS-TEMPLATE-HELP:END -->"
TEMPLATE_FILTER_TABLE_START = (
"!-- OSXPHOTOS-FILTER-TABLE:START - Do not remove or modify this section -->"
)
TEMPLATE_FILTER_TABLE_STOP = "<!-- OSXPHOTOS-FILTER-TABLE:END -->"
def generate_template_table():
"""generate template substitution table for README.md"""
template_table = "| Substitution | Description |"
template_table += "\n|--------------|-------------|"
for subst, descr in [
*TEMPLATE_SUBSTITUTIONS.items(),
*TEMPLATE_SUBSTITUTIONS_MULTI_VALUED.items(),
]:
# replace '|' with '\|' to avoid markdown parsing issues (e.g. in {pipe} description)
descr = descr.replace("'|'", "'\|'")
template_table += f"\n|{subst}|{descr}|"
return template_table
def replace_text(text, start_tag, stop_tag, replacement_text, prefix="", postfix=""):
"""replace text between start/stop tags with new text
@ -81,27 +56,14 @@ def replace_text(text, start_tag, stop_tag, replacement_text, prefix="", postfix
def main():
"""generate docsrc/source/template_help.md"""
# update phototemplate.md with info on filters
filter_help = "\n".join(f"- `{f}`: {descr}" for f, descr in FILTER_VALUES.items())
with open(TEMPLATE_HELP) as file:
template_help = file.read()
template_help = replace_text(
template_help,
TEMPLATE_FILTER_TABLE_START,
TEMPLATE_FILTER_TABLE_STOP,
filter_help,
prefix="\n",
postfix="\n",
)
template_help = get_template_help()
# Add header
template_help = "# osxphotos Template System\n\n" + template_help
template_help = "# OSXPhotos Template System\n\n" + template_help
# Add the template substitution table
print("Adding template substitution table")
template_help += "\n\n## Template Substitutions\n\n"
template_table = generate_template_table()
template_table = get_template_field_table()
template_help += template_table
template_help = strip_html_comments(template_help)

50
utils/update_readme.py
View File

@ -15,13 +15,8 @@ import re
from click.testing import CliRunner
from osxphotos.cli import cli_main
from osxphotos.phototemplate import (
FILTER_VALUES,
TEMPLATE_SUBSTITUTIONS,
TEMPLATE_SUBSTITUTIONS_MULTI_VALUED,
)
from osxphotos.phototemplate import get_template_field_table, get_template_help
TEMPLATE_HELP = "osxphotos/phototemplate.md"
TUTORIAL_HELP = "osxphotos/tutorial.md"
USAGE_START = (
@ -39,11 +34,6 @@ TEMPLATE_HELP_START = (
)
TEMPLATE_HELP_STOP = "<!-- OSXPHOTOS-TEMPLATE-HELP:END -->"
TEMPLATE_FILTER_TABLE_START = (
"!-- OSXPHOTOS-FILTER-TABLE:START - Do not remove or modify this section -->"
)
TEMPLATE_FILTER_TABLE_STOP = "<!-- OSXPHOTOS-FILTER-TABLE:END -->"
TUTORIAL_START = "<!-- OSXPHOTOS-TUTORIAL:START -->"
TUTORIAL_STOP = "<!-- OSXPHOTOS-TUTORIAL:END -->"
@ -53,20 +43,7 @@ TUTORIAL_HEADER_STOP = "<!-- OSXPHOTOS-TUTORIAL-HEADER:END -->"
TEMPLATE_SYSTEM_LINK_START = "<!-- OSXPHOTOS-TEMPLATE-SYSTEM-LINK:START -->"
TEMPLATE_SYSTEM_LINK_STOP = "<!-- OSXPHOTOS-TEMPLATE-SYSTEM-LINK:END -->"
def generate_template_table():
"""generate template substitution table for README.md"""
template_table = "| Substitution | Description |"
template_table += "\n|--------------|-------------|"
for subst, descr in [
*TEMPLATE_SUBSTITUTIONS.items(),
*TEMPLATE_SUBSTITUTIONS_MULTI_VALUED.items(),
]:
# replace '|' with '\|' to avoid markdown parsing issues (e.g. in {pipe} description)
descr = descr.replace("'|'", "'\|'")
template_table += f"\n|{subst}|{descr}|"
return template_table
API_README = "API_README.md"
def generate_help_text(command):
@ -117,23 +94,6 @@ def replace_text(text, start_tag, stop_tag, replacement_text, prefix="", postfix
def main():
"""update README.md"""
# update phototemplate.md with info on filters
print(f"Updating {TEMPLATE_HELP}")
filter_help = "\n".join(f"- `{f}`: {descr}" for f, descr in FILTER_VALUES.items())
with open(TEMPLATE_HELP) as file:
template_help = file.read()
template_help = replace_text(
template_help,
TEMPLATE_FILTER_TABLE_START,
TEMPLATE_FILTER_TABLE_STOP,
filter_help,
prefix="\n",
postfix="\n",
)
with open(TEMPLATE_HELP, "w") as file:
file.write(template_help)
# update the help text for `osxphotos help export`
print("Updating help for `osxphotos help export`")
@ -146,7 +106,7 @@ def main():
# update the template substitution table
print("Updating template substitution table")
template_table = generate_template_table()
template_table = get_template_field_table()
new_readme = replace_text(
new_readme,
TEMPLATE_TABLE_START,
@ -157,9 +117,7 @@ def main():
)
# update the template system docs
print("Updating template system help")
with open(TEMPLATE_HELP) as fd:
template_help = fd.read()
template_help = get_template_help()
new_readme = replace_text(
new_readme,