lkj 0.1.47__py3-none-any.whl → 0.1.49__py3-none-any.whl

lkj/__init__.py

@@ -15,7 +15,12 @@ from lkj.dicts import (
     merge_dicts,  # Merge multiple dictionaries recursively
     compare_field_values,  # Compare two dictionaries' values
 )
-from lkj.filesys import get_app_data_dir, get_watermarked_dir, enable_sourcing_from_file
+from lkj.filesys import (
+    get_app_data_dir,
+    get_watermarked_dir,
+    enable_sourcing_from_file,
+    search_folder_fast,  # Fast search for a term in files under a folder (uses rg command)
+)
 from lkj.strings import (
     print_list,  # Print a list in a nice format (or get a string to process yourself)
     FindReplaceTool,  # Tool for finding and replacing substrings in a string

lkj/chunking.py

@@ -3,29 +3,26 @@
 from itertools import zip_longest, chain, islice
 
 from typing import (
-    Iterable,
     Union,
     Dict,
     List,
     Tuple,
-    Mapping,
     TypeVar,
-    Iterator,
-    Callable,
     Optional,
     T,
 )
+from collections.abc import Iterable, Mapping, Iterator, Callable
 
 KT = TypeVar("KT")  # there's a typing.KT, but pylance won't allow me to use it!
 VT = TypeVar("VT")  # there's a typing.VT, but pylance won't allow me to use it!
 
 
 def chunk_iterable(
-    iterable: Union[Iterable[T], Mapping[KT, VT]],
+    iterable: Iterable[T] | Mapping[KT, VT],
     chk_size: int,
     *,
-    chunk_type: Optional[Callable[..., Union[Iterable[T], Mapping[KT, VT]]]] = None,
-) -> Iterator[Union[List[T], Tuple[T, ...], Dict[KT, VT]]]:
+    chunk_type: Callable[..., Iterable[T] | Mapping[KT, VT]] | None = None,
+) -> Iterator[list[T] | tuple[T, ...] | dict[KT, VT]]:
     """
     Divide an iterable into chunks/batches of a specific size.
 
@@ -78,7 +75,7 @@ def chunk_iterable(
 
 def chunker(
     a: Iterable[T], chk_size: int, *, include_tail: bool = True
-) -> Iterator[Tuple[T, ...]]:
+) -> Iterator[tuple[T, ...]]:
     """
     Chunks an iterable into non-overlapping chunks of size `chk_size`.
 

lkj/dicts.py

@@ -45,20 +45,24 @@ def exclusive_subdict(d, exclude):
 def truncate_dict_values(
     d: dict,
     *,
-    max_list_size: Optional[int] = 2,
-    max_string_size: Optional[int] = 66,
+    max_list_size: int | None = 2,
+    max_string_size: int | None = 66,
     middle_marker: str = "...",
+    d_ingress: callable = lambda d: d,
 ) -> dict:
     """
     Returns a new dictionary with the same nested keys structure, where:
     - List values are reduced to a maximum size of max_list_size.
     - String values longer than max_string_size are truncated in the middle.
+    - Values are preprocessed with d_ingress before type checking.
 
     Parameters:
     d (dict): The input dictionary.
     max_list_size (int, optional): Maximum size for lists. Defaults to 2.
     max_string_size (int, optional): Maximum length for strings. Defaults to None (no truncation).
     middle_marker (str, optional): String to insert in the middle of truncated strings. Defaults to '...'.
+    d_ingress (callable, optional): Function applied to each value before type checking.
+        Defaults to identity function. Useful for handling special types like pandas Series.
 
     Returns:
     dict: A new dictionary with truncated lists and strings.
@@ -79,6 +83,14 @@ def truncate_dict_values(
     ...     == large_dict
     ... )
 
+    For handling special types like pandas Series:
+
+    >>> def handle_pandas(obj):
+    ...     if hasattr(obj, 'head'):  # pandas Series/DataFrame
+    ...         return f"<{type(obj).__name__}: {len(obj)} items>"
+    ...     return obj
+    >>> # truncate_dict_values(data_with_pandas, d_ingress=handle_pandas)
+
     """
 
     def truncate_string(value, max_len, marker):
@@ -87,26 +99,34 @@ def truncate_dict_values(
         half_len = (max_len - len(marker)) // 2
         return value[:half_len] + marker + value[-half_len:]
 
+    # Apply d_ingress to preprocess the value
+    d = d_ingress(d)
+
     kwargs = dict(
         max_list_size=max_list_size,
         max_string_size=max_string_size,
         middle_marker=middle_marker,
+        d_ingress=d_ingress,
     )
     if isinstance(d, dict):
         return {k: truncate_dict_values(v, **kwargs) for k, v in d.items()}
-    elif isinstance(d, list):
-        return (
-            [truncate_dict_values(v, **kwargs) for v in d[:max_list_size]]
-            if max_list_size is not None
-            else d
-        )
+    elif isinstance(d, (list, tuple)):
+        container_type = type(d)
+        if max_list_size is not None:
+            truncated_items = [
+                truncate_dict_values(v, **kwargs) for v in d[:max_list_size]
+            ]
+        else:
+            truncated_items = [truncate_dict_values(v, **kwargs) for v in d]
+        return container_type(truncated_items)
     elif isinstance(d, str):
         return truncate_string(d, max_string_size, middle_marker)
     else:
         return d
 
 
-from typing import Mapping, Callable, TypeVar, Iterable, Tuple
+from typing import TypeVar, Tuple
+from collections.abc import Mapping, Callable, Iterable
 
 KT = TypeVar("KT")  # Key type
 VT = TypeVar("VT")  # Value type
@@ -119,7 +139,7 @@ def merge_dicts(
     *mappings: Mapping[KT, VT],
     recursive_condition: Callable[[VT], bool] = lambda v: isinstance(v, Mapping),
     conflict_resolver: Callable[[VT, VT], VT] = lambda x, y: y,
-    mapping_constructor: Callable[[Iterable[Tuple[KT, VT]]], Mapping[KT, VT]] = dict,
+    mapping_constructor: Callable[[Iterable[tuple[KT, VT]]], Mapping[KT, VT]] = dict,
 ) -> Mapping[KT, VT]:
     """
     Merge multiple mappings into a single mapping, recursively if needed,
@@ -218,7 +238,8 @@ def merge_dicts(
 
 
 import operator
-from typing import Callable, Dict, Any
+from typing import Dict, Any
+from collections.abc import Callable
 
 Comparison = Any
 Comparator = Callable[[dict, dict], Comparison]
@@ -232,10 +253,10 @@ def compare_field_values(
     dict1,
     dict2,
     *,
-    field_comparators: Dict[KT, Comparator] = {},
+    field_comparators: dict[KT, Comparator] = {},
     default_comparator: Comparator = operator.eq,
     aggregator: Callable[
-        [Dict[KT, Comparison]], Any
+        [dict[KT, Comparison]], Any
     ] = lambda d: d,  # lambda d: np.mean(list(d.values())),
     get_comparison_fields: Callable[[dict], Iterable[KT]] = _common_keys_list,
 ):

lkj/filesys.py

@@ -1,7 +1,160 @@
 """File system utils"""
 
+# -------------------------------------------------------------------------------------
+# Search (on linux and macOS) using rg (ripgrep)
+import subprocess
+import json
+import shutil
+from typing import Callable, Any, Optional
+
+# simple parser that returns list of dicts objects from a JSONL string
+simple_jsonl_parser = lambda string: list(map(json.loads, string.splitlines()))
+
+# --- Default Egress Function ---
+
+
+def _ripgrep_json_parser(rg_output: str) -> list[dict]:
+    """
+    Parses the line-by-line JSON stream output from ripgrep (rg --json).
+
+    This output is NOT a single valid JSON object, but a stream of JSON lines.
+    We only care about 'match' entries for the results.
+    """
+    results = []
+
+    # ripgrep outputs one JSON object per line, so we iterate line by line
+    for line in rg_output.strip().split("\n"):
+        if not line:
+            continue
+
+        try:
+            data = json.loads(line)
+        except json.JSONDecodeError:
+            # Skip any lines that aren't valid JSON (shouldn't happen with --json)
+            continue
+
+        if data.get("type") == "match":
+            match_data = data.get("data", {})
+
+            # Extract key information from the match
+            result = {
+                "path": match_data.get("path", {}).get("text"),
+                "line_number": match_data.get("line_number"),
+                # The text of the matched line, decoded
+                "line_text": match_data.get("lines", {}).get("text"),
+                "submatches": [
+                    {
+                        "match_text": sub.get("match", {}).get("text"),
+                        "start": sub.get("start"),
+                        "end": sub.get("end"),
+                    }
+                    for sub in match_data.get("submatches", [])
+                ],
+            }
+            results.append(result)
+
+    return results
+
+
+def search_folder_fast(
+    search_term: str,
+    path_to_search: str = ".",
+    *,  # Enforce 'egress' as a keyword-only argument
+    egress: Optional[Callable[[str], Any]] = _ripgrep_json_parser,
+) -> Any:
+    """
+    Executes a fast, recursive search using ripgrep and processes the results.
+
+    :param search_term: The regex pattern or text string to search for.
+    :param path_to_search: The folder path to start searching from. Defaults to current directory.
+    :param egress: A callable function to process the raw ripgrep output string.
+                   Defaults to a parser that returns a list of dictionaries for matches.
+                   If set to None, it defaults to a lambda returning the raw output (string).
+                   You can also give it simple_jsonl_parser to get a list of all JSON objects in the output.
+    :return: The output of the 'egress' function.
+
+    Example usage:
+    -------------
+    >>> results = search_folder_fast("my_function_name", path_to_search='/path/to/project')  # doctest: +SKIP
+    >>> for match in results:  # doctest: +SKIP
+    ...     print(f"Found in {match['path']} at line {match['line_number']}: {match['line_text']}")  # doctest: +SKIP
+
+
+    """
+
+    if shutil.which("rg") is None:
+        print("=" * 60)
+        print(
+            "🚨 Error: The 'rg' (ripgrep) command was not found in your system's PATH."
+        )
+        print("\nTo install ripgrep:")
+        print("  - Linux (Debian/Ubuntu): sudo apt install ripgrep")
+        print("  - macOS (Homebrew):      brew install ripgrep")
+        print("  - Windows (Chocolatey):  choco install ripgrep")
+        print(f"\nMore details: https://github.com/BurntSushi/ripgrep#installation")
+        print("=" * 60)
+        return None
+
+    # Standard ripgrep command with JSON output
+    # -i: case-insensitive, -r: recursive, -n: show line numbers
+    # --json: outputs machine-readable JSON format
+    # --color never: ensures no ANSI color codes in the output stream
+    command = [
+        "rg",
+        "-i",
+        "-r",
+        "-n",
+        "--json",
+        "--color",
+        "never",
+        search_term,
+        path_to_search,
+    ]
+
+    # Handle the default None case for egress (return raw string)
+    if egress is None:
+        egress = lambda x: x
+
+    try:
+        # Use text=True and capture_output=True for string output and capturing stdout/stderr
+        result = subprocess.run(command, capture_output=True, text=True, check=True)
+
+        # Call the egress function on the raw standard output
+        return egress(result.stdout)
+
+    except subprocess.CalledProcessError as e:
+        # ripgrep returns a non-zero code if no matches are found.
+        # This is expected behavior and should not be treated as an error
+        # unless stderr indicates a true issue.
+        # Check stderr for real errors
+        if e.stderr:
+            # Handle genuine errors like permissions or file issues
+            print(f"A genuine ripgrep error occurred: {e.stderr.strip()}")
+            return None
+
+        # If check=True and return code is 1, it usually means "no matches found."
+        # If there's no stderr, return the egress of an empty string (or handle as no results)
+        return egress("")
+
+    except FileNotFoundError:
+        print(
+            "Error: ripgrep ('rg') command not found. Please ensure it is installed and in your PATH."
+        )
+        return None
+
+
+# Example usage will require 'rg' installed and a file system to search
+# For demonstration purposes, assume 'rg' is installed and you are searching for 'wrap_kvs'
+# search_results = search_folder_fast("wrap_kvs", path_to_search='/path/to/your/project')
+#
+# print(search_results)
+
+# -------------------------------------------------------------------------------------
+# General utils for file system operations
+
 import os
-from typing import Callable, Any
+from typing import Any
+from collections.abc import Callable
 from pathlib import Path
 from functools import wraps, partial
 
@@ -32,7 +185,7 @@ def enable_sourcing_from_file(func=None, *, write_output=False):
         if args and isinstance(args[0], str) and os.path.isfile(args[0]):
             file_path = args[0]
             # Read the file content
-            with open(file_path, "r") as file:
+            with open(file_path) as file:
                 file_content = file.read()
             # Call the function with the file content and other arguments
             new_args = (file_content,) + args[1:]

lkj/iterables.py

@@ -1,6 +1,7 @@
 """Tools with iterables (dicts, lists, tuples, sets, etc.)."""
 
-from typing import Sequence, Mapping, KT, VT, Iterable, Iterable, NamedTuple
+from typing import KT, VT, NamedTuple
+from collections.abc import Sequence, Mapping, Iterable, Iterable
 
 
 class SetsComparisonResult(NamedTuple):

lkj/loggers.py

@@ -1,6 +1,7 @@
 """Utils for logging."""
 
-from typing import Callable, Tuple, Any, Optional, Union, Iterable
+from typing import Tuple, Any, Optional, Union
+from collections.abc import Callable, Iterable
 from functools import partial, wraps
 from operator import attrgetter
 
@@ -9,7 +10,7 @@ from operator import attrgetter
 # TODO: Merge with wrap_text_with_exact_spacing
 # TODO: Add doctests for string
 def wrapped_print(
-    items: Union[str, Iterable],
+    items: str | Iterable,
     sep=", ",
     max_width=80,
     *,
@@ -166,15 +167,15 @@ def clog(condition, *args, log_func=print, **kwargs):
         return log_func(*args, **kwargs)
 
 
-def _calling_name(func_name: str, args: Tuple, kwargs: dict) -> str:
+def _calling_name(func_name: str, args: tuple, kwargs: dict) -> str:
     return f"Calling {func_name}..."
 
 
-def _done_calling_name(func_name: str, args: Tuple, kwargs: dict, result: Any) -> str:
+def _done_calling_name(func_name: str, args: tuple, kwargs: dict, result: Any) -> str:
     return f".... Done calling {func_name}"
 
 
-def _always_log(func: Callable, args: Tuple, kwargs: dict) -> bool:
+def _always_log(func: Callable, args: tuple, kwargs: dict) -> bool:
     """Return True no matter what"""
     return True
 
@@ -183,10 +184,10 @@ def log_calls(
     func: Callable = None,
     *,
     logger: Callable[[str], None] = print,
-    ingress_msg: Callable[[str, Tuple, dict], str] = _calling_name,
-    egress_msg: Callable[[str, Tuple, dict, Any], str] = _done_calling_name,
+    ingress_msg: Callable[[str, tuple, dict], str] = _calling_name,
+    egress_msg: Callable[[str, tuple, dict, Any], str] = _done_calling_name,
     func_name: Callable[[Callable], str] = attrgetter("__name__"),
-    log_condition: Callable[[Callable, Tuple, dict], bool] = _always_log,
+    log_condition: Callable[[Callable, tuple, dict], bool] = _always_log,
 ) -> Callable:
     """
     Decorator that adds logging before and after the function's call.
@@ -337,10 +338,12 @@ log_calls.instance_flag_is_set = instance_flag_is_set
 # Error handling
 
 
-from typing import Callable, Tuple, Any
+from typing import Tuple, Any
+from collections.abc import Callable
 from dataclasses import dataclass
 import traceback
-from typing import Callable, Any, Tuple
+from typing import Any, Tuple
+from collections.abc import Callable
 from functools import partial, wraps
 from operator import attrgetter
 
@@ -371,7 +374,7 @@ def dflt_error_info_processor(
 def return_error_info_on_error(
     func,
     *,
-    caught_error_types: Tuple[Exception] = (Exception,),
+    caught_error_types: tuple[Exception] = (Exception,),
     error_info_processor: Callable[[ErrorInfo], Any] = dflt_error_info_processor,
 ):
     """Decorator that returns traceback and local variables on error.

lkj/misc.py

@@ -2,7 +2,8 @@
 
 from operator import attrgetter, ge, gt, le, lt
 from functools import partial
-from typing import Callable, T, Optional, Any
+from typing import T, Optional, Any
+from collections.abc import Callable
 
 
 def identity(x):
@@ -14,8 +15,8 @@ def value_in_interval(
     /,
     *,
     get_val: Callable[[Any], T] = identity,
-    min_val: Optional[T] = None,
-    max_val: Optional[T] = None,
+    min_val: T | None = None,
+    max_val: T | None = None,
     is_minimum: Callable[[T, T], bool] = ge,
     is_maximum: Callable[[T, T], bool] = lt,
 ):

lkj/strings.py

@@ -22,7 +22,8 @@ These utilities are designed to make it easier to display, format, and manipulat
 """
 
 import re
-from typing import Iterable, Sequence, Callable, Optional, Any, Literal
+from typing import Optional, Any, Literal
+from collections.abc import Iterable, Sequence, Callable
 from functools import partial
 
 
@@ -327,7 +328,7 @@ def regex_based_substitution(replacements: dict, regex=None, s: str = None):
         )
 
 
-from typing import Callable, Iterable, Sequence
+from collections.abc import Callable, Iterable, Sequence
 
 
 class TrieNode:
@@ -453,12 +454,13 @@ def unique_affixes(
     return affixes
 
 
-from typing import Union, Callable, Dict, Any
+from typing import Union, Dict, Any
+from collections.abc import Callable
 
 # A match is represented as a dictionary (keys like "start", "end", etc.)
 # and the replacement is either a static string or a callable that takes that
 # dictionary and returns a string.
-Replacement = Union[str, Callable[[Dict[str, Any]], str]]
+Replacement = Union[str, Callable[[dict[str, Any]], str]]
 
 
 class FindReplaceTool:
@@ -770,7 +772,7 @@ class FindReplaceTool:
 
 
 def print_list(
-    items: Optional[Iterable[Any]] = None,
+    items: Iterable[Any] | None = None,
     *,
     style: Literal[
         "wrapped", "columns", "numbered", "bullet", "table", "compact"
@@ -779,7 +781,7 @@ def print_list(
     sep: str = ", ",
     line_prefix: str = "",
     items_per_line=None,
-    show_count: Union[bool, Callable[[int], str]] = False,
+    show_count: bool | Callable[[int], str] = False,
     title=None,
     print_func=print,
 ):

{lkj-0.1.47.dist-info → lkj-0.1.49.dist-info}/METADATA

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: lkj
-Version: 0.1.47
+Version: 0.1.49
 Summary: A dump of homeless useful utils
 Home-page: https://github.com/thorwhalen/lkj
 Author: Thor Whalen
@@ -8,6 +8,8 @@ License: apache-2.0
 Platform: any
 Description-Content-Type: text/markdown
 License-File: LICENSE
+Provides-Extra: testing
+Dynamic: license-file
 
 # lkj
 

lkj-0.1.49.dist-info/RECORD

@@ -0,0 +1,17 @@
+lkj/__init__.py,sha256=z8IZi5ql-bCM0xRgcEERg48oi2SRkgX9qSZdyaKb62Y,7300
+lkj/chunking.py,sha256=K7yakDuTgyn6t2rvFeDIWS5pO636BKGOe1spKk7v4Mc,3746
+lkj/dicts.py,sha256=67E9qwxPLLsBeRj67cSDgkAGvB6xfmNsi8igXdFGwjA,11307
+lkj/filesys.py,sha256=hYWztDoJUvVcPMD5AxRyYKkTB-sy5hx6_RDw4OyRcos,14628
+lkj/funcs.py,sha256=LXJlj3gMMsbD0t2gn2NZZ6mOqmW5bxM-94uGoYgrhzI,8930
+lkj/importing.py,sha256=TcW3qUDmw7jqswpxXnksjlHkkbOJq70NbUk1ZyaafT0,6658
+lkj/iterables.py,sha256=JSuTm7XpaTjIlv_9XZTrApLBohu5hRu7ZHi0wDT_ky0,2828
+lkj/loggers.py,sha256=eCudnqFaQhWz95qZtB57DDhvhXYvwl1JVCVernMhE5c,13781
+lkj/misc.py,sha256=RqJg4HgcT1ZZRBtxOppwYibvvLIyn6pNqI-WMg0uKgI,1457
+lkj/strings.py,sha256=JukQ4pvLlwGajBEK0PXyqsumEFKm8i1rx6SgASz7tqo,43798
+lkj/tests/__init__.py,sha256=kReYfWiyz1T79AuZAy5m4PIBj3Oj_Dlc0E-T8HVQ504,20
+lkj/tests/test_strings.py,sha256=Ix54io8WqWmYTY4guBgZShtKabtjd5uVpdxzxwJkgNA,1707
+lkj-0.1.49.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+lkj-0.1.49.dist-info/METADATA,sha256=pURwBZHm355AXQBzLViKArzBWbJhCFLxiNiHRaNRih8,8267
+lkj-0.1.49.dist-info/WHEEL,sha256=SmOxYU7pzNKBqASvQJ7DjX3XGUF92lrGhMb3R6_iiqI,91
+lkj-0.1.49.dist-info/top_level.txt,sha256=3DZOUwYmyurJFBXQCvCmEIVm8z2b42O5Sx3RDQyePfg,4
+lkj-0.1.49.dist-info/RECORD,,

{lkj-0.1.47.dist-info → lkj-0.1.49.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: bdist_wheel (0.45.1)
+Generator: setuptools (79.0.1)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

lkj-0.1.47.dist-info/RECORD

@@ -1,17 +0,0 @@
-lkj/__init__.py,sha256=IbBzGqZp9oXRt5oFyZwRFh9MHcFy8HW30S7Ox15RxEs,7191
-lkj/chunking.py,sha256=RpNdx5jEuO4mFg2qoTkD47iL35neBneuZ5xgQ_cBkiM,3755
-lkj/dicts.py,sha256=z2o7njvLNJkh1ZgSH-SLtz13SdW_YfUsTA1yTY-kVLE,10382
-lkj/filesys.py,sha256=NbWDuc848h8O42gwX7d9yNJkrWBgzSFnkoEdSRgvBAg,8883
-lkj/funcs.py,sha256=LXJlj3gMMsbD0t2gn2NZZ6mOqmW5bxM-94uGoYgrhzI,8930
-lkj/importing.py,sha256=TcW3qUDmw7jqswpxXnksjlHkkbOJq70NbUk1ZyaafT0,6658
-lkj/iterables.py,sha256=9jeO36w-IGiZryge7JKgXZOGZAgehUvhwKV3nHPcZWk,2801
-lkj/loggers.py,sha256=ImmBdacz89Lvb3dg_xI5jOct_44rSRv0hNI_CVehy60,13706
-lkj/misc.py,sha256=IZf05tkl0cgiMgBwCMH5cLSC59fRXwnemPRo8G0OxQg,1436
-lkj/strings.py,sha256=eFPA1EzEyLaF8wPk0Srj8rzrdEN9GNXc03wfvV4MOGU,43744
-lkj/tests/__init__.py,sha256=kReYfWiyz1T79AuZAy5m4PIBj3Oj_Dlc0E-T8HVQ504,20
-lkj/tests/test_strings.py,sha256=Ix54io8WqWmYTY4guBgZShtKabtjd5uVpdxzxwJkgNA,1707
-lkj-0.1.47.dist-info/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-lkj-0.1.47.dist-info/METADATA,sha256=bpcIVJxkJl8wIa2ycVWRmbhVJ3-o-5y-S46A3wepHeo,8221
-lkj-0.1.47.dist-info/WHEEL,sha256=tZoeGjtWxWRfdplE7E3d45VPlLNQnvbKiYnx7gwAy8A,92
-lkj-0.1.47.dist-info/top_level.txt,sha256=3DZOUwYmyurJFBXQCvCmEIVm8z2b42O5Sx3RDQyePfg,4
-lkj-0.1.47.dist-info/RECORD,,