python-fsutil 0.14.0__tar.gz → 0.15.0__tar.gz

{python-fsutil-0.14.0/python_fsutil.egg-info → python_fsutil-0.15.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.2
 Name: python-fsutil
-Version: 0.14.0
+Version: 0.15.0
 Summary: high-level file-system operations for lazy devs.
 Author-email: Fabio Caccamo <fabio.caccamo@gmail.com>
 Maintainer-email: Fabio Caccamo <fabio.caccamo@gmail.com>
@@ -42,11 +42,10 @@ Classifier: License :: OSI Approved :: MIT License
 Classifier: Natural Language :: English
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.8
-Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: Implementation :: PyPy
 Classifier: Topic :: Desktop Environment :: File Managers
 Classifier: Topic :: Software Development :: Build Tools
@@ -507,7 +506,7 @@ permissions = fsutil.get_permissions(path)
 #### `get_unique_name`
 
 ```python
-# Get a unique name for a directory/file ath the given directory path.
+# Get a unique name for a directory/file at the given directory path.
 unique_name = fsutil.get_unique_name(path, prefix="", suffix="", extension="", separator="-")
 ```
 

{python-fsutil-0.14.0 → python_fsutil-0.15.0}/README.md

@@ -449,7 +449,7 @@ permissions = fsutil.get_permissions(path)
 #### `get_unique_name`
 
 ```python
-# Get a unique name for a directory/file ath the given directory path.
+# Get a unique name for a directory/file at the given directory path.
 unique_name = fsutil.get_unique_name(path, prefix="", suffix="", extension="", separator="-")
 ```
 

python_fsutil-0.15.0/fsutil/__init__.py

@@ -0,0 +1,199 @@
+from __future__ import annotations
+
+from fsutil.archives import (
+    create_tar_file,
+    create_zip_file,
+    extract_tar_file,
+    extract_zip_file,
+)
+from fsutil.checks import (
+    assert_dir,
+    assert_exists,
+    assert_file,
+    assert_not_dir,
+    assert_not_exists,
+    assert_not_file,
+    exists,
+    is_dir,
+    is_empty,
+    is_empty_dir,
+    is_empty_file,
+    is_file,
+)
+from fsutil.converters import convert_size_bytes_to_string, convert_size_string_to_bytes
+from fsutil.info import (
+    get_dir_creation_date,
+    get_dir_creation_date_formatted,
+    get_dir_hash,
+    get_dir_last_modified_date,
+    get_dir_last_modified_date_formatted,
+    get_dir_size,
+    get_dir_size_formatted,
+    get_file_creation_date,
+    get_file_creation_date_formatted,
+    get_file_hash,
+    get_file_last_modified_date,
+    get_file_last_modified_date_formatted,
+    get_file_size,
+    get_file_size_formatted,
+)
+from fsutil.io import (
+    read_file,
+    read_file_from_url,
+    read_file_json,
+    read_file_lines,
+    read_file_lines_count,
+    write_file,
+    write_file_json,
+)
+from fsutil.metadata import (
+    __author__,
+    __copyright__,
+    __description__,
+    __email__,
+    __license__,
+    __title__,
+    __version__,
+)
+from fsutil.operations import (
+    clean_dir,
+    copy_dir,
+    copy_dir_content,
+    copy_file,
+    create_dir,
+    create_file,
+    delete_dir,
+    delete_dir_content,
+    delete_dirs,
+    delete_file,
+    delete_files,
+    download_file,
+    list_dirs,
+    list_files,
+    make_dirs,
+    make_dirs_for_file,
+    move_dir,
+    move_file,
+    remove_dir,
+    remove_dir_content,
+    remove_dirs,
+    remove_file,
+    remove_files,
+    rename_dir,
+    rename_file,
+    rename_file_basename,
+    rename_file_extension,
+    replace_dir,
+    replace_file,
+    search_dirs,
+    search_files,
+)
+from fsutil.paths import (
+    get_file_basename,
+    get_file_extension,
+    get_filename,
+    get_parent_dir,
+    get_unique_name,
+    join_filename,
+    join_filepath,
+    join_path,
+    split_filename,
+    split_filepath,
+    split_path,
+    transform_filepath,
+)
+from fsutil.perms import get_permissions, set_permissions
+
+__all__ = [
+    "__author__",
+    "__copyright__",
+    "__description__",
+    "__email__",
+    "__license__",
+    "__title__",
+    "__version__",
+    "assert_dir",
+    "assert_exists",
+    "assert_file",
+    "assert_not_dir",
+    "assert_not_exists",
+    "assert_not_file",
+    "clean_dir",
+    "convert_size_bytes_to_string",
+    "convert_size_string_to_bytes",
+    "copy_dir",
+    "copy_dir_content",
+    "copy_file",
+    "create_dir",
+    "create_file",
+    "create_tar_file",
+    "create_zip_file",
+    "delete_dir",
+    "delete_dir_content",
+    "delete_dirs",
+    "delete_file",
+    "delete_files",
+    "download_file",
+    "exists",
+    "extract_tar_file",
+    "extract_zip_file",
+    "get_dir_creation_date",
+    "get_dir_creation_date_formatted",
+    "get_dir_hash",
+    "get_dir_last_modified_date",
+    "get_dir_last_modified_date_formatted",
+    "get_dir_size",
+    "get_dir_size_formatted",
+    "get_file_basename",
+    "get_file_creation_date",
+    "get_file_creation_date_formatted",
+    "get_file_extension",
+    "get_file_hash",
+    "get_file_last_modified_date",
+    "get_file_last_modified_date_formatted",
+    "get_file_size",
+    "get_file_size_formatted",
+    "get_filename",
+    "get_parent_dir",
+    "get_permissions",
+    "get_unique_name",
+    "is_dir",
+    "is_empty",
+    "is_empty_dir",
+    "is_empty_file",
+    "is_file",
+    "join_filename",
+    "join_filepath",
+    "join_path",
+    "list_dirs",
+    "list_files",
+    "make_dirs",
+    "make_dirs_for_file",
+    "move_dir",
+    "move_file",
+    "read_file",
+    "read_file_from_url",
+    "read_file_json",
+    "read_file_lines",
+    "read_file_lines_count",
+    "remove_dir",
+    "remove_dir_content",
+    "remove_dirs",
+    "remove_file",
+    "remove_files",
+    "rename_dir",
+    "rename_file",
+    "rename_file_basename",
+    "rename_file_extension",
+    "replace_dir",
+    "replace_file",
+    "search_dirs",
+    "search_files",
+    "set_permissions",
+    "split_filename",
+    "split_filepath",
+    "split_path",
+    "transform_filepath",
+    "write_file",
+    "write_file_json",
+]

python_fsutil-0.15.0/fsutil/archives.py

@@ -0,0 +1,163 @@
+from __future__ import annotations
+
+import os
+import sys
+import tarfile
+import zipfile
+from collections.abc import Callable, Iterable
+from typing import Literal
+
+from fsutil.args import get_path as _get_path
+from fsutil.checks import (
+    assert_exists,
+    assert_file,
+    assert_not_dir,
+    assert_not_exists,
+    assert_not_file,
+    is_dir,
+    is_file,
+)
+from fsutil.operations import make_dirs, make_dirs_for_file, remove_file
+from fsutil.paths import get_filename, join_path
+from fsutil.types import PathIn
+
+
+def create_tar_file(
+    path: PathIn,
+    content_paths: list[PathIn],
+    *,
+    overwrite: bool = True,
+    compression: str = "",  # literal: gz, bz2, xz
+) -> None:
+    """
+    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.
+    """
+    path = _get_path(path)
+    assert_not_dir(path)
+    if not overwrite:
+        assert_not_exists(path)
+    make_dirs_for_file(path)
+
+    def _write_content_to_tar_file(
+        file: tarfile.TarFile, content_path: PathIn, basedir: str = ""
+    ) -> None:
+        path = _get_path(content_path)
+        assert_exists(path)
+        if is_file(path):
+            filename = get_filename(path)
+            filepath = join_path(basedir, filename)
+            file.add(path, filepath)
+        elif is_dir(path):
+            for item_name in os.listdir(path):
+                item_path = join_path(path, item_name)
+                item_basedir = (
+                    join_path(basedir, item_name) if is_dir(item_path) else basedir
+                )
+                _write_content_to_tar_file(file, item_path, item_basedir)
+
+    mode = f"w:{compression}" if compression else "w"
+    with tarfile.open(path, mode=mode) as file:  # type: ignore
+        for content_path in content_paths:
+            _write_content_to_tar_file(file, content_path)
+
+
+def create_zip_file(
+    path: PathIn,
+    content_paths: list[PathIn],
+    *,
+    overwrite: bool = True,
+    compression: int = zipfile.ZIP_DEFLATED,
+) -> None:
+    """
+    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.
+    """
+    path = _get_path(path)
+    assert_not_dir(path)
+    if not overwrite:
+        assert_not_exists(path)
+    make_dirs_for_file(path)
+
+    def _write_content_to_zip_file(
+        file: zipfile.ZipFile, content_path: PathIn, basedir: str = ""
+    ) -> None:
+        path = _get_path(content_path)
+        assert_exists(path)
+        if is_file(path):
+            filename = get_filename(path)
+            filepath = join_path(basedir, filename)
+            file.write(path, filepath)
+        elif is_dir(path):
+            for item_name in os.listdir(path):
+                item_path = join_path(path, item_name)
+                item_basedir = (
+                    join_path(basedir, item_name) if is_dir(item_path) else basedir
+                )
+                _write_content_to_zip_file(file, item_path, item_basedir)
+
+    with zipfile.ZipFile(path, "w", compression) as file:
+        for content_path in content_paths:
+            _write_content_to_zip_file(file, content_path)
+
+
+def extract_tar_file(
+    path: PathIn,
+    dest: PathIn,
+    *,
+    autodelete: bool = False,
+    content_paths: Iterable[tarfile.TarInfo] | None = None,
+    filter: (
+        Callable[[tarfile.TarInfo, str], tarfile.TarInfo | None]
+        | Literal["fully_trusted", "tar", "data"]
+    )
+    | None = None,
+) -> None:
+    """
+    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.
+    """
+    path = _get_path(path)
+    dest = _get_path(dest)
+    assert_file(path)
+    assert_not_file(dest)
+    make_dirs(dest)
+    with tarfile.TarFile(path, "r") as file:
+        if sys.version_info < (3, 12):
+            file.extractall(dest, members=content_paths)
+        else:
+            # https://docs.python.org/3/library/tarfile.html#tarfile-extraction-filter
+            file.extractall(
+                dest,
+                members=content_paths,
+                numeric_owner=False,
+                filter=(filter or "data"),
+            )
+    if autodelete:
+        remove_file(path)
+
+
+def extract_zip_file(
+    path: PathIn,
+    dest: PathIn,
+    *,
+    autodelete: bool = False,
+    content_paths: Iterable[str | zipfile.ZipInfo] | None = None,
+) -> None:
+    """
+    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.
+    """
+    path = _get_path(path)
+    dest = _get_path(dest)
+    assert_file(path)
+    assert_not_file(dest)
+    make_dirs(dest)
+    with zipfile.ZipFile(path, "r") as file:
+        file.extractall(dest, members=content_paths)
+    if autodelete:
+        remove_file(path)

python_fsutil-0.15.0/fsutil/args.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+import os
+
+from fsutil.types import PathIn
+
+
+def get_path(path: PathIn) -> str:
+    if path is None:
+        return None
+    if isinstance(path, str):
+        return os.path.normpath(path)
+    return str(path)

python_fsutil-0.15.0/fsutil/checks.py

@@ -0,0 +1,114 @@
+from __future__ import annotations
+
+import os
+
+from fsutil.args import get_path as _get_path
+from fsutil.types import PathIn
+
+
+def assert_dir(path: PathIn) -> None:
+    """
+    Raise an OSError if the given path doesn't exist or it is not a directory.
+    """
+    path = _get_path(path)
+    if not is_dir(path):
+        raise OSError(f"Invalid directory path: {path}")
+
+
+def assert_exists(path: PathIn) -> None:
+    """
+    Raise an OSError if the given path doesn't exist.
+    """
+    path = _get_path(path)
+    if not exists(path):
+        raise OSError(f"Invalid item path: {path}")
+
+
+def assert_file(path: PathIn) -> None:
+    """
+    Raise an OSError if the given path doesn't exist or it is not a file.
+    """
+    path = _get_path(path)
+    if not is_file(path):
+        raise OSError(f"Invalid file path: {path}")
+
+
+def assert_not_dir(path: PathIn) -> None:
+    """
+    Raise an OSError if the given path is an existing directory.
+    """
+    path = _get_path(path)
+    if is_dir(path):
+        raise OSError(f"Invalid path, directory already exists: {path}")
+
+
+def assert_not_exists(path: PathIn) -> None:
+    """
+    Raise an OSError if the given path already exists.
+    """
+    path = _get_path(path)
+    if exists(path):
+        raise OSError(f"Invalid path, item already exists: {path}")
+
+
+def assert_not_file(path: PathIn) -> None:
+    """
+    Raise an OSError if the given path is an existing file.
+    """
+    path = _get_path(path)
+    if is_file(path):
+        raise OSError(f"Invalid path, file already exists: {path}")
+
+
+def exists(path: PathIn) -> bool:
+    """
+    Check if a directory of a file exists at the given path.
+    """
+    path = _get_path(path)
+    return os.path.exists(path)
+
+
+def is_dir(path: PathIn) -> bool:
+    """
+    Determine whether the specified path represents an existing directory.
+    """
+    path = _get_path(path)
+    return os.path.isdir(path)
+
+
+def is_empty(path: PathIn) -> bool:
+    """
+    Determine whether the specified path represents an empty directory or an empty file.
+    """
+    path = _get_path(path)
+    assert_exists(path)
+    if is_dir(path):
+        return is_empty_dir(path)
+    return is_empty_file(path)
+
+
+def is_empty_dir(path: PathIn) -> bool:
+    """
+    Determine whether the specified path represents an empty directory.
+    """
+    path = _get_path(path)
+    assert_dir(path)
+    return len(os.listdir(path)) == 0
+
+
+def is_empty_file(path: PathIn) -> bool:
+    """
+    Determine whether the specified path represents an empty file.
+    """
+    from fsutil.info import get_file_size
+
+    path = _get_path(path)
+    return get_file_size(path) == 0
+
+
+def is_file(path: PathIn) -> bool:
+    """
+    Determine whether the specified path represents an existing file.
+    """
+    path = _get_path(path)
+    return os.path.isfile(path)

python_fsutil-0.15.0/fsutil/converters.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+SIZE_UNITS = ["bytes", "KB", "MB", "GB", "TB", "PB", "EB", "ZB", "YB"]
+
+
+def convert_size_bytes_to_string(size: int) -> str:
+    """
+    Convert the given size bytes to string using the right unit suffix.
+    """
+    size_num = float(size)
+    units = SIZE_UNITS
+    factor = 0
+    factor_limit = len(units) - 1
+    while (size_num >= 1024) and (factor <= factor_limit):
+        size_num /= 1024
+        factor += 1
+    size_units = units[factor]
+    size_str = f"{size_num:.2f}" if (factor > 1) else f"{size_num:.0f}"
+    size_str = f"{size_str} {size_units}"
+    return size_str
+
+
+def convert_size_string_to_bytes(size: str) -> float | int:
+    """
+    Convert the given size string to bytes.
+    """
+    units = [item.lower() for item in SIZE_UNITS]
+    parts = size.strip().replace("  ", " ").split(" ")
+    amount = float(parts[0])
+    unit = parts[1]
+    factor = units.index(unit.lower())
+    if not factor:
+        return amount
+    return int((1024**factor) * amount)

python_fsutil-0.15.0/fsutil/deps.py

@@ -0,0 +1,13 @@
+from types import ModuleType
+
+
+def require_requests() -> ModuleType:
+    try:
+        import requests
+
+        return requests
+    except ImportError as error:
+        raise ModuleNotFoundError(
+            "'requests' module is not installed, "
+            "it can be installed by running: 'pip install requests'"
+        ) from error