From aa64283b558c38b9c242d32b9013b00b0ae5d54b Mon Sep 17 00:00:00 2001 From: Rhet Turnbull Date: Tue, 6 Jul 2021 12:17:02 -0700 Subject: [PATCH] Updated README.md [skip ci], closes #488 --- README.md | 29 ++++++++++++++++++----------- 1 file changed, 18 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 1b48297e..fcceb205 100644 --- a/README.md +++ b/README.md @@ -2843,24 +2843,31 @@ Then If overwrite=False and increment=False, export will fail if destination file already exists -#### `render_template()` - -`render_template(template_str, none_str = "_", path_sep = None, expand_inplace = False, inplace_sep = None, filename=False, dirname=False, strip=False)` +#### `render_template(template_str, options=None)` Render template string for photo. none_str is used if template substitution results in None value and no default specified. - `template_str`: str in osxphotos template language (OTL) format. See also [Template System](#template-system) table. See notes below regarding specific details of the syntax. -- `none_str`: optional str to use as substitution when template value is None and no default specified in the template string. default is "_". -- `path_sep`: optional character to use as path separator when joining path like fields such as `{folder_album}`; default is `os.path.sep`. May also be provided in the template itself. If provided both in the call to `render_template()` and in the template itself, the value in the template string takes precedence. -- `expand_inplace`: expand multi-valued substitutions in-place as a single string instead of returning individual strings -- `inplace_sep`: optional string to use as separator between multi-valued keywords with expand_inplace; default is ',' -- `filename`: if True, template output will be sanitized to produce valid file name -- `dirname`: if True, template output will be sanitized to produce valid directory name -- `strip`: if True, leading/trailign whitespace will be stripped from rendered template strings +- `options`: an optional osxphotos.phototemplate.RenderOptions object specifying the options to pass to the rendering engine. + +`RenderOptions` has the following properties: + +- template: str template +- none_str: str to use default for None values, default is '_' +- path_sep: optional string to use as path separator, default is os.path.sep +- expand_inplace: expand multi-valued substitutions in-place as a single string instead of returning individual strings +- inplace_sep: optional string to use as separator between multi-valued keywords with expand_inplace; default is ',' +- filename: if True, template output will be sanitized to produce valid file name +- dirname: if True, template output will be sanitized to produce valid directory name +- strip: if True, strips leading/trailing whitespace from rendered templates +- edited_version: set to True if you want {edited_version} to resolve to True (e.g. exporting edited version of photo) +- export_dir: set to the export directory if you want to evalute {export_dir} template +- filepath: set to value for filepath of the exported photo if you want to evaluate {filepath} template +- quote: quote path templates for execution in the shell Returns a tuple of (rendered, unmatched) where rendered is a list of rendered strings with all substitutions made and unmatched is a list of any strings that resembled a template substitution but did not match a known substitution. E.g. if template contained "{foo}", unmatched would be ["foo"]. If there are unmatched strings, rendered will be []. E.g. a template statement must fully match or will result in error and return all unmatched fields in unmatched. -e.g. `render_template("{created.year}/{foo}", photo)` would return `([],["foo"])` +e.g. `photo.render_template("{created.year}/{foo}")` would return `([],["foo"])` Some substitutions, notably `album`, `keyword`, and `person` could return multiple values, hence a new string will be return for each possible substitution (hence why a list of rendered strings is returned). For example, a photo in 2 albums: 'Vacation' and 'Family' would result in the following rendered values if template was "{created.year}/{album}" and created.year == 2020: `["2020/Vacation","2020/Family"]`