--post-function signature should return optional list of file paths

[RhetTbull]

--post-function function signature should return an optional list of of files created or modified by the function. This would allow these files to be incorporated with --cleanup and --report.

• update function signature
• update ExportResults to add user_file and user_error
• update example function & docs to show new fields for ExportResults

If signature was None | list[tuple[str, str]] then user function could return (filepath, error) for logging in the report alongside other errors.

Reference discussion:
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]:
    ...

Originally posted by @RhetTbull in #1133 (reply in thread)

[RhetTbull]

Could also allow for return of an error string that could be logged and reported -> tuple[list[str], str | None] | None

[RhetTbull]

Completed in v0.62.0

[RhetTbull]

Implemented by allowing the user function to return ExportResults with new user_error and user_written, user_skipped fields.