speedy-utils 1.1.26__py3-none-any.whl → 1.1.28__py3-none-any.whl

llm_utils/vector_cache/utils.py

@@ -3,17 +3,19 @@
 import os
 from typing import Optional
 
+
 def get_default_cache_path() -> str:
     """Get the default cache path based on environment."""
     cache_dir = os.getenv("EMBED_CACHE_DIR", ".")
     return os.path.join(cache_dir, "embed_cache.sqlite")
 
+
 def validate_model_name(model_name: str) -> bool:
     """Validate if a model name is supported."""
     # Check if it's a URL
     if model_name.startswith("http"):
         return True
-    
+
     # Check if it's a valid model path/name
     supported_prefixes = [
         "Qwen/",
@@ -23,20 +25,22 @@ def validate_model_name(model_name: str) -> bool:
         "microsoft/",
         "nvidia/",
     ]
-    
-    return any(model_name.startswith(prefix) for prefix in supported_prefixes) or os.path.exists(model_name)
+
+    return any(
+        model_name.startswith(prefix) for prefix in supported_prefixes
+    ) or os.path.exists(model_name)
+
 
 def estimate_cache_size(num_texts: int, embedding_dim: int = 1024) -> str:
     """Estimate cache size for given number of texts."""
     # Rough estimate: hash (40 bytes) + text (avg 100 bytes) + embedding (embedding_dim * 4 bytes)
     bytes_per_entry = 40 + 100 + (embedding_dim * 4)
     total_bytes = num_texts * bytes_per_entry
-    
+
     if total_bytes < 1024:
         return f"{total_bytes} bytes"
-    elif total_bytes < 1024 * 1024:
+    if total_bytes < 1024 * 1024:
         return f"{total_bytes / 1024:.1f} KB"
-    elif total_bytes < 1024 * 1024 * 1024:
+    if total_bytes < 1024 * 1024 * 1024:
         return f"{total_bytes / (1024 * 1024):.1f} MB"
-    else:
-        return f"{total_bytes / (1024 * 1024 * 1024):.1f} GB"
+    return f"{total_bytes / (1024 * 1024 * 1024):.1f} GB"

speedy_utils/__imports.py

@@ -0,0 +1,244 @@
+# type: ignore
+from __future__ import annotations
+
+import time
+import warnings
+
+
+# Suppress lazy_loader subpackage warning
+warnings.filterwarnings(
+    'ignore',
+    message='subpackages can technically be lazily loaded',
+    category=RuntimeWarning,
+    module='lazy_loader',
+)
+
+t = time.time()
+# Third-party imports
+try:
+    # Python 3.10+
+    from typing import ParamSpec
+except ImportError:  # pragma: no cover
+    from typing_extensions import ParamSpec  # type: ignore
+
+
+import asyncio
+import contextlib
+import copy
+import ctypes
+import datetime
+import functools
+import gc
+import inspect
+import io
+import json
+import multiprocessing
+import os
+import os.path as osp
+import pathlib
+import pickle
+import pprint
+import random
+import re
+import sys
+import textwrap
+import threading
+import time
+import traceback
+import types
+import uuid
+import weakref
+from collections import Counter, OrderedDict, defaultdict
+from collections.abc import Awaitable, Callable, Iterable, Mapping, Sequence
+from collections.abc import Callable as TypingCallable
+from concurrent.futures import (
+    FIRST_COMPLETED,
+    Future,
+    ThreadPoolExecutor,
+    as_completed,
+    wait,
+)
+from datetime import datetime  # noqa: F811
+from glob import glob
+from heapq import heappop, heappush
+from itertools import islice
+from multiprocessing import Pool
+from pathlib import Path
+from threading import Lock
+from types import MappingProxyType
+from typing import (
+    IO,
+    TYPE_CHECKING,
+    Annotated,
+    Any,
+    Dict,
+    Generic,
+    List,
+    Literal,
+    Optional,
+    Set,
+    Tuple,
+    Type,
+    TypeVar,
+    Union,
+    cast,
+    overload,
+)
+
+import cachetools
+import lazy_loader as lazy
+import psutil
+from fastcore.parallel import parallel
+from json_repair import loads as jloads
+from loguru import logger
+from tqdm import tqdm
+
+
+# Resolve long-import-time dependencies lazily
+
+torch = lazy.load('torch')  # lazy at runtime
+np = lazy.load('numpy')
+pd = lazy.load('pandas')
+tqdm = lazy.load('tqdm').tqdm  # type: ignore  # noqa: F811
+pd = lazy.load('pandas')
+tabulate = lazy.load('tabulate').tabulate
+xxhash = lazy.load('xxhash')
+get_ipython = lazy.load('IPython.core.getipython')
+HTML = lazy.load('IPython.display').HTML
+display = lazy.load('IPython.display').display
+# logger = lazy.load('loguru').logger
+BaseModel = lazy.load('pydantic').BaseModel
+_pil = lazy.load('PIL.Image')
+Image = _pil.Image
+matplotlib = lazy.load('matplotlib')
+plt = lazy.load('matplotlib.pyplot')
+
+
+ray = lazy.load('ray')  # lazy at runtime
+if TYPE_CHECKING:
+    import numpy as np
+    import pandas as pd
+    import ray
+    import torch
+    import matplotlib.pyplot as plt
+    # xxhash
+    import xxhash  # type: ignore
+    from IPython.core.getipython import get_ipython  # type: ignore
+    from IPython.display import HTML, display  # type: ignore
+    from loguru import logger  # type: ignore
+    from PIL import Image
+    from pydantic import BaseModel  # type: ignore
+    from tabulate import tabulate  # type: ignore
+    from tqdm import tqdm  # type: ignore
+
+__all__ = [
+    # ------------------------------------------------------------------
+    # Lazy-loaded external modules / objects
+    # ------------------------------------------------------------------
+    'torch',
+    'np',
+    'pd',
+    'tqdm',
+    'tabulate',
+    'xxhash',
+    'get_ipython',
+    'HTML',
+    'display',
+    'BaseModel',
+    'Image',
+    'ray',
+    # ------------------------------------------------------------------
+    # Standard library modules imported
+    # ------------------------------------------------------------------
+    'asyncio',
+    'contextlib',
+    'copy',
+    'ctypes',
+    'datetime',
+    'functools',
+    'gc',
+    'inspect',
+    'io',
+    'json',
+    'multiprocessing',
+    'os',
+    'osp',
+    'pathlib',
+    'pickle',
+    'pprint',
+    'random',
+    're',
+    'sys',
+    'textwrap',
+    'threading',
+    'time',
+    'traceback',
+    'types',
+    'uuid',
+    'weakref',
+    'warnings',
+    # ------------------------------------------------------------------
+    # Data structures
+    # ------------------------------------------------------------------
+    'Counter',
+    'OrderedDict',
+    'defaultdict',
+    'MappingProxyType',
+    # ------------------------------------------------------------------
+    # File & path utilities
+    # ------------------------------------------------------------------
+    'Path',
+    'glob',
+    # ------------------------------------------------------------------
+    # Concurrency / parallelism
+    # ------------------------------------------------------------------
+    'ThreadPoolExecutor',
+    'as_completed',
+    'wait',
+    'FIRST_COMPLETED',
+    'Future',
+    'Pool',
+    'Lock',
+    # ------------------------------------------------------------------
+    # Algorithms / heap helpers
+    # ------------------------------------------------------------------
+    'heappop',
+    'heappush',
+    'islice',
+    # ------------------------------------------------------------------
+    # Typing
+    # ------------------------------------------------------------------
+    'Annotated',
+    'Any',
+    'Awaitable',
+    'Callable',
+    'Dict',
+    'Generic',
+    'IO',
+    'Iterable',
+    'List',
+    'Literal',
+    'Mapping',
+    'Optional',
+    'ParamSpec',
+    'Sequence',
+    'Set',
+    'Tuple',
+    'Type',
+    'TYPE_CHECKING',
+    'TypeVar',
+    'TypingCallable',
+    'Union',
+    'cast',
+    'overload',
+    # ------------------------------------------------------------------
+    # Third-party modules
+    # ------------------------------------------------------------------
+    'cachetools',
+    'lazy',
+    'psutil',
+    'parallel',
+    'jloads',
+    'logger',
+    'plt',
+]

speedy_utils/__init__.py

@@ -1,122 +1,18 @@
-# ----------------------------------------------------------------------------
-# speedy_utils/__init__.py
-#
-# Main entry point and public API for the Speedy Utils library
-#
-# This module exports the primary utilities for enhanced Python development
-# productivity including caching mechanisms, parallel processing, file I/O,
-# timing utilities, and data manipulation functions. It provides a convenient
-# single-import interface for the most commonly used functionality.
-#
-# Public API / Data Contracts:
-# • setup_logger(min_interval: int = 5) -> None - Configure logging system
-# • log(*args, **kwargs) -> None - Rate-limited logging function
-# • Clock() - Timing and performance measurement utility
-# • speedy_timer: Clock - Pre-configured global timer instance
-# • timef(func) -> Callable - Function execution time decorator
-# • retry_runtime(sleep_seconds: int, max_retry: int, exceptions) -> Callable
-# • memoize(func) -> Callable - Function result caching decorator
-# • imemoize(func) -> Callable - In-memory caching decorator (global persistent)
-# • identify(obj: Any) -> str - Generate unique object identifier
-# • identify_uuid(obj: Any) -> str - Generate UUID-based object identifier
-# • load_by_ext(fname: Union[str, list[str]]) -> Any - Auto-detect file format loader
-# • dump_json_or_pickle(obj: Any, fname: str) -> None - Smart file serializer
-# • load_json_or_pickle(fname: str) -> Any - Smart file deserializer
-# • multi_thread(func, items, **kwargs) -> list - Parallel thread execution
-# • multi_process(func, items, **kwargs) -> list - Parallel process execution
-#
-# Invariants / Constraints:
-# • MUST import only stable, tested utilities into public namespace
-# • SHOULD maintain backward compatibility across minor versions
-# • MUST provide consistent error handling across all public functions
-# • SHOULD use lazy imports for heavy dependencies when possible
-#
-# Usage Example:
-# ```python
-# from speedy_utils import Clock, memoize, multi_thread, load_by_ext
-#
-# @memoize
-# def expensive_computation(x):
-#     return x ** 2
-#
-# timer = Clock()
-# timer.start()
-# results = multi_thread(expensive_computation, range(100))
-# timer.end()
-# data = load_by_ext("config.json")
-# ```
-#
-# TODO & Future Work:
-# • Add async variants for I/O operations
-# • Implement distributed caching backend
-# • Add GPU acceleration utilities
-# ----------------------------------------------------------------------------
-
-# Import specific functions and classes from modules
-# Logger
-# Standard library imports
-import copy
-import functools
-import gc
-import inspect
-import json
-import multiprocessing
-import os
-import os.path as osp
-import pickle
-import pprint
-import random
-import re
-import sys
-import textwrap
-import threading
 import time
-import traceback
-import uuid
-from collections import Counter, defaultdict
-from collections.abc import Callable
-from concurrent.futures import ThreadPoolExecutor, as_completed
-from glob import glob
-from multiprocessing import Pool
-from pathlib import Path
-from threading import Lock
-from typing import (
-    Any,
-    Awaitable,
-    Callable as TypingCallable,
-    Dict,
-    Generic,
-    Iterable,
-    List,
-    Literal,
-    Mapping,
-    Optional,
-    Sequence,
-    Set,
-    Tuple,
-    Type,
-    TypeVar,
-    Union,
-)
 
+
+t = time.time()
 # Third-party imports
-import numpy as np
-import pandas as pd
-import xxhash
-from IPython.core.getipython import get_ipython
-from IPython.display import HTML, display
-from loguru import logger
-from pydantic import BaseModel
-from tabulate import tabulate
-from tqdm import tqdm
 
-from speedy_utils.common.logger import log, setup_logger
+
+from .__imports import *
 
 # Clock module
 from .common.clock import Clock, speedy_timer, timef
 
 # Function decorators
 from .common.function_decorator import retry_runtime
+from .common.logger import log, setup_logger
 
 # notebook
 from .common.notebook_utils import (
@@ -159,101 +55,101 @@ from .common.utils_print import (
 from .multi_worker.process import multi_process
 from .multi_worker.thread import kill_all_thread, multi_thread
 
-# Define __all__ explicitly
+
 __all__ = [
     # Standard library
-    "random",
-    "copy",
-    "functools",
-    "gc",
-    "inspect",
-    "json",
-    "multiprocessing",
-    "os",
-    "osp",
-    "pickle",
-    "pprint",
-    "re",
-    "sys",
-    "textwrap",
-    "threading",
-    "time",
-    "traceback",
-    "uuid",
-    "Counter",
-    "ThreadPoolExecutor",
-    "as_completed",
-    "glob",
-    "Pool",
-    "Path",
-    "Lock",
-    "defaultdict",
+    'random',
+    'copy',
+    'functools',
+    'gc',
+    'inspect',
+    'json',
+    'multiprocessing',
+    'os',
+    'osp',
+    'pickle',
+    'pprint',
+    're',
+    'sys',
+    'textwrap',
+    'threading',
+    'time',
+    'traceback',
+    'uuid',
+    'Counter',
+    'ThreadPoolExecutor',
+    'as_completed',
+    'glob',
+    'Pool',
+    'Path',
+    'Lock',
+    'defaultdict',
     # Typing
-    "Any",
-    "Awaitable",
-    "Callable",
-    "TypingCallable",
-    "Dict",
-    "Generic",
-    "Iterable",
-    "List",
-    "Literal",
-    "Mapping",
-    "Optional",
-    "Sequence",
-    "Set",
-    "Tuple",
-    "Type",
-    "TypeVar",
-    "Union",
+    'Any',
+    'Awaitable',
+    'Callable',
+    'TypingCallable',
+    'Dict',
+    'Generic',
+    'Iterable',
+    'List',
+    'Literal',
+    'Mapping',
+    'Optional',
+    'Sequence',
+    'Set',
+    'Tuple',
+    'Type',
+    'TypeVar',
+    'Union',
     # Third-party
-    "pd",
-    "xxhash",
-    "get_ipython",
-    "HTML",
-    "display",
-    "logger",
-    "BaseModel",
-    "tabulate",
-    "tqdm",
-    "np",
+    'pd',
+    'xxhash',
+    'get_ipython',
+    'HTML',
+    'display',
+    'logger',
+    'BaseModel',
+    'tabulate',
+    'tqdm',
+    'np',
     # Clock module
-    "Clock",
-    "speedy_timer",
-    "timef",
+    'Clock',
+    'speedy_timer',
+    'timef',
     # Function decorators
-    "retry_runtime",
+    'retry_runtime',
     # Cache utilities
-    "memoize",
-    "imemoize",
-    "identify",
-    "identify_uuid",
+    'memoize',
+    'imemoize',
+    'identify',
+    'identify_uuid',
     # IO utilities
-    "dump_json_or_pickle",
-    "dump_jsonl",
-    "load_by_ext",
-    "load_json_or_pickle",
-    "load_jsonl",
-    "jdumps",
-    "jloads",
+    'dump_json_or_pickle',
+    'dump_jsonl',
+    'load_by_ext',
+    'load_json_or_pickle',
+    'load_jsonl',
+    'jdumps',
+    'jloads',
     # Misc utilities
-    "mkdir_or_exist",
-    "flatten_list",
-    "get_arg_names",
-    "is_notebook",
-    "convert_to_builtin_python",
-    "dedup",
+    'mkdir_or_exist',
+    'flatten_list',
+    'get_arg_names',
+    'is_notebook',
+    'convert_to_builtin_python',
+    'dedup',
     # Print utilities
-    "display_pretty_table_html",
-    "flatten_dict",
-    "fprint",
-    "print_table",
-    "setup_logger",
-    "log",
+    'display_pretty_table_html',
+    'flatten_dict',
+    'fprint',
+    'print_table',
+    'setup_logger',
+    'log',
     # Multi-worker processing
-    "multi_process",
-    "multi_thread",
-    "kill_all_thread",
+    'multi_process',
+    'multi_thread',
+    'kill_all_thread',
     # Notebook utilities
-    "change_dir",
+    'change_dir',
 ]