stdl 0.6.7__py3-none-any.whl

stdl/import_lazy.py

@@ -0,0 +1,123 @@
+import importlib
+import sys
+import time
+from typing import Any
+
+
+class LazyImport:
+    """A lazy import that loads the actual object on first access."""
+
+    def __init__(
+        self,
+        module_name: str,
+        attr_name: str | None = None,
+        verbose: bool = False,
+    ):
+        self.module_name = module_name
+        self.attr_name = attr_name
+        self.verbose = verbose
+
+        self._cached_value: Any = None
+        self._loaded = False
+
+    def _load(self) -> Any:
+        if not self._loaded:
+            if self.verbose:
+                start_time = time.time()
+
+            module_already_loaded = self.module_name in sys.modules
+            try:
+                module = importlib.import_module(self.module_name)
+            except ImportError as e:
+                if self.attr_name:
+                    raise ImportError(
+                        f"Cannot import '{self.attr_name}' from '{self.module_name}': {e}"
+                    )
+                else:
+                    raise ImportError(f"Cannot import module '{self.module_name}': {e}")
+
+            if self.attr_name:
+                try:
+                    self._cached_value = getattr(module, self.attr_name)
+                except AttributeError:
+                    raise ImportError(
+                        f"Module '{self.module_name}' has no attribute '{self.attr_name}'"
+                    )
+            else:
+                self._cached_value = module
+
+            if self.verbose and not module_already_loaded:
+                end_time = time.time()
+                import_time = end_time - start_time
+                import_target = (
+                    f"{self.module_name}.{self.attr_name}" if self.attr_name else self.module_name
+                )
+
+                print(
+                    f'importing "{import_target}" took {import_time:.3f}s',
+                    file=sys.stderr,
+                )
+
+            self._loaded = True
+
+        return self._cached_value
+
+    def __call__(self, *args: Any, **kwargs: Any) -> Any:
+        return self._load()(*args, **kwargs)
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._load(), name)
+
+    def __setattr__(self, name: str, value: Any) -> None:
+        if name in ("module_name", "attr_name", "verbose", "_cached_value", "_loaded"):
+            super().__setattr__(name, value)
+        else:
+            setattr(self._load(), name, value)
+
+    def __repr__(self) -> str:
+        if self._loaded:
+            return repr(self._cached_value)
+        return f"<LazyImport: {self.module_name}{('.' + self.attr_name) if self.attr_name else ''}>"
+
+
+def import_lazy(
+    module: str,
+    names: list[str] | None = None,
+    alias: str | None = None,
+    verbose: bool = False,
+) -> None:
+    """
+    Lazy import a module.
+
+    Args:
+        module (str): Module name to import
+        names (list[str] | None): List of specific names to import from the module. If None, imports the module itself.
+        alias (str | None): Alias to use for the imported module (only valid when names is None)
+        verbose (bool): If True, print timing information when imports actually happen
+
+    Example:
+        ```python
+        >>> import_lazy("module", ["name_1", "name_2"])  # from module import name_1, name_2
+        >>> import_lazy("module")                      # import module
+        >>> import_lazy("module", alias="mod")          # import module as mod
+        >>> import_lazy("package.submodule", ["name_1"])   # from package.submodule import name_1
+        ```
+    """
+    frame = sys._getframe(1)
+    caller_globals = frame.f_globals
+
+    if names is None:
+        lazy_import = LazyImport(module, verbose=verbose)
+        if alias:
+            caller_globals[alias] = lazy_import
+        else:
+            caller_globals[module.split(".")[-1]] = lazy_import
+    else:
+        if alias:
+            raise ValueError("Cannot use alias with named imports")
+        for name in names:
+            lazy_import = LazyImport(module, name, verbose=verbose)
+            caller_globals[name] = lazy_import
+
+
+__all__ = ["import_lazy", "LazyImport"]

stdl/log.py

@@ -0,0 +1,142 @@
+from collections.abc import Callable
+from shutil import get_terminal_size
+from typing import Any, ClassVar
+
+from stdl.st import ForegroundColor, colored
+
+IGNORE_BREAKS = False
+
+
+def color_tag(text: str, color: str) -> str:
+    return f"<{color}>{text}</{color}>"
+
+
+class LoguruFormatter:
+    time = color_tag("{time:YYYY-MM-DD HH:mm:ss}", "green")
+    level = color_tag("{level: <8}", "level")
+    msg = color_tag("{message:<24}", "level")
+    name = color_tag("{name}", "light-blue")
+    func = color_tag("{function}", "light-blue")
+    lineno = color_tag("{line}", "light-blue")
+    extra_key_skips: ClassVar[list[str]] = ["title"]
+    extra_key_name_color: ForegroundColor = "white"
+
+    def format(self, record: dict[str, Any]) -> str:
+        """
+        Example:
+            ```python
+            >>> import sys
+            >>> from loguru import logger
+            >>> logger.remove()
+            >>> logger.add(sys.stdout, level="DEBUG", format=loguru_formater)
+            ```
+        """
+        extras = ""
+        if len(record["extra"]):
+            for key in record["extra"].keys():
+                if key in self.extra_key_skips:
+                    continue
+                extras = (
+                    extras
+                    + colored(key, self.extra_key_name_color)
+                    + "="
+                    + "{extra["
+                    + key
+                    + "]}, "
+                )
+            extras = extras[:-2]
+
+        if title := record["extra"].get("title"):
+            return f"{self.time} | {self.level} | [ {title} ] {self.name}:{self.func}:{self.lineno} - {self.msg} {extras}\n"
+        return f"{self.time} | {self.level} | {self.name}:{self.func}:{self.lineno} - {self.msg} {extras}\n"
+
+
+class SimpleLoguruFormatter(LoguruFormatter):
+    def format(self, record: dict[str, Any]) -> str:
+        extras = ""
+        if len(record["extra"]):
+            for key in record["extra"].keys():
+                if key in self.extra_key_skips:
+                    continue
+                extras = (
+                    extras
+                    + colored(key, self.extra_key_name_color)
+                    + "="
+                    + "{extra["
+                    + key
+                    + "]}, "
+                )
+            extras = extras[:-2]
+
+        return f"{self.level} - {self.msg} {extras}\n"
+
+
+loguru_formater = LoguruFormatter().format
+simple_loguru_formater = SimpleLoguruFormatter().format
+
+
+def get_logging_config(
+    format: str | None = None,
+    level: str = "INFO",
+    filename: str | None = None,
+    backup_count: int = 0,
+    disable_existing: bool = False,
+    console_handler: str = "logging.StreamHandler",
+    file_handler: str = "logging.handlers.TimedRotatingFileHandler",
+    format_style: str = "{",
+) -> dict[str, Any]:
+    format = (
+        format
+        or "{asctime} | {levelname:<8s} | [ {name} ] {module}.{funcName}:{lineno} - {message}"
+    )
+
+    config = {
+        "version": 1,
+        "disable_existing_loggers": disable_existing,
+        "formatters": {
+            "standard": {
+                "format": format,
+                "datefmt": "%Y-%m-%d %H:%M:%S",
+                "style": format_style,
+            }
+        },
+        "handlers": {
+            "console": {
+                "class": console_handler,
+                "level": level,
+                "formatter": "standard",
+                "stream": "ext://sys.stdout",
+            },
+        },
+        "root": {"level": level, "handlers": ["console"]},
+    }
+    if filename:
+        config["handlers"]["file"] = {
+            "class": file_handler,
+            "level": level,
+            "formatter": "standard",
+            "backupCount": backup_count,
+            "filename": filename,
+        }
+        config["root"]["handlers"].append("file")
+
+    return config
+
+
+def br(
+    c: str = "_",
+    length: int | None = None,
+    handler: Callable[[str], None] = print,
+    *,
+    newline: bool = False,
+) -> None:
+    if IGNORE_BREAKS:
+        return
+    length = length or get_terminal_size().columns
+    line = c * length
+    if newline:
+        line += "\n"
+    handler(line)
+
+
+__all__ = ["loguru_formater", "br", "get_logging_config", "LoguruFormatter"]

stdl/lst.py

@@ -0,0 +1,166 @@
+from collections import Counter
+from collections.abc import Sequence
+from typing import Any, TypeVar
+
+T = TypeVar("T")
+
+
+def chunks(l: list[T], size: int) -> list[list[T]]:
+    """
+    Splits a list into chunks of a specified size.
+
+    Args:
+        l (list[T]): list to be split
+        size (int): Size of each chunk.
+
+    Returns:
+        list[list[T]] : a list containing the chunks.
+
+    Raises:
+        ValueError : if the size is less than 1 or greater than the length of the list
+    """
+    if size < 1 or size > len(l):
+        raise ValueError(size)
+    return [l[i : i + size] for i in range(0, len(l), size)]
+
+
+def split(l: list[T], parts: int) -> list[list[T]]:
+    """
+    Splits a list into a specified number of parts
+
+    Args:
+        l (list[T]): List to be split
+        parts (int): Number of parts to split the list into.
+
+    Returns:
+        list[list[T]] : a list containing the split parts.
+
+    Raises:
+        ValueError : if the parts is less than 1 or greater than the length of the list.
+    """
+    if parts < 1 or parts > len(l):
+        raise ValueError(parts)
+
+    def inner(l: list[T], parts: int) -> list[list[T]]:
+        length = len(l)
+        si = length // parts
+        if length - si > 0:
+            return [l[:si], *inner(l[si:], parts - 1)]
+        else:
+            return [l]
+
+    return inner(l, parts)
+
+
+def unique(l: Sequence[T]) -> list[T]:
+    """
+    Filter out all non-unique values from a list.
+
+    Args:
+        l (Sequence[T]): The list to filter.
+
+    Returns:
+        list[T]: A list of only unique values.
+    """
+    return [i for i, count in Counter(l).items() if count == 1]
+
+
+def non_unique(l: Sequence[T]) -> list[T]:
+    """
+    Filter out all unique values from a list.
+
+    Args:
+        l (Sequence[T]): The list to filter.
+
+    Returns:
+        list[T]: A list of only non-unique values.
+    """
+    return [i for i, count in Counter(l).items() if count > 1]
+
+
+def every_nth(l: list[T], n: int) -> list[T]:
+    """
+    Return every nth element from a list
+    Args:
+        l (list[T]): The list to extract elements from.
+        n (int): The index to extract the element at
+    Returns:
+        list[T]: A list of every nth element
+    """
+    return l[n - 1 :: n]
+
+
+def occurrences(l: Sequence[T], val: Any) -> int:
+    """
+    Count the number of occurrences of a value in a list
+    Args:
+        l (Sequence[T]): The list to count values in.
+        val (Any): The value to count
+    Returns:
+        int: Number of occurrences
+    """
+    return len([i for i in l if i == val and type(i) is type(val)])
+
+
+def nodups(l: Sequence[T]) -> list[T]:
+    """Remove duplicates from a list and maintain the order"""
+    result: list[T] = []
+    for i in l:
+        if i not in result:
+            result.append(i)
+    return result
+
+
+def replace_sublists(l: list[Any], sublist: list[Any], replacement: list[Any]) -> list[Any]:
+    """
+    Replaces all occurrences of sublist `sublist` with `replacement` in `main`.
+
+    Args:
+        l: The list in which to search for sublists.
+        sublist: The sublist to replace.
+        replacement: The sublist to replace `sublist` with.
+
+    Example:
+        >>> replace_all_sublist([1, 2, 3, 2, 3], [2, 3], [5])
+        [1, 5, 5]
+    """
+    result = []
+    i = 0
+    len_old = len(sublist)
+    while i <= len(l) - len_old:
+        if l[i : i + len_old] == sublist:
+            result.extend(replacement)
+            i += len_old
+        else:
+            result.append(l[i])
+            i += 1
+    result.extend(l[i:])
+    return result
+
+
+def contains_sublist(l: list[Any], sublist: list[Any]) -> bool:
+    """
+    Checks if list contains a sublist.
+
+    Args:
+        l: The list to search.
+        sublist: The sublist to search for.
+
+    """
+    len_b = len(sublist)
+    for i in range(len(l) - len_b + 1):
+        if l[i : i + len_b] == sublist:
+            return True
+    return False
+
+
+__all__ = [
+    "unique",
+    "non_unique",
+    "every_nth",
+    "occurrences",
+    "chunks",
+    "split",
+    "replace_sublists",
+    "contains_sublist",
+]

stdl/net.py

@@ -0,0 +1,80 @@
+import os
+import warnings
+from http.client import HTTPMessage
+from urllib.request import urlopen, urlretrieve
+
+try:
+    from tqdm import tqdm
+except ImportError:  # pragma: no cover - optional dependency
+    tqdm = None
+
+from stdl.fs import bytes_readable, readable_size_to_bytes
+
+if tqdm is not None:
+
+    class ProgressBarTQDM(tqdm):
+        def update_to(self, b: int = 1, bsize: int = 1, tsize: int | None = None) -> None:
+            if tsize is not None:
+                self.total = tsize
+            self.update(b * bsize - self.n)
+else:
+    ProgressBarTQDM = None
+
+
+class DownloadSizeExceededError(Exception):
+    def __init__(self, filesize: int, maxsize: int):
+        self.filesize = filesize
+        self.maxsize = maxsize
+
+    def __str__(self) -> str:
+        return f"File size {self.filesize} ({bytes_readable(self.filesize)}) exceeds maximum size limit of {self.maxsize} bytes ({bytes_readable(self.maxsize)})"
+
+
+def download(
+    url: str,
+    path: str,
+    *,
+    maxsize: int | str | None = None,
+    progressbar: bool = False,
+    overwrite: bool = False,
+) -> tuple[str, HTTPMessage]:
+    """
+    Download a file
+
+    Args:
+        url (str): File URL
+        path (str): Save path
+        maxsize (int | str | None, optional): Maximum file size in bytes or human readable format.
+        progressbar (bool, optional): Display progress bar in console.
+        overwrite (bool, optional): Overwrite destination path if it already exists.
+
+    Raises:
+        FileExistsError: if path already exists and overwrite is set to False
+        DownloadSizeExceededError: if file size exceeds maxsize
+    """
+    if maxsize is not None:
+        if isinstance(maxsize, str):
+            maxsize = readable_size_to_bytes(maxsize)
+        filesize = int(urlopen(url).headers.get("Content-Length", 0))
+        if filesize > maxsize:
+            raise DownloadSizeExceededError(filesize, maxsize)
+
+    if os.path.exists(path) and not overwrite:
+        raise FileExistsError(path)
+
+    if progressbar and ProgressBarTQDM is not None:
+        with ProgressBarTQDM(unit="B", unit_scale=True, unit_divisor=1024) as t:
+            r = urlretrieve(url, path, reporthook=t.update_to, data=None)
+        t.total = t.n
+    else:
+        if progressbar and ProgressBarTQDM is None:
+            warnings.warn(
+                "progressbar=True requested but tqdm is not installed; downloading without progress bar.",
+                RuntimeWarning,
+                stacklevel=2,
+            )
+        r = urlretrieve(url, path)
+    return r
+
+
+__all__ = ["download"]