maestral.utils.path

This module contains functions for common path operations.

Module Contents

Functions

is_fs_case_sensitive(path: str) → bool

Checks if path lies on a partition with a case-sensitive file system.

is_child(path: str, parent: str) → bool

Checks if path semantically is inside parent. Neither path needs to

is_equal_or_child(path: str, parent: str) → bool

Checks if path semantically is inside parent or equals parent. Neither

cased_path_candidates(path: str, root: str = osp.sep, is_fs_case_sensitive: bool = True) → List[str]

Returns a list of cased versions of the given path as far as corresponding nodes

to_cased_path(path: str, root: str = osp.sep, is_fs_case_sensitive: bool = True) → str

Returns a cased version of the given path as far as corresponding nodes (with

to_existing_cased_path(path: str, root: str = osp.sep, is_fs_case_sensitive: bool = True) → str

Returns a cased version of the given path if corresponding nodes (with arbitrary

path_exists_case_insensitive(path: str, root: str = osp.sep, is_fs_case_sensitive: bool = True) → bool

Checks if a path exists in given root directory, similar to

generate_cc_name(path: str, suffix: str = 'conflicting copy', is_fs_case_sensitive: bool = True) → str

Generates a path for a conflicting copy of path. The file name is created by

delete(path: str, raise_error: bool = False) → Optional[OSError]

Deletes a file or folder at path.

move(src_path: str, dest_path: str, raise_error: bool = False, preserve_dest_permissions=False) → Optional[OSError]

Moves a file or folder from src_path to dest_path. If either the source or

content_hash(local_path: str, chunk_size: int = 1024) → Tuple[Optional[str], Optional[float]]

Computes content hash of a local file.

maestral.utils.path.is_fs_case_sensitive(path: str)bool[source]

Checks if path lies on a partition with a case-sensitive file system.

Parameters

path – Path to check.

Returns

Whether path lies on a partition with a case-sensitive file system.

maestral.utils.path.is_child(path: str, parent: str)bool[source]

Checks if path semantically is inside parent. Neither path needs to refer to an actual item on the drive. This function is case sensitive.

Parameters
  • path – Item path.

  • parent – Parent path.

Returns

Whether path semantically lies inside parent.

maestral.utils.path.is_equal_or_child(path: str, parent: str)bool[source]

Checks if path semantically is inside parent or equals parent. Neither path needs to refer to an actual item on the drive. This function is case sensitive.

Parameters
  • path – Item path.

  • parent – Parent path.

Returns

True if path semantically lies inside parent or path == parent.

maestral.utils.path.cased_path_candidates(path: str, root: str = osp.sep, is_fs_case_sensitive: bool = True) → List[str][source]

Returns a list of cased versions of the given path as far as corresponding nodes exist in the given root directory. For instance, if a case sensitive root directory contains two folders “/parent/subfolder/child” and “/parent/Subfolder/child”, there will be two matches for “/parent/subfolder/child/file.txt”. If the root directory does not exist, only one candidate os.path.join(root, path) is returned.

Parameters
  • path – Original path relative to root.

  • root – Parent directory to search in. There are significant performance improvements if a root directory with a small tree is given.

  • is_fs_case_sensitive – Bool indicating if the file system is case sensitive. If False, we know that there can be at most one match and choose a faster algorithm.

Returns

Candidates for correctly cased local paths.

maestral.utils.path.to_cased_path(path: str, root: str = osp.sep, is_fs_case_sensitive: bool = True)str[source]

Returns a cased version of the given path as far as corresponding nodes (with arbitrary casing) exist in the given root directory. If multiple matches are found, only one is returned. If path does not exist in root root or root does not exist, the return value will be os.path.join(root, path).

Parameters
  • path – Original path relative to root.

  • root – Parent directory to search in. There are significant performance improvements if a root directory with a small tree is given.

  • is_fs_case_sensitive – Bool indicating if the file system is case sensitive. If False, we know that there can be at most one match and choose a faster algorithm.

Returns

Absolute and cased version of given path.

maestral.utils.path.to_existing_cased_path(path: str, root: str = osp.sep, is_fs_case_sensitive: bool = True)str[source]

Returns a cased version of the given path if corresponding nodes (with arbitrary casing) exist in the given root directory. If multiple matches are found, only one is returned.

Parameters
  • path – Original path relative to root.

  • root – Parent directory to search in. There are significant performance improvements if a root directory with a small tree is given.

  • is_fs_case_sensitive – Bool indicating if the file system is case sensitive. If False, we know that there can be at most one match and choose a faster algorithm.

Returns

Absolute and cased version of given path.

Raises

FileNotFoundError – if path does not exist in root root or root itself does not exist.

maestral.utils.path.path_exists_case_insensitive(path: str, root: str = osp.sep, is_fs_case_sensitive: bool = True)bool[source]

Checks if a path exists in given root directory, similar to os.path.exists but case-insensitive.

Parameters
  • path – Path relative to root.

  • root – Directory where we will look for path. There are significant performance improvements if a root directory with a small tree is given.

  • is_fs_case_sensitive – Bool indicating if the file system is case sensitive. If False, we know that there can be at most one match and choose a faster algorithm.

Returns

Whether an arbitrarily cased version of path exists.

maestral.utils.path.generate_cc_name(path: str, suffix: str = 'conflicting copy', is_fs_case_sensitive: bool = True)str[source]

Generates a path for a conflicting copy of path. The file name is created by inserting the given suffix between the the filename and extension. For instance:

“my_file.txt” -> “my_file (conflicting copy).txt”

If a file with the resulting path already exists (case-insensitive!), we additionally append an integer number, for instance:

“my_file.txt” -> “my_file (conflicting copy 1).txt”

Parameters
  • path – Original path name.

  • suffix – Suffix to use. Defaults to “conflicting copy”.

  • is_fs_case_sensitive – Bool indicating if the file system is case sensitive. If False, we know that there can be at most one match and choose a faster algorithm.

Returns

New path.

maestral.utils.path.delete(path: str, raise_error: bool = False) → Optional[OSError][source]

Deletes a file or folder at path.

Parameters
  • path – Path of item to delete.

  • raise_error – If True, raise any OSErrors. If False, catch OSErrors and return them.

Returns

Any caught exception during the deletion.

maestral.utils.path.move(src_path: str, dest_path: str, raise_error: bool = False, preserve_dest_permissions=False) → Optional[OSError][source]

Moves a file or folder from src_path to dest_path. If either the source or the destination path no longer exist, this function does nothing. Any other exceptions are either raised or returned if raise_error is False.

Parameters
  • src_path – Path of item to move.

  • dest_path – Destination path. Any existing file at this path will be replaced by the move. Any existing empty folder will be replaced if the source is also a folder.

  • raise_error – If True, raise any OSErrors. If False, catch OSErrors and return them.

  • preserve_dest_permissions – If True, attempt to preserve the permissions of any file at the destination. If False, the permissions of src_path will be used.

Returns

Any caught exception during the move.

maestral.utils.path.content_hash(local_path: str, chunk_size: int = 1024) → Tuple[Optional[str], Optional[float]][source]

Computes content hash of a local file.

Parameters
  • local_path – Absolute path on local drive.

  • chunk_size – Size of chunks to hash in bites.

Returns

Content hash to compare with Dropbox’s content hash and mtime just before the hash was computed.