Path Mapper

Operations relating to mapping and re-mapping of paths.

Classes:

PathMapper()	Simple path mapper which extracts paths from File objects.
PathStemMapper([stem_map, available_paths])	A more complex path mapper which attempts to replace the stems of paths from strings and File objects.

class musify.file.path_mapper.PathMapper

Bases: PrettyPrinter

Simple path mapper which extracts paths from File objects. Can be extended by child classes for more complex mapping operations.

Methods:

map(value[, check_existence])	Map the given value by either extracting the path from a File object, or returning the value as is, assuming it is a string.
map_many(values[, check_existence])	Run map() operation on many values only returning those values that are not None or empty.
unmap(value[, check_existence])	Map the given value by either extracting the path from a File object, or returning the value as is, assuming it is a string.
unmap_many(values[, check_existence])	Run unmap() operation on many values only returning those values that are not None or empty.
as_dict()	Return a dictionary representation of the key attributes of this object.

map(value, check_existence=False)

Map the given value by either extracting the path from a File object, or returning the value as is, assuming it is a string.

Parameters:

• value (str | File | None) – The value to extract a path from.

• check_existence (bool (default: False)) – When True, check the path exists before returning it. If it doesn’t exist, returns None.

Returns:

str | None – The path if check_existence is False, or if check_existence is True and path exists, None otherwise.

map_many(values, check_existence=False)

Run map() operation on many values only returning those values that are not None or empty.

Return type:

list[str]

unmap(value, check_existence=False)

Map the given value by either extracting the path from a File object, or returning the value as is, assuming it is a string.

Parameters:

• value (str | File | None) – The value to extract a path from.

• check_existence (bool (default: False)) – When True, check the path exists before returning it. If it doesn’t exist, returns None.

Returns:

str | None – The path if check_existence is False, or if check_existence is True and path exists, None otherwise.

unmap_many(values, check_existence=False)

Run unmap() operation on many values only returning those values that are not None or empty.

Return type:

list[str]

as_dict()

Return a dictionary representation of the key attributes of this object.

Return type:

dict[str, Any]

The results of this function are used to produce the following:

• A JSON representation of the object when calling json()

• The string representation of the object when calling str() on the object

• The representation of the object when calling repr() on the object

class musify.file.path_mapper.PathStemMapper(stem_map=None, available_paths=())

Bases: PathMapper

A more complex path mapper which attempts to replace the stems of paths from strings and File objects. Plus, attempts to case-correct paths.

Useful for cross-platform support. Can be used to correct paths if the same file exists in different locations according to different mounts and/or multiple operating systems.

Attributes:

stem_unmap	A map of {<replacement stems>: <stem to be replaced>} i.e. just the opposite map of stem_map.
stem_map	A map of {<stem to be replaced>: <its replacement>}.
available_paths	A map of the available paths stored in this object.

Methods:

map(value[, check_existence])	Map the given value by replacing its stem according to stored stem_map, correcting path separators according to the separators of the replacement stem, and case correcting path from stored available_paths.
unmap(value[, check_existence])	Map the given value by replacing its stem according to stored stem_unmap, correcting path separators according to the separators of the replacement stem, and case correcting path from stored available_paths (i.e. mostly the reverse of map()).
as_dict()	Return a dictionary representation of the key attributes of this object.

property stem_unmap: dict[str, str]

A map of {<replacement stems>: <stem to be replaced>} i.e. just the opposite map of stem_map. Assign new values to stem_map to update.

property stem_map: dict[str, str]

A map of {<stem to be replaced>: <its replacement>}. Assigning new values to this property updates itself plus the stem_unmap property with the reverse of this map.

property available_paths: dict[str, str]

A map of the available paths stored in this object. Simply {<lower-case path>: <correctly-cased path>}. When assigning new values to this property, the stored map will update itself with the new values rather than overwrite.

map(value, check_existence=False)

Map the given value by replacing its stem according to stored stem_map, correcting path separators according to the separators of the replacement stem, and case correcting path from stored available_paths.

Parameters:

• value (str | File | None) – The value to map.

• check_existence (bool (default: False)) – When True, check the path exists before returning it. If it doesn’t exist, returns None.

Returns:

str | None – The path if check_existence is False, or if check_existence is True and path exists, None otherwise.

unmap(value, check_existence=False)

Map the given value by replacing its stem according to stored stem_unmap, correcting path separators according to the separators of the replacement stem, and case correcting path from stored available_paths (i.e. mostly the reverse of map()).

Parameters:

• value (str | File | None) – The value to map.

• check_existence (bool (default: False)) – When True, check the path exists before returning it. If it doesn’t exist, returns None.

Returns:

str | None – The path if check_existence is False, or if check_existence is True and path exists, None otherwise.

as_dict()

Return a dictionary representation of the key attributes of this object.

Return type:

dict[str, Any]

The results of this function are used to produce the following:

• A JSON representation of the object when calling json()

• The string representation of the object when calling str() on the object

• The representation of the object when calling repr() on the object