pythonwrench 0.6.4__py3-none-any.whl

pythonwrench/__init__.py

@@ -0,0 +1,490 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+"""Python library with tools for typing, manipulating collections, and more!"""
+
+__name__ = "pythonwrench"
+__author__ = "Étienne Labbé (Labbeti)"
+__author_email__ = "labbeti.pub@gmail.com"
+__license__ = "MIT"
+__maintainer__ = "Étienne Labbé (Labbeti)"
+__status__ = "Development"
+__version__ = "0.6.4"
+
+
+from typing import TYPE_CHECKING
+
+try:
+    import lazy_loader as lazy  # type: ignore
+except ImportError:
+    lazy = None
+
+
+if TYPE_CHECKING or lazy is None:
+    # 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 concurrent as concurrent
+    from . import dataclasses as dataclasses
+    from . import datetime as datetime
+    from . import difflib as difflib
+    from . import disk_cache as disk_cache
+    from . import entrypoints as entrypoints
+    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 logging as logging
+    from . import math as math
+    from . import os as os
+    from . import random as random
+    from . import re as re
+    from . import semver as semver
+    from . import serialization as serialization
+    from . import time as time
+    from . import warnings as warnings
+
+    # Global library imports
+    from .abc import Singleton
+    from .argparse import (
+        add_dataclass_fields_to_parser,
+        get_parse_fn,
+        new_parser_from_dataclass,
+        parse_args_using_dataclass,
+        parse_to,
+        parse_to_bool,
+        parse_to_float,
+        parse_to_int,
+        parse_to_none,
+        parse_to_optional_bool,
+        parse_to_optional_float,
+        parse_to_optional_int,
+        parse_to_optional_str,
+        parse_to_type,
+        register_parser_fn,
+        str_to_bool,
+        str_to_float,
+        str_to_int,
+        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, register_as_builtin_fn
+    from .checksum import checksum_any, checksum_object, register_checksum_fn
+    from .collections import (
+        SizedGenerator,
+        all_eq,
+        all_ne,
+        contained,
+        dict_list_to_list_dict,
+        dump_dict,
+        duplicate_list,
+        filter_iterable,
+        find,
+        flat_dict_of_dict,
+        flat_list_of_list,
+        flatten,
+        intersect,
+        intersect_lists,
+        is_full,
+        is_sorted,
+        is_unique,
+        list_dict_to_dict_list,
+        prod,
+        recursive_generator,
+        reduce_add,
+        reduce_and,
+        reduce_matmul,
+        reduce_mul,
+        reduce_or,
+        shuffled,
+        sorted_dict,
+        sum,
+        unflat_dict_of_dict,
+        unflat_list_of_list,
+        union,
+        union_dicts,
+        union_lists,
+        unzip,
+    )
+    from .dataclasses import add_dict_methods, dataclassdict, get_defaults_values
+    from .datetime import get_now, get_now_iso8601
+    from .difflib import find_closest_in_list, sequence_matcher_ratio
+    from .disk_cache import disk_cache_call, disk_cache_decorator
+    from .enum import StrEnum
+    from .functools import (
+        Compose,
+        compose,
+        filter_and_call,
+        function_alias,
+        identity,
+        repeat_fn,
+    )
+    from .hashlib import hash_file
+    from .importlib import (
+        ModulePlaceholder,
+        Placeholder,
+        import_if_available,
+        is_available_package,
+        is_editable_package,
+        reload_editable_packages,
+        reload_submodules,
+        requires_packages,
+        search_submodules,
+    )
+    from .inspect import get_argnames, get_current_fn_name, get_fullname
+    from .logging import (
+        VERBOSE_DEBUG,
+        VERBOSE_ERROR,
+        VERBOSE_INFO,
+        VERBOSE_WARNING,
+        MkdirFileHandler,
+        get_current_file_logger,
+        get_ipython_name,
+        get_null_logger,
+        log_once,
+        running_on_interpreter,
+        running_on_notebook,
+        running_on_terminal,
+        setup_logging_level,
+        setup_logging_verbose,
+    )
+    from .math import argmax, argmin, argsort, clamp, clip
+    from .os import get_num_cpus_available, safe_rmdir, tree_iter
+    from .random import randstr
+    from .re import (
+        PatternLike,
+        PatternListLike,
+        compile_patterns,
+        filter_with_patterns,
+        find_patterns,
+        get_key_fn,
+        match_patterns,
+        sort_with_patterns,
+    )
+    from .semver import Version
+    from .serialization import (
+        dump_csv,
+        dump_json,
+        dump_jsonl,
+        dump_pickle,
+        dumps_csv,
+        dumps_json,
+        dumps_jsonl,
+        dumps_pickle,
+        load_csv,
+        load_json,
+        load_jsonl,
+        load_pickle,
+        loads_csv,
+        loads_json,
+        loads_jsonl,
+        loads_pickle,
+        read_csv,
+        read_json,
+        read_jsonl,
+        read_pickle,
+        save_csv,
+        save_json,
+        save_jsonl,
+        save_pickle,
+    )
+    from .time import Ticker
+    from .typing import (
+        BuiltinCollection,
+        BuiltinNumber,
+        BuiltinScalar,
+        Dataclass,
+        DataclassInstance,
+        EllipsisType,
+        ListOrTuple,
+        NamedTupleInstance,
+        NoneType,
+        SupportsAdd,
+        SupportsAnd,
+        SupportsBool,
+        SupportsDiv,
+        SupportsGetitem,
+        SupportsGetitem2,
+        SupportsGetitemIterLen,
+        SupportsGetitemIterLen2,
+        SupportsGetitemLen,
+        SupportsGetitemLen2,
+        SupportsIter,
+        SupportsIterLen,
+        SupportsLen,
+        SupportsMatmul,
+        SupportsMul,
+        SupportsOr,
+        T_BuiltinNumber,
+        T_BuiltinScalar,
+        check_args_types,
+        is_builtin_collection,
+        is_builtin_number,
+        is_builtin_obj,
+        is_builtin_scalar,
+        is_collection_alias,
+        is_dataclass_instance,
+        is_dataclass_type,
+        is_iterable_bool,
+        is_iterable_bytes_or_list,
+        is_iterable_float,
+        is_iterable_int,
+        is_iterable_integral,
+        is_iterable_str,
+        is_namedtuple_instance,
+        is_parameterized,
+        is_sequence_str,
+        is_special_form,
+        is_typed_dict,
+        isinstance_generic,
+    )
+    from .warnings import deprecated_alias, deprecated_function, warn_once
+
+else:
+    __getattr__, __dir__, __all__ = lazy.attach(
+        __name__,
+        submodules=[
+            "abc",
+            "argparse",
+            "cast",
+            "checksum",
+            "collections",
+            "concurrent",
+            "dataclasses",
+            "datetime",
+            "difflib",
+            "disk_cache",
+            "entrypoints",
+            "enum",
+            "functools",
+            "hashlib",
+            "importlib",
+            "inspect",
+            "logging",
+            "math",
+            "os",
+            "random",
+            "re",
+            "semver",
+            "serialization",
+            "time",
+            "typing",
+            "warnings",
+        ],
+        submod_attrs={
+            "argparse": [
+                "add_dataclass_fields_to_parser",
+                "get_parse_fn",
+                "new_parser_from_dataclass",
+                "parse_args_using_dataclass",
+                "parse_to",
+                "parse_to_bool",
+                "parse_to_float",
+                "parse_to_int",
+                "parse_to_none",
+                "parse_to_optional_bool",
+                "parse_to_optional_float",
+                "parse_to_optional_int",
+                "parse_to_optional_str",
+                "parse_to_type",
+                "register_parser_fn",
+                "str_to_bool",
+                "str_to_float",
+                "str_to_int",
+                "str_to_none",
+                "str_to_optional_bool",
+                "str_to_optional_float",
+                "str_to_optional_int",
+                "str_to_optional_str",
+                "str_to_type",
+            ],
+            "abc": ["Singleton"],
+            "cast": ["as_builtin", "register_as_builtin_fn"],
+            "checksum": ["checksum_any", "checksum_object", "register_checksum_fn"],
+            "collections": [
+                "SizedGenerator",
+                "all_eq",
+                "all_ne",
+                "contained",
+                "dict_list_to_list_dict",
+                "dump_dict",
+                "duplicate_list",
+                "filter_iterable",
+                "find",
+                "flat_dict_of_dict",
+                "flat_list_of_list",
+                "flatten",
+                "intersect",
+                "intersect_lists",
+                "is_full",
+                "is_sorted",
+                "is_unique",
+                "list_dict_to_dict_list",
+                "prod",
+                "recursive_generator",
+                "reduce_add",
+                "reduce_and",
+                "reduce_matmul",
+                "reduce_mul",
+                "reduce_or",
+                "shuffled",
+                "sorted_dict",
+                "sum",
+                "unflat_dict_of_dict",
+                "unflat_list_of_list",
+                "union",
+                "union_dicts",
+                "union_lists",
+                "unzip",
+            ],
+            "serialization": [
+                "dump_csv",
+                "dump_json",
+                "dump_jsonl",
+                "dump_pickle",
+                "dumps_csv",
+                "dumps_json",
+                "dumps_jsonl",
+                "dumps_pickle",
+                "load_csv",
+                "load_json",
+                "load_jsonl",
+                "load_pickle",
+                "loads_csv",
+                "loads_json",
+                "loads_jsonl",
+                "loads_pickle",
+                "read_csv",
+                "read_json",
+                "read_jsonl",
+                "read_pickle",
+                "save_csv",
+                "save_json",
+                "save_jsonl",
+                "save_pickle",
+            ],
+            "dataclasses": ["add_dict_methods", "dataclassdict", "get_defaults_values"],
+            "datetime": ["get_now", "get_now_iso8601"],
+            "difflib": ["find_closest_in_list", "sequence_matcher_ratio"],
+            "disk_cache": ["disk_cache_call", "disk_cache_decorator"],
+            "enum": ["StrEnum"],
+            "functools": [
+                "Compose",
+                "compose",
+                "filter_and_call",
+                "function_alias",
+                "identity",
+                "repeat_fn",
+            ],
+            "hashlib": ["hash_file"],
+            "importlib": [
+                "import_if_available",
+                "ModulePlaceholder",
+                "is_available_package",
+                "is_editable_package",
+                "reload_editable_packages",
+                "reload_submodules",
+                "requires_packages",
+                "search_submodules",
+                "Placeholder",
+            ],
+            "inspect": ["get_argnames", "get_current_fn_name", "get_fullname"],
+            "logging": [
+                "VERBOSE_DEBUG",
+                "VERBOSE_ERROR",
+                "VERBOSE_INFO",
+                "VERBOSE_WARNING",
+                "MkdirFileHandler",
+                "get_current_file_logger",
+                "get_ipython_name",
+                "get_null_logger",
+                "log_once",
+                "running_on_interpreter",
+                "running_on_notebook",
+                "running_on_terminal",
+                "setup_logging_level",
+                "setup_logging_verbose",
+            ],
+            "math": ["argmax", "argmin", "argsort", "clamp", "clip"],
+            "os": ["get_num_cpus_available", "safe_rmdir", "tree_iter"],
+            "random": ["randstr"],
+            "re": [
+                "PatternLike",
+                "PatternListLike",
+                "compile_patterns",
+                "filter_with_patterns",
+                "find_patterns",
+                "get_key_fn",
+                "match_patterns",
+                "sort_with_patterns",
+            ],
+            "semver": ["Version"],
+            "time": ["Ticker"],
+            "typing": [
+                "BuiltinCollection",
+                "BuiltinNumber",
+                "BuiltinScalar",
+                "Dataclass",
+                "DataclassInstance",
+                "EllipsisType",
+                "ListOrTuple",
+                "NamedTupleInstance",
+                "NoneType",
+                "SupportsAdd",
+                "SupportsAnd",
+                "SupportsBool",
+                "SupportsDiv",
+                "SupportsGetitem",
+                "SupportsGetitem2",
+                "SupportsGetitemIterLen",
+                "SupportsGetitemIterLen2",
+                "SupportsGetitemLen",
+                "SupportsGetitemLen2",
+                "SupportsIter",
+                "SupportsIterLen",
+                "SupportsLen",
+                "SupportsMatmul",
+                "SupportsMul",
+                "SupportsOr",
+                "T_BuiltinNumber",
+                "T_BuiltinScalar",
+                "check_args_types",
+                "is_builtin_collection",
+                "is_builtin_number",
+                "is_builtin_obj",
+                "is_builtin_scalar",
+                "is_collection_alias",
+                "is_dataclass_instance",
+                "is_dataclass_type",
+                "is_iterable_bool",
+                "is_iterable_bytes_or_list",
+                "is_iterable_float",
+                "is_iterable_int",
+                "is_iterable_integral",
+                "is_iterable_str",
+                "is_namedtuple_instance",
+                "is_parameterized",
+                "is_sequence_str",
+                "is_special_form",
+                "is_typed_dict",
+                "isinstance_generic",
+            ],
+            "warnings": ["deprecated_alias", "deprecated_function", "warn_once"],
+        },
+    )
+
+    Version = __getattr__("Version")
+
+
+version = __version__
+version_info = Version(__version__)
+
+del TYPE_CHECKING, lazy

pythonwrench/__main__.py

@@ -0,0 +1,7 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+from .entrypoints.info import main_info
+
+if __name__ == "__main__":
+    main_info()

pythonwrench/_core.py

@@ -0,0 +1,192 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+from functools import wraps
+from typing import (
+    Any,
+    Callable,
+    Dict,
+    Generic,
+    Literal,
+    Optional,
+    Protocol,
+    Tuple,
+    Union,
+    get_args,
+    runtime_checkable,
+)
+
+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])
+
+UnkMode = Literal["identity", "error"]
+ClassOrTuple = Union[type, Tuple[type, ...]]
+
+
+@runtime_checkable
+class Predicate(Protocol[T_PredicateArg]):
+    def __call__(self, /, x: T_PredicateArg) -> bool:
+        """Call the instance."""
+        ...
+
+
+def return_none(*args, **kwargs) -> None:
+    """Return None function placeholder."""
+    return None
+
+
+def _decorator_factory(
+    inner_fn: Optional[T_Function],
+    *,
+    pre_fn: Optional[Callable[..., Any]] = None,
+    post_fn: Optional[Callable[..., Any]] = None,
+) -> Callable[[T_Function], T_Function]:
+    """Decorator for function aliases."""
+    if pre_fn is None:
+        pre_fn = return_none
+    if post_fn is None:
+        post_fn = return_none
+
+    def wrapper_factory(fn: T_Function) -> T_Function:
+        """Perform the wrapper factory operation."""
+        if inner_fn is None:
+            _inner_fn = fn
+        else:
+            _inner_fn = inner_fn
+
+        @wraps(_inner_fn)
+        def wrapped(*args, **kwargs):
+            """Perform the wrapped operation."""
+            pre_fn(fn, *args, **kwargs)
+            result = _inner_fn(*args, **kwargs)
+            post_fn(fn, *args, **kwargs)
+            return result
+
+        return wrapped  # type: ignore
+
+    return wrapper_factory
+
+
+class _FunctionRegistry(Generic[T_Output]):
+    def __init__(self) -> None:
+        """Initialize the instance."""
+        fns: Dict[
+            Callable[..., T_Output],
+            Tuple[Optional[ClassOrTuple], Optional[Predicate], int],
+        ] = {}
+
+        super().__init__()
+        self.fns = fns
+
+    def register(
+        self,
+        fn: Callable[[T], T_Output],
+        class_or_tuple: Optional[ClassOrTuple] = None,
+        *,
+        custom_predicate: Optional[Predicate] = None,
+        priority: int = 0,
+    ) -> Callable[[T], T_Output]:
+        """Perform the register operation."""
+        return self.register_decorator(
+            class_or_tuple,
+            custom_predicate=custom_predicate,
+            priority=priority,
+        )(fn)
+
+    def register_decorator(
+        self,
+        class_or_tuple: Optional[ClassOrTuple] = None,
+        *,
+        custom_predicate: Optional[Predicate] = None,
+        priority: int = 0,
+    ) -> Callable:
+        """Perform the register decorator operation."""
+        if (class_or_tuple is None) == (custom_predicate is None):
+            msg = f"Invalid combinaison of arguments: {class_or_tuple=} and {custom_predicate=}. (only one of them must be None)"
+            raise ValueError(msg)
+
+        def _impl(new_fn: Callable[[T], T_Output]) -> Callable[[T], T_Output]:
+            """Perform the impl operation."""
+            new_value = (class_or_tuple, custom_predicate, priority)
+            self.fns = _insert_in_dict(
+                self.fns,
+                new_fn,
+                new_value,
+                priority,
+                priority_key=2,
+            )
+            return new_fn
+
+        return _impl
+
+    def apply(
+        self,
+        x: Any,
+        *,
+        isinstance_fn: Callable[[Any, Union[type, tuple]], bool] = isinstance,
+        unk_mode: UnkMode = "error",
+        **kwargs,
+    ) -> T_Output:
+        """Perform the apply operation."""
+        for fn, (class_or_tuple, custom_predicate, _) in self.fns.items():
+            if custom_predicate is not None:
+                predicate = custom_predicate
+
+            elif class_or_tuple is not None:
+
+                def target_isinstance_fn_wrap(x: Any) -> bool:
+                    """Perform the target isinstance fn wrap operation."""
+                    return isinstance_fn(x, class_or_tuple)  # type: ignore
+
+                predicate = target_isinstance_fn_wrap
+            else:
+                msg = f"Invalid function registered. (found {class_or_tuple=} and {custom_predicate=})"
+                raise TypeError(msg)
+
+            if predicate(x):
+                return fn(x, **kwargs)
+
+        if unk_mode == "identity":
+            return x
+        elif unk_mode == "error":
+            valid_types = [
+                class_or_tuple
+                for class_or_tuple, _, _ in self.fns.values()
+                if class_or_tuple is not None
+            ]
+            msg = f"Invalid argument type {type(x)}. (expected one of {tuple(valid_types)})"
+            raise TypeError(msg)
+        else:
+            msg = f"Invalid argument {unk_mode=}. (expected one of {get_args(UnkMode)})"
+            raise ValueError(msg)
+
+
+def _insert_in_dict(
+    dic: Dict,
+    key: Any,
+    value: Any,
+    priority: int,
+    priority_key: int,
+) -> Dict:
+    """Perform the insert in dict operation."""
+    if key in dic:
+        return dic
+    insert_index = _get_insertion_index(list(dic.values()), priority, priority_key)
+    items = list(dic.items())
+    items.insert(insert_index, (key, value))
+    return dict(items)
+
+
+def _get_insertion_index(lst: list, priority: int, priority_key: int) -> int:
+    """Perform the get insertion index operation."""
+    for i, item in enumerate(lst):
+        other_priority = item[priority_key]
+        if priority >= other_priority:
+            return i
+    return len(lst)