pythonwrench 0.3.0__tar.gz → 0.4.0__tar.gz

{pythonwrench-0.3.0/src/pythonwrench.egg-info → pythonwrench-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pythonwrench
-Version: 0.3.0
+Version: 0.4.0
 Summary: Set of tools for Python that could be in the standard library.
 Author-email: "Étienne Labbé (Labbeti)" <labbeti.pub@gmail.com>
 Maintainer-email: "Étienne Labbé (Labbeti)" <labbeti.pub@gmail.com>

{pythonwrench-0.3.0 → pythonwrench-0.4.0}/pyproject.toml

@@ -8,6 +8,7 @@ readme = "README.md"
 requires-python = ">=3.8"
 keywords = ["python", "tools", "utilities"]
 license = {file = "LICENSE"}
+# license-files = ["LICENSE"]  # unsupported by python 3.8, but will be required in 2026
 classifiers = [
     "Intended Audience :: Developers",
     "Intended Audience :: Science/Research",
@@ -40,6 +41,9 @@ Tracker = "https://github.com/Labbeti/pythonwrench/issues"
 pythonwrench-info = "pythonwrench.entries:print_install_info"
 pythonwrench-tree = "pythonwrench.entries:main_tree"
 pythonwrench-safe-rmdir = "pythonwrench.entries:main_safe_rmdir"
+pyw-info = "pythonwrench.entries:print_install_info"
+pyw-tree = "pythonwrench.entries:main_tree"
+pyw-safe-rmdir = "pythonwrench.entries:main_safe_rmdir"
 
 [build-system]
 requires = ["setuptools >= 61.0"]

{pythonwrench-0.3.0 → pythonwrench-0.4.0}/src/pythonwrench/__init__.py

@@ -9,7 +9,7 @@ __author_email__ = "labbeti.pub@gmail.com"
 __license__ = "MIT"
 __maintainer__ = "Étienne Labbé (Labbeti)"
 __status__ = "Development"
-__version__ = "0.3.0"
+__version__ = "0.4.0"
 
 
 # Re-import for language servers
@@ -40,11 +40,14 @@ from . import warnings as warnings
 # Global library imports
 from .abc import Singleton
 from .argparse import (
+    parse_to,
     str_to_bool,
+    str_to_none,
     str_to_optional_bool,
     str_to_optional_float,
     str_to_optional_int,
     str_to_optional_str,
+    str_to_type,
 )
 from .cast import as_builtin
 from .checksum import checksum_any, register_checksum_fn
@@ -54,6 +57,7 @@ from .collections import (
     contained,
     dict_list_to_list_dict,
     dump_dict,
+    duplicate_list,
     filter_iterable,
     find,
     flat_dict_of_dict,
@@ -81,7 +85,7 @@ from .collections import (
     union_lists,
     unzip,
 )
-from .csv import dump_csv, load_csv
+from .csv import dump_csv, dumps_csv, load_csv, loads_csv, read_csv, save_csv
 from .dataclasses import get_defaults_values
 from .datetime import get_now, get_now_iso8601
 from .difflib import find_closest_in_list, sequence_matcher_ratio
@@ -93,6 +97,7 @@ from .functools import (
     filter_and_call,
     function_alias,
     identity,
+    repeat_fn,
 )
 from .hashlib import hash_file
 from .importlib import (
@@ -103,7 +108,15 @@ from .importlib import (
     search_submodules,
 )
 from .inspect import get_argnames, get_current_fn_name, get_fullname
-from .json import dump_json, load_json
+from .json import dump_json, dumps_json, load_json, loads_json, read_json, save_json
+from .jsonl import (
+    dump_jsonl,
+    dumps_jsonl,
+    load_jsonl,
+    loads_jsonl,
+    read_jsonl,
+    save_jsonl,
+)
 from .logging import (
     VERBOSE_DEBUG,
     VERBOSE_ERROR,
@@ -122,7 +135,14 @@ from .logging import (
 )
 from .math import argmax, argmin, argsort, clamp, clip
 from .os import get_num_cpus_available, safe_rmdir, tree_iter
-from .pickle import dump_pickle, load_pickle
+from .pickle import (
+    dump_pickle,
+    dumps_pickle,
+    load_pickle,
+    loads_pickle,
+    read_pickle,
+    save_pickle,
+)
 from .random import randstr
 from .re import (
     PatternLike,

{pythonwrench-0.3.0 → pythonwrench-0.4.0}/src/pythonwrench/_core.py

@@ -37,7 +37,7 @@ def _decorator_factory(
     *,
     pre_fn: Callable[..., Any] = return_none,
     post_fn: Callable[..., Any] = return_none,
-) -> Callable[..., Callable[P, U]]:
+) -> Callable[[Callable[P, U]], Callable[P, U]]:
     """Deprecated decorator for function aliases."""
 
     def wrapper_factory(fn: Callable[P, U]) -> Callable[P, U]:
@@ -77,7 +77,9 @@ class _FunctionRegistry(Generic[T_Output]):
         priority: int = 0,
     ) -> Callable[[T], T_Output]:
         return self.register_decorator(
-            class_or_tuple, custom_predicate=custom_predicate
+            class_or_tuple,
+            custom_predicate=custom_predicate,
+            priority=priority,
         )(fn)
 
     def register_decorator(

pythonwrench-0.4.0/src/pythonwrench/argparse.py

@@ -0,0 +1,313 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+from functools import partial
+from typing import (
+    Any,
+    Callable,
+    Iterable,
+    List,
+    Optional,
+    Type,
+    TypeVar,
+    Union,
+    get_args,
+    get_origin,
+)
+
+from pythonwrench.typing.classes import NoneType
+
+T = TypeVar("T")
+
+
+DEFAULT_TRUE_VALUES = ("True", "t", "yes", "y", "1")
+DEFAULT_FALSE_VALUES = ("False", "f", "no", "n", "0")
+DEFAULT_NONE_VALUES = ("None", "null")
+
+
+def parse_to(
+    target_type: Type[T],
+    *,
+    case_sensitive: bool = False,
+    true_values: Union[str, Iterable[str]] = DEFAULT_TRUE_VALUES,
+    false_values: Union[str, Iterable[str]] = DEFAULT_FALSE_VALUES,
+    none_values: Union[str, Iterable[str]] = DEFAULT_NONE_VALUES,
+) -> Callable[[str], T]:
+    """Returns a callable that convert string value to target type safely.
+
+    Intended for argparse boolean arguments.
+    """
+    return partial(
+        str_to_type,
+        target_type=target_type,
+        case_sensitive=case_sensitive,
+        true_values=true_values,
+        false_values=false_values,
+        none_values=none_values,
+    )
+
+
+def str_to_type(
+    x: str,
+    target_type: Type[T],
+    *,
+    case_sensitive: bool = False,
+    true_values: Union[str, Iterable[str]] = DEFAULT_TRUE_VALUES,
+    false_values: Union[str, Iterable[str]] = DEFAULT_FALSE_VALUES,
+    none_values: Union[str, Iterable[str]] = DEFAULT_NONE_VALUES,
+) -> T:
+    """Convert string values to target type safely. Intended for argparse boolean arguments.
+
+    - True values: 'True', 'T', 'yes', 'y', '1'.
+    - False values: 'False', 'F', 'no', 'n', '0'.
+    - None values: 'None', 'null'
+    - Other raises ValueError.
+    """
+    result = _str_to_type_impl(
+        x,
+        target_type,
+        case_sensitive=case_sensitive,
+        true_values=true_values,
+        false_values=false_values,
+        none_values=none_values,
+    )
+    if isinstance(result, Exception):
+        raise result
+    else:
+        return result
+
+
+def str_to_bool(
+    x: str,
+    *,
+    case_sensitive: bool = False,
+    true_values: Union[str, Iterable[str]] = DEFAULT_TRUE_VALUES,
+    false_values: Union[str, Iterable[str]] = DEFAULT_FALSE_VALUES,
+) -> bool:
+    """Convert string values to bool safely. Intended for argparse boolean arguments.
+
+    - True values: 'True', 'T', 'yes', 'y', '1'.
+    - False values: 'False', 'F', 'no', 'n', '0'.
+    - Other raises ValueError.
+    """
+    return str_to_type(
+        x,
+        bool,
+        case_sensitive=case_sensitive,
+        true_values=true_values,
+        false_values=false_values,
+    )
+
+
+def str_to_none(
+    x: str,
+    *,
+    case_sensitive: bool = False,
+    none_values: Union[str, Iterable[str]] = DEFAULT_NONE_VALUES,
+) -> None:
+    """Convert string values to None safely. Intended for argparse boolean arguments.
+
+    - None values: 'None', 'null'
+    - Other raises ValueError.
+    """
+    return str_to_type(
+        x, NoneType, case_sensitive=case_sensitive, none_values=none_values
+    )
+
+
+def str_to_optional_bool(
+    x: str,
+    *,
+    case_sensitive: bool = False,
+    true_values: Union[str, Iterable[str]] = DEFAULT_TRUE_VALUES,
+    false_values: Union[str, Iterable[str]] = DEFAULT_FALSE_VALUES,
+    none_values: Union[str, Iterable[str]] = DEFAULT_NONE_VALUES,
+) -> Optional[bool]:
+    """Convert string values to optional bool safely. Intended for argparse boolean arguments.
+
+    - True values: 'True', 'T', 'yes', 'y', '1'.
+    - False values: 'False', 'F', 'no', 'n', '0'.
+    - None values: 'None', 'null'
+    - Other raises ValueError.
+    """
+    return str_to_type(
+        x, Optional[bool], case_sensitive=case_sensitive, none_values=none_values
+    )
+
+
+def str_to_optional_float(
+    x: str,
+    *,
+    case_sensitive: bool = False,
+    none_values: Union[str, Iterable[str]] = DEFAULT_NONE_VALUES,
+) -> Optional[float]:
+    """Convert string values to optional float safely. Intended for argparse boolean arguments."""
+    return str_to_type(
+        x, Optional[float], case_sensitive=case_sensitive, none_values=none_values
+    )
+
+
+def str_to_optional_int(
+    x: str,
+    *,
+    case_sensitive: bool = False,
+    none_values: Union[str, Iterable[str]] = DEFAULT_NONE_VALUES,
+) -> Optional[int]:
+    """Convert string values to optional int safely. Intended for argparse boolean arguments."""
+    return str_to_type(
+        x, Optional[int], case_sensitive=case_sensitive, none_values=none_values
+    )
+
+
+def str_to_optional_str(
+    x: str,
+    *,
+    case_sensitive: bool = False,
+    none_values: Union[str, Iterable[str]] = DEFAULT_NONE_VALUES,
+) -> Optional[str]:
+    """Convert string values to optional str safely. Intended for argparse boolean arguments."""
+    return str_to_type(
+        x, Optional[str], case_sensitive=case_sensitive, none_values=none_values
+    )
+
+
+def _str_to_type_impl(
+    x: str,
+    target_type: Type[T],
+    *,
+    case_sensitive: bool = False,
+    true_values: Union[str, Iterable[str]] = DEFAULT_TRUE_VALUES,
+    false_values: Union[str, Iterable[str]] = DEFAULT_FALSE_VALUES,
+    none_values: Union[str, Iterable[str]] = DEFAULT_NONE_VALUES,
+) -> Union[T, Exception]:
+    if target_type in (str, int, float, None, NoneType, bool):
+        return _str_to_scalar_impl(
+            x,
+            target_type,
+            case_sensitive=case_sensitive,
+            true_values=true_values,
+            false_values=false_values,
+            none_values=none_values,
+        )
+
+    origin = get_origin(target_type)
+    if getattr(target_type, "__name__", None) == "Optional":
+        args = (None,) + get_args(target_type)
+    elif origin == Union or origin.__name__ in ("Union", "UnionType"):  # type: ignore
+        args = get_args(target_type)
+    else:
+        msg = f"Invalid argument {target_type=}. (unsupported type)"
+        raise ValueError(msg)
+
+    # str is always at the end
+    def key_fn(xi: Any) -> int:
+        if xi is str:
+            return 1
+        else:
+            return 0
+
+    args = sorted(args, key=key_fn)
+
+    for arg in args:
+        result = _str_to_type_impl(
+            x,
+            arg,  # type: ignore
+            case_sensitive=case_sensitive,
+            true_values=true_values,
+            false_values=false_values,
+        )
+        if not isinstance(result, Exception):
+            return result
+
+    return ValueError(f"Invalid argument {x=} with {target_type=}.")
+
+
+def _str_to_scalar_impl(
+    x: str,
+    target_type: Type[T],
+    *,
+    case_sensitive: bool = False,
+    true_values: Union[str, Iterable[str]] = DEFAULT_TRUE_VALUES,
+    false_values: Union[str, Iterable[str]] = DEFAULT_FALSE_VALUES,
+    none_values: Union[str, Iterable[str]] = DEFAULT_NONE_VALUES,
+) -> Any:
+    if target_type is str:
+        return x
+    elif target_type is int:
+        try:
+            return int(x)
+        except ValueError as err:
+            return err
+    elif target_type is float:
+        try:
+            return float(x)
+        except ValueError as err:
+            return err
+    elif target_type in (None, NoneType):
+        return _str_to_none_impl(
+            x, case_sensitive=case_sensitive, none_values=none_values
+        )
+    elif target_type is bool:
+        return _str_to_bool_impl(
+            x,
+            case_sensitive=case_sensitive,
+            true_values=true_values,
+            false_values=false_values,
+        )
+    else:
+        raise ValueError(f"Invalid argument {target_type=}. (unsupported type)")
+
+
+def _str_to_bool_impl(
+    x: str,
+    *,
+    case_sensitive: bool = False,
+    true_values: Union[str, Iterable[str]] = DEFAULT_TRUE_VALUES,
+    false_values: Union[str, Iterable[str]] = DEFAULT_FALSE_VALUES,
+) -> Union[bool, Exception]:
+    true_values = _sanitize_values(true_values)
+    if _str_in(x, true_values, case_sensitive):
+        return True
+
+    false_values = _sanitize_values(false_values)
+    if _str_in(x, false_values, case_sensitive):
+        return False
+
+    values = tuple(true_values + false_values)
+    err = ValueError(f"Invalid argument '{x}'. (expected one of {values})")
+    return err
+
+
+def _str_to_none_impl(
+    x: str,
+    *,
+    case_sensitive: bool = False,
+    none_values: Union[str, Iterable[str]] = DEFAULT_NONE_VALUES,
+) -> Union[None, Exception]:
+    """Convert string values to None safely. Intended for argparse boolean arguments.
+
+    - None values: 'None', 'null'
+    - Other raises ValueError.
+    """
+    none_values = _sanitize_values(none_values)
+    if _str_in(x, none_values, case_sensitive):
+        return None
+
+    values = tuple(none_values)
+    err = ValueError(f"Invalid argument '{x}'. (expected one of {values})")
+    return err
+
+
+def _sanitize_values(values: Union[str, Iterable[str]]) -> List[str]:
+    if isinstance(values, str):
+        values = [values]
+    else:
+        values = list(values)
+    return values
+
+
+def _str_in(x: str, values: List[str], case_sensitive: bool) -> bool:
+    if case_sensitive:
+        return x in values
+    else:
+        return x.lower() in map(str.lower, values)

{pythonwrench-0.3.0 → pythonwrench-0.4.0}/src/pythonwrench/checksum.py

@@ -18,20 +18,15 @@ from typing import (
     Optional,
     TypeVar,
     Union,
-    get_args,
     overload,
 )
 
 from pythonwrench._core import ClassOrTuple, Predicate, _FunctionRegistry
 from pythonwrench.inspect import get_fullname
 from pythonwrench.typing import (
-    BuiltinNumber,
-    BuiltinScalar,
     DataclassInstance,
     NamedTupleInstance,
     NoneType,
-    is_builtin_number,
-    is_builtin_scalar,
 )
 
 T = TypeVar("T")
@@ -127,38 +122,6 @@ def checksum_int(x: int, **kwargs) -> int:
 
 
 # Intermediate functions
-@register_checksum_fn(None, custom_predicate=is_builtin_scalar)
-def checksum_builtin_scalar(x: BuiltinScalar, **kwargs) -> int:
-    if is_builtin_number(x):
-        return checksum_builtin_number(x, **kwargs)
-    elif isinstance(x, bytes):
-        return checksum_bytes(x, **kwargs)
-    elif x is None:
-        return checksum_none(x, **kwargs)
-    elif isinstance(x, str):
-        return checksum_str(x, **kwargs)
-    else:
-        msg = f"Invalid argument type {type(x)}. (expected one of {get_args(BuiltinScalar)})"
-        raise TypeError(msg)
-
-
-@register_checksum_fn(None, custom_predicate=is_builtin_number)
-def checksum_builtin_number(x: BuiltinNumber, **kwargs) -> int:
-    """Compute a simple checksum of a builtin scalar number."""
-    # Note: instance check must follow this order: bool, int, float, complex, because isinstance(True, int) returns True !
-    if isinstance(x, bool):
-        return checksum_bool(x, **kwargs)
-    elif isinstance(x, int):
-        return checksum_int(x, **kwargs)
-    elif isinstance(x, float):
-        return checksum_float(x, **kwargs)
-    elif isinstance(x, complex):
-        return checksum_complex(x, **kwargs)
-    else:
-        msg = f"Invalid argument type {type(x)}. (expected one of {get_args(BuiltinNumber)})"
-        raise TypeError(msg)
-
-
 @register_checksum_fn(bytearray)
 def checksum_bytearray(x: bytearray, **kwargs) -> int:
     kwargs["accumulator"] = kwargs.get("accumulator", 0) + _cached_checksum_str(

{pythonwrench-0.3.0 → pythonwrench-0.4.0}/src/pythonwrench/collections/__init__.py

@@ -5,6 +5,7 @@ from .collections import (
     contained,
     dict_list_to_list_dict,
     dump_dict,
+    duplicate_list,
     filter_iterable,
     find,
     flat_dict_of_dict,

{pythonwrench-0.3.0 → pythonwrench-0.4.0}/src/pythonwrench/collections/collections.py

@@ -736,3 +736,26 @@ def unzip(lst):
         ... [1, 2, 3, 4], [5, 6, 7, 8]
     """
     return tuple(map(list, zip(*lst)))
+
+
+def duplicate_list(lst: List[T], sizes: List[int]) -> List[T]:
+    """Duplicate elements elements of a list with the corresponding sizes.
+
+    Example 1
+    ----------
+    >>> lst = ["a", "b", "c", "d", "e"]
+    >>> sizes = [1, 0, 2, 1, 3]
+    >>> duplicate_list(lst, sizes)
+    ... ["a", "c", "c", "d", "e", "e", "e"]
+    """
+    if len(lst) != len(sizes):
+        msg = f"Invalid arguments lengths. (found {len(lst)=} != {len(sizes)=})"
+        raise ValueError(msg)
+
+    out_size = sum(sizes)
+    out: List[T] = [None for _ in range(out_size)]  # type: ignore
+    curidx = 0
+    for size, elt in zip(sizes, lst):
+        out[curidx : curidx + size] = [elt] * size
+        curidx += size
+    return out

{pythonwrench-0.3.0 → pythonwrench-0.4.0}/src/pythonwrench/collections/reducers.py

@@ -56,6 +56,7 @@ def reduce_add(
 
 
 def reduce_add(*args, start=None):
+    """Reduce elements using "add" operator (+)."""
     return _reduce(*args, start=start, op_fn=operator.add, type_=SupportsAdd)
 
 
@@ -85,6 +86,7 @@ def reduce_and(
 
 
 def reduce_and(*args, start=None):
+    """Reduce elements using "and" operator (&)."""
     return _reduce(*args, start=start, op_fn=operator.and_, type_=SupportsAnd)
 
 
@@ -114,6 +116,7 @@ def reduce_mul(
 
 
 def reduce_mul(*args, start=None):
+    """Reduce elements using "mul" operator (*)."""
     return _reduce(*args, start=start, op_fn=operator.mul, type_=SupportsMul)
 
 
@@ -143,6 +146,7 @@ def reduce_or(
 
 
 def reduce_or(*args, start=None):
+    """Reduce elements using "or" operator (|)."""
     return _reduce(*args, start=start, op_fn=operator.or_, type_=SupportsOr)
 
 
@@ -204,6 +208,7 @@ def sum(
 
 
 def sum(*args, start: Any = 0):
+    """Compute sum of elements."""
     return reduce_add(*args, start=start)
 
 
@@ -233,6 +238,7 @@ def prod(
 
 
 def prod(*args, start: Any = 1):
+    """Compute product of elements."""
     return reduce_mul(*args, start=start)