Custom sidecars

[RhetTbull]

@neilpa suggested a new feature (#1123) to allow custom sidecars. This is now implemented in v0.61.0.

Custom sidecars can be defined using a Mako template. The Mako sidecar template is passed three variables:

• photo: a PhotoInfo object for the photo being exported
• photo_path: a pathlib.Path object for the photo file being exported
• sidecar_path: a pathlib.Path object for the sidecar file being written

There are three example Mako sidecars in the examples directory:

• custom_sidecar.mako: creates a simple text file with a few details.
• custom_sidecar_xmp.mako: creates an XMP sidecar
• custom_sidecar_json.mako: creates a JSON sidecar with the full JSON dump of the PhotoInfo object for the photo (everything osxphotos knows about the. photo).

Because the PhotoInfo object is available to the sidecar template, this last example is as simple as:

${photo.json(shallow=False, indent=4)}

This is definitely a niche option but it might be very useful for creating and sharing sidecars for specific apps. If you create any sidecars that might be useful for other osxphotos users please share them here.

Note that version 0.61.0 has one potentially breaking change if you --report report.csv --append to append to a CSV formatted report as the report now includes a new column name user_sidecar so I suggest you archive your existing report and create a new one. JSON and SQlite reports should continue to work fine (but will include the new field for all added data).

You can create multiple sidecars by repeating the --sidecar-template option. The generated sidecars are fully integrated into --update, --cleanup, and --report options however, you must specify in the --sidecar-template options the behavior for --update. The two options currently available are to skip the sidecar if the photo is skipped or to regenerate the sidecar if the photo is skipped. Unlike with the built in sidecars, osxphotos does not know about the contents of the sidecar and thus cannot determine at run time whether a specific sidecar should be updated. Thus if you use custom sidecars with --update, you may increase the run time of current export sets as the sidecars might be generated for every photo every time the export is run. See osxphotos help export sidecar-template for additional information on usage.

[neilpa]

photo_path: a pathlib.Path object for the photo file being exported

Is it guaranteed that the photo is already exported when the sidecar template is rendered? Having the exported images available may be useful in some situations.

[RhetTbull]

Yes. The sidecar is generated after the export happens.

[RhetTbull]

Hmmmm...but if write_skipped=True, then I need to check to see if skipped file is always there. I think that's the case otherwise file wouldn't be skipped. If source is missing file would be missing, not skipped

[RhetTbull]

If you're generating something that's not really a sidecar, like generating a GIF, a more elegant solution would be to update the --post-function function signature to return a list of files generated and these would be added to cleanup to keep and also added to reports as a user_file column. This could be done with backwards compatibility using:

# current signature
def post_function(
    photo: PhotoInfo, results: ExportResults, verbose: Callable, **kwargs
):
    ...

# new signature
def post_function(
    photo: PhotoInfo, results: ExportResults, verbose: Callable, **kwargs
) -> None | list[str]:
    ...

[neilpa]

Yea, that's a better approach for the crazy hypothetical I proposed in the other thread.

[RhetTbull]

Added new issue #1136 to implement this

[RhetTbull]

I've refactored the --sidecar-template option to take a comma-separated list of options instead of a list of booleans. This should make it easier to use and to modify in the future. Will be released after I include some other fixes I'm working on.

--sidecar-template MAKO_TEMPLATE_FILE SIDECAR_FILENAME_TEMPLATE OPTIONS
                                Create a custom sidecar file for each photo exported with user provided Mako
                                template (MAKO_TEMPLATE_FILE). MAKO_TEMPLATE_FILE must be a valid Mako
                                template (see https://www.makotemplates.org/). The template will passed the
                                following variables: photo (PhotoInfo object for the photo being exported),
                                sidecar_path (pathlib.Path object for the path to the sidecar being
                                written), and photo_path (pathlib.Path object for the path to the exported
                                photo. SIDECAR_FILENAME_TEMPLATE must be a valid template string (see
                                Templating System in help) which will be rendered to generate the filename
                                of the sidecar file. The `{filepath}` template variable may be used in the
                                SIDECAR_FILENAME_TEMPLATE to refer to the filename of the photo being
                                exported. OPTIONS is a comma-separated list of strings providing additional
                                options to the template. Valid options are: write_skipped, strip_whitespace,
                                strip_lines, none. write_skipped will cause the sidecar file to be written
                                even if the photo is skipped during export. If write_skipped is not passed
                                as an option, the sidecar file will not be written if the photo is skipped
                                during export. strip_whitespace and strip_lines indicate whether or not to
                                strip whitespace and blank lines, respectively, from the resulting sidecar
                                file. For example, to create a sidecar file with extension .xmp using a
                                template file named 'sidecar.mako' and write a sidecar for skipped photos
                                and strip blank lines but not whitespace: `--sidecar-
                                template sidecar.mako '{filepath}.xmp'
                                write_skipped,strip_lines`. To do the same but to drop the photo extension
                                from the sidecar filename: `--sidecar-template
                                sidecar.mako '{filepath.parent}/{filepath.stem}.xmp'
                                write_skipped,strip_lines`. If you are not passing any options, you must
                                pass 'none' as the last argument to --sidecar-template: `--sidecar-template
                                sidecar.mako '{filepath}.xmp' none`. For an example Mako file see https://ra
                                w.githubusercontent.com/RhetTbull/osxphotos/main/examples/custom_sidecar.mak
                                o

[RhetTbull]

In v0.62.0 I've changed the way this works to allow named options instead of the boolean options.

--sidecar-template MAKO_TEMPLATE_FILE SIDECAR_FILENAME_TEMPLATE OPTIONS

OPTIONS is a comma-separated list of strings providing additional
options to the template. Valid options are: write_skipped, strip_whitespace,
strip_lines, skip_zero, catch_errors, none. write_skipped will cause the
sidecar file to be written even if the photo is skipped during export. If
write_skipped is not passed as an option, the sidecar file will not be
written if the photo is skipped during export. strip_whitespace and
strip_lines indicate whether or not to strip whitespace and blank lines,
respectively, from the resulting sidecar file. skip_zero causes the sidecar
file to be skipped if the rendered template is zero-length. catch_errors
causes errors in the template to be caught and logged but not raised.
Without catch_errors, osxphotos will abort the export if an error occurs in
the template.