pythonwrench 0.4.0__tar.gz → 0.4.2__tar.gz

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

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.1
 Name: pythonwrench
-Version: 0.4.0
+Version: 0.4.2
 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>
@@ -47,7 +47,7 @@ Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: typing-extensions>=4.10.0
-Dynamic: license-file
+Provides-Extra: dev
 
 # pythonwrench
 

pythonwrench-0.4.2/docs/requirements.txt

@@ -0,0 +1,3 @@
+# -*- coding: utf-8 -*-
+
+sphinx-immaterial>=0.11.14

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

@@ -45,6 +45,9 @@ pyw-info = "pythonwrench.entries:print_install_info"
 pyw-tree = "pythonwrench.entries:main_tree"
 pyw-safe-rmdir = "pythonwrench.entries:main_safe_rmdir"
 
+[project.optional-dependencies]
+dev = []
+
 [build-system]
 requires = ["setuptools >= 61.0"]
 build-backend = "setuptools.build_meta"
@@ -87,6 +90,6 @@ dev = [
     "ruff>=0.12.0",
     "setuptools",
     "sphinx",
-    "sphinx-press-theme",
+    "sphinx-immaterial>=0.11.14",
     "twine",
 ]

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

@@ -9,25 +9,28 @@ __author_email__ = "labbeti.pub@gmail.com"
 __license__ = "MIT"
 __maintainer__ = "Étienne Labbé (Labbeti)"
 __status__ = "Development"
-__version__ = "0.4.0"
+__version__ = "0.4.2"
 
 
 # Re-import for language servers
 from . import abc as abc
 from . import argparse as argparse
+from . import cast as cast
+from . import checksum as checksum
 from . import collections as collections
 from . import csv as csv
 from . import dataclasses as dataclasses
 from . import datetime as datetime
 from . import difflib as difflib
+from . import disk_cache as disk_cache
 from . import entries as entries
 from . import enum as enum
 from . import functools as functools
 from . import hashlib as hashlib
 from . import importlib as importlib
 from . import inspect as inspect
-from . import io as io
 from . import json as json
+from . import jsonl as jsonl
 from . import logging as logging
 from . import math as math
 from . import os as os
@@ -166,6 +169,7 @@ from .typing import (
     SupportsAnd,
     SupportsBool,
     SupportsDiv,
+    SupportsGetitem,
     SupportsGetitemIterLen,
     SupportsGetitemLen,
     SupportsIterLen,

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

@@ -1,7 +1,10 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
 
+import os
 from functools import wraps
+from io import TextIOWrapper
+from pathlib import Path
 from typing import (
     Any,
     Callable,
@@ -9,22 +12,27 @@ from typing import (
     Generic,
     Literal,
     Optional,
+    Protocol,
     Tuple,
-    TypeVar,
     Union,
     get_args,
+    overload,
 )
 
-from typing_extensions import ParamSpec
+from typing_extensions import ParamSpec, TypeVar
 
 P = ParamSpec("P")
-T = TypeVar("T")
-U = TypeVar("U")
+T = TypeVar("T", covariant=True)
+U = TypeVar("U", covariant=True)
 T_Output = TypeVar("T_Output")
+T_Any = TypeVar("T_Any", contravariant=True, default=Any)
 
 UnkMode = Literal["identity", "error"]
 ClassOrTuple = Union[type, Tuple[type, ...]]
-Predicate = Callable[[Any], bool]
+
+
+class Predicate(Protocol[T_Any]):
+    def __call__(self, x: T_Any) -> bool: ...
 
 
 def return_none(*args, **kwargs) -> None:
@@ -161,3 +169,53 @@ class _FunctionRegistry(Generic[T_Output]):
         else:
             msg = f"Invalid argument {unk_mode=}. (expected one of {get_args(UnkMode)})"
             raise ValueError(msg)
+
+
+@overload
+def _setup_output_fpath(
+    fpath: Union[str, Path, os.PathLike],
+    overwrite: bool,
+    make_parents: bool,
+    absolute: bool = True,
+) -> Path: ...
+
+
+@overload
+def _setup_output_fpath(
+    fpath: TextIOWrapper,
+    overwrite: bool,
+    make_parents: bool,
+    absolute: bool = True,
+) -> TextIOWrapper: ...
+
+
+@overload
+def _setup_output_fpath(
+    fpath: None,
+    overwrite: bool,
+    make_parents: bool,
+    absolute: bool = True,
+) -> None: ...
+
+
+def _setup_output_fpath(
+    fpath: Union[str, Path, os.PathLike, TextIOWrapper, None],
+    overwrite: bool,
+    make_parents: bool,
+    absolute: bool = True,
+) -> Union[Path, None, TextIOWrapper]:
+    """Resolve path, expand path and create intermediate parents."""
+    if not isinstance(fpath, (str, Path, os.PathLike)):
+        return fpath
+
+    fpath = Path(fpath)
+    if absolute:
+        fpath = fpath.resolve().expanduser()
+
+    if not overwrite and fpath.exists():
+        msg = f"File {fpath} already exists."
+        raise FileExistsError(msg)
+    elif make_parents:
+        fpath.parent.mkdir(parents=True, exist_ok=True)
+
+    return fpath

{pythonwrench-0.4.0 → pythonwrench-0.4.2}/src/pythonwrench/abc.py

@@ -7,14 +7,15 @@ from typing import Any, ClassVar, Dict, Type
 class Singleton(type):
     """Singleton metaclass.
 
-    To use it, just inherit from metaclass:
-    ```
+    To use it, just inherit from metaclass.
+
+    Example
+    -------
     >>> class MyClass(metaclass=Singleton):
     >>>     pass
     >>> a1 = MyClass()
     >>> a2 = MyClass()
     >>> # a1 and a2 are exactly the same instance, i.e. id(a1) == id(a2)
-    ```
     """
 
     _instances: ClassVar[Dict[Type, Any]] = {}

{pythonwrench-0.4.0 → pythonwrench-0.4.2}/src/pythonwrench/argparse.py

@@ -35,7 +35,7 @@ def parse_to(
 ) -> Callable[[str], T]:
     """Returns a callable that convert string value to target type safely.
 
-    Intended for argparse boolean arguments.
+    Intended for argparse arguments.
     """
     return partial(
         str_to_type,
@@ -56,7 +56,7 @@ def str_to_type(
     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.
+    """Convert string values to target type safely. Intended for argparse arguments.
 
     - True values: 'True', 'T', 'yes', 'y', '1'.
     - False values: 'False', 'F', 'no', 'n', '0'.
@@ -84,7 +84,7 @@ def str_to_bool(
     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.
+    """Convert string values to bool safely. Intended for argparse arguments.
 
     - True values: 'True', 'T', 'yes', 'y', '1'.
     - False values: 'False', 'F', 'no', 'n', '0'.
@@ -105,7 +105,7 @@ def str_to_none(
     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.
+    """Convert string values to None safely. Intended for argparse arguments.
 
     - None values: 'None', 'null'
     - Other raises ValueError.
@@ -123,7 +123,7 @@ def str_to_optional_bool(
     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.
+    """Convert string values to optional bool safely. Intended for argparse arguments.
 
     - True values: 'True', 'T', 'yes', 'y', '1'.
     - False values: 'False', 'F', 'no', 'n', '0'.
@@ -141,7 +141,7 @@ def str_to_optional_float(
     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."""
+    """Convert string values to optional float safely. Intended for argparse arguments."""
     return str_to_type(
         x, Optional[float], case_sensitive=case_sensitive, none_values=none_values
     )
@@ -153,7 +153,7 @@ def str_to_optional_int(
     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."""
+    """Convert string values to optional int safely. Intended for argparse arguments."""
     return str_to_type(
         x, Optional[int], case_sensitive=case_sensitive, none_values=none_values
     )
@@ -165,7 +165,7 @@ def str_to_optional_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."""
+    """Convert string values to optional str safely. Intended for argparse arguments."""
     return str_to_type(
         x, Optional[str], case_sensitive=case_sensitive, none_values=none_values
     )
@@ -284,7 +284,7 @@ def _str_to_none_impl(
     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.
+    """Convert string values to None safely. Intended for argparse arguments.
 
     - None values: 'None', 'null'
     - Other raises ValueError.

{pythonwrench-0.4.0 → pythonwrench-0.4.2}/src/pythonwrench/cast.py

@@ -63,16 +63,15 @@ def register_as_builtin_fn(
     priority: int = 0,
 ) -> Callable:
     """Decorator to add an as_builtin function.
-    ```
-    >>> import numpy as np
 
+    Example
+    -------
+    >>> import numpy as np
     >>> @register_as_builtin_fn(np.ndarray)
     >>> def my_checksum_for_numpy(x: np.ndarray):
     >>>     return x.tolist()
-
     >>> pw.as_builtin([np.array([1, 2]), [3, 4]])
     ... [[1, 2], [3, 4]]
-    ```
     """
     return _AS_BUILTIN_REGISTRY.register_decorator(
         class_or_tuple,

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

@@ -60,15 +60,14 @@ def register_checksum_fn(
     priority: int = 0,
 ) -> Callable:
     """Decorator to add a checksum function.
-    ```
-    >>> import numpy as np
 
+    Example
+    -------
+    >>> import numpy as np
     >>> @register_checksum_fn(np.ndarray)
     >>> def my_checksum_for_numpy(x: np.ndarray):
     >>>     return int(x.sum())
-
     >>> pw.checksum_any(np.array([1, 2]))  # calls my_checksum_for_numpy internally, even if array in nested inside a list, dict, etc.
-    ```
     """
     return _CHECKSUM_REGISTRY.register_decorator(
         class_or_tuple,
@@ -196,7 +195,9 @@ def checksum_set(x: Union[set, frozenset], **kwargs) -> int:
     kwargs["accumulator"] = kwargs.get("accumulator", 0) + _cached_checksum_str(
         get_fullname(x)
     )
-    return _checksum_iterable(sorted(x), **kwargs)
+    # Simply use sum here, order does not matter
+    csum = sum(checksum_any(xi, **kwargs) for xi in x)
+    return csum
 
 
 @register_checksum_fn(range)

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

@@ -74,17 +74,17 @@ def contained(
 @overload
 def dict_list_to_list_dict(
     dic: Mapping[T, Iterable[U]],
-    key_mode: Literal["same", "intersect"],
-    default_val: Any = None,
-) -> List[Dict[T, U]]: ...
+    key_mode: Literal["union"] = "union",
+    default_val: W = None,
+) -> List[Dict[T, Union[U, W]]]: ...
 
 
 @overload
 def dict_list_to_list_dict(
     dic: Mapping[T, Iterable[U]],
-    key_mode: Literal["union"] = "union",
-    default_val: W = None,
-) -> List[Dict[T, Union[U, W]]]: ...
+    key_mode: Literal["same", "intersect"],
+    default_val: Any = None,
+) -> List[Dict[T, U]]: ...
 
 
 def dict_list_to_list_dict(
@@ -95,20 +95,16 @@ def dict_list_to_list_dict(
     """Convert dict of lists with same sizes to list of dicts.
 
     Example 1
-    ----------
-    ```
+    ---------
     >>> dic = {"a": [1, 2], "b": [3, 4]}
     >>> dict_list_to_list_dict(dic)
     ... [{"a": 1, "b": 3}, {"a": 2, "b": 4}]
-    ```
 
     Example 2
-    ----------
-    ```
+    ---------
     >>> dic = {"a": [1, 2, 3], "b": [4], "c": [5, 6]}
     >>> dict_list_to_list_dict(dic, key_mode="union", default=-1)
     ... [{"a": 1, "b": 4, "c": 5}, {"a": 2, "b": -1, "c": 6}, {"a": 3, "b": -1, "c": -1}]
-    ```
     """
     if len(dic) == 0:
         return []
@@ -151,11 +147,9 @@ def dump_dict(
 
     Example 1:
     ----------
-    ```
     >>> d = {"a": 1, "b": 2}
     >>> dump_dict(d)
     ... 'a=1, b=2'
-    ```
     """
     if dic is None:
         dic = {}
@@ -360,7 +354,6 @@ def flat_dict_of_dict(
 
     Example 1
     ---------
-    ```
     >>> dic = {
     ...     "a": 1,
     ...     "b": {
@@ -370,15 +363,12 @@ def flat_dict_of_dict(
     ... }
     >>> flat_dict_of_dict(dic)
     ... {"a": 1, "b.a": 2, "b.b": 10}
-    ```
 
     Example 2
     ---------
-    ```
     >>> dic = {"a": ["hello", "world"], "b": 3}
     >>> flat_dict_of_dict(dic, flat_iterables=True)
     ... {"a.0": "hello", "a.1": "world", "b": 3}
-    ```
 
     Args:
         nested_dic: Nested mapping containing sub-mappings or iterables.
@@ -508,10 +498,11 @@ def list_dict_to_dict_list(
 
     Args:
         lst: The list of dict to merge.
-        key_mode: Can be "same" or "intersect".
-            If "same", all the dictionaries must contains the same keys otherwise a ValueError will be raised.
-            If "intersect", only the intersection of all keys will be used in output.
-            If "union", the output dict will contains the union of all keys, and the missing value will use the argument default_val.
+        key_mode: Can be "same" or "intersect". \
+            - If "same", all the dictionaries must contains the same keys otherwise a ValueError will be raised. \
+            - If "intersect", only the intersection of all keys will be used in output. \
+            - If "union", the output dict will contains the union of all keys, and the missing value will use the argument default_val. \
+            - If an iterable of elements, use them as keys for output dict.
         default_val: Default value of an element when key_mode is "union". defaults to None.
         default_val_fn: Function to return the default value according to a specific key. defaults to None.
         list_fn: Optional function to build the values. defaults to identity.
@@ -622,7 +613,6 @@ def unflat_dict_of_dict(dic: Mapping[str, Any], *, sep: str = ".") -> Dict[str,
 
     Example 1
     ----------
-    ```
     >>> dic = {
         "a.a": 1,
         "b.a": 2,
@@ -631,7 +621,6 @@ def unflat_dict_of_dict(dic: Mapping[str, Any], *, sep: str = ".") -> Dict[str,
     }
     >>> unflat_dict_of_dict(dic)
     ... {"a": {"a": 1}, "b": {"a": 2, "b": 3}, "c": 4}
-    ```
     """
     output = {}
     for k, v in dic.items():
@@ -671,6 +660,7 @@ def unflat_list_of_list(
 
 
 def union_dicts(dicts: Iterable[Dict[K, V]]) -> Dict[K, V]:
+    """Performs union of dictionaries."""
     if Version.python() >= Version("3.9.0"):
         return reduce_or(*dicts)
 
@@ -721,19 +711,24 @@ def unzip(
 ) -> Tuple[List[T], List[U], List[V], List[W], List[X]]: ...
 
 
+@overload
+def unzip(
+    lst: Iterable[Tuple[T, ...]],
+) -> Tuple[List[T], ...]: ...
+
+
 def unzip(lst):
     """Invert function of builtin zip().
 
-    .. code-block:: python
-        :caption:  Example
-
-        >>> lst1 = [1, 2, 3, 4]
-        >>> lst2 = [5, 6, 7, 8]
-        >>> lst_zipped = list(zip(lst1, lst2))
-        >>> lst_zipped
-        ... [(1, 5), (2, 6), (3, 7), (4, 8)]
-        >>> unzip(lst_zipped)
-        ... [1, 2, 3, 4], [5, 6, 7, 8]
+    Example
+    -------
+    >>> lst1 = [1, 2, 3, 4]
+    >>> lst2 = [5, 6, 7, 8]
+    >>> zipped_list = list(zip(lst1, lst2))
+    >>> zipped_list
+    ... [(1, 5), (2, 6), (3, 7), (4, 8)]
+    >>> unzip(zipped_list)
+    ... [1, 2, 3, 4], [5, 6, 7, 8]
     """
     return tuple(map(list, zip(*lst)))
 
@@ -741,8 +736,8 @@ def unzip(lst):
 def duplicate_list(lst: List[T], sizes: List[int]) -> List[T]:
     """Duplicate elements elements of a list with the corresponding sizes.
 
-    Example 1
-    ----------
+    Example
+    -------
     >>> lst = ["a", "b", "c", "d", "e"]
     >>> sizes = [1, 0, 2, 1, 3]
     >>> duplicate_list(lst, sizes)

{pythonwrench-0.4.0 → pythonwrench-0.4.2}/src/pythonwrench/csv.py

@@ -21,10 +21,10 @@ from typing import (
     overload,
 )
 
+from pythonwrench._core import _setup_output_fpath
 from pythonwrench.cast import as_builtin
 from pythonwrench.collections import dict_list_to_list_dict, list_dict_to_dict_list
 from pythonwrench.functools import function_alias
-from pythonwrench.io import _setup_output_fpath
 from pythonwrench.typing import isinstance_generic
 
 T = TypeVar("T")
@@ -48,7 +48,7 @@ def dump_csv(
     replace_newline_by: Optional[str] = "\\n",
     **csv_writer_kwds,
 ) -> str:
-    """Dump content to CSV format into string and/or file.
+    r"""Dump content to CSV format into string and/or file.
 
     Args:
         data: Data to serialize. Can be a list of dicts, dicts of lists or list of lists.
@@ -59,7 +59,7 @@ def dump_csv(
         header: Indicates if CSV must have header. If "auto", an header is added when a dict of list or list of dicts is passed. defaults to "auto".
         align_content: If True, center content at the middle of each row for better visualization. defaults to False.
         replace_newline_by: Replace newline character to avoid newline in CSV content. defaults to "\\n".
-        **csv_writer_kwds: Others optional arguments passed to CSV writer object.
+        \*\*csv_writer_kwds: Others optional arguments passed to CSV writer object.
 
     Returns:
         Dumped content as string.
@@ -98,7 +98,7 @@ def dumps_csv(
     replace_newline_by: Optional[str] = "\\n",
     **csv_writer_kwds,
 ) -> str:
-    """Dump content to CSV format into string.
+    r"""Dump content to CSV format into string.
 
     Args:
         data: Data to serialize. Can be a list of dicts, dicts of lists or list of lists.
@@ -108,7 +108,7 @@ def dumps_csv(
         header: Indicates if CSV must have header. If "auto", an header is added when a dict of list or list of dicts is passed. defaults to "auto".
         align_content: If True, center content at the middle of each row for better visualization. defaults to False.
         replace_newline_by: Replace newline character to avoid newline in CSV content. defaults to "\\n".
-        **csv_writer_kwds: Others optional arguments passed to CSV writer object.
+        \*\*csv_writer_kwds: Others optional arguments passed to CSV writer object.
 
     Returns:
         Dumped content as string.
@@ -140,7 +140,7 @@ def save_csv(
     replace_newline_by: Optional[str] = "\\n",
     **csv_writer_kwds,
 ) -> None:
-    """Save content to CSV format into a file or buffer.
+    r"""Save content to CSV format into a file or buffer.
 
     Args:
         data: Data to serialize. Can be a list of dicts, dicts of lists or list of lists.
@@ -150,7 +150,7 @@ def save_csv(
         header: Indicates if CSV must have header. If "auto", an header is added when a dict of list or list of dicts is passed. defaults to "auto".
         align_content: If True, center content at the middle of each row for better visualization. defaults to False.
         replace_newline_by: Replace newline character to avoid newline in CSV content. defaults to "\\n".
-        **csv_writer_kwds: Others optional arguments passed to CSV writer object.
+        \*\*csv_writer_kwds: Others optional arguments passed to CSV writer object.
     """
     if isinstance(file, (str, Path, PathLike)):
         file = _setup_output_fpath(file, overwrite=overwrite, make_parents=make_parents)
@@ -320,14 +320,14 @@ def load_csv(
     delimiter: Optional[str] = ",",
     **csv_reader_kwds,
 ) -> Union[List[Dict[str, Any]], Dict[str, List[Any]]]:
-    """Load content from csv filepath.
+    r"""Load content from csv filepath.
 
     Args:
         orient: Orientation of the output value. Can be "list" or "dict". defaults to "list".
         header: Specify if CSV has header column. defaults to True.
         comment_start: If this string is not None and a line starts with this string, the line will be ignored. defaults to None.
         delimiter: Value delimiter. defaults to ",".
-        **csv_reader_kwds: Other optional csv arguments.
+        \*\*csv_reader_kwds: Other optional csv arguments.
 
     Returns:
         The loaded values as dict of lists, list of dicts or list of lists.