ml3macro-utils 0.0.0__py3-none-any.whl

ml3macro/utils/__init__.py

@@ -0,0 +1 @@
+"""ml3macro Utils - Common utilities and shared code for ml3macro projects."""

ml3macro/utils/additive_mapping.py

@@ -0,0 +1,125 @@
+"""This is like a frozen (immutable) dict, except that you can add new keys to it.
+Not allowed: updating/deleting existing keys or their values."""
+
+from typing import (
+    Any,
+    Generic,
+    Hashable,
+    ItemsView,
+    Iterator,
+    KeysView,
+    Mapping,
+    Self,
+    TypeVar,
+    ValuesView,
+    overload,
+)
+
+KeyType = TypeVar("KeyType", bound=Hashable)  # Allow any hashable type as key
+ValueType = TypeVar("ValueType")
+_T = TypeVar("_T")
+
+
+class AdditiveMapping(Generic[KeyType, ValueType], Mapping[KeyType, ValueType]):
+    """An immutable mapping that allows adding new keys but not modifying existing ones.
+
+    Once created, existing keys cannot be updated or deleted, but new keys can be
+    added using the `add()` method.
+    """
+
+    __map: dict[KeyType, ValueType]
+
+    def __init__(self, **kwargs: ValueType) -> None:
+        self.__map = dict(kwargs)  # type: ignore[assignment]
+
+    def __getitem__(self, key: KeyType, /) -> ValueType:
+        return self.__map[key]
+
+    def __len__(self) -> int:
+        return len(self.__map)
+
+    def __iter__(self) -> Iterator[KeyType]:
+        return iter(self.__map)
+
+    @overload
+    def get(self, __key: KeyType) -> ValueType | None: ...
+
+    @overload
+    def get(self, __key: KeyType, __default: ValueType) -> ValueType: ...
+
+    @overload
+    def get(self, __key: KeyType, __default: _T) -> ValueType | _T: ...
+
+    def get(self, __key: KeyType, __default: Any = None) -> ValueType | Any:
+        """Return the value for key if key is in the mapping, else default."""
+        return self.__map.get(__key, __default)
+
+    def add(self, remove_none_values: bool = True, **kwargs: ValueType) -> Self:
+        """Add new key-value pairs to the mapping.
+
+        Args:
+            remove_none_values: If True, skip any keys with None values
+            **kwargs: Key-value pairs to add
+
+        Returns:
+            Self for method chaining
+
+        Raises:
+            KeyError: If any key already exists
+        """
+        self.append(kwargs, remove_none_values=remove_none_values)
+        return self
+
+    def append(
+        self,
+        additional_mappings: Mapping[KeyType, ValueType] | dict[Any, ValueType],
+        /,
+        *,
+        remove_none_values: bool = True,
+    ) -> None:
+        """Append new key-value pairs from another mapping.
+
+        Args:
+            additional_mappings: Mapping containing key-value pairs to add
+            remove_none_values: If True, skip any keys with None values
+
+        Raises:
+            KeyError: If any key already exists
+        """
+        kvs_to_add = (
+            additional_mappings
+            if not remove_none_values
+            else {k: v for k, v in additional_mappings.items() if v is not None}
+        )
+        keys_to_add = kvs_to_add.keys()
+        conflicting_keys = [k for k in keys_to_add if k in self.__map]
+        if conflicting_keys:
+            raise KeyError(
+                f"{type(self).__qualname__} cannot update existing keys (but new keys can be added). "
+                f"Conflicting keys: {', '.join(str(k) for k in conflicting_keys)}"
+            )
+        self.__map.update(kvs_to_add)
+
+    def __setitem__(self, key: KeyType, value: ValueType) -> None:
+        """Prevent direct item assignment."""
+        raise TypeError(
+            f"'{type(self).__name__}' object does not support item assignment"
+        )
+
+    def __delitem__(self, key: KeyType) -> None:
+        """Prevent item deletion."""
+        raise TypeError(
+            f"'{type(self).__name__}' object does not support item deletion"
+        )
+
+    def keys(self) -> KeysView[KeyType]:
+        """Return a list of keys in the mapping."""
+        return KeysView(self.__map)
+
+    def values(self) -> ValuesView[ValueType]:
+        """Return a list of values in the mapping."""
+        return ValuesView(self.__map)
+
+    def items(self) -> ItemsView[KeyType, ValueType]:
+        """Return a list of (key, value) pairs in the mapping."""
+        return ItemsView(self.__map)

ml3macro/utils/base_enum.py

@@ -0,0 +1,4 @@
+from enum import StrEnum
+
+
+class BaseML3MacroStrEnum(StrEnum): ...

ml3macro/utils/decorators/layered_abstract_class.py

@@ -0,0 +1,66 @@
+from typing import Any, Callable, TypeVar
+
+T = TypeVar("T")
+
+
+def layered_abstract_class(base_class: type[T]) -> type[T]:
+    """
+    Decorator to enforce that concrete classes cannot inherit directly from the base class.
+    They must inherit from an intermediate abstract class.
+
+    Args:
+        base_class: The base class that should only be inherited by abstract classes
+
+    Returns:
+        The same base class with the enforcement logic added
+    """
+    original_init_subclass: Callable[..., None] | None = getattr(
+        base_class, "__init_subclass__", None
+    )
+
+    def decorator_error(s: str, /) -> TypeError:
+        return TypeError(f"[@{layered_abstract_class.__name__}]: {s}")
+
+    def __init_subclass__(cls: type, **kwargs: Any) -> None:
+        # Call original __init_subclass__ if it exists
+        if original_init_subclass:
+            original_init_subclass(**kwargs)
+
+        # Check if base_class is a direct parent
+        if base_class in cls.__bases__:
+            # Check if the class is abstract by looking for any unimplemented abstract methods
+            # in the entire inheritance chain (excluding object)
+            has_unimplemented_abstract_methods = False
+
+            # Get all abstract methods from the inheritance chain
+            all_abstract_methods = set()
+            for base in cls.__mro__[1:]:  # Skip the class itself
+                if base is object:
+                    continue
+                if hasattr(base, "__abstractmethods__"):
+                    all_abstract_methods.update(base.__abstractmethods__)
+
+            # Check if any of these abstract methods are still unimplemented in cls
+            if all_abstract_methods:
+                # Get the methods that cls has implemented
+                implemented_methods = set()
+                for name in all_abstract_methods:
+                    if name in cls.__dict__ and not getattr(
+                        cls.__dict__[name], "__isabstractmethod__", False
+                    ):
+                        implemented_methods.add(name)
+
+                # If there are still unimplemented abstract methods, the class is abstract
+                if all_abstract_methods - implemented_methods:
+                    has_unimplemented_abstract_methods = True
+
+            if not has_unimplemented_abstract_methods:
+                raise decorator_error(
+                    f"{cls.__name__} cannot inherit directly from {base_class.__name__}. "
+                    "It must inherit from an intermediate abstract class."
+                )
+
+    # Add the __init_subclass__ method to the base class
+    # We use setattr to avoid mypy's method assignment complaints
+    setattr(base_class, "__init_subclass__", classmethod(__init_subclass__))
+    return base_class

ml3macro/utils/identifier.py

@@ -0,0 +1,11 @@
+import uuid
+
+from ulid import ULID
+
+
+def short_id() -> str:
+    return str(uuid.uuid4())[:6].lower()
+
+
+def ulid_str() -> str:
+    return str(ULID())

ml3macro/utils/iterables.py

@@ -0,0 +1,12 @@
+from itertools import tee
+from typing import Callable, Iterable, TypeVar
+
+Item = TypeVar("Item")
+
+
+# TODO: WRITE UNIT TESTS
+def partition(
+    iterable: Iterable[Item], /, *, condition: Callable[[Item], bool]
+) -> tuple[Iterable[Item], Iterable[Item]]:
+    t1, t2 = tee(iterable)
+    return filter(condition, t1), filter(lambda x: not condition(x), t2)

ml3macro/utils/optional.py

@@ -0,0 +1,96 @@
+"""Optional value handling utilities with clear callable behavior documentation.
+
+Callable Handling Guidelines:
+1. PREFER returning values from getters when possible
+2. ONLY return callables when you specifically want deferred execution
+3. ALWAYS document when getters return callables
+4. CONSIDER using type hints to clarify callable intent
+"""
+
+from typing import Callable, Optional, TypeVar
+
+ValueType = TypeVar("ValueType")
+Object = TypeVar("Object")
+
+
+def _get_default(
+    default: ValueType | Callable[[], ValueType],
+) -> ValueType:
+    """Get the default value, calling callable defaults if needed."""
+    if callable(default):
+        return default()
+    return default
+
+
+def get_or_else(
+    value: Optional[ValueType],
+    default: ValueType | Callable[[], ValueType],
+) -> ValueType:
+    """Return the value if not None, otherwise return the default.
+
+    Args:
+        value: The value to check (returns this if not None)
+        default: Value or callable to return if value is None
+
+    Returns:
+        The value if not None, otherwise the default (calling callable defaults)
+
+    Example:
+        >>> get_or_else("value", "default")
+        "value"
+        >>> get_or_else(None, lambda: "computed")
+        "computed"
+    """
+    if value is None:
+        return _get_default(default)
+    return value
+
+
+def obj_get_or_else(
+    obj: Optional[Object],
+    get_value: Callable[[Object], Optional[ValueType]],
+    default: ValueType | Callable[[], ValueType],
+) -> ValueType:
+    """Retrieve a value from an object or return a default.
+
+    Important Behavior Notes:
+    1. Callable Defaults: If default is callable, it's called when needed
+    2. Getter Results: The getter's return value is returned AS-IS
+       - If getter returns a callable, YOU must decide whether to call it
+       - This function does NOT automatically call callables returned by getters
+    3. None Handling: Returns default if obj is None OR getter returns None
+
+    Example Patterns:
+    Pattern A - Getter returns values (most common):
+        >>> result = obj_get_or_else(person, lambda p: p.name, "Unknown")
+        >>> # result is a string, no calling needed
+
+    Pattern B - Getter returns callables (advanced):
+        >>> result = obj_get_or_else(config, lambda c: c.loader, default_loader)
+        >>> # result might be callable - check before using!
+        >>> final_value = result() if callable(result) else result
+
+    Args:
+        obj: The object to extract value from (None returns default)
+        get_value: Function that extracts value from obj (returns None uses default)
+        default: Value or callable to return when obj/value is None
+
+    Returns:
+        The extracted value, or default value/callable result
+
+    Example:
+        >>> class Person:
+        ...     def __init__(self, name):
+        ...         self.name = name
+        >>> person = Person("Alice")
+        >>> obj_get_or_else(person, lambda p: p.name, "Unknown")
+        "Alice"
+        >>> obj_get_or_else(None, lambda p: p.name, "Unknown")
+        "Unknown"
+    """
+    if obj is None:
+        return _get_default(default)
+    value = get_value(obj)
+    if value is None:
+        return _get_default(default)
+    return value

ml3macro/utils/reference.py

@@ -0,0 +1,77 @@
+"""Utility functions for working with Python object references"""
+
+from functools import partial
+from typing import Any
+
+
+def fully_qualified_name(obj: Any) -> str:
+    """Get the fully qualified name of a Python object (module.class)."""
+
+    # ------------------------------------------------------------------
+    # Partial functions (explicitly not supported)
+    # ------------------------------------------------------------------
+    if isinstance(obj, partial):
+        raise ValueError("Partial functions are not supported")
+
+    # ------------------------------------------------------------------
+    # Properties
+    # ------------------------------------------------------------------
+    if isinstance(obj, property):
+        # The getter (`fget`) carries the real qualified name.
+        fget = getattr(obj, "fget", None)
+        if (
+            fget is not None
+            and hasattr(fget, "__module__")
+            and hasattr(fget, "__qualname__")
+        ):
+            return f"{fget.__module__}.{fget.__qualname__}"
+        raise ValueError(f"Cannot determine FQN for property {obj}")
+
+    # ------------------------------------------------------------------
+    # Modules
+    # ------------------------------------------------------------------
+    if hasattr(obj, "__name__") and not hasattr(obj, "__qualname__"):
+        # Built‑in modules (e.g. sys, os, math) – just the name
+        if getattr(obj, "__name__", "").startswith(("builtins", "sys", "os", "math")):
+            return str(obj.__name__)
+        return str(obj.__name__)
+
+    # ------------------------------------------------------------------
+    # Primitive values – not supported
+    # ------------------------------------------------------------------
+    if obj is None or isinstance(obj, (int, float, str, bool, list, dict, tuple, set)):
+        raise ValueError(
+            f"Cannot get FQN for primitive value: {obj}. "
+            f"Pass the class attribute descriptor instead, e.g., Parent.attr1"
+        )
+
+    # ------------------------------------------------------------------
+    # Lambda functions
+    # ------------------------------------------------------------------
+    if getattr(obj, "__name__", None) == "<lambda>":
+        raise ValueError("Cannot get FQN for lambda function")
+
+    # ------------------------------------------------------------------
+    # Bound methods – reject instance methods, allow class/static methods
+    # ------------------------------------------------------------------
+    if hasattr(obj, "__self__"):
+        if getattr(obj, "__module__", None) == "builtins":
+            # built‑in function – keep going
+            pass
+        elif obj.__self__ is not None and not isinstance(obj.__self__, type):
+            raise ValueError("Cannot get FQN for bound method")
+        # staticmethod / classmethod – continue
+
+    # ------------------------------------------------------------------
+    # Objects without __module__ / __qualname__
+    # ------------------------------------------------------------------
+    if not hasattr(obj, "__module__") or not hasattr(obj, "__qualname__"):
+        raise ValueError(
+            f"Object {obj} does not have __module__ and __qualname__ attributes"
+        )
+
+    module = obj.__module__
+    qualname = obj.__qualname__
+    if not module or not qualname:
+        raise ValueError(f"Object {obj} has empty __module__ or __qualname__")
+    return f"{module}.{qualname}"

ml3macro/utils/strings.py

@@ -0,0 +1,50 @@
+from functools import reduce
+from typing import Tuple
+
+
+def strip_margin(s: str, /) -> str:
+    if not isinstance(s, str):
+        raise TypeError("Input must be a string")
+
+    lines: Tuple[str, ...] = tuple(s.splitlines())
+
+    # Remove empty leading lines (immutable approach)
+    first_non_empty_idx = next(
+        (i for i, line in enumerate(lines) if line.strip()), len(lines)
+    )
+    trimmed_lines: Tuple[str, ...] = lines[first_non_empty_idx:]
+
+    # Remove empty trailing lines (immutable approach)
+    last_non_empty_idx = next(
+        (i for i, line in enumerate(reversed(trimmed_lines)) if line.strip()),
+        len(trimmed_lines),
+    )
+    trimmed_lines = trimmed_lines[: len(trimmed_lines) - last_non_empty_idx]
+
+    if not trimmed_lines:
+        return ""
+
+    # Calculate margin length from first line
+    first_line: str = trimmed_lines[0]
+    margin_length: int = len(first_line) - len(first_line.lstrip())
+
+    # Verify all lines have consistent margin
+    for line in trimmed_lines:
+        if not line:
+            continue  # Skip empty lines
+        if len(line) < margin_length:
+            raise ValueError(
+                f"Line '{line}' is shorter than margin length {margin_length}"
+            )
+        if line[:margin_length].strip():
+            raise ValueError(f"Line '{line}' has non-whitespace in margin area")
+
+    # Process all lines using reduce
+    def process_line(acc: Tuple[str, ...], line: str) -> Tuple[str, ...]:
+        return (*acc, line[margin_length:]) if line else (*acc, line)
+
+    result_lines: Tuple[str, ...] = reduce(
+        process_line, trimmed_lines[1:], (trimmed_lines[0][margin_length:],)
+    )
+
+    return "\n".join(result_lines)

ml3macro_utils-0.0.0.dist-info/METADATA

@@ -0,0 +1,87 @@
+Metadata-Version: 2.4
+Name: ml3macro-utils
+Version: 0.0.0
+Summary: ml3macro common utils - immutable data structures, enhanced enums, decorators, and utilities
+Author-email: macro <your-email@example.com>
+Maintainer-email: macro <your-email@example.com>
+License: MIT
+Project-URL: Homepage, https://codeberg.org/gxyflow/ml3macro
+Project-URL: Repository, https://codeberg.org/gxyflow/ml3macro
+Project-URL: Issues, https://codeberg.org/gxyflow/ml3macro/issues
+Keywords: ml3macro,utils,immutable,enum,decorators
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: <3.15,>=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: frozendict>=2.3.0
+Requires-Dist: strenum>=0.4.0
+Requires-Dist: overrides>=7.0.0
+Requires-Dist: python-ulid>=1.0.0
+
+# ml3macro utils
+
+[![PyPI](https://img.shields.io/pypi/v/ml3macro-utils.svg)](https://pypi.org/project/ml3macro-utils/)
+[![Python Version](https://img.shields.io/pypi/pyversions/ml3macro-utils.svg)](https://pypi.org/project/ml3macro-utils/)
+
+
+
+Common utilities and shared code for ml3macro projects.
+
+## Status: In Development
+
+This is a new package with general-purpose helper functions/classes/etc for use in my other projects.
+
+## Overview
+
+This package contains reusable utilities and helpers used across ml3macro projects:
+
+- **Data Structures**: Immutable/constrained collections like `AdditiveMapping`
+- **Enums**: Enhanced enumeration base classes
+- **Decorators**: Class structure enforcement decorators
+- **Identifiers**: Unique ID generation utilities
+- **Functional Helpers**: Iterables processing, optional value handling
+- **Reflection**: Object introspection utilities
+- **Text Processing**: String manipulation helpers
+
+## Installation
+
+```bash
+pip install ml3macro-utils
+```
+
+## Usage
+
+Import specific utilities as needed:
+
+```python
+from ml3macro.utils.additive_mapping import AdditiveMapping
+from ml3macro.utils.identifier import short_id
+from ml3macro.utils.optional import get_or_else
+```
+
+Or import from the main package:
+
+```python
+from ml3macro.utils import AdditiveMapping, short_id, get_or_else
+```
+
+## Requirements
+
+- Python 3.11+
+- frozendict
+- strenum
+- overrides
+- python-ulid
+
+## License
+
+MIT License
+

ml3macro_utils-0.0.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+ml3macro/utils/__init__.py,sha256=EkR0neMLRYRaImWE9EuGVHwAYSYtSccIJTyfH-UWX5U,79
+ml3macro/utils/additive_mapping.py,sha256=KBTErJU073W8FkDXvnReb037fSfpzRZmfuWca4oKI-A,4003
+ml3macro/utils/base_enum.py,sha256=rVp_NvzNuoYDooIXWzUf12LZT7zBVn7QEzvG5AlM_mk,67
+ml3macro/utils/identifier.py,sha256=7Ib2WxnlwwjQ_ydnJI-51tivcOtgnIUwTIBdT-YdBkE,149
+ml3macro/utils/iterables.py,sha256=H0lBNxx-XF7HQRMb3KLY2LJm2fpl_nQy6dwvV5b4jKs,353
+ml3macro/utils/optional.py,sha256=KsLOUUmGPavLZSV67teNUvyYe5H-o5Vvu5z_CcOg5xE,3216
+ml3macro/utils/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ml3macro/utils/reference.py,sha256=DXAxctJAN580C8hSg6lTNuXhmM89j3hb8hnGegltrGg,3470
+ml3macro/utils/strings.py,sha256=6CRXThYlzhxU0Pmbui6kf8tkTycI93ntd_cg6qK3mjE,1700
+ml3macro/utils/decorators/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ml3macro/utils/decorators/layered_abstract_class.py,sha256=WpDuv6NhSzS3QrJVumBjAG2rzD2CI2aJAESjZiiuxJo,2776
+ml3macro_utils-0.0.0.dist-info/METADATA,sha256=NDW1jVFhcHvIxhUIkyWJqWmszluIdB3AEl8100V4ZEU,2640
+ml3macro_utils-0.0.0.dist-info/WHEEL,sha256=YCfwYGOYMi5Jhw2fU4yNgwErybb2IX5PEwBKV4ZbdBo,91
+ml3macro_utils-0.0.0.dist-info/top_level.txt,sha256=lfZK6lm0zMRNkTTOFqQzbBU0gf7ed_O_Wat-yy13Gwc,9
+ml3macro_utils-0.0.0.dist-info/RECORD,,

ml3macro_utils-0.0.0.dist-info/WHEEL

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

ml3macro_utils-0.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+ml3macro