pythonwrench 0.6.7__tar.gz → 0.6.8__tar.gz

{pythonwrench-0.6.7 → pythonwrench-0.6.8}/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.6.8] 2026-10-26
+### Added
+- `remove_children` function to remove all content of a directory.
+- `filter_dict_with_patterns` function.
+- `parse_args_using_dataclass` and `add_dataclass_fields_to_parser` functions now supports nested dataclasses with subparsers.
+
+### Modified
+- `Version` is now converted to str by default in `as_builtin`.
+- `isinstance_generic` now raises explicit exception when forwarded ref is given.
+
+
 ## [0.6.7] 2026-09-07
 ### Added
 - `on_error` and `default` arguments to `load_json`, `load_pickle`, `load_jsonl` functions.

{pythonwrench-0.6.7 → pythonwrench-0.6.8}/CITATION.cff

@@ -17,5 +17,5 @@ keywords:
   - tools
   - utilities
 license: MIT
-version: 0.6.7
-date-released: '2026-09-07'
+version: 0.6.8
+date-released: '2026-10-26'

{pythonwrench-0.6.7 → pythonwrench-0.6.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pythonwrench
-Version: 0.6.7
+Version: 0.6.8
 Summary: Python library with tools for typing, manipulating collections, and more!
 Project-URL: Homepage, https://pypi.org/project/pythonwrench/
 Project-URL: Documentation, https://pythonwrench.readthedocs.io/

pythonwrench-0.6.8/pythonwrench.code-workspace

@@ -0,0 +1,13 @@
+{
+    "folders": [
+        {
+            "path": "."
+        }
+    ],
+    "settings": {
+        "files.exclude": {
+            "**/.coverage": true,
+            "**/*.egg-info": true
+        }
+    }
+}

{pythonwrench-0.6.7 → pythonwrench-0.6.8}/src/pythonwrench/__init__.py

@@ -9,7 +9,7 @@ __author_email__ = "labbeti.pub@gmail.com"
 __license__ = "MIT"
 __maintainer__ = "Étienne Labbé (Labbeti)"
 __status__ = "Development"
-__version__ = "0.6.7"
+__version__ = "0.6.8"
 
 
 from typing import TYPE_CHECKING
@@ -157,12 +157,14 @@ if TYPE_CHECKING or lazy is None:
         setup_logging_verbose,
     )
     from .math import argmax, argmin, argsort, clamp, clip
-    from .os import get_num_cpus_available, safe_rmdir, tree_iter
+    from .os import get_num_cpus_available, remove_children, safe_rmdir, tree_iter
     from .random import randstr
     from .re import (
         PatternLike,
         PatternListLike,
         compile_patterns,
+        filter_dict_with_patterns,
+        filter_iter_with_patterns,
         filter_with_patterns,
         find_patterns,
         get_key_fn,
@@ -245,6 +247,7 @@ if TYPE_CHECKING or lazy is None:
         is_special_form,
         is_typed_dict,
         isinstance_generic,
+        isinstance_parametrized,
     )
     from .warnings import deprecated_alias, deprecated_function, warn_once
 
@@ -414,13 +417,20 @@ else:
                 "setup_logging_verbose",
             ],
             "math": ["argmax", "argmin", "argsort", "clamp", "clip"],
-            "os": ["get_num_cpus_available", "safe_rmdir", "tree_iter"],
+            "os": [
+                "get_num_cpus_available",
+                "remove_children",
+                "safe_rmdir",
+                "tree_iter",
+            ],
             "random": ["randstr"],
             "re": [
                 "PatternLike",
                 "PatternListLike",
                 "compile_patterns",
                 "filter_with_patterns",
+                "filter_iter_with_patterns",
+                "filter_dict_with_patterns",
                 "find_patterns",
                 "get_key_fn",
                 "match_patterns",
@@ -476,6 +486,7 @@ else:
                 "is_special_form",
                 "is_typed_dict",
                 "isinstance_generic",
+                "isinstance_parametrized",
             ],
             "warnings": ["deprecated_alias", "deprecated_function", "warn_once"],
         },

{pythonwrench-0.6.7 → pythonwrench-0.6.8}/src/pythonwrench/_core.py

@@ -1,7 +1,8 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
 
-from functools import wraps
+import warnings
+from functools import lru_cache, partial, wraps
 from typing import (
     Any,
     Callable,
@@ -11,8 +12,10 @@ from typing import (
     Optional,
     Protocol,
     Tuple,
+    Type,
     Union,
     get_args,
+    overload,
     runtime_checkable,
 )
 
@@ -21,6 +24,7 @@ from typing_extensions import ParamSpec, TypeVar
 P = ParamSpec("P")
 T = TypeVar("T", covariant=True)
 U = TypeVar("U", covariant=True)
+
 T_Output = TypeVar("T_Output", default=Any)
 T_PredicateArg = TypeVar("T_PredicateArg", contravariant=True, default=Any)
 T_Function = TypeVar("T_Function", bound=Callable[..., Any])
@@ -41,6 +45,31 @@ def return_none(*args, **kwargs) -> None:
     return None
 
 
+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 _decorator_factory(
     inner_fn: Optional[T_Function],
     *,
@@ -190,3 +219,108 @@ def _get_insertion_index(lst: list, priority: int, priority_key: int) -> int:
         if priority >= other_priority:
             return i
     return len(lst)
+
+
+@overload
+def warn_once(
+    message: str,
+    category: Optional[Type[Warning]] = None,
+    stacklevel: int = 1,
+    source: Any = None,
+) -> None:
+    """Warn message once using warnings module."""
+    ...
+
+
+@overload
+def warn_once(
+    message: Warning,
+    category: Any = None,
+    stacklevel: int = 1,
+    source: Any = None,
+) -> None:
+    """Warn message once using warnings module."""
+    ...
+
+
+@lru_cache(maxsize=None)
+def warn_once(
+    message: Union[str, Warning],
+    category: Optional[Type[Warning]] = None,
+    stacklevel: int = 1,
+    source: Any = None,
+) -> None:
+    """Warn message once using warnings module."""
+    warnings.warn(message, category, stacklevel, source)
+
+
+def deprecated_alias(
+    alternative: T_Function,
+    msg_fmt: str = "Deprecated call to '{fn_name}', use '{alternative_name}' instead.",
+    warn_fn: Callable[[str], Any] = partial(warn_once, category=DeprecationWarning),
+    *,
+    pre_fn: Optional[Callable[..., Any]] = None,
+    post_fn: Optional[Callable[..., Any]] = None,
+) -> Callable[..., T_Function]:
+    """Decorator to wrap deprecated function aliases."""
+    alternative_name = alternative.__name__ if alternative is not None else "None"
+    if pre_fn is None:
+        pre_fn = return_none
+
+    def inner_pre_fn(fn, *args, **kwargs) -> None:
+        """Perform the inner pre fn operation."""
+        msg = msg_fmt.format(fn_name=fn.__name__, alternative_name=alternative_name)
+        warn_fn(msg)
+        pre_fn(fn, *args, **kwargs)
+
+    return _decorator_factory(alternative, pre_fn=inner_pre_fn, post_fn=post_fn)
+
+
+@overload
+def deprecated_function(
+    fn: None = None,
+    /,
+    *,
+    msg_fmt: str = "Deprecated call to '{fn_name}'.",
+    warn_fn: Callable[[str], Any] = partial(warn_once, category=DeprecationWarning),
+) -> Callable[[T_Function], T_Function]:
+    """Perform the deprecated function operation."""
+    ...
+
+
+@overload
+def deprecated_function(
+    fn: T_Function,
+    /,
+    *,
+    msg_fmt: str = "Deprecated call to '{fn_name}'.",
+    warn_fn: Callable[[str], Any] = partial(warn_once, category=DeprecationWarning),
+) -> T_Function:
+    """Perform the deprecated function operation."""
+    ...
+
+
+def deprecated_function(
+    fn: Optional[T_Function] = None,
+    /,
+    *,
+    msg_fmt: str = "Deprecated call to '{fn_name}'.",
+    warn_fn: Callable[[str], Any] = partial(warn_once, category=DeprecationWarning),
+    pre_fn: Optional[Callable[..., Any]] = None,
+    post_fn: Optional[Callable[..., Any]] = None,
+) -> Union[Callable[[T_Function], T_Function], T_Function]:
+    """Decorator to wrap deprecated functions."""
+    if pre_fn is None:
+        pre_fn = return_none
+
+    def inner_pre_fn(fn, *args, **kwargs):
+        """Perform the inner pre fn operation."""
+        msg = msg_fmt.format(fn_name=fn.__qualname__)
+        warn_fn(msg)
+        pre_fn(fn, *args, **kwargs)
+
+    decorator = _decorator_factory(None, pre_fn=inner_pre_fn, post_fn=post_fn)
+    if fn is None:
+        return decorator
+    else:
+        return decorator(fn)

{pythonwrench-0.6.7 → pythonwrench-0.6.8}/src/pythonwrench/argparse/dataclass_.py

@@ -1,12 +1,14 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
 
+import copy
 from argparse import ArgumentParser, Namespace
 from dataclasses import MISSING, fields
 from typing import (
     Any,
     Dict,
     Iterable,
+    List,
     Literal,
     Optional,
     Tuple,
@@ -21,9 +23,11 @@ from pythonwrench.argparse.parsers import (
     ListParsing,
     _is_iterable_type_like,
     _is_literal_type,
+    _is_union_type,
     _search_parse_fn,
 )
 from pythonwrench.functools import filter_and_call
+from pythonwrench.typing.checks import is_dataclass_type
 from pythonwrench.typing.classes import (
     Dataclass,
     DataclassInstance,
@@ -165,8 +169,8 @@ def parse_args_using_dataclass(
 
 
 def parse_args_using_dataclass(
-    dataclass_type: Type[DataclassInstance],
-    *dataclass_types: Type[DataclassInstance],
+    dataclass_type: Dataclass,
+    *dataclass_types: Dataclass,
     args: Optional[Iterable[str]] = None,
     parser: Optional[ArgumentParser] = None,
     list_parsing: ListParsing = "argparse",
@@ -198,25 +202,21 @@ def parse_args_using_dataclass(
         )
     assert parser is not None
 
-    parsed, argv = parser.parse_known_args(args)
-    if len(argv) > 0:
-        msg = f"Found {len(argv)} unknown arguments: {argv}."
+    parsed, other_args = parser.parse_known_args(args)
+    if len(other_args) > 0:
+        msg = f"Found {len(other_args)} unknown arguments: {other_args}. (with source {args=})"
         raise ValueError(msg)
 
     if return_single_namespace:
         return parsed
 
-    dataclass_insts = []
-    for dataclass_type_i in dataclass_types:
-        if init_parser is None and len(dataclass_types) == 1:
-            instance = dataclass_type_i(**parsed.__dict__)
-        else:
-            instance = filter_and_call(
-                dataclass_type_i,
-                _fill_all_arguments=True,
-                **parsed.__dict__,
-            )
-        dataclass_insts.append(instance)
+    accept_more_args = (init_parser is not None) or (len(dataclass_types) != 1)
+    # breakpoint()  # TODO
+    dataclass_insts = _instantiate_dataclasses(
+        dataclass_types,
+        parsed,
+        accept_more_args=accept_more_args,
+    )
 
     if len(dataclass_insts) == 1:
         return dataclass_insts[0]
@@ -224,6 +224,79 @@ def parse_args_using_dataclass(
         return tuple(dataclass_insts)
 
 
+def _instantiate_dataclasses(
+    dcls_types: Tuple[Dataclass, ...],
+    parsed: Union[Namespace, Dict[str, Any]],
+    accept_more_args: bool,
+) -> List[DataclassInstance]:
+    if isinstance(parsed, Namespace):
+        parsed = parsed.__dict__
+
+    subparser_fields = {
+        field.name
+        for dcls_type in dcls_types
+        for field in fields(dcls_type)
+        if _is_dataclass_or_union_of_dataclasses(field.type)
+    }
+    base_kwds = {
+        k: v for k, v in parsed.items() if "." not in k and k not in subparser_fields
+    }
+
+    dcls_insts = []
+
+    for dcls_type_i in dcls_types:
+        sub_dclasses = {
+            field.name: field.type
+            for field in fields(dcls_type_i)
+            if _is_dataclass_or_union_of_dataclasses(field.type)
+        }
+
+        kwds_i = copy.copy(base_kwds)
+        for name, dcls_union in sub_dclasses.items():
+            selected = parsed.get(name)
+            if selected is None:
+                # note: an optional subparser that was not selected is None,
+                # it must not replace the dataclass field's default/default_factory.
+                continue
+
+            if _is_union_type(dcls_union):
+                dclasses = get_args(dcls_union)
+                dclasses_names = {dcls.__name__: dcls for dcls in dclasses}
+                try:
+                    dclass_type = dclasses_names[selected]
+                except KeyError as err:
+                    msg = f"Invalid subparser {selected!r} for field {name!r}."
+                    raise ValueError(msg) from err
+            else:
+                dclass_type = dcls_union
+
+            field_prefix = f"{name}."
+            field_kwds = {
+                key[len(field_prefix) :]: value
+                for key, value in parsed.items()
+                if key.startswith(field_prefix)
+            }
+            dclass_inst = _instantiate_dataclasses(
+                (dclass_type,),  # type: ignore
+                parsed=field_kwds,
+                accept_more_args=True,
+            )[0]
+            kwds_i[name] = dclass_inst
+
+        if accept_more_args:
+            instance = filter_and_call(
+                dcls_type_i,
+                _fill_all_arguments=True,
+                **kwds_i,
+            )
+        else:
+            instance = dcls_type_i(**kwds_i)
+
+        dcls_insts.append(instance)
+
+    return dcls_insts
+
+
 def add_dataclass_fields_to_parser(
     dataclass_type: Type[T_DataclassInstance],
     *,
@@ -232,12 +305,13 @@ def add_dataclass_fields_to_parser(
     bool_action: BoolAction = "store",
     add_dashed_arg: bool = True,
     posonly_for_required: bool = False,
+    argprefix: str = "",
 ) -> ArgumentParser:
     """Perform the add dataclass fields to parser operation."""
     if posonly_for_required:
-        prefix = ""
+        prefix = argprefix
     else:
-        prefix = "--"
+        prefix = f"--{argprefix}"
 
     if parser is None:
         parser = ArgumentParser()
@@ -258,19 +332,45 @@ def add_dataclass_fields_to_parser(
         elif field.default is not MISSING:
             kwds["default"] = field.default
         elif field.default_factory is not MISSING:
-            kwds["default"] = field.default_factory()  # type: ignore
+            kwds["default"] = field.default_factory()
         else:
-            msg = f"Invalid field {field.name}: found values for default and default_factory."
+            msg = f"Invalid field '{field.name}': found values for default and default_factory."
             raise ValueError(msg)
 
-        try:
-            inner_kwds = _get_kwds_for_type(field.type, list_parsing, bool_action)
-        except (ValueError, TypeError, RuntimeError) as err:
-            msg = f"Invalid field {field.name}: field type '{field.type}' is not supported."
-            raise type(err)(msg) from err
+        if is_dataclass_type(field.type):
+            subclasses = (field.type,)
+        elif _is_union_of_dataclasses(field.type):
+            subclasses = get_args(field.type)
+        else:
+            subclasses = None
+
+        if subclasses is not None:
+            subparsers = parser.add_subparsers(
+                dest=f"{argprefix}{field.name}",
+                required=kwds.get("required", False),
+            )
+            for subcls in subclasses:
+                subparser = subparsers.add_parser(subcls.__name__)
+                add_dataclass_fields_to_parser(
+                    subcls,
+                    parser=subparser,
+                    list_parsing=list_parsing,
+                    bool_action=bool_action,
+                    add_dashed_arg=add_dashed_arg,
+                    posonly_for_required=posonly_for_required,
+                    argprefix=f"{argprefix}{field.name}.",
+                )
+
+        else:
+            try:
+                inner_kwds = _get_kwds_for_type(field.type, list_parsing, bool_action)
+            except (ValueError, TypeError, RuntimeError) as err:
+                msg = f"Invalid field '{field.name}': field type '{field.type}' is not supported."
+                raise type(err)(msg) from err
+
+            kwds.update(inner_kwds)
 
-        kwds.update(inner_kwds)
-        parser.add_argument(*posargs, **kwds)
+            parser.add_argument(*posargs, **kwds)
 
     return parser
 
@@ -314,6 +414,16 @@ def _get_kwds_for_type(
         raise TypeError(msg)
 
 
+def _is_dataclass_or_union_of_dataclasses(x: Any) -> bool:
+    return is_dataclass_type(x) or _is_union_of_dataclasses(x)
+
+
+def _is_union_of_dataclasses(x: Any) -> bool:
+    return _is_union_type(x) and all(
+        is_dataclass_type(subcls) for subcls in get_args(x)
+    )
+
+
 # ALIASES
 @deprecated_alias(add_dataclass_fields_to_parser)
 def new_parser_from_dataclass(*args, **kwargs):

{pythonwrench-0.6.7 → pythonwrench-0.6.8}/src/pythonwrench/cast.py

@@ -22,6 +22,7 @@ from typing import (
 
 from pythonwrench._core import ClassOrTuple, Predicate, _FunctionRegistry
 from pythonwrench.functools import identity
+from pythonwrench.semver import Version
 from pythonwrench.typing import (
     DataclassInstance,
     NamedTupleInstance,
@@ -136,11 +137,16 @@ def _dataclass_to_builtin(x: DataclassInstance, **kwargs) -> Any:
 
 
 @register_as_builtin_fn(NamedTupleInstance)
-def _namedtuple_to_builtin(x: NamedTupleInstance, **kwargs) -> Any:
+def _namedtuple_to_builtin(x: NamedTupleInstance, **kwargs) -> Dict[str, Any]:
     """Perform the namedtuple to builtin operation."""
     return as_builtin(x._asdict(), **kwargs)
 
 
+@register_as_builtin_fn(Version)
+def _version_to_str(x: Version, **kwargs) -> str:
+    return x.to_str()
+
+
 @register_as_builtin_fn(Mapping, priority=-100)
 def _mapping_to_builtin(x: Mapping, **kwargs) -> Any:
     """Perform the mapping to builtin operation."""

{pythonwrench-0.6.7 → pythonwrench-0.6.8}/src/pythonwrench/collections/collections.py

@@ -47,6 +47,8 @@ Y = TypeVar("Y", covariant=True)
 
 KeyMode = Literal["intersect", "same", "union"]
 Order = Literal["left", "right"]
+DictByKV = Literal["key", "value"]
+DictByKVI = Literal["key", "value", "item"]
 
 
 class SizedGenerator(Generic[T]):
@@ -304,9 +306,8 @@ def find(
 
         match_fn = revert(match_fn)
     else:
-        raise ValueError(
-            f"Invalid argument {order=}. (expected one of {get_args(Order)})"
-        )
+        msg = f"Invalid argument {order=}. (expected one of {get_args(Order)})"
+        raise ValueError(msg)
 
     for i, xi in enumerate(it):
         if match_fn(xi, target):
@@ -684,7 +685,7 @@ def sorted_dict(
     x: Mapping[K, V],
     /,
     *,
-    by: Literal["key", "value", "item"] = "key",
+    by: DictByKVI = "key",
     key: Optional[Callable[[Any], Any]] = None,
     reverse: bool = False,
 ) -> Dict[K, V]:
@@ -709,7 +710,7 @@ def sorted_dict(
         impl_key = by_value_fn
 
     else:
-        msg = f"Invalid argument {by=}. (expected one of {('key', 'value', 'item')})"
+        msg = f"Invalid argument {by=}. (expected one of {get_args(DictByKVI)})"
         raise ValueError(msg)
 
     return {k: v for k, v in sorted(x.items(), key=impl_key, reverse=reverse)}  # type: ignore
@@ -738,7 +739,9 @@ def shuffled(
         return x
 
 
-def unflat_dict_of_dict(dic: Mapping[str, Any], *, sep: str = ".") -> Dict[str, Any]:
+def unflat_dict_of_dict(
+    dic: Mapping[str, Any], *, sep: str = ".", overwrite: bool = True
+) -> Dict[str, Any]:
     """Unflat a dictionary.
 
     Example 1
@@ -754,18 +757,26 @@ def unflat_dict_of_dict(dic: Mapping[str, Any], *, sep: str = ".") -> Dict[str,
     """
     output = {}
     for k, v in dic.items():
-        if sep not in k:
+        if not overwrite and k in output:
+            msg = f"Ambiguous flatten dict with key {k=}. (with value {v})"
+            raise ValueError(msg)
+        elif sep not in k:
             output[k] = v
+            continue
+
+        idx = k.index(sep)
+        k, kk = k[:idx], k[idx + 1 :]
+        if k not in output:
+            output[k] = {}
+        elif isinstance(output[k], Mapping):
+            pass
+        elif overwrite:
+            output[k] = {}
         else:
-            idx = k.index(sep)
-            k, kk = k[:idx], k[idx + 1 :]
-            if k not in output:
-                output[k] = {}
-            elif not isinstance(output[k], Mapping):
-                msg = f"Invalid dict argument. (found keys {k} and {k}{sep}{kk})"
-                raise ValueError(msg)
+            msg = f"Invalid dict argument. (found keys {k} and {k}{sep}{kk})"
+            raise ValueError(msg)
 
-            output[k][kk] = v
+        output[k][kk] = v
 
     output = {
         k: (unflat_dict_of_dict(v) if isinstance(v, Mapping) else v)

{pythonwrench-0.6.7 → pythonwrench-0.6.8}/src/pythonwrench/collections/reducers.py

@@ -277,6 +277,7 @@ def sum(
     ...
 
 
+# note: we do not use function_alias because start arg has default value of 0
 def sum(*args, start: Any = 0):
     """Compute sum of elements."""
     return reduce_add(*args, start=start)
@@ -313,6 +314,7 @@ def prod(
     ...
 
 
+# note: we do not use function_alias because start arg has default value of 1
 def prod(*args, start: Any = 1):
     """Compute product of elements."""
     return reduce_mul(*args, start=start)