pythonwrench 0.6.4__py3-none-any.whl

pythonwrench/entrypoints/safe_rmdir.py

@@ -0,0 +1,98 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+import logging
+from argparse import ArgumentParser
+from pathlib import Path
+from typing import Union
+
+from pythonwrench.argparse import str_to_bool
+from pythonwrench.os import safe_rmdir
+
+logger = logging.getLogger(__name__)
+
+
+def print_safe_rmdir(
+    root: Union[str, Path],
+    *,
+    rm_root: bool = True,
+    error_on_non_empty_dir: bool = True,
+    followlinks: bool = False,
+    dry_run: bool = False,
+    verbose: int = 0,
+) -> None:
+    """Perform the print safe rmdir operation."""
+    deleted, reviewed = safe_rmdir(
+        root=root,
+        rm_root=rm_root,
+        error_on_non_empty_dir=error_on_non_empty_dir,
+        followlinks=followlinks,
+        dry_run=dry_run,
+        verbose=verbose,
+    )
+    if dry_run:
+        msg = f"Dry run mode enabled. Here is the list of directories to delete ({len(deleted)}/{len(reviewed)}):"
+        print(msg)
+        for path in deleted:
+            print(f" - {path}")
+
+    elif verbose >= 1:
+        print(f"{len(deleted)} directories has been deleted.")
+
+
+def main_safe_rmdir() -> None:
+    """Perform the main safe rmdir operation."""
+    parser = ArgumentParser()
+    parser.add_argument(
+        "root",
+        type=str,
+        help="Root directory path.",
+    )
+    parser.add_argument(
+        "--rm_root",
+        "--rm-root",
+        type=str_to_bool,
+        default=True,
+        help="If True, remove the root directory too if it is empty at the end. defaults to True.",
+    )
+    parser.add_argument(
+        "--error_on_non_empty_dir",
+        "--error-on-non-empty-dir",
+        type=str_to_bool,
+        default=True,
+        help="If True, raises a RuntimeError if a subdirectory contains at least 1 file. Otherwise it will ignore non-empty directories. defaults to True.",
+    )
+    parser.add_argument(
+        "--followlinks",
+        "--follow_links",
+        "--follow-links",
+        type=str_to_bool,
+        default=False,
+        help="Indicates whether or not symbolic links shound be followed. defaults to False.",
+    )
+    parser.add_argument(
+        "--dry_run",
+        "--dry-run",
+        type=str_to_bool,
+        default=False,
+        help="If True, does not remove any directory and just output the list of directories which could be deleted. defaults to False.",
+    )
+    parser.add_argument(
+        "--verbose",
+        type=int,
+        default=0,
+        help="Verbose level. defaults to 0.",
+    )
+    args = parser.parse_args()
+    print_safe_rmdir(
+        root=args.root,
+        rm_root=args.rm_root,
+        error_on_non_empty_dir=args.error_on_non_empty_dir,
+        followlinks=args.followlinks,
+        dry_run=args.dry_run,
+        verbose=args.verbose,
+    )
+
+
+if __name__ == "__main__":
+    main_safe_rmdir()

pythonwrench/entrypoints/tree.py

@@ -0,0 +1,113 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+import logging
+import sys
+from argparse import ArgumentParser
+from pathlib import Path
+from typing import Union
+
+from pythonwrench.argparse import str_to_bool
+from pythonwrench.os import tree_iter
+from pythonwrench.re import PatternListLike
+
+logger = logging.getLogger(__name__)
+
+
+def main_tree() -> None:
+    """Perform the main tree operation."""
+    parser = ArgumentParser()
+    parser.add_argument(
+        "root",
+        type=str,
+        help="Root directory path.",
+        default=".",
+        nargs="?",  # for optional positional argument
+    )
+    parser.add_argument(
+        "--include",
+        type=str,
+        help="Include file/dir patterns.",
+        default=".*",
+        nargs="*",
+    )
+    parser.add_argument(
+        "--exclude",
+        type=str,
+        help="Exclude file/dir patterns.",
+        default=(),
+        nargs="*",
+    )
+    parser.add_argument(
+        "--max_depth",
+        type=int,
+        help="Max directory tree depth.",
+        default=sys.maxsize,
+    )
+    parser.add_argument(
+        "--followlinks",
+        type=str_to_bool,
+        help="Indicates whether or not symbolic links should be followed. defaults to True.",
+        default=True,
+    )
+    parser.add_argument(
+        "--skipfiles",
+        type=str_to_bool,
+        help="Indicates whether or not symbolic files should be shown. defaults to False.",
+        default=False,
+    )
+    parser.add_argument(
+        "--sort",
+        type=str_to_bool,
+        help="Sort element by name. defaults to False.",
+        default=False,
+    )
+    args = parser.parse_args()
+
+    print_tree(
+        root=args.root,
+        include=args.include,
+        exclude=args.exclude,
+        max_depth=args.max_depth,
+        followlinks=args.followlinks,
+        skipfiles=args.skipfiles,
+        sort=args.sort,
+    )
+
+
+def print_tree(
+    root: Union[str, Path],
+    *,
+    include: PatternListLike = ".*",
+    exclude: PatternListLike = (),
+    max_depth: int = sys.maxsize,
+    followlinks: bool = False,
+    skipfiles: bool = False,
+    sort: bool = False,
+) -> None:
+    """Print directory tree to stdout."""
+    num_dirs = 0
+    num_files = 0
+
+    iterable = tree_iter(
+        root=root,
+        include=include,
+        exclude=exclude,
+        max_depth=max_depth,
+        followlinks=followlinks,
+        skipfiles=skipfiles,
+        sort=sort,
+    )
+    for line in iterable:
+        print(f"{line}")
+
+        if line.endswith("/"):
+            num_dirs += 1
+        else:
+            num_files += 1
+
+    print(f"\n{num_dirs} directories, {num_files} files")
+
+
+if __name__ == "__main__":
+    main_tree()

pythonwrench/enum.py

@@ -0,0 +1,55 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+from enum import Enum
+
+from typing_extensions import Self
+
+
+class StrEnum(str, Enum):
+    """StrEnum is the same as Enum, but its members are also strings and can be used in most of the same places that a string can be used.
+
+    Note: when used as keys of dicts, enums are considered different from strings keys.
+
+    This class has the same objective than https://docs.python.org/3/library/enum.html#enum.StrEnum, which was introduced in Python 3.11.
+    """
+
+    @classmethod
+    def from_str(
+        cls,
+        value: str,
+        case_sensitive: bool = False,
+    ) -> Self:
+        """Create an instance from str."""
+        members = cls.__members__.keys()
+        for member in members:
+            if member == value or (
+                not case_sensitive and member.lower() == value.lower()
+            ):
+                return cls[member]
+
+        msg = f"Invalid argument {value=}. (expected one of {tuple(members)})"
+        raise ValueError(msg)
+
+    @staticmethod
+    def _generate_next_value_(name, start, count, last_values) -> str:
+        """Perform the generate next value operation."""
+        return name
+
+    @property
+    def value(self) -> str:
+        """Perform the value operation."""
+        return self._value_
+
+    def __eq__(self, other: object) -> bool:
+        """Return whether this instance equals another object."""
+        other = other.value if isinstance(other, Enum) else str(other)
+        return self.value == other  # type: ignore
+
+    def __hash__(self) -> int:
+        """Return the hash of the instance."""
+        return hash(self.value)
+
+    def __str__(self) -> str:
+        """Return the string representation of the instance."""
+        return self.name

pythonwrench/functools.py

@@ -0,0 +1,234 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+import inspect
+from types import CodeType
+from typing import (
+    Any,
+    Callable,
+    Generic,
+    Iterable,
+    Optional,
+    Tuple,
+    TypeVar,
+    overload,
+)
+
+from typing_extensions import ParamSpec
+
+from pythonwrench._core import T_Function, _decorator_factory, return_none  # noqa: F401
+from pythonwrench.inspect import get_argnames, get_fullname
+from pythonwrench.typing import isinstance_generic
+
+T = TypeVar("T")
+U = TypeVar("U")
+P = ParamSpec("P")
+
+
+class Compose(Generic[T, U]):
+    """Compose callables to chain calls sequentially."""
+
+    @overload
+    def __init__(self) -> None:
+        """Initialize the instance."""
+        ...
+
+    @overload
+    def __init__(
+        self,
+        fn0: Iterable[Callable[[T], T]],
+        /,
+    ) -> None:
+        """Initialize the instance."""
+        ...
+
+    @overload
+    def __init__(
+        self,
+        fn0: Callable[[T], U],
+        /,
+    ) -> None:
+        """Initialize the instance."""
+        ...
+
+    @overload
+    def __init__(
+        self,
+        fn0: Callable[[T], Any],
+        fn1: Callable[[Any], U],
+        /,
+    ) -> None:
+        """Initialize the instance."""
+        ...
+
+    @overload
+    def __init__(
+        self,
+        fn0: Callable[[T], Any],
+        fn1: Callable[[Any], Any],
+        fn2: Callable[[Any], U],
+        /,
+    ) -> None:
+        """Initialize the instance."""
+        ...
+
+    @overload
+    def __init__(
+        self,
+        fn0: Callable[[T], Any],
+        fn1: Callable[[Any], Any],
+        fn2: Callable[[Any], Any],
+        fn3: Callable[[Any], U],
+        /,
+    ) -> None:
+        """Initialize the instance."""
+        ...
+
+    @overload
+    def __init__(
+        self,
+        fn0: Callable[[T], Any],
+        fn1: Callable[[Any], Any],
+        fn2: Callable[[Any], Any],
+        fn3: Callable[[Any], Any],
+        fn4: Callable[[Any], U],
+        /,
+    ) -> None:
+        """Initialize the instance."""
+        ...
+
+    @overload
+    def __init__(self, *fns: Callable) -> None:
+        """Initialize the instance."""
+        ...
+
+    def __init__(self, *fns) -> None:
+        """Initialize the instance."""
+        if isinstance_generic(fns, Tuple[Iterable[Callable]]):
+            fns = fns[0]
+        elif isinstance_generic(fns, Tuple[Callable, ...]):
+            pass
+        else:
+            msg = f"Invalid argument types {type(fns)=}. (with {fns=})"
+            raise TypeError(msg)
+
+        super().__init__()
+        self.fns = fns
+
+    def __call__(self, x: T) -> U:
+        """Call the instance."""
+        for fn in self.fns:
+            x = fn(x)
+        return x  # type: ignore
+
+    def __getitem__(self, idx: int, /) -> Callable[[Any], Any]:
+        """Return the item at the requested index or key."""
+        return self.fns[idx]
+
+    def __len__(self) -> int:
+        """Return the number of items in the instance."""
+        return len(self.fns)
+
+
+compose = Compose  # type: ignore
+
+
+def filter_and_call(
+    fn: Callable[..., T],
+    _fill_all_arguments: bool = False,
+    **kwargs: Any,
+) -> T:
+    """Call object only with the valid keyword arguments. Non-valid arguments are ignored.
+
+    Arguments:
+        fn: Callable to call.
+        _fill_all_arguments: If True, all arguments of fn must be provided in kwargs. defaults to False.
+        **kwargs: Superset of arguments to pass to fn. Name that does not match any argument of fn are ignored.
+
+    Examples:
+    ---------
+    >>> def f(x, y):
+    >>>     return x + y
+    >>> filter_and_call(f, y=2, x=1)
+    ... 3
+    >>> filter_and_call(f, y=2, x=1, z=0)  # z is ignored
+    ... 3
+    """
+    argnames = get_argnames(fn)
+    code, _start = _get_code_and_start(fn)
+
+    if "_fill_all_arguments" in argnames:
+        msg = f"Invalid argument {get_fullname(fn)}, because it has argument '_fill_all_arguments'."
+        raise RuntimeError(msg)
+
+    if _fill_all_arguments:
+        missing = set(argnames).difference(kwargs)
+        if len(missing) > 0:
+            msg = f"Missing {len(missing)}/{len(argnames)} arguments: {tuple(missing)}. (with {_fill_all_arguments=})"
+            raise ValueError(msg)
+
+    pos_argnames = argnames[: code.co_posonlyargcount]
+    other_argnames = argnames[code.co_posonlyargcount :]
+
+    posonly_args = {
+        name: value for name, value in kwargs.items() if name in pos_argnames
+    }
+    other_kwds = {
+        name: value for name, value in kwargs.items() if name in other_argnames
+    }
+    result = fn(*posonly_args.values(), **other_kwds)
+    return result
+
+
+def function_alias(
+    alternative: T_Function,
+    *,
+    pre_fn: Optional[Callable[..., Any]] = None,
+    post_fn: Optional[Callable[..., Any]] = None,
+) -> Callable[..., T_Function]:
+    """Decorator to wrap function aliases.
+
+    Unlike setting directly an alias, this preserve the nature of the alias for language server.
+
+    Example
+    -------
+    >>> def f(a: int, b: str) -> str:
+    >>>    return a * b
+    >>> @function_alias(f)
+    >>> def g(*args, **kwargs): ...
+    >>> f(2, "a")
+    ... "aa"
+    >>> g(3, "b")  # calls function f() internally.
+    ... "bbb"
+
+    """
+    return _decorator_factory(alternative, pre_fn=pre_fn, post_fn=post_fn)
+
+
+def identity(x: T, **kwargs) -> T:
+    """Identity function placeholder. Returns the first argument. Other keywords arguments are ignored."""
+    return x
+
+
+def repeat_fn(f: Callable[[T], T], n: int) -> Callable[[T], T]:
+    """Creates wrapper which call a function n items."""
+    return Compose([f] * n)
+
+
+def _get_code_and_start(fn: Callable) -> Tuple[CodeType, int]:
+    """Perform the get code and start operation."""
+    if inspect.isfunction(fn):
+        code = fn.__code__
+        start = 0
+    elif inspect.ismethod(fn):
+        code = fn.__code__
+        start = 1  # If method, remove 'self' arg
+    elif inspect.isclass(fn):
+        # If init, remove 'self' arg
+        code = fn.__init__.__code__
+        start = 1  # If init, remove 'self' arg
+    else:
+        code = fn.__call__.__code__
+        start = 0
+
+    return code, start

pythonwrench/hashlib.py

@@ -0,0 +1,95 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+import hashlib
+import logging
+from io import BufferedReader
+from pathlib import Path
+from typing import Literal, Optional, Protocol, Union, get_args, runtime_checkable
+
+from typing_extensions import Buffer
+
+HasherName = Literal["sha256", "md5"]
+HashName = HasherName  # alias
+
+DEFAULT_CHUNK_SIZE = 256 * 1024**2  # 256 MiB
+
+logger = logging.getLogger(__name__)
+
+
+@runtime_checkable
+class Hasher(Protocol):
+    """Hasher protocol class."""
+
+    @property
+    def digest_size(self) -> int: ...
+    @property
+    def block_size(self) -> int: ...
+    @property
+    def name(self) -> str: ...
+
+    def digest(self) -> bytes:
+        """Perform the digest operation."""
+        ...
+
+    def update(self, data: Buffer, /) -> None:
+        """Perform the update operation."""
+        ...
+
+
+def hash_file(
+    fpath: Union[str, Path, BufferedReader],
+    hash_type: Union[HasherName, Hasher] = "md5",
+    chunk_size: Optional[int] = DEFAULT_CHUNK_SIZE,
+    *,
+    init_bytes: bytes = b"",
+) -> str:
+    """Return the hash value for a file.
+
+    Based on https://github.com/pytorch/audio/blob/v0.13.0/torchaudio/datasets/utils.py#L110
+
+    Args:
+        fpath: Path to existing file.
+        hash_type: Hash name or custom Hasher algorithm.
+        chunk_size: Max chunk size in bytes. defaults to 268435456 (256 MiB).
+
+    Returns:
+        Hash value as string.
+    """
+    if isinstance(fpath, (str, Path)):
+        with open(fpath, "rb") as file:
+            return hash_file(file, hash_type, chunk_size)
+    else:
+        file = fpath
+    del fpath
+
+    if isinstance(hash_type, str):
+        hasher = _get_hasher(hash_type, init_bytes)
+    elif isinstance(hash_type, Hasher):
+        hasher = hash_type
+    else:
+        msg = f"Invalid argument {hash_type=}. (expected one of {get_args(HasherName)} or custom Hasher type)"
+        raise ValueError(msg)
+    del hash_type
+
+    while True:
+        chunk = file.read(chunk_size)
+        if not chunk:
+            break
+        hasher.update(chunk)
+
+    hash_bytes = hasher.digest()
+    return hash_bytes.hex()
+
+
+def _get_hasher(hasher_name: HasherName, init_bytes: bytes = b"") -> Hasher:
+    if hasher_name == "sha256":
+        hasher = hashlib.sha256(init_bytes)
+    elif hasher_name == "md5":
+        hasher = hashlib.md5(init_bytes)
+    else:
+        msg = (
+            f"Invalid argument {hasher_name=}. (expected one of {get_args(HasherName)})"
+        )
+        raise ValueError(msg)
+    return hasher