Skip to main content

high-level file-system operations for lazy devs.

Project description

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_tar_file

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

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_tar_file

# Extract tar 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_tar_file(path, dest, content_paths=None, autodelete=False)

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_permissions

# Get the file/directory permissions.
permissions = fsutil.get_permissions(path)

get_unique_name

# Get a unique name for a directory/file at 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="**/*.*")

set_permissions

# Set the file/directory permissions.
fsutil.set_permissions(path, 700)

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)

transform_filepath

# Trasform a filepath by applying the provided optional changes.
filepath = fsutil.transform_filepath(path, dirpath=None, basename=lambda b: slugify(b), extension="webp")

write_file

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

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, encoding="utf-8", atomic=False, 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

  • :star: Star this project on GitHub
  • :octocat: Follow me on GitHub
  • :blue_heart: Follow me on Twitter
  • :moneybag: Sponsor me on Github

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. 🧢

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

python_fsutil-0.15.0.tar.gz (29.7 kB view details)

Uploaded Source

Built Distribution

python_fsutil-0.15.0-py3-none-any.whl (20.9 kB view details)

Uploaded Python 3

File details

Details for the file python_fsutil-0.15.0.tar.gz.

File metadata

  • Download URL: python_fsutil-0.15.0.tar.gz
  • Upload date:
  • Size: 29.7 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.12.8

File hashes

Hashes for python_fsutil-0.15.0.tar.gz
Algorithm Hash digest
SHA256 b51d8ab7ee218314480ea251fff7fef513be4fbccfe72a5af4ff2954f8a4a2c4
MD5 3e75d4c80b0e5de7da31ee9f0245f00d
BLAKE2b-256 f94a494de3f8b079f077d687f7b3e32b963f7613eaae2d7b5c1be34d7eafd19a

See more details on using hashes here.

Provenance

The following attestation bundles were made for python_fsutil-0.15.0.tar.gz:

Publisher: create-release.yml on fabiocaccamo/python-fsutil

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file python_fsutil-0.15.0-py3-none-any.whl.

File metadata

  • Download URL: python_fsutil-0.15.0-py3-none-any.whl
  • Upload date:
  • Size: 20.9 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.12.8

File hashes

Hashes for python_fsutil-0.15.0-py3-none-any.whl
Algorithm Hash digest
SHA256 8ae31def522916e35caf67723b8526fe6e5fcc1e160ea2dc23c845567708ca6e
MD5 20c49b435b6518ca0f6bec7eeb516878
BLAKE2b-256 33defc2c3fa9d1f29c017c8eba2448efe86495b762111cf613a4c6d860158970

See more details on using hashes here.

Provenance

The following attestation bundles were made for python_fsutil-0.15.0-py3-none-any.whl:

Publisher: create-release.yml on fabiocaccamo/python-fsutil

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page