wholecell.utils.filepath

filepath.py File and filename path utilities.

wholecell.utils.filepath.git_branch()[source]

Return the source code git branch name, or the environment variable $IMAGE_GIT_BRANCH if there’s no git repo (in a Docker Image), or ‘–‘.

wholecell.utils.filepath.git_hash()[source]

Return the source code git hash, or the environment variable $IMAGE_GIT_HASH if there’s no git repo (in a Docker Image), or else ‘–‘.

wholecell.utils.filepath.iter_variants(variant_type, first_index, last_index)[source]

Generate Variant subdirs (index, name) over [first .. last] inclusive.

Parameters:
  • variant_type (str)

  • first_index (int)

  • last_index (int)

Return type:

Generator[tuple[int, str], None, None]

wholecell.utils.filepath.makedirs(path, *paths)[source]

Join one or more path components, make that directory path (using the default mode 0o0777), and return the full path.

Raise FileExistsError if there’s a file (not a directory) with that path. No exception if the directory already exists.

Parameters:
Return type:

str

wholecell.utils.filepath.read_json_file(filename)[source]

Read and parse JSON file. This supports Unicode.

Parameters:

filename (str)

Return type:

Any

wholecell.utils.filepath.run_cmd(tokens, trim=True, timeout=60, env=None, input_=None)[source]

Run a shell command-line (in token list form) and return its stdout. See run_cmd2().

Parameters:
Return type:

str

wholecell.utils.filepath.run_cmd2(tokens, trim=True, timeout=60, env=None, input_=None)[source]

Run a shell command-line (in token list form) and return a tuple containing its (stdout, stderr). This does not expand filename patterns or environment variables or do other shell processing steps.

Parameters:
  • tokens (list[str]) – The command line as a list of string tokens.

  • trim (bool) – Whether to trim off trailing whitespace. This is useful because the outputs usually end with a newline.

  • timeout (int) – timeout in seconds; None for no timeout.

  • env (dict | None) – optional environment variables for the new process to use instead of inheriting the current process’ environment.

  • input – input for any prompts that may appear (passed to the subprocess’ stdin)

  • input_ (str | None)

Returns:

The command’s stdout and stderr strings.

Raises:
Return type:

tuple[str, str]

wholecell.utils.filepath.run_cmdline(line, trim=True, timeout=60, input_=None, fallback=None)[source]

Run a shell command-line string then return its output or fallback if it failed. This does not expand filename patterns or environment variables or do other shell processing steps like quoting.

Parameters:
  • line (str) – The command line as a string to split.

  • trim (bool) – Whether to trim off trailing whitespace. This is useful because the subprocess output usually ends with a newline.

  • timeout (int) – timeout in seconds; None for no timeout.

  • input – input for any prompts that may appear (passed to the subprocess’ stdin)

  • fallback (str | None) – Return this if the subprocess fails, e.g. trying to run git in a Docker Image that has no git repo.

  • input_ (str | None)

Returns:

The command’s output string, or None if it couldn’t even run.

Return type:

str | None

wholecell.utils.filepath.timestamp(dt=None)[source]

Construct a datetime-timestamp from dt [default = now()], such as we use to timestamp a simulation output directory.

Parameters:

dt (datetime | None)

Return type:

str

wholecell.utils.filepath.verify_dir_exists(dir_path, message='')[source]

Raise an IOError if dir_path isn’t an existing directory.

Parameters:
  • dir_path (str)

  • message (str)

wholecell.utils.filepath.verify_file_exists(file_path, message='')[source]

Raise an IOError if file_path isn’t an existing file.

Parameters:
  • file_path (str)

  • message (str)

wholecell.utils.filepath.write_file(filename, content)[source]

Write text string content as a utf-8 text file.

Parameters:
  • filename (str)

  • content (str)

wholecell.utils.filepath.write_json_file(filename, obj, indent=4)[source]

Write obj to a file in a pretty JSON format. This supports Unicode.

Parameters: