Skip to content

fabiocaccamo/python-fsutil

main
Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.

python-fsutil

high-level file-system operations for lazy devs.

Installation

pip install python-fsutil

Usage

Just import the main module and call its methods.

import fsutil

Methods

assert_dir

# Raise an OSError if the given path doesn't exist or it is not a directory.
fsutil.assert_dir(path)

assert_exists

# Raise an OSError if the given path doesn't exist.
fsutil.assert_exists(path)

assert_file

# Raise an OSError if the given path doesn't exist or it is not a file.
fsutil.assert_file(path)

assert_not_dir

# Raise an OSError if the given path is an existing directory.
fsutil.assert_not_dir(path)

assert_not_exists

# Raise an OSError if the given path already exists.
fsutil.assert_not_exists(path)

assert_not_file

# Raise an OSError if the given path is an existing file.
fsutil.assert_not_file(path)

clean_dir

# Clean a directory by removing empty sub-directories and/or empty files.
fsutil.clean_dir(path, dirs=True, files=True)

convert_size_bytes_to_string

# Convert the given size bytes to string using the right unit suffix.
size_str = fsutil.convert_size_bytes_to_string(size)

convert_size_string_to_bytes

# Convert the given size string to bytes.
size_bytes = fsutil.convert_size_string_to_bytes(size)

copy_dir

# Copy the directory at the given path and all its content to dest path.
# If overwrite is not allowed and dest path exists, an OSError is raised.
# More informations about kwargs supported options here:
# https://docs.python.org/3/library/shutil.html#shutil.copytree
fsutil.copy_dir(path, dest, overwrite=False, **kwargs)

copy_dir_content

# Copy the content of the directory at the given path to dest path.
# More informations about kwargs supported options here:
# https://docs.python.org/3/library/shutil.html#shutil.copytree
fsutil.copy_dir_content(path, dest, **kwargs)

copy_file

# Copy the file at the given path and its metadata to dest path.
# If overwrite is not allowed and dest path exists, an OSError is raised.
# More informations about kwargs supported options here:
# https://docs.python.org/3/library/shutil.html#shutil.copy2
fsutil.copy_file(path, dest, overwrite=False, **kwargs)

create_dir

# Create directory at the given path.
# If overwrite is not allowed and path exists, an OSError is raised.
fsutil.create_dir(path, overwrite=False)

create_file

# Create file with the specified content at the given path.
# If overwrite is not allowed and path exists, an OSError is raised.
fsutil.create_file(path, content="", overwrite=False)

create_zip_file

# Create zip file at path compressing directories/files listed in content_paths.
# If overwrite is allowed and dest zip already exists, it will be overwritten.
fsutil.create_zip_file(path, content_paths, overwrite=True, compression=zipfile.ZIP_DEFLATED)

delete_dir

# Alias for remove_dir.
fsutil.delete_dir(path)

delete_dir_content

# Alias for remove_dir_content.
fsutil.delete_dir_content(path)

delete_dirs

# Alias for remove_dirs.
fsutil.delete_dirs(*paths)

delete_file

# Alias for remove_file.
fsutil.delete_file(path)

delete_files

# Alias for remove_files.
fsutil.delete_files(*paths)

download_file

# Download a file from url to the given dirpath and return the filepath.
# If dirpath is not provided, the file will be downloaded to a temp directory.
# If filename is provided, the file will be named using filename.
# It is possible to pass extra request options (eg. for authentication) using **kwargs.
filepath = fsutil.download_file(url, dirpath=None, filename="archive.zip", chunk_size=8192, **kwargs)

exists

# Check if a directory of a file exists at the given path.
value = fsutil.exists(path)

extract_zip_file

# Extract zip file at path to dest path.
# If autodelete, the archive will be deleted after extraction.
# If content_paths list is defined, only listed items will be extracted, otherwise all.
fsutil.extract_zip_file(path, dest, content_paths=None, autodelete=False)

get_dir_creation_date

# Get the directory creation date.
date = fsutil.get_dir_creation_date(path)

get_dir_creation_date_formatted

# Get the directory creation date formatted using the given format.
date_str = fsutil.get_dir_creation_date_formatted(path, format='%Y-%m-%d %H:%M:%S')

get_dir_hash

# Get the hash of the directory at the given path using
# the specified algorithm function (md5 by default).
hash = fsutil.get_dir_hash(path, func="md5")

get_dir_last_modified_date

# Get the directory last modification date.
date = fsutil.get_dir_last_modified_date(path)

get_dir_last_modified_date_formatted

# Get the directory last modification date formatted using the given format.
date_str = fsutil.get_dir_last_modified_date_formatted(path, format="%Y-%m-%d %H:%M:%S")

get_dir_size

# Get the directory size in bytes.
size = fsutil.get_dir_size(path)

get_dir_size_formatted

# Get the directory size formatted using the right unit suffix.
size_str = fsutil.get_dir_size_formatted(path)

get_file_basename

# Get the file basename from the given path/url.
basename = fsutil.get_file_basename(path)

get_file_creation_date

# Get the file creation date.
date = fsutil.get_file_creation_date(path)

get_file_creation_date_formatted

# Get the file creation date formatted using the given format.
date_str = fsutil.get_file_creation_date_formatted(path, format="%Y-%m-%d %H:%M:%S")

get_file_extension

# Get the file extension from the given path/url.
extension = fsutil.get_file_extension(path)

get_file_hash

# Get the hash of the file at the given path using
# the specified algorithm function (md5 by default).
filehash = fsutil.get_file_hash(path, func="md5")

get_file_last_modified_date

# Get the file last modification date.
date = fsutil.get_file_last_modified_date(path)

get_file_last_modified_date_formatted

# Get the file last modification date formatted using the given format.
date_str = fsutil.get_file_last_modified_date_formatted(path, format="%Y-%m-%d %H:%M:%S")

get_file_size

# Get the file size in bytes.
size = fsutil.get_file_size(path)

get_file_size_formatted

# Get the file size formatted using the right unit suffix.
size_str = fsutil.get_file_size_formatted(path)

get_filename

# Get the filename from the given path/url.
filename = fsutil.get_filename(path)

get_parent_dir

# Get the parent directory for the given path going up N levels.
parent_dir = fsutil.get_parent_dir(path, levels=1)

get_unique_name

# Gets a unique name for a directory/file ath the given directory path.
unique_name = fsutil.get_unique_name(path, prefix="", suffix="", extension="", separator="-")

is_dir

# Determine whether the specified path represents an existing directory.
value = fsutil.is_dir(path)

is_empty

# Determine whether the specified path represents an empty directory or an empty file.
value = fsutil.is_empty(path)

is_empty_dir

# Determine whether the specified path represents an empty directory.
value = fsutil.is_empty_dir(path)

is_empty_file

# Determine whether the specified path represents an empty file.
value = fsutil.is_empty_file(path)

is_file

# Determine whether the specified path represents an existing file.
value = fsutil.is_file(path)

join_filename

# Create a filename joining the file basename and the extension.
filename = fsutil.join_filename(basename, extension)

join_filepath

# Create a filepath joining the directory path and the filename.
filepath = fsutil.join_filepath(dirpath, filename)

join_path

# Create a path joining path and paths.
# If path is __file__ (or a .py file), the resulting path will be relative
# to the directory path of the module in which it's used.
path = fsutil.join_path(path, *paths)

list_dirs

# List all directories contained at the given directory path.
dirs = fsutil.list_dirs(path)

list_files

# List all files contained at the given directory path.
files = fsutil.list_files(path)

make_dirs

# Create the directories needed to ensure that the given path exists.
# If a file already exists at the given path an OSError is raised.
fsutil.make_dirs(path)

make_dirs_for_file

# Create the directories needed to ensure that the given path exists.
# If a directory already exists at the given path an OSError is raised.
fsutil.make_dirs_for_file(path)

move_dir

# Move an existing dir from path to dest directory.
# If overwrite is not allowed and dest path exists, an OSError is raised.
# More informations about kwargs supported options here:
# https://docs.python.org/3/library/shutil.html#shutil.move
fsutil.move_dir(path, dest, overwrite=False, **kwargs)

move_file

# Move an existing file from path to dest directory.
# If overwrite is not allowed and dest path exists, an OSError is raised.
# More informations about kwargs supported options here:
# https://docs.python.org/3/library/shutil.html#shutil.move
fsutil.move_file(path, dest, overwrite=False, **kwargs)

read_file

# Read the content of the file at the given path using the specified encoding.
content = fsutil.read_file(path, encoding="utf-8")

read_file_from_url

# Read the content of the file at the given url.
content = fsutil.read_file_from_url(url, **kwargs)

read_file_json

# Read and decode a json encoded file at the given path.
data = fsutil.read_file_json(path, cls=None, object_hook=None, parse_float=None, parse_int=None, parse_constant=None, object_pairs_hook=None)

read_file_lines

# Read file content lines.
# It is possible to specify the line indexes (negative indexes too),
# very useful especially when reading large files.
content = fsutil.read_file_lines(path, line_start=0, line_end=-1, strip_white=True, skip_empty=True, encoding="utf-8")

read_file_lines_count

# Read file lines count.
lines_count = fsutil.read_file_lines_count(path)

remove_dir

# Remove a directory at the given path and all its content.
# If the directory is removed with success returns True, otherwise False.
# More informations about kwargs supported options here:
# https://docs.python.org/3/library/shutil.html#shutil.rmtree
fsutil.remove_dir(path, **kwargs)

remove_dir_content

# Removes all directory content (both sub-directories and files).
fsutil.remove_dir_content(path)

remove_dirs

# Remove multiple directories at the given paths and all their content.
fsutil.remove_dirs(*paths)

remove_file

# Remove a file at the given path.
# If the file is removed with success returns True, otherwise False.
fsutil.remove_file(path)

remove_files

# Remove multiple files at the given paths.
fsutil.remove_files(*paths)

rename_dir

# Rename a directory with the given name.
# If a directory or a file with the given name already exists, an OSError is raised.
fsutil.rename_dir(path, name)

rename_file

# Rename a file with the given name.
# If a directory or a file with the given name already exists, an OSError is raised.
fsutil.rename_file(path, name)

rename_file_basename

# Rename a file basename with the given basename.
fsutil.rename_file_basename(path, basename)

rename_file_extension

# Rename a file extension with the given extension.
fsutil.rename_file_extension(path, extension)

replace_dir

# Replace directory at the specified path with the directory located at src.
# If autodelete, the src directory will be removed at the end of the operation.
# Optimized for large directories.
fsutil.replace_dir(path, src, autodelete=False)

replace_file

# Replace file at the specified path with the file located at src.
# If autodelete, the src file will be removed at the end of the operation.
# Optimized for large files.
fsutil.replace_file(path, src, autodelete=False)

search_dirs

# Search for directories at path matching the given pattern.
dirs = fsutil.search_dirs(path, pattern="**/*")

search_files

# Search for files at path matching the given pattern.
files = fsutil.search_files(path, pattern="**/*.*")

split_filename

# Split a filename and returns its basename and extension.
basename, extension = fsutil.split_filename(path)

split_filepath

# Split a filename and returns its directory-path and filename.
dirpath, filename = fsutil.split_filepath(path)

split_path

# Split a path and returns its path-names.
path_names = fsutil.split_path(path)

write_file

# Write file with the specified content at the given path.
fsutil.write_file(path, content, append=False, encoding="utf-8")

write_file_json

# Write a json file at the given path with the specified data encoded in json format.
fsutil.write_file_json(path, data, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, cls=None, indent=None, separators=None, default=None, sort_keys=False)

Testing

# clone repository
git clone https://github.com/fabiocaccamo/python-fsutil.git && cd python-fsutil

# create virtualenv and activate it
python -m venv venv && . venv/bin/activate

# upgrade pip
python -m pip install --upgrade pip

# install requirements
python -m pip install -r requirements.txt -r requirements-test.txt

# install pre-commit to run formatters and linters
pre-commit install --install-hooks

# run tests using tox
tox

# or run tests using unittest
python -m unittest

License

Released under MIT License.


Supporting

See also

  • python-benedict - dict subclass with keylist/keypath support, I/O shortcuts (base64, csv, json, pickle, plist, query-string, toml, xml, yaml) and many utilities. 📘

  • python-fontbro - friendly font operations on top of fontTools. 🧢