python-fsutil 0.14.1__tar.gz → 0.16.0__tar.gz

{python-fsutil-0.14.1 → python_fsutil-0.16.0}/MANIFEST.in

@@ -1,4 +1,5 @@
 include LICENSE.txt
 include README.md
-recursive-include fsutil *
+recursive-include src *
+recursive-include tests *
 recursive-exclude * *.pyc __pycache__ .DS_Store

{python-fsutil-0.14.1/python_fsutil.egg-info → python_fsutil-0.16.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: python-fsutil
-Version: 0.14.1
+Version: 0.16.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,11 @@ 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 :: 3.14
 Classifier: Programming Language :: Python :: Implementation :: PyPy
 Classifier: Topic :: Desktop Environment :: File Managers
 Classifier: Topic :: Software Development :: Build Tools
@@ -55,6 +55,7 @@ Classifier: Topic :: System :: Filesystems
 Classifier: Topic :: Utilities
 Description-Content-Type: text/markdown
 License-File: LICENSE.txt
+Dynamic: license-file
 
 [![](https://img.shields.io/pypi/pyversions/python-fsutil.svg?color=blue&logo=python&logoColor=white)](https://www.python.org/)
 [![](https://img.shields.io/pypi/v/python-fsutil.svg?color=blue&logo=pypi&logoColor=white)](https://pypi.org/project/python-fsutil/)
@@ -66,7 +67,6 @@ License-File: LICENSE.txt
 [![](https://img.shields.io/github/actions/workflow/status/fabiocaccamo/python-fsutil/test-package.yml?branch=main&label=build&logo=github)](https://github.com/fabiocaccamo/python-fsutil)
 [![](https://img.shields.io/codecov/c/gh/fabiocaccamo/python-fsutil?logo=codecov)](https://codecov.io/gh/fabiocaccamo/python-fsutil)
 [![](https://img.shields.io/codacy/grade/fc40788ae7d74d1fb34a38934113c4e5?logo=codacy)](https://www.codacy.com/app/fabiocaccamo/python-fsutil)
-[![](https://img.shields.io/codeclimate/maintainability/fabiocaccamo/python-fsutil?logo=code-climate)](https://codeclimate.com/github/fabiocaccamo/python-fsutil/)
 [![](https://img.shields.io/badge/code%20style-black-000000.svg?logo=python&logoColor=black)](https://github.com/psf/black)
 [![](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
 
@@ -507,7 +507,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="-")
 ```
 
@@ -826,8 +826,8 @@ pre-commit install --install-hooks
 # run tests using tox
 tox
 
-# or run tests using unittest
-python -m unittest
+# or run tests using pytest
+pytest
 ```
 
 ## License
@@ -839,7 +839,7 @@ Released under [MIT License](LICENSE.txt).
 
 - :star: Star this project on [GitHub](https://github.com/fabiocaccamo/python-fsutil)
 - :octocat: Follow me on [GitHub](https://github.com/fabiocaccamo)
-- :blue_heart: Follow me on [Twitter](https://twitter.com/fabiocaccamo)
+- :blue_heart: Follow me on [Bluesky](https://bsky.app/profile/fabiocaccamo.bsky.social)
 - :moneybag: Sponsor me on [Github](https://github.com/sponsors/fabiocaccamo)
 
 ## See also

{python-fsutil-0.14.1 → python_fsutil-0.16.0}/README.md

@@ -8,7 +8,6 @@
 [![](https://img.shields.io/github/actions/workflow/status/fabiocaccamo/python-fsutil/test-package.yml?branch=main&label=build&logo=github)](https://github.com/fabiocaccamo/python-fsutil)
 [![](https://img.shields.io/codecov/c/gh/fabiocaccamo/python-fsutil?logo=codecov)](https://codecov.io/gh/fabiocaccamo/python-fsutil)
 [![](https://img.shields.io/codacy/grade/fc40788ae7d74d1fb34a38934113c4e5?logo=codacy)](https://www.codacy.com/app/fabiocaccamo/python-fsutil)
-[![](https://img.shields.io/codeclimate/maintainability/fabiocaccamo/python-fsutil?logo=code-climate)](https://codeclimate.com/github/fabiocaccamo/python-fsutil/)
 [![](https://img.shields.io/badge/code%20style-black-000000.svg?logo=python&logoColor=black)](https://github.com/psf/black)
 [![](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
 
@@ -449,7 +448,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="-")
 ```
 
@@ -768,8 +767,8 @@ pre-commit install --install-hooks
 # run tests using tox
 tox
 
-# or run tests using unittest
-python -m unittest
+# or run tests using pytest
+pytest
 ```
 
 ## License
@@ -781,7 +780,7 @@ Released under [MIT License](LICENSE.txt).
 
 - :star: Star this project on [GitHub](https://github.com/fabiocaccamo/python-fsutil)
 - :octocat: Follow me on [GitHub](https://github.com/fabiocaccamo)
-- :blue_heart: Follow me on [Twitter](https://twitter.com/fabiocaccamo)
+- :blue_heart: Follow me on [Bluesky](https://bsky.app/profile/fabiocaccamo.bsky.social)
 - :moneybag: Sponsor me on [Github](https://github.com/sponsors/fabiocaccamo)
 
 ## See also

{python-fsutil-0.14.1 → python_fsutil-0.16.0}/pyproject.toml

@@ -34,11 +34,11 @@ classifiers = [
     "Natural Language :: English",
     "Operating System :: OS Independent",
     "Programming Language :: Python :: 3",
-    "Programming Language :: Python :: 3.8",
-    "Programming Language :: Python :: 3.9",
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
     "Programming Language :: Python :: Implementation :: PyPy",
     "Topic :: Desktop Environment :: File Managers",
     "Topic :: Software Development :: Build Tools",
@@ -86,25 +86,31 @@ exclude = '''
 '''
 
 [tool.mypy]
-files = ["fsutil"]
+files = ["src"]
 disable_error_code = "import-untyped"
 ignore_missing_imports = true
 install_types = true
 non_interactive = true
 strict = true
 
+[tool.pytest.ini_options]
+pythonpath = "src"
+addopts = "-v"
+testpaths = ["tests"]
+
 [tool.ruff]
 line-length = 88
 
 [tool.ruff.lint]
 ignore = []
-select = ["B", "B9", "C", "E", "F", "W"]
+select = ["B", "B9", "C", "E", "F", "I", "W"]
 
 [tool.ruff.lint.mccabe]
 max-complexity = 10
 
-[tool.setuptools.packages.find]
-include = ["fsutil*"]
+[tool.setuptools]
+package-dir = {"" = "src"}
+packages = ["fsutil"]
 
 [tool.setuptools.dynamic.version]
 attr = "fsutil.metadata.__version__"

python_fsutil-0.16.0/src/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.16.0/src/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.16.0/src/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.16.0/src/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.16.0/src/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)