lkj 0.1.47__tar.gz → 0.1.48__tar.gz

{lkj-0.1.47 → lkj-0.1.48}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: lkj
-Version: 0.1.47
+Version: 0.1.48
 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.47 → lkj-0.1.48}/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-0.1.47 → lkj-0.1.48}/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-0.1.47 → lkj-0.1.48}/lkj/dicts.py

@@ -45,8 +45,8 @@ 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 = "...",
 ) -> dict:
     """
@@ -106,7 +106,8 @@ def truncate_dict_values(
         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 +120,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 +219,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 +234,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-0.1.47 → lkj-0.1.48}/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-0.1.47 → lkj-0.1.48}/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-0.1.47 → lkj-0.1.48}/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-0.1.47 → lkj-0.1.48}/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-0.1.47 → lkj-0.1.48}/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 → lkj-0.1.48}/lkj.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: lkj
-Version: 0.1.47
+Version: 0.1.48
 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.47 → lkj-0.1.48}/lkj.egg-info/SOURCES.txt

@@ -16,6 +16,7 @@ lkj.egg-info/PKG-INFO
 lkj.egg-info/SOURCES.txt
 lkj.egg-info/dependency_links.txt
 lkj.egg-info/not-zip-safe
+lkj.egg-info/requires.txt
 lkj.egg-info/top_level.txt
 lkj/tests/__init__.py
 lkj/tests/test_strings.py

lkj-0.1.48/lkj.egg-info/requires.txt

@@ -0,0 +1,2 @@
+
+[testing]

{lkj-0.1.47 → lkj-0.1.48}/setup.cfg

@@ -1,6 +1,6 @@
 [metadata]
 name = lkj
-version = 0.1.47
+version = 0.1.48
 url = https://github.com/thorwhalen/lkj
 platforms = any
 description_file = README.md
@@ -19,6 +19,9 @@ include_package_data = True
 zip_safe = False
 install_requires = 
 
+[options.extras_require]
+testing = 
+
 [egg_info]
 tag_build = 
 tag_date = 0