bs-python-utils 1.0__tar.gz → 1.1__tar.gz

{bs_python_utils-1.0 → bs_python_utils-1.1}/PKG-INFO

@@ -1,8 +1,8 @@
 Metadata-Version: 2.4
 Name: bs-python-utils
-Version: 1.0
+Version: 1.1
 Summary: Utilities programs for my Python code
-Requires-Python: >=3.12
+Requires-Python: >=3.13
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: altair>=5.5.0
@@ -26,14 +26,19 @@ Requires-Dist: streamlit>=1.49.1
 Requires-Dist: vega-datasets>=0.9.0
 Requires-Dist: colorama>=0.4.6
 Requires-Dist: pyarrow>=23.0.0
+Requires-Dist: scipy-stubs~=1.16.2
 Dynamic: license-file
 
 ## bs-python-utils
 
 [![PyPI version](https://img.shields.io/pypi/v/bs-python-utils)](https://pypi.org/project/bs-python-utils/)
+<!--
 [![Release](https://img.shields.io/github/v/release/bsalanie/bs-python-utils)](https://github.com/bsalanie/bs-python-utils/releases)
+-->
 [![Build status](https://img.shields.io/github/actions/workflow/status/bsalanie/bs-python-utils/main.yml?branch=main)](https://github.com/bsalanie/bs-python-utils/actions/workflows/main.yml?query=branch%3Amain)
+<!--
 [![Tests](https://img.shields.io/github/actions/workflow/status/bsalanie/bs-python-utils/tests.yml?branch=main&label=tests)](https://github.com/bsalanie/bs-python-utils/actions/workflows/tests.yml?query=branch%3Amain)
+-->
 [![Commit activity](https://img.shields.io/github/commit-activity/m/bsalanie/bs-python-utils)](https://github.com/bsalanie/bs-python-utils/commits/main)
 ![GitHub last commit](https://img.shields.io/github/last-commit/bsalanie/bs-python-utils)
 [![License](https://img.shields.io/github/license/bsalanie/bs-python-utils)](https://img.shields.io/github/license/bsalanie/bs-python-utils)
@@ -45,6 +50,9 @@ Dynamic: license-file
 
 ### Release notes
 
+#### 1.0.1 (May 9, 2026)
+Fixed badges.
+
 #### 1.0 (May 9, 2026)
 Created subpackages (no change in the API).
 

{bs_python_utils-1.0 → bs_python_utils-1.1}/README.md

@@ -1,9 +1,13 @@
 ## bs-python-utils
 
 [![PyPI version](https://img.shields.io/pypi/v/bs-python-utils)](https://pypi.org/project/bs-python-utils/)
+<!--
 [![Release](https://img.shields.io/github/v/release/bsalanie/bs-python-utils)](https://github.com/bsalanie/bs-python-utils/releases)
+-->
 [![Build status](https://img.shields.io/github/actions/workflow/status/bsalanie/bs-python-utils/main.yml?branch=main)](https://github.com/bsalanie/bs-python-utils/actions/workflows/main.yml?query=branch%3Amain)
+<!--
 [![Tests](https://img.shields.io/github/actions/workflow/status/bsalanie/bs-python-utils/tests.yml?branch=main&label=tests)](https://github.com/bsalanie/bs-python-utils/actions/workflows/tests.yml?query=branch%3Amain)
+-->
 [![Commit activity](https://img.shields.io/github/commit-activity/m/bsalanie/bs-python-utils)](https://github.com/bsalanie/bs-python-utils/commits/main)
 ![GitHub last commit](https://img.shields.io/github/last-commit/bsalanie/bs-python-utils)
 [![License](https://img.shields.io/github/license/bsalanie/bs-python-utils)](https://img.shields.io/github/license/bsalanie/bs-python-utils)
@@ -15,6 +19,9 @@
 
 ### Release notes
 
+#### 1.0.1 (May 9, 2026)
+Fixed badges.
+
 #### 1.0 (May 9, 2026)
 Created subpackages (no change in the API).
 

bs_python_utils-1.1/bs_python_utils/core/Timer.py

@@ -0,0 +1,81 @@
+"""
+Utilities to time code:
+
+* a `Timer` class that can be used as a context manager
+* a `timeit` decorator for functions.
+"""
+
+import time
+from functools import wraps
+from typing import Any, Callable, Iterable
+
+
+def timeit(func: Callable) -> Callable:
+    """
+    Decorator to time a function
+    """
+
+    @wraps(func)
+    def wrapper(*args: Iterable, **kwargs: dict) -> Any:
+        start = time.perf_counter()
+        result = func(*args, **kwargs)
+        end = time.perf_counter()
+        print(f"{func.__name__} executed in {end - start:.3f} seconds")
+        return result
+
+    return wrapper
+
+
+class Timer:
+    """
+    A timer that can be started, stopped, and reset as needed by the user.
+    It keeps track of the total elapsed time in the `elapsed` attribute::
+
+    Examples:
+        >>> with Timer() as t:
+        >>>  ....
+        >>> print(f"... took {t.elapsed} seconds")
+
+    use `Timer(time.process_time)` to get only CPU time.
+
+    can also do:
+
+    Examples:
+        >>> t = Timer()
+        >>> t.start()
+        >>> t.stop()
+        >>> t.start()   # will add to the same counter
+        >>> t.stop()
+        >>> print(f"{t.elapsed} seconds total")
+    """
+
+    def __init__(self, func: Callable = time.perf_counter) -> None:
+        self.elapsed = 0.0
+        self._func = func
+        self._start = None
+
+    def start(self) -> None:
+        if self._start is not None:
+            raise RuntimeError("Already started")
+        self._start = self._func()
+
+    def stop(self) -> None:
+        if self._start is None:
+            raise RuntimeError("Not started")
+        end = self._func()
+        self.elapsed += end - self._start
+        self._start = None
+
+    def reset(self) -> None:
+        self.elapsed = 0.0
+
+    @property
+    def running(self) -> bool:
+        return self._start is not None
+
+    def __enter__(self) -> Any:
+        self.start()
+        return self
+
+    def __exit__(self, *args: Iterable) -> None:
+        self.stop()

bs_python_utils-1.1/bs_python_utils/core/__init__.py

@@ -0,0 +1 @@
+# core: general utilities — bsutils, Timer, bs_logging, bs_mathstr, bs_mem

bs_python_utils-1.1/bs_python_utils/core/bs_logging.py

@@ -0,0 +1,168 @@
+"""Utilities for logging:
+
+* `get_logger` creates and returns a logger with colored output
+* `init_logger` initializes and returns a customized logger
+* `log_execution` is a decorator to log entry into and ext from a function.
+"""
+
+import functools
+import logging
+import sys
+from pathlib import Path
+from typing import Callable
+
+from colorama import Fore, Style, init
+
+# Initialize colorama
+init(autoreset=True)
+
+COLOR_MAP = {
+    "DEBUG": Fore.CYAN,
+    "INFO": Fore.GREEN,
+    "WARNING": Fore.YELLOW,
+    "ERROR": Fore.RED,
+    "CRITICAL": Fore.MAGENTA,
+}
+
+
+class ColorFormatter(logging.Formatter):
+    def format(self, record):
+        # Mirror the standard Formatter logic so we still get message, asctime, and exception text
+        record.message = record.getMessage()
+        if self.usesTime():
+            record.asctime = self.formatTime(record, self.datefmt)
+
+        color = COLOR_MAP.get(record.levelname, "")
+        level = f"{color}{record.levelname}{Style.RESET_ALL}"
+        output = f"{record.asctime} [{record.name}] {level}: {record.message}"
+
+        if record.exc_info and not record.exc_text:
+            record.exc_text = self.formatException(record.exc_info)
+        if record.exc_text:
+            output = f"{output}\n{record.exc_text}"
+
+        return output
+
+
+def get_logger(
+    name: str,
+    level: int = logging.INFO,
+    log_to_file: bool = False,
+) -> logging.Logger:
+    """Create and return a logger with colored output.
+
+    Args:
+        name: Name of the logger.
+        level: Minimum logging level.
+        log_to_file: If True, also log to a file named '{name}.log'.
+
+    Returns:
+        Configured logger instance.
+
+    Examples:
+        >>> logger = get_logger("my_logger", level=logging.DEBUG, log_to_file=True)
+        >>> logger.debug("This is a debug message.")
+    """
+    logger = logging.getLogger(name)
+    if logger.handlers:
+        return logger  # Already configured
+    logger.setLevel(level)
+    formatter = ColorFormatter("%(asctime)s", datefmt="%H:%M:%S")
+    stream_handler = logging.StreamHandler(sys.stdout)
+    stream_handler.setFormatter(formatter)
+    logger.addHandler(stream_handler)
+    if log_to_file:
+        file_handler = logging.FileHandler(f"{name}.log")
+        file_handler.setFormatter(formatter)
+        logger.addHandler(file_handler)
+    return logger
+
+
+def init_logger(
+    logger_name: str,
+    log_level_for_console: str = "info",
+    log_level_for_file: str = "debug",
+    save_dir: str | None = None,
+) -> logging.Logger:
+    """
+    Initialize a logger
+
+    Args:
+        logger_name: name for the logger
+        log_level_for_console: minimum level of messages logged to the
+            console logging
+        log_level_for_file:
+        save_dir:
+
+    Returns:
+        the logger
+
+    Examples:
+        >>> logger_dir = "logs"
+        >>> logger_name = "check_log"
+        >>> logger = init_logger(logger_name, save_dir=logger_dir)
+
+        This will create two logs:
+
+        * one printed to console where we run the code (the
+          `StreamHandler`),
+        * and one that will be saved to file `save_dir/logger_name.txt`
+          (the `FileHandler`).
+
+        `'logger.propagate = False'` makes sure that the logs sent to file
+        will not be printed to console.
+
+        We use the `Formatter` class to define the format of the logs.
+        Here:
+
+        * The time of the log in a human-readable format, `asctime`
+        * `levelname` is the level of the log, one out of `INFO, DEBUG, WARNING, ERROR, CRITICAL`.
+        * The name of the file, `filename`, from which the log was generated,
+        and the line number, `lineno`.
+        * Lastly,  the message itself — `message`.
+
+        The default has only `INFO` logs and above (i.e., also
+        `WARNING, ERROR` and `CRITICAL`)
+        displayed in the console; the file will also include `DEBUG` logs.
+    """
+    logger = logging.getLogger()
+    logger.setLevel(level=logging.DEBUG)
+    logger.propagate = False
+
+    formatter = logging.Formatter(
+        "%(asctime)s [%(levelname)s] %(filename)s %(lineno)d - %(message)s",
+        "%Y-%m-%d %H:%M:%S",
+    )
+
+    ch = logging.StreamHandler()
+    ch.setLevel(log_level_for_console.upper())
+    ch.setFormatter(formatter)
+    logger.addHandler(ch)
+
+    if save_dir is not None:
+        Path(save_dir).mkdir(exist_ok=True, parents=True)
+        fh = logging.FileHandler(save_dir + f"/{logger_name}.txt")
+        fh.setLevel(log_level_for_file.upper())
+        fh.setFormatter(formatter)
+        logger.addHandler(fh)
+
+    return logger
+
+
+def log_execution(func: Callable) -> Callable:
+    """Decorator to log the execution of a function.
+    Only records entry to and exit from the function, to the console.
+    """
+    loglevel = logging.info
+
+    @functools.wraps(func)
+    def wrapper(*args, **kwargs):
+        loglevel(f"Executing {func.__name__}")
+        result = func(*args, **kwargs)
+        loglevel(f"Finished executing {func.__name__}")
+        return result
+
+    return wrapper
+
+    return wrapper
+    return wrapper

bs_python_utils-1.1/bs_python_utils/core/bs_mathstr.py

@@ -0,0 +1,121 @@
+"""Some useful strings for math formulae.
+
+Note:
+    if the math looks strange in the documentation, just reload the page.
+
+Attributes:
+    * str_beta0: the LaTeX string $\\beta_0$
+    * str_beta1: the LaTeX string $\\beta_1$
+    * str_pi: the LaTeX string $\\pi$
+    * str_sigma: the LaTeX string $\\sigma$
+    * str_sigma2: the LaTeX string $\\sigma^2$
+    * uni_beta0: the Unicode string $\\beta_0$
+    * uni_beta1: the Unicode string $\\beta_1$
+    * uni_pi: the Unicode string $\\pi$
+    * uni_sigma: the Unicode string $\\sigma$
+    * uni_sigma2: the Unicode string $\\sigma^2$
+    * uni_s2: the Unicode string $s^2$
+    * uni_R2: the Unicode string $R^2$
+    * sub_sub_scripts: a dictionary of unicodes for subscripts and superscripts;
+        e.g $a^b$ would be `"a" + sub_sup_scripts['b'][0]`
+"""
+
+#  LaTeX strings
+str_beta0 = r"$\beta_0$"
+str_beta1 = r"$\beta_1$"
+str_pi = r"$\pi$"
+str_sigma = r"$\sigma$"
+str_sigma2 = r"$\sigma^2$"
+
+# * unicode
+uni_beta0 = "\N{GREEK SMALL LETTER BETA}\N{SUBSCRIPT ZERO}"
+uni_beta1 = "\N{GREEK SMALL LETTER BETA}\N{SUBSCRIPT ONE}"
+uni_pi = "\N{GREEK SMALL LETTER PI}"
+uni_sigma = "\N{GREEK SMALL LETTER SIGMA}"
+uni_sigma2 = "\N{GREEK SMALL LETTER SIGMA}\N{SUPERSCRIPT TWO}"
+uni_s2 = "s\N{SUPERSCRIPT TWO}"
+uni_R2 = "R\N{SUPERSCRIPT TWO}"
+
+
+sub_sup_scripts = {
+    #           superscript     subscript
+    "0": ("\u2070", "\u2080"),
+    "1": ("\u00b9", "\u2081"),
+    "2": ("\u00b2", "\u2082"),
+    "3": ("\u00b3", "\u2083"),
+    "4": ("\u2074", "\u2084"),
+    "5": ("\u2075", "\u2085"),
+    "6": ("\u2076", "\u2086"),
+    "7": ("\u2077", "\u2087"),
+    "8": ("\u2078", "\u2088"),
+    "9": ("\u2079", "\u2089"),
+    "a": ("\u1d43", "\u2090"),
+    "b": ("\u1d47", "?"),
+    "c": ("\u1d9c", "?"),
+    "d": ("\u1d48", "?"),
+    "e": ("\u1d49", "\u2091"),
+    "f": ("\u1da0", "?"),
+    "g": ("\u1d4d", "?"),
+    "h": ("\u02b0", "\u2095"),
+    "i": ("\u2071", "\u1d62"),
+    "j": ("\u02b2", "\u2c7c"),
+    "k": ("\u1d4f", "\u2096"),
+    "l": ("\u02e1", "\u2097"),
+    "m": ("\u1d50", "\u2098"),
+    "n": ("\u207f", "\u2099"),
+    "o": ("\u1d52", "\u2092"),
+    "p": ("\u1d56", "\u209a"),
+    "q": ("?", "?"),
+    "r": ("\u02b3", "\u1d63"),
+    "s": ("\u02e2", "\u209b"),
+    "t": ("\u1d57", "\u209c"),
+    "u": ("\u1d58", "\u1d64"),
+    "v": ("\u1d5b", "\u1d65"),
+    "w": ("\u02b7", "?"),
+    "x": ("\u02e3", "\u2093"),
+    "y": ("\u02b8", "?"),
+    "z": ("?", "?"),
+    "A": ("\u1d2c", "?"),
+    "B": ("\u1d2e", "?"),
+    "C": ("?", "?"),
+    "D": ("\u1d30", "?"),
+    "E": ("\u1d31", "?"),
+    "F": ("?", "?"),
+    "G": ("\u1d33", "?"),
+    "H": ("\u1d34", "?"),
+    "I": ("\u1d35", "?"),
+    "J": ("\u1d36", "?"),
+    "K": ("\u1d37", "?"),
+    "L": ("\u1d38", "?"),
+    "M": ("\u1d39", "?"),
+    "N": ("\u1d3a", "?"),
+    "O": ("\u1d3c", "?"),
+    "P": ("\u1d3e", "?"),
+    "Q": ("?", "?"),
+    "R": ("\u1d3f", "?"),
+    "S": ("?", "?"),
+    "T": ("\u1d40", "?"),
+    "U": ("\u1d41", "?"),
+    "V": ("\u2c7d", "?"),
+    "W": ("\u1d42", "?"),
+    "X": ("?", "?"),
+    "Y": ("?", "?"),
+    "Z": ("?", "?"),
+    "+": ("\u207a", "\u208a"),
+    "-": ("\u207b", "\u208b"),
+    "=": ("\u207c", "\u208c"),
+    "(": ("\u207d", "\u208d"),
+    ")": ("\u207e", "\u208e"),
+    ":alpha": ("\u1d45", "?"),
+    ":beta": ("\u1d5d", "\u1d66"),
+    ":gamma": ("\u1d5e", "\u1d67"),
+    ":delta": ("\u1d5f", "?"),
+    ":epsilon": ("\u1d4b", "?"),
+    ":theta": ("\u1dbf", "?"),
+    ":iota": ("\u1da5", "?"),
+    ":pho": ("?", "\u1d68"),
+    ":phi": ("\u1db2", "?"),
+    ":psi": ("\u1d60", "\u1d69"),
+    ":chi": ("\u1d61", "\u1d6a"),
+    ":coffee": ("\u2615", "\u2615"),
+}

bs_python_utils-1.1/bs_python_utils/core/bs_mem.py

@@ -0,0 +1,157 @@
+"""Reports on memory usage:
+
+* `mem_usage`: prints the top `n` largest global items in memory
+* `memory_display_top`: prints the top `n` largest memory allocations
+  since tracing started
+* `memory_display_top_diffs`: prints the top `n` largest memory
+  allocations since the last snapshot.
+"""
+
+import linecache
+import sys
+import tracemalloc
+
+import pandas as pd
+
+from bs_python_utils.core.bsutils import print_stars
+
+
+def _obj_size_fmt(num: int) -> str:
+    """
+    format sizes from bytes to appropriate strings depending on size
+
+    Args:
+        num: size of object in bytes
+
+    Returns:
+        its formatted size
+    """
+    if num < 10**3:
+        return "{:.2f}{}".format(num, "B")
+    elif (num >= 10**3) & (num < 10**6):
+        return "{:.2f}{}".format(num / (1.024 * 10**3), "KB")
+    elif (num >= 10**6) & (num < 10**9):
+        return "{:.2f}{}".format(num / (1.024 * 10**6), "MB")
+    else:
+        return "{:.2f}{}".format(num / (1.024 * 10**9), "GB")
+
+
+def memory_usage(n: int | None = 10) -> None:
+    """
+    prints the top `n` largest global items in memory
+
+    Args:
+        n: we report the size of the largest `n` global items
+
+    Returns:
+        nothing.
+    """
+    memory_usage_by_variable = pd.DataFrame(
+        {k: sys.getsizeof(v) for (k, v) in globals().items()}, index=["Size"]
+    )
+    memory_usage_by_variable = memory_usage_by_variable.T
+    total_usage = _obj_size_fmt(memory_usage_by_variable["Size"].sum())
+    memory_usage_by_variable = memory_usage_by_variable.sort_values(
+        by="Size", ascending=False
+    ).head(n)
+    memory_usage_by_variable["Size"] = memory_usage_by_variable["Size"].apply(
+        lambda x: _obj_size_fmt(x)
+    )
+    print_stars(
+        f"Currently used memory = {total_usage}\n\t\t\t\t Top {n} global objects:"
+    )
+    print(memory_usage_by_variable)
+
+    return
+
+
+def memory_display_top(
+    snapshot: tracemalloc.Snapshot, key_type: str = "lineno", limit: int | None = 5
+) -> None:
+    """
+    prints out the lines with the top `limit` allocations of memory since
+    `tracemalloc.start()`
+
+    Args:
+        snapshot: obtained from tracemalloc.take_snapshot()
+        key_type: 'lineno' gives file and line number; 'traceback' gives all
+        limit: how many top allocations we want
+
+    Returns:
+        just prints.
+
+    Examples:
+       >>> tracemalloc.start()
+       >>> .... execute ...
+       >>> snapshot = tracemalloc.take_snapshot()
+       >>> memory_display_top(snapshot)
+    """
+
+    top_stats = snapshot.statistics(key_type)
+
+    print_stars(f"Top {limit} memory allocations")
+    for index, stat in enumerate(top_stats[:limit], 1):
+        frame = stat.traceback[0]
+        print(
+            "#%s: %s:%s: %.1f KiB"
+            % (index, frame.filename, frame.lineno, stat.size / 1024)
+        )
+        line = linecache.getline(frame.filename, frame.lineno).strip()
+        if line:
+            print("    %s" % line)
+
+    other = top_stats[limit:]
+    if other:
+        size = sum(stat.size for stat in other)
+        print(f"{len(other)} other: {size / 1024:.1f} KiB")
+    total = sum(stat.size for stat in top_stats)
+    print("Total allocated size: %.1f KiB" % (total / 1024))
+
+
+def memory_display_top_diffs(
+    snapshot1: tracemalloc.Snapshot,
+    snapshot2: tracemalloc.Snapshot,
+    key_type: str = "lineno",
+    limit: int = 5,
+) -> None:
+    """
+    prints out the lines with the top `limit` allocations between the two snapshots
+
+    Args:
+        snapshot1: previous snapshot
+        snapshot2: new snapshot
+        key_type: 'lineno' gives file and line number; 'traceback' gives all
+        limit: how many top allocations we want
+
+    Returns:
+        just prints.
+
+    Examples:
+       >>> tracemalloc.start()
+       >>> .... execute ...
+       >>> snapshot1 = tracemalloc.take_snapshot()
+       >>> .... execute ...
+       >>> snapshot2 = tracemalloc.take_snapshot()
+       >>>  memory_display_top_diffs(snapshot1, snapshot2)
+
+    """
+
+    top_stats = snapshot2.compare_to(snapshot1, key_type)
+
+    print_stars(f"Top {limit} new memory allocations")
+    for index, stat in enumerate(top_stats[:limit], 1):
+        frame = stat.traceback[0]
+        print(
+            "#%s: %s:%s: %.1f KiB"
+            % (index, frame.filename, frame.lineno, stat.size / 1024)
+        )
+        line = linecache.getline(frame.filename, frame.lineno).strip()
+        if line:
+            print("    %s" % line)
+
+    other = top_stats[limit:]
+    if other:
+        size = sum(stat.size for stat in other)
+        print(f"{len(other)} other: {size / 1024:.1f} KiB")
+    total = sum(stat.size for stat in top_stats)
+    print("Total allocated size: %.1f KiB" % (total / 1024))