Democritus File System (Files and Directories)

Democritus functions^[1] for working with files and directories.

[1] Democritus functions are simple, effective, modular, well-tested, and well-documented Python functions.

We use d8s (pronounced "dee-eights") as an abbreviation for democritus (you can read more about this here).

Installation

pip install d8s-file-system

Usage

You import the library like:

from d8s_file_system import *

Once imported, you can use any of the functions listed below.

Functions

• def is_file(path: str) -> bool:
      """Determine if the given path is a file."""
  

• def file_read(file_path: str) -> str:
      """Read the file at the given file_path as a string."""
  

• def file_read_bytes(file_path: str) -> bytes:
      """Read the file at the given file_path as bytes."""
  

• def file_write(file_path: str, file_contents: Any) -> bool:
      """Write the given content to the file at the given path (including a file name)."""
  

• def file_append(file_path: str, file_contents: Any) -> bool:
      """Append the given content to the file at the given path (including a file name)."""
  

• def file_move(starting_path: str, destination_path: str):
      """Move the file from the starting path to the destination path."""
  

• def file_copy(starting_path: str, destination_path: str, *, preserve_metadata: bool = False):
      """Copy the file from the starting_path to the destination path."""
  

• def file_delete(file_path: str):
      """Delete the given file."""
  

• def file_owner_name(file_path: str) -> str:
      """Find the owner of the file at the given path."""
  

• def file_change_owner(file_path: str):
      """Change the ownership of the given file."""
  

• def file_ssdeep(file_path: str) -> str:
      """Find the ssdeep fuzzy hash of the file."""
  

• def file_md5(file_path: str) -> str:
      """Find the md5 hash of the given file."""
  

• def file_sha1(file_path: str) -> str:
      """Find the sha1 hash of the given file."""
  

• def file_sha256(file_path: str) -> str:
      """Find the sha256 hash of the given file."""
  

• def file_sha512(file_path: str) -> str:
      """Find the sha512 hash of the given file."""
  

• def file_name_escape(file_name_arg: str) -> str:
      """Escape the name of a file so that it can be used as a file name in a file path."""
  

• def file_name(file_path: str) -> str:
      """Find the file name from the given file path."""
  

• def file_name_windows(windows_file_path: str) -> str:
      """Find the file name from the given windows_file_path."""
  

• def file_name_unix(unix_file_path: str) -> str:
      """Find the file name from the given unix_file_path."""
  

• def file_size(file_path: str) -> int:
      """Find the file size."""
  

• def file_directory(file_path: str) -> str:
      """Return the directory in which the given file resides."""
  

• def file_details(file_path: str) -> Dict[str, Union[str, int]]:
      """Get file hashes and file size for the given file."""
  

• def file_exists(file_path: str) -> bool:
      """Check if the file exists."""
  

• def file_is_readable(file_path: str) -> bool:
      """Check if the file is readable."""
  

• def file_is_writable(file_path: str) -> bool:
      """Check if the file is writable."""
  

• def file_is_executable(file_path: str) -> bool:
      """Check if the file is executable."""
  

• def file_contains(file_path: str, pattern: str, *, pattern_is_regex: bool = False) -> bool:
      """Return whether or not the file contains the given pattern."""
  

• def file_search(file_path: str, pattern: str, *, pattern_is_regex: bool = False) -> List[str]:
      """Search for the given pattern in the file."""
  

• def file_name_matches(file_path: str, pattern: str) -> bool:
      """Return whether or not the file name contains the given pattern."""
  

• def is_directory(path: str) -> bool:
      """Determine if the given path is a directory."""
  

• def directory_exists(directory_path: str) -> bool:
      """Check if the directory exists."""
  

• def directory_file_names(directory_path: str, *, recursive: bool = False) -> List[str]:
      """List files at the given directory_path."""
  

• def directory_file_paths(directory_path: str, *, recursive: bool = False) -> List[str]:
      """List the file paths at the given directory_path."""
  

• def directory_copy(src_path: str, dst_path: str):
      """Copy the directory from the src_path to the destination path."""
  

• def directory_delete(directory_path: str):
      """Delete the given directory."""
  

• def directory_create(directory_path: str, mode=0o777):
      """Create a directory."""
  

• def directory_disk_usage(directory_path: str):
      """Return the disk usage for the given directory."""
  

• def directory_disk_free_space(directory_path: str):
      """Return the free space in the given directory."""
  

• def directory_disk_used_space(directory_path: str):
      """Return the used space in the given directory."""
  

• def directory_disk_total_space(directory_path: str):
      """Return the total space in the given directory."""
  

• def home_directory() -> str:
      """Return the home directory."""
  

• def home_directory_join(path: str) -> str:
      """Join the given path with the home directory."""
  

• def directory_move(src_path: str, dst_path: str):
      """Move the directory from the src_path to the dst_path."""
  

• def directory_files_details(directory_path: str, *, recursive: bool = False) -> Dict[str, Dict[str, Union[str, int]]]:
      """Return the file details for each file in the directory at the given path."""
  

• def directory_files_read(directory_path: str, *, recursive: bool = False) -> Iterable[Tuple[str, str]]:
      """Read all files in the directory_path."""
  

• def directory_subdirectory_names(directory_path: str, *, recursive: bool = False) -> List[str]:
      """List the names of all subdirectories in the given directory."""
  

• def directory_files_containing(
      directory_path: str, pattern: str, *, pattern_is_regex: bool = False, recursive: bool = False
  ) -> Dict[str, List[str]]:
      """Search for the given pattern in all files in the given directory_path."""
  

• def directory_file_paths_matching(directory_path: str, pattern: str, *, recursive: bool = False) -> List[str]:
      """Return the paths of all of the files in the given directory which match the pattern."""
  

• def directory_file_names_matching(directory_path: str, pattern: str, *, recursive: bool = False) -> List[str]:
      """Return the names of all of the files in the given directory which match the pattern."""
  

• def directory_read_files_with_path_matching(
      directory_path: str, pattern: str, *, recursive: bool = False
  ) -> Iterable[Tuple[str, str]]:
      """Read all of the files in the given directory whose paths match the given pattern."""
  

• def atomic_write(fpath, *, overwrite: bool = True, **cls_kwargs):
      """Create a context manager to write atomically using the AtomicWriterPerms class to update file permissions."""
  

Development

👋  If you want to get involved in this project, we have some short, helpful guides below:

• contribute to this project 🥇
• test it 🧪
• lint it 🧹
• explore it 🔭

If you have any questions or there is anything we did not cover, please raise an issue and we'll be happy to help.

Credits

This package was created with Cookiecutter and Floyd Hightower's Python project template.