lkj 0.1.33__tar.gz → 0.1.35__tar.gz

{lkj-0.1.33 → lkj-0.1.35}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: lkj
-Version: 0.1.33
+Version: 0.1.35
 Summary: A dump of homeless useful utils
 Home-page: https://github.com/thorwhalen/lkj
 Author: Thor Whalen

{lkj-0.1.33 → lkj-0.1.35}/lkj/__init__.py

@@ -8,18 +8,25 @@ from lkj.iterables import (
     get_by_value,  # Get a dictionary from a list of dictionaries by a field value
 )
 from lkj.funcs import mk_factory
-from lkj.dicts import truncate_dict_values, inclusive_subdict, exclusive_subdict
+from lkj.dicts import (
+    truncate_dict_values,  # Truncate list and string values in a dictionary
+    inclusive_subdict,  # new dictionary with only the keys in `include`
+    exclusive_subdict,  # new dictionary with only the keys not in `exclude`.
+    merge_dicts,  # Merge multiple dictionaries recursively
+)
 from lkj.filesys import get_app_data_dir, get_watermarked_dir, enable_sourcing_from_file
 from lkj.strings import (
     indent_lines,  # Indent all lines of a string
     most_common_indent,  # Get the most common indent of a multiline string
     regex_based_substitution,
-    truncate_string_with_marker,  # Truncate a string to a maximum length, inserting a marker in the middle.
+    truncate_string,  # Truncate a string to a maximum length, inserting a marker in the middle.
+    truncate_lines,  # Truncate a multiline string to a maximum number of lines
     unique_affixes,  # Get unique prefixes or suffixes of a list of strings
     camel_to_snake,  # Convert CamelCase to snake_case
     snake_to_camel,  # Convert snake_case to CamelCase
     fields_of_string_format,  # Extract field names from a string format
-    fields_of_string_formats,  # Extract field names from an iterable of string formats
+    fields_of_string_formats,  # Extract field names from an iterable of string formats,
+    truncate_string_with_marker,  # Deprecated: Backcompatibility alias
 )
 from lkj.loggers import (
     print_with_timestamp,

lkj-0.1.35/lkj/dicts.py

@@ -0,0 +1,223 @@
+"""
+Tools for working with dictionaries (and other Mappings).
+
+If you are looking for more, check out the `lkj.iterables` module too
+(after all, dicts are iterables).
+
+"""
+
+from typing import Optional
+
+
+def inclusive_subdict(d, include):
+    """
+    Returns a new dictionary with only the keys in `include`.
+
+    Parameters:
+    d (dict): The input dictionary.
+    include (set): The set of keys to include in the new dictionary.
+
+    Example:
+    >>> inclusive_subdict({'a': 1, 'b': 2, 'c': 3}, {'a', 'c'})
+    {'a': 1, 'c': 3}
+
+    """
+    return {k: d[k] for k in d.keys() & include}
+
+
+def exclusive_subdict(d, exclude):
+    """
+    Returns a new dictionary with only the keys not in `exclude`.
+
+    Parameters:
+    d (dict): The input dictionary.
+    exclude (set): The set of keys to exclude from the new dictionary.
+
+    Example:
+    >>> exclusive_subdict({'a': 1, 'b': 2, 'c': 3}, {'a', 'c'})
+    {'b': 2}
+
+    """
+    return {k: d[k] for k in d.keys() - exclude}
+
+
+# Note: There is a copy of truncate_dict_values in the ju package.
+def truncate_dict_values(
+    d: dict,
+    *,
+    max_list_size: Optional[int] = 2,
+    max_string_size: Optional[int] = 66,
+    middle_marker: str = "...",
+) -> 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.
+
+    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 '...'.
+
+    Returns:
+    dict: A new dictionary with truncated lists and strings.
+
+    This can be useful when you have a large dictionary that you want to investigate,
+    but printing/logging it takes too much space.
+
+    Example:
+
+    >>> large_dict = {'a': [1, 2, 3, 4, 5], 'b': {'c': [6, 7, 8, 9], 'd': 'A string like this that is too long'}, 'e': [10, 11]}
+    >>> truncate_dict_values(large_dict, max_list_size=3, max_string_size=20)
+    {'a': [1, 2, 3], 'b': {'c': [6, 7, 8], 'd': 'A string...too long'}, 'e': [10, 11]}
+
+    You can use `None` to indicate "no max":
+
+    >>> assert (
+    ...     truncate_dict_values(large_dict, max_list_size=None, max_string_size=None)
+    ...     == large_dict
+    ... )
+
+    """
+
+    def truncate_string(value, max_len, marker):
+        if max_len is None or len(value) <= max_len:
+            return value
+        half_len = (max_len - len(marker)) // 2
+        return value[:half_len] + marker + value[-half_len:]
+
+    kwargs = dict(
+        max_list_size=max_list_size,
+        max_string_size=max_string_size,
+        middle_marker=middle_marker,
+    )
+    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, str):
+        return truncate_string(d, max_string_size, middle_marker)
+    else:
+        return d
+
+
+from typing import Mapping, Callable, TypeVar, Iterable, Tuple
+
+KT = TypeVar("KT")  # Key type
+VT = TypeVar("VT")  # Value type
+
+# Note: Could have all function parameters (recursive_condition, etc.) also take the
+#       enumerated index of the mapping as an argument. That would give us even more
+#       flexibility, but it might be overkill and make the interface more complex.
+from typing import Mapping, Callable, TypeVar, Iterable, Tuple
+from collections import defaultdict
+
+KT = TypeVar("KT")  # Key type
+VT = TypeVar("VT")  # Value type
+
+
+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[KT, VT]:
+    """
+    Merge multiple mappings into a single mapping, recursively if needed,
+    with customizable conflict resolution for non-mapping values.
+
+    This function generalizes the normal `dict.update()` method, which takes the union
+    of the keys and resolves conflicting values by overriding them with the last value.
+    While `dict.update()` performs a single-level merge, `merge_dicts` provides additional
+    flexibility to handle nested mappings. With `merge_dicts`, you can:
+    - Control when to recurse (e.g., based on whether a value is a `Mapping`).
+    - Specify how to resolve value conflicts (e.g., override, add, or accumulate in a list).
+    - Choose the type of mapping (e.g., `dict`, `defaultdict`) to use as the container.
+
+    Args:
+        mappings: The mappings to merge.
+        recursive_condition: A callable to determine if values should be merged recursively.
+                             By default, checks if the value is a `Mapping`.
+        conflict_resolver: A callable that resolves conflicts between two values.
+                           By default, overrides with the last seen value (`lambda x, y: y`).
+        mapping_constructor: A callable to construct the resulting mapping.
+                             Defaults to the standard `dict` constructor.
+
+    Returns:
+        A merged mapping that combines all the input mappings.
+
+    Examples:
+        Basic usage with single-level merge (override behavior):
+        >>> dict1 = {"a": 1}
+        >>> dict2 = {"a": 2, "b": 3}
+        >>> merge_dicts(dict1, dict2)
+        {'a': 2, 'b': 3}
+
+        Handling nested mappings with default behavior (override conflicts):
+        >>> dict1 = {"a": 1, "b": {"x": 10, "y": 20}}
+        >>> dict2 = {"b": {"y": 30, "z": 40}, "c": 3}
+        >>> dict3 = {"b": {"x": 50}, "d": 4}
+        >>> merge_dicts(dict1, dict2, dict3)
+        {'a': 1, 'b': {'x': 50, 'y': 30, 'z': 40}, 'c': 3, 'd': 4}
+
+        Resolving conflicts by summing values:
+        >>> dict1 = {"a": 1}
+        >>> dict2 = {"a": 2}
+        >>> merge_dicts(dict1, dict2, conflict_resolver=lambda x, y: x + y)
+        {'a': 3}
+
+        Accumulating conflicting values into a list:
+        >>> dict1 = {"a": 1, "b": [1, 2]}
+        >>> dict2 = {"b": [3, 4]}
+        >>> merge_dicts(dict1, dict2, conflict_resolver=lambda x, y: x + y if isinstance(x, list) else [x, y])
+        {'a': 1, 'b': [1, 2, 3, 4]}
+
+        Recursing only on specific conditions:
+        >>> dict1 = {"a": {"nested": 1}}
+        >>> dict2 = {"a": {"nested": 2, "new": 3}}
+        >>> merge_dicts(dict1, dict2)
+        {'a': {'nested': 2, 'new': 3}}
+
+        >>> dict1 = {"a": {"nested": [1, 2]}}
+        >>> dict2 = {"a": {"nested": [3, 4]}}
+        >>> merge_dicts(dict1, dict2, recursive_condition=lambda v: isinstance(v, dict))
+        {'a': {'nested': [3, 4]}}
+
+        Using a custom mapping type (`defaultdict`):
+        >>> from collections import defaultdict
+        >>> merge_dicts(
+        ...     dict1, dict2, mapping_constructor=lambda items: defaultdict(int, items)
+        ... )
+        defaultdict(<class 'int'>, {'a': defaultdict(<class 'int'>, {'nested': [3, 4]})})
+    """
+    # Initialize merged mapping with an empty iterable for constructors requiring input
+    merged = mapping_constructor([])
+
+    for mapping in mappings:
+        for key, value in mapping.items():
+            if (
+                key in merged
+                and recursive_condition(value)
+                and recursive_condition(merged[key])
+            ):
+                # Recursively merge nested mappings
+                merged[key] = merge_dicts(
+                    merged[key],
+                    value,
+                    recursive_condition=recursive_condition,
+                    conflict_resolver=conflict_resolver,
+                    mapping_constructor=mapping_constructor,
+                )
+            elif key in merged:
+                # Resolve conflict using the provided resolver
+                merged[key] = conflict_resolver(merged[key], value)
+            else:
+                # Otherwise, add the value
+                merged[key] = value
+
+    return merged

{lkj-0.1.33 → lkj-0.1.35}/lkj/strings.py

@@ -136,9 +136,7 @@ def snake_to_camel(snake_string):
 
 
 # Note: Vendored in i2.multi_objects and dol.util
-def truncate_string_with_marker(
-    s, *, left_limit=15, right_limit=15, middle_marker="..."
-):
+def truncate_string(s: str, *, left_limit=15, right_limit=15, middle_marker="..."):
     """
     Truncate a string to a maximum length, inserting a marker in the middle.
 
@@ -148,23 +146,23 @@ def truncate_string_with_marker(
     If the string is shorter than the sum of the left_limit and right_limit,
     the string is returned as is.
 
-    >>> truncate_string_with_marker('1234567890')
+    >>> truncate_string('1234567890')
     '1234567890'
 
     But if the string is longer than the sum of the limits, it is truncated:
 
-    >>> truncate_string_with_marker('1234567890', left_limit=3, right_limit=3)
+    >>> truncate_string('1234567890', left_limit=3, right_limit=3)
     '123...890'
-    >>> truncate_string_with_marker('1234567890', left_limit=3, right_limit=0)
+    >>> truncate_string('1234567890', left_limit=3, right_limit=0)
     '123...'
-    >>> truncate_string_with_marker('1234567890', left_limit=0, right_limit=3)
+    >>> truncate_string('1234567890', left_limit=0, right_limit=3)
     '...890'
 
     If you're using a specific parametrization of the function often, you can
     create a partial function with the desired parameters:
 
     >>> from functools import partial
-    >>> truncate_string = partial(truncate_string_with_marker, left_limit=2, right_limit=2, middle_marker='---')
+    >>> truncate_string = partial(truncate_string, left_limit=2, right_limit=2, middle_marker='---')
     >>> truncate_string('1234567890')
     '12---90'
     >>> truncate_string('supercalifragilisticexpialidocious')
@@ -181,6 +179,54 @@ def truncate_string_with_marker(
         return s[:left_limit] + middle_marker + s[-right_limit:]
 
 
+truncate_string_with_marker = truncate_string  # backwards compatibility alias
+
+
+def truncate_lines(
+    s: str, top_limit: int = None, bottom_limit: int = None, middle_marker: str = "..."
+) -> str:
+    """
+    Truncates a string by limiting the number of lines from the top and bottom.
+    If the total number of lines is greater than top_limit + bottom_limit,
+    it keeps the first `top_limit` lines, keeps the last `bottom_limit` lines,
+    and replaces the omitted middle portion with a single line containing
+    `middle_marker`.
+
+    If top_limit or bottom_limit is None, it is treated as 0.
+
+    Example:
+        >>> text = '''Line1
+        ... Line2
+        ... Line3
+        ... Line4
+        ... Line5
+        ... Line6'''
+
+        >>> print(truncate_lines(text, top_limit=2, bottom_limit=2))
+        Line1
+        Line2
+        ...
+        Line5
+        Line6
+    """
+    # Interpret None as zero for convenience
+    top = top_limit if top_limit is not None else 0
+    bottom = bottom_limit if bottom_limit is not None else 0
+
+    # Split on line boundaries (retaining any trailing newlines in each piece)
+    lines = s.splitlines(True)
+    total_lines = len(lines)
+
+    # If no need to truncate, return as is
+    if total_lines <= top + bottom:
+        return s
+
+    # Otherwise, keep the top lines, keep the bottom lines,
+    # and insert a single marker line in the middle
+    truncated = lines[:top] + [middle_marker + "\n"] + lines[-bottom:]
+    return "".join(truncated)
+
+
 # TODO: Generalize so that it can be used with regex keys (not escaped)
 def regex_based_substitution(replacements: dict, regex=None, s: str = None):
     """
@@ -201,29 +247,41 @@ def regex_based_substitution(replacements: dict, regex=None, s: str = None):
     'I like orange and grapes.'
 
     You have access to the ``replacements`` and ``regex`` attributes of the
-    ``substitute`` function:
+    ``substitute`` function. See how the replacements dict has been ordered by
+    descending length of keys. This is to ensure that longer keys are replaced
+    before shorter keys, avoiding partial replacements.
 
     >>> substitute.replacements
-    {'apple': 'orange', 'banana': 'grape'}
+    {'banana': 'grape', 'apple': 'orange'}
 
     """
     import re
     from functools import partial
 
     if regex is None and s is None:
-        replacements = dict(replacements)
-
-        if not replacements:  # if replacements iterable is empty.
-            return lambda s: s  # return identity function
-
-        regex = re.compile("|".join(re.escape(key) for key in replacements.keys()))
-
-        substitute = partial(regex_based_substitution, replacements, regex)
-        substitute.replacements = replacements
+        # Sort keys by length while maintaining value alignment
+        sorted_replacements = sorted(
+            replacements.items(), key=lambda x: len(x[0]), reverse=True
+        )
+
+        # Create regex pattern from sorted keys (without escaping to allow regex)
+        sorted_keys = [pair[0] for pair in sorted_replacements]
+        sorted_values = [pair[1] for pair in sorted_replacements]
+        regex = re.compile("|".join(sorted_keys))
+
+        # Prepare the substitution function with aligned replacements
+        aligned_replacements = dict(zip(sorted_keys, sorted_values))
+        substitute = partial(regex_based_substitution, aligned_replacements, regex)
+        substitute.replacements = aligned_replacements
         substitute.regex = regex
         return substitute
-    else:
+    elif s is not None:
+        # Perform substitution using the compiled regex and aligned replacements
         return regex.sub(lambda m: replacements[m.group(0)], s)
+    else:
+        raise ValueError(
+            "Invalid usage: provide either `s` or let the function construct itself."
+        )
 
 
 from typing import Callable, Iterable, Sequence

{lkj-0.1.33 → lkj-0.1.35}/lkj.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: lkj
-Version: 0.1.33
+Version: 0.1.35
 Summary: A dump of homeless useful utils
 Home-page: https://github.com/thorwhalen/lkj
 Author: Thor Whalen

{lkj-0.1.33 → lkj-0.1.35}/setup.cfg

@@ -1,6 +1,6 @@
 [metadata]
 name = lkj
-version = 0.1.33
+version = 0.1.35
 url = https://github.com/thorwhalen/lkj
 platforms = any
 description_file = README.md

lkj-0.1.33/lkj/dicts.py

@@ -1,106 +0,0 @@
-"""
-Tools for working with dictionaries (and other Mappings).
-
-If you are looking for more, check out the `lkj.iterables` module too 
-(after all, dicts are iterables).
-
-"""
-
-from typing import Optional
-
-
-def inclusive_subdict(d, include):
-    """
-    Returns a new dictionary with only the keys in `include`.
-
-    Parameters:
-    d (dict): The input dictionary.
-    include (set): The set of keys to include in the new dictionary.
-
-    Example:
-    >>> inclusive_subdict({'a': 1, 'b': 2, 'c': 3}, {'a', 'c'})
-    {'a': 1, 'c': 3}
-
-    """
-    return {k: d[k] for k in d.keys() & include}
-
-
-def exclusive_subdict(d, exclude):
-    """
-    Returns a new dictionary with only the keys not in `exclude`.
-
-    Parameters:
-    d (dict): The input dictionary.
-    exclude (set): The set of keys to exclude from the new dictionary.
-
-    Example:
-    >>> exclusive_subdict({'a': 1, 'b': 2, 'c': 3}, {'a', 'c'})
-    {'b': 2}
-
-    """
-    return {k: d[k] for k in d.keys() - exclude}
-
-
-# Note: There is a copy of truncate_dict_values in the ju package.
-def truncate_dict_values(
-    d: dict,
-    *,
-    max_list_size: Optional[int] = 2,
-    max_string_size: Optional[int] = 66,
-    middle_marker: str = "..."
-) -> 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.
-
-    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 '...'.
-
-    Returns:
-    dict: A new dictionary with truncated lists and strings.
-
-    This can be useful when you have a large dictionary that you want to investigate,
-    but printing/logging it takes too much space.
-
-    Example:
-
-    >>> large_dict = {'a': [1, 2, 3, 4, 5], 'b': {'c': [6, 7, 8, 9], 'd': 'A string like this that is too long'}, 'e': [10, 11]}
-    >>> truncate_dict_values(large_dict, max_list_size=3, max_string_size=20)
-    {'a': [1, 2, 3], 'b': {'c': [6, 7, 8], 'd': 'A string...too long'}, 'e': [10, 11]}
-
-    You can use `None` to indicate "no max":
-
-    >>> assert (
-    ...     truncate_dict_values(large_dict, max_list_size=None, max_string_size=None)
-    ...     == large_dict
-    ... )
-
-    """
-
-    def truncate_string(value, max_len, marker):
-        if max_len is None or len(value) <= max_len:
-            return value
-        half_len = (max_len - len(marker)) // 2
-        return value[:half_len] + marker + value[-half_len:]
-
-    kwargs = dict(
-        max_list_size=max_list_size,
-        max_string_size=max_string_size,
-        middle_marker=middle_marker,
-    )
-    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, str):
-        return truncate_string(d, max_string_size, middle_marker)
-    else:
-        return d