Utils

Utilities for paths.

disseminate.paths.utils.find_file(path, context, raise_error=True)

Search for an existing file given the path and, if needed, the ‘paths’ entry from a context.

Parameters
pathUnion[str, pathlib.Path]

The path stub to search.

contextcontext.Context

The document’s context with an entry of ‘paths’ to search.

raise_errorOptional[bool]

If True (default), raise error if a file isn’t found.

Returns
valid_pathpathlib.Path

A path for a file that exists.

Raises
FileNotFoundError

Raised if the file could not be found.

disseminate.paths.utils.find_files(string, context)

Determine if filenames for valid files are present in the given string.

Parameters
stringstr

The string that may contain filenames

contextDocumentContext

A document context that contains paths to search.

Returns
filepathsList[pathlib.Path]

List of found paths

disseminate.paths.utils.rename(path, filename=None, append=None, extension=None)

Rename the filename from a path with optional modifiers.

Parameters
pathUnion[str, pathlib.Path]

The path to rename

filenameOptional[str]

The new filename to rename the filename (without the extension)

appendOptional[str]

If specified, add the string to the filename

extensionOptional[str]

If specified, replace the extension with the given extension

Returns
new_pathpathlib.Path

The new path with the filename renamed.

Examples

>>> rename('/tmp/ch1_file.png', filename='test')
PosixPath('/tmp/test.png')
>>> rename('/tmp/ch1_file.png', append='_crop2')
PosixPath('/tmp/ch1_file_crop2.png')
>>> rename('/tmp/ch1_file.png', append='_crop2', extension='ext')
PosixPath('/tmp/ch1_file_crop2.ext')
>>> rename('/tmp/ch1.1_file.png', filename='test')
PosixPath('/tmp/test.png')
>>> rename('/tmp/ch1.1_file.png', filename='test', append='_crop2')
PosixPath('/tmp/test_crop2.png')
>>> rename('/tmp/ch1.1_file.png', filename='test', append='_crop2',
...        extension='svg')
PosixPath('/tmp/test_crop2.svg')
>>> rename('/tmp/ch1.1_file', extension='html')  # this won't work
PosixPath('/tmp/ch1.html')