cement.utils.fs

Common File System Utilities.

class cement.utils.fs.Tmp(**kwargs: str)

Bases: object

Provides creation and cleanup of a separate temporary directory, and file.

Keyword Arguments:

• cleanup (bool) – Whether or not to delete the temporary directory and file on exit (when used with the with operator).

• suffix (str) – The suffix that the directory and file will end with. Default: no suffix

• prefix (str) – The prefix that the directory and file will start with. Default: no prefix

• dir (str) – The parent directory path that the temp directory and file will be created in. Default: system default temporary path

Example

from cement.utils import fs

with fs.Tmp() as tmp:
    # do something with a temporary directory
    os.path.listdir(tmp.dir)

    # do something with a temporary file
    with open(tmp.file, 'w') as f:
        f.write('some data')

remove() → None

Remove the temporary directory (and file) if it exists, and self.cleanup is True.

cement.utils.fs.abspath(path: str, strip_trailing_slash: bool = True) → str

Return an absolute path, while also expanding the ~ user directory shortcut.

Parameters:

path (str) – The original path to expand.

Returns:

The fully expanded, absolute path to the given path

Return type:

str

Example

from cement.utils import fs

fs.abspath('~/some/path')
fs.abspath('./some.file')

cement.utils.fs.backup(path: str, suffix: str = '.bak', **kwargs: Any) → str | None

Rename a file or directory safely without overwriting an existing backup of the same name.

Parameters:

• path (str) – The path to the file or directory to make a backup of.

• suffix (str) – The suffix to rename files with.

Keyword Arguments:

• timestamp (bool) – whether to add a timestamp to the backup suffix

• timestamp_format (str) – Date-Time format in python datetime.datetime notation. default ‘%Y-%m-%d-%H:%M:%S’

Returns:

The new path of backed up file/directory

Return type:

str

Example

from cement.utils import fs

fs.backup('/path/to/original/file')

cement.utils.fs.ensure_dir_exists(path: str) → None

Ensure the directory path exists, and if not create it.

Parameters:

path (str) – The filesystem path of a directory.

Raises:

• AssertionError – If the directory path exists, but is not a

• directory. –

Returns: None

cement.utils.fs.ensure_parent_dir_exists(path: str) → None

Ensure the parent directory of path (file, or directory) exists, and if not create it.

Parameters:

path (str) – The filesystem path of a file or directory.

Returns: None

cement.utils.fs.join(*args: str, **kwargs: Any) → str

Return a complete, joined path, by first calling abspath() on the first item to ensure the final path is complete.

Parameters:

paths (list) – A list of paths to join together.

Returns:

The complete and absolute joined path.

Return type:

list

Example

from cement.utils import fs

fs.join('~/some/path', 'some/other/relevant/paht')

cement.utils.fs.join_exists(*paths: str) → tuple[str, bool]

Wrapper around os.path.join(), os.path.abspath(), and os.path.exists().

Parameters:

paths (list) – List of paths to join, and then return True if that path exists, or False if it does not.

Returns:

First item is the fully joined absolute path, and the second

is bool (whether that path exists or not).

Return type:

tuple