Updated README.md [skip ci], closes #488

README.md

@@ -2843,24 +2843,31 @@ Then
 If overwrite=False and increment=False, export will fail if destination file already exists
 
 
-#### <a name="rendertemplate">`render_template()`</a>
+#### <a name="rendertemplate">`render_template(template_str, options=None)`</a>
-
-`render_template(template_str, none_str = "_", path_sep = None, expand_inplace = False, inplace_sep = None, filename=False, dirname=False, strip=False)`
 
 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 "_".
+- `options`: an optional osxphotos.phototemplate.RenderOptions object specifying the options to pass to the rendering engine.
-- `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
+`RenderOptions` has the following properties:
-- `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
+- template: str template
-- `dirname`: if True, template output will be sanitized to produce valid directory name
+- none_str: str to use default for None values, default is '_'
-- `strip`: if True, leading/trailign whitespace will be stripped from rendered template strings
+- 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"]`