labm8.fs

High level filesystem interface.

exception labm8.fs.Error
exception labm8.fs.File404
labm8.fs.abspath(*components)

Get an absolute file path.

Concatenate all components into an absolute path.

labm8.fs.basename(*components)

Return the basename of a given file path.

labm8.fs.cd(path)

Change working directory.

Returns absolute path to new working directory.

labm8.fs.cdpop()

Return the last directory.

Returns absolute path to new working directory.

labm8.fs.cp(src, dst)

Copy a file or directory.

If source is a directory, this recursively copies the directory and its contents. If the destination is a directory, then this creates a copy of the source in the destination directory with the same basename.

If the destination already exists, this will attempt to overwrite it.

Parameters:
  • src (string) – path to the source file or directory.
  • dst (string) – path to the destination file or directory.
Raises:

IOError – if source does not exist.
labm8.fs.dirname(*components)

Return the directory name of a given file path.

labm8.fs.du(*components, **kwargs)

Get the size of a file in bytes or as a human-readable string.

Parameters:
  • *components (str[]) – Path to file.
  • **kwargs – If “human_readable” is True, return a formatted string, e.g. “976.6 KiB” (default True)
Returns:

If “human_readble” kwarg is True, return str, else int.
Return type:

int or str
labm8.fs.exists(*components)

Return whether a file exists.

labm8.fs.files_from_list(*paths)

Return a list of all file paths from a list of files or directories.

For each path in the input: if it is a file, return it; if it is a directory, return a list of files in the directory.

Parameters:paths (list of str) – List of file and directory paths.
Returns:Absolute file paths.
Return type:list of str
Raises:File404 – If any of the paths do not exist.
labm8.fs.is_subdir(child, parent)

Determine if “child” is a subdirectory of “parent”.

If child == parent, returns True.

labm8.fs.isdir(*components)

Return whether a path exists, and is a directory.

labm8.fs.isexe(*components)

Return whether a path is an executable file.

Parameters:path (str) – Path of the file to check.

Examples

>>> fs.isexe("/bin/ls")
True

>>> fs.isexe("/home")
False

>>> fs.isexe("/not/a/real/path")
False
Returns:True if file is executable, else false.
Return type:bool
labm8.fs.isfile(*components)

Return whether a path exists, and is a file.

labm8.fs.ls(root='.', abspaths=False, recursive=False)

Return a list of files in directory.

Directory listings are sorted alphabetically. If the named directory is a file, return it’s path.

Examples

>>> fs.ls("foo")
["a", "b", "c"]

>>> fs.ls("foo/a")
["foo/a"]

>>> fs.ls("foo", abspaths=True)
["/home/test/foo/a", "/home/test/foo/b", "/home/test/foo/c"]

>>> fs.ls("foo", recursive=True)
["a", "b", "b/d", "b/d/e", "c"]
Parameters:
  • root (str) – Path to directory. Can be relative or absolute.
  • abspaths (bool, optional) – Return absolute paths if true.
  • recursive (bool, optional) – Recursively list subdirectories if true.
Returns:

A list of paths.
Return type:

list of str
Raises:

OSError – If root directory does not exist.
labm8.fs.lsdirs(root='.', **kwargs)

Return only subdirectories from a directory listing.

Parameters:
  • root (str) – Path to directory. Can be relative or absolute.
  • **kwargs – Any additional arguments to be passed to ls().
Returns:

A list of directory paths.
Return type:

list of str
Raises:

OSError – If root directory does not exist.
labm8.fs.lsfiles(root='.', **kwargs)

Return only files from a directory listing.

Parameters:
  • root (str) – Path to directory. Can be relative or absolute.
  • **kwargs – Any additional arguments to be passed to ls().
Returns:

A list of file paths.
Return type:

list of str
Raises:

OSError – If root directory does not exist.
labm8.fs.mkdir(*components, **kwargs)

Make directory “path”, including any required parents. If directory already exists, do nothing.

labm8.fs.mkopen(p, *args, **kwargs)

A wrapper for the open() builtin which makes parent directories if needed.

labm8.fs.must_exist(*components)

Ensure path exists.

Parameters:*components (str[]) – Path components.
Returns:File path.
Return type:str
Raises:File404 – If path does not exist.
labm8.fs.mv(src, dst)

Move a file or directory.

If the destination already exists, this will attempt to overwrite it.

Parameters:
  • src (string) – path to the source file or directory.
  • dst (string) – path to the destination file or directory.
Raises:
  • File404 – if source does not exist.
  • IOError – in case of error.
labm8.fs.path(*components)

Get a file path.

Concatenate all components into a path.

labm8.fs.pwd()

Return the path to the current working directory.

labm8.fs.read(*components, **kwargs)

Read file and return a list of lines. If comment_char is set, ignore the contents of lines following the comment_char.

Raises:IOError – if reading path fails
labm8.fs.read_file(path)

Read file to string.

Parameters:path (str) – Source.
labm8.fs.rm(*components, **kwargs)

Remove a file or directory.

If path is a directory, this recursively removes the directory and any contents. Non-existent paths are silently ignored.

Supports Unix style globbing by default (disable using glob=False). For details on globbing pattern expansion, see:

Parameters:
  • *components (string[]) – path to the file or directory to remove. May be absolute or relative. May contain unix glob
  • **kwargs – if “glob” is True, perform Unix style pattern expansion of paths (default: True).
labm8.fs.rmtrash(*components)

Move a file or directory to trash.

If file does not exist, nothing happens.

Examples

>>> fs.rmtrash("foo", "bar")

>>> fs.rmtrash("/home/labm8/file.txt")
Parameters:*components (string[]) – path to the file or directory.
labm8.fs.write_file(path, contents)

Write string to file.

Parameters:
  • path (str) – Destination.
  • contents (str) – Contents.