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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bs-python-utils
-Version: 1.1
+Version: 1.1.3
 Summary: Utilities programs for my Python code
 Requires-Python: >=3.13
 Description-Content-Type: text/markdown
@@ -50,6 +50,13 @@ Dynamic: license-file
 
 ### Release notes
 
+#### 1.1.2 and 1.1.3(September 11, 2026)
+- Improved the `Timer` class.
+- added `bs_derivs` with Richardson derivatives.
+
+#### 1.1.1 (September 04, 2026)
+Added simulation-based bivariate ranks.
+
 #### 1.0.1 (May 9, 2026)
 Fixed badges.
 

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

@@ -19,6 +19,13 @@
 
 ### Release notes
 
+#### 1.1.2 and 1.1.3(September 11, 2026)
+- Improved the `Timer` class.
+- added `bs_derivs` with Richardson derivatives.
+
+#### 1.1.1 (September 04, 2026)
+Added simulation-based bivariate ranks.
+
 #### 1.0.1 (May 9, 2026)
 Fixed badges.
 

{bs_python_utils-1.1 → bs_python_utils-1.1.3}/bs_python_utils/__init__.py

@@ -6,7 +6,8 @@ programming.
 * `bs_logging` has customized logging
 * `bs_mathstr` has Unicode for math strings
 * `bs_mem` reports memory usage
-* `Timer` has a `Timer` class to time code execution.
+* `Timer` has a `Timer` context manager to time code execution.
+* `bs_derivs` has Richardson derivatives
 * `bsnputils` has Numpy functions
 * `bssputils` has Scipy functions
 * `sklearn_utils` has Sklearn functions

bs_python_utils-1.1.3/bs_python_utils/bs_derivs.py

@@ -0,0 +1 @@
+from bs_python_utils.numerical.bs_derivs import *  # noqa: F401, F403

bs_python_utils-1.1.3/bs_python_utils/core/Timer.py

@@ -0,0 +1,176 @@
+"""
+Utilities to time code:
+
+* a `Timer` class that can be used as a context manager
+* a `timeit` decorator for functions.
+"""
+
+import time
+from collections.abc import Callable, Iterable
+from dataclasses import dataclass, field
+from functools import wraps
+from typing import Any, ClassVar, Self
+
+
+def timeit(func: Callable) -> Callable:
+    """Decorator to measure and print execution time of a function.
+
+    Wraps a function to measure its execution time using perf_counter()
+    for high precision, and prints the elapsed time to stdout.
+
+    Args:
+        func: The function to be timed.
+
+    Returns:
+        A wrapped function that prints the execution time when called.
+
+    Example:
+        >>> @timeit
+        ... def slow_function():
+        ...     time.sleep(0.1)  # doctest: +SKIP
+        >>> slow_function()  # doctest: +SKIP
+        slow_function executed in 0.100 seconds
+    """
+
+    @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 TimerError(Exception):
+    """A custom exception used to report errors in use of Timer class"""
+
+
+@dataclass
+class Timer:
+    """A flexible timer class for measuring execution time.
+
+    This class can be used in three ways:
+
+    1. **As a context manager**: automatically starts and stops timing
+    2. **With manual calls**: call start() and stop() explicitly
+    3. **As a named timer**: accumulate timing across multiple calls using the `name` attribute
+
+    Attributes:
+        name: Optional name for the timer. If provided, cumulative elapsed time is stored
+            in the class-level `timers` dict. Use None for one-off timings.
+        text: Format string for displaying elapsed time. Defaults to "Elapsed time: {:0.4f} seconds".
+            The string is formatted with a single float representing elapsed seconds.
+        logger: Callable to handle output. Defaults to print(). Set to None to suppress output.
+        timers: Class-level dictionary storing cumulative times for all named timers.
+
+    Raises:
+        TimerError: If stop() is called without start(), or start() is called on a running timer.
+
+    Example:
+        >>> # As a context manager (recommended for simple use cases)
+        >>> with Timer():
+        ...     time.sleep(0.1)  # doctest: +SKIP
+        Elapsed time: 0.1000 seconds
+
+        >>> # With a custom message
+        >>> with Timer(text="My code took {:0.2f}s"):
+        ...     time.sleep(0.05)  # doctest: +SKIP
+        My code took 0.05s
+
+        >>> # Suppress output
+        >>> with Timer(logger=None):
+        ...     time.sleep(0.1)  # doctest: +SKIP
+
+        >>> # Suppress output and capture elapsed time
+        >>> with Timer(logger=None) as t:
+        ...     time.sleep(0.1)  # doctest: +SKIP
+        >>> elapsed = t.stop()
+
+        >>> # Manual start/stop
+        >>> timer = Timer()
+        >>> timer.start()  # doctest: +SKIP
+        >>> time.sleep(0.1)  # doctest: +SKIP
+        >>> elapsed = timer.stop()  # doctest: +SKIP
+        Elapsed time: 0.1000 seconds
+
+        >>> # Named timer for cumulative timing
+        >>> Timer(name="db_queries").start()  # doctest: +SKIP
+        >>> time.sleep(0.05)  # doctest: +SKIP
+        >>> Timer(name="db_queries").stop()  # doctest: +SKIP
+        Elapsed time: 0.0500 seconds
+        >>> Timer.timers  # doctest: +SKIP
+        {'db_queries': 0.05}
+    """
+
+    timers: ClassVar = {}
+    name: Any = None
+    text: Any = "Elapsed time: {:0.4f} seconds"
+    logger: Any = print
+    _start_time: Any = field(default=None, init=False, repr=False)
+
+    def __post_init__(self):
+        """Initialize the timer and register it if named.
+
+        For named timers, creates an entry in the class-level `timers` dict
+        to accumulate elapsed time across multiple start/stop cycles.
+        """
+        if self.name is not None:
+            self.timers.setdefault(self.name, 0)
+
+    def start(self):
+        """Start the timer.
+
+        Records the current time using perf_counter() for high precision.
+
+        Raises:
+            TimerError: If the timer is already running.
+        """
+        if self._start_time is not None:
+            raise TimerError("Timer is running. Use .stop() to stop it")
+
+        self._start_time = time.perf_counter()
+
+    def stop(self) -> float:
+        """Stop the timer and report elapsed time.
+
+        Calculates elapsed time since start() was called, sends output to the logger
+        if configured, and accumulates the time if this is a named timer.
+
+        Returns:
+            Elapsed time in seconds as a float.
+
+        Raises:
+            TimerError: If the timer is not running.
+        """
+        if self._start_time is None:
+            raise TimerError("Timer is not running. Use .start() to start it")
+
+        # Calculate elapsed time
+        elapsed_time: float = time.perf_counter() - self._start_time
+        self._start_time = None
+
+        # Report elapsed time
+        if self.logger:
+            self.logger(self.text.format(elapsed_time))
+        if self.name:
+            self.timers[self.name] += elapsed_time
+
+        return elapsed_time
+
+    def __enter__(self) -> Self:
+        """Enter context manager: start the timer.
+
+        Returns:
+            self: The Timer instance.
+        """
+        self.start()
+        return self
+
+    def __exit__(self, *exc_info):
+        """Exit context manager: stop the timer.
+
+        Stops the timer regardless of whether an exception occurred in the with block.
+        """
+        self.stop()

bs_python_utils-1.1.3/bs_python_utils/numerical/bs_derivs.py

@@ -0,0 +1,49 @@
+from collections.abc import Callable
+
+
+def richardson_derivative(
+    f: Callable[[float, list], float], x: float, args: list, h: float
+) -> float:
+    """Compute the first derivative of $f(x, args)$ at $x$ via Richardson extrapolation.
+
+    Uses a 5-point central-difference stencil (step `h` and `2h`) that is
+    fourth-order accurate.
+
+    Args:
+        f: The function to differentiate, called as `f(x, args)`.
+        x: The point at which to differentiate.
+        args: Other arguments passed through to `f`.
+        h: The step size.
+
+    Returns:
+        An approximation of the first derivative of `f` at `x`.
+    """
+    f1 = f(x + h, args)
+    f2 = f(x - h, args)
+    f3 = f(x + 2.0 * h, args)
+    f4 = f(x - 2.0 * h, args)
+    return (8.0 * (f1 - f2) - (f3 - f4)) / (12.0 * h)
+
+
+def richardson_second_derivative(
+    f: Callable[[float, list], float], x: float, args: list, h: float
+) -> float:
+    """Compute the second derivative of $f(x, args)$ at $x$ via Richardson extrapolation.
+
+    Applies `richardson_derivative` to the (Richardson-extrapolated) first
+    derivative of `f`.
+
+    Args:
+        f: The function to differentiate, called as `f(x, args)`.
+        x: The point at which to differentiate.
+        args: Other arguments passed through to `f`.
+        h: The step size.
+
+    Returns:
+        An approximation of the second derivative of `f` at `x`.
+    """
+
+    def fprime(y, a):
+        return richardson_derivative(f, y, a, h)
+
+    return richardson_derivative(fprime, x, args, h)

{bs_python_utils-1.1 → bs_python_utils-1.1.3}/bs_python_utils/numerical/bsnputils.py

@@ -300,9 +300,7 @@ def npmaxabs(arr: np.ndarray) -> float:
     return cast(float, np.max(np.abs(arr)))
 
 
-def rice_stderr(
-    y: np.ndarray, x: np.ndarray, is_sorted: bool = False
-) -> np.ndarray | float:
+def rice_stderr(y: np.ndarray, x: np.ndarray, is_sorted: bool = False) -> np.ndarray:
     """
     computes the Rice local estimators of the standard error of y | x
 

{bs_python_utils-1.1 → bs_python_utils-1.1.3}/bs_python_utils/opt/bs_opt.py

@@ -420,8 +420,8 @@ def minimize_some_fixed(
             obj,
             x_init,
             method="L-BFGS-B",
-            args=args,
-            options=options,
+            args=(args,),
+            options=cast(Any, options),
             jac=grad_obj,
             bounds=bounds,
         )
@@ -453,8 +453,8 @@ def minimize_some_fixed(
             fixed_obj,
             t_init,
             method="L-BFGS-B",
-            args=args,
-            options=options,
+            args=(args,),
+            options=cast(Any, options),
             jac=fixed_grad_obj,
             bounds=t_bounds,
         )
@@ -508,8 +508,8 @@ def minimize_free(
             obj,
             x_init,
             method="BFGS",
-            args=args,
-            options=options,
+            args=(args,),
+            options=cast(Any, options),
             jac=grad_obj,
         )
     else:
@@ -517,8 +517,8 @@ def minimize_free(
             obj,
             x_init,
             method="L-BFGS-B",
-            args=args,
-            options=options,
+            args=(args,),
+            options=cast(Any, options),
             jac=grad_obj,
             bounds=bounds,
         )

{bs_python_utils-1.1 → bs_python_utils-1.1.3}/bs_python_utils/stats/bivariate_quantiles.py

@@ -66,25 +66,25 @@ def bivariate_ranks_simul(
         probs = np.exp(psi_vals / h - lse_vals.reshape((-1, 1)))
         mean_probs = np.mean(probs, axis=0)
         if ret == 0:
-            return obj_val
+            return cast(float, obj_val)
         elif ret == 1:
             grad = -mean_probs[:-1] + mean_probs[-1]
-            return grad
+            return cast(np.ndarray, grad)
         elif ret == 2:
             ranks = (probs.T @ tau_draws / n_draws) / mean_probs.reshape((-1, 1))
-            return ranks
+            return cast(np.ndarray, ranks)
         else:
             bs_error_abort("Invalid value for ret. Must be 0, 1, or 2.")
             return None
 
     def objv(v: np.ndarray, args: list) -> float:
-        return objv_and_grad(v, ret=0)
+        return cast(float, objv_and_grad(v, ret=0))
 
     def grad_objv(v: np.ndarray, args: list) -> np.ndarray:
-        return objv_and_grad(v, ret=1)
+        return cast(np.ndarray, objv_and_grad(v, ret=1))
 
     def ranks(v: np.ndarray, args: list) -> np.ndarray:
-        return objv_and_grad(v, ret=2)
+        return cast(np.ndarray, objv_and_grad(v, ret=2))
 
     resv = minimize_free(objv, grad_objv, v_init, args=[])
     if not resv.success:
@@ -319,6 +319,7 @@ def bivariate_ranks(
         bs_error_abort(f"only works for 2-dimensional y, not for {d}")
 
     _, bivranks = _solve_for_v(y, n_nodes, verbose)
+    return bivranks
 
 
 def bivariate_quantiles(

{bs_python_utils-1.1 → bs_python_utils-1.1.3}/bs_python_utils/stats/bsstats.py

@@ -342,6 +342,7 @@ def bs_multivariate_normal_pdf(
             bs_error_abort(
                 f"cov_mat should be a matrix ({nvars}, {nvars}) not ({nrows}, {ncols})"
             )
+        cov_mat = cast(np.ndarray, cov_mat)
         resid = values_x - means_x
         argresid = spla.solve(cov_mat, resid.T)
         argexp = np.zeros(n)

{bs_python_utils-1.1 → bs_python_utils-1.1.3}/bs_python_utils.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bs-python-utils
-Version: 1.1
+Version: 1.1.3
 Summary: Utilities programs for my Python code
 Requires-Python: >=3.13
 Description-Content-Type: text/markdown
@@ -50,6 +50,13 @@ Dynamic: license-file
 
 ### Release notes
 
+#### 1.1.2 and 1.1.3(September 11, 2026)
+- Improved the `Timer` class.
+- added `bs_derivs` with Richardson derivatives.
+
+#### 1.1.1 (September 04, 2026)
+Added simulation-based bivariate ranks.
+
 #### 1.0.1 (May 9, 2026)
 Fixed badges.
 

{bs_python_utils-1.1 → bs_python_utils-1.1.3}/bs_python_utils.egg-info/SOURCES.txt

@@ -5,6 +5,7 @@ bs_python_utils/Timer.py
 bs_python_utils/__init__.py
 bs_python_utils/bivariate_quantiles.py
 bs_python_utils/bs_altair.py
+bs_python_utils/bs_derivs.py
 bs_python_utils/bs_logging.py
 bs_python_utils/bs_mathstr.py
 bs_python_utils/bs_mem.py
@@ -60,6 +61,7 @@ bs_python_utils/examples/examples_seaborn.py
 bs_python_utils/examples/examples_sklearn.py
 bs_python_utils/examples/examples_sparse_gaussian.py
 bs_python_utils/numerical/__init__.py
+bs_python_utils/numerical/bs_derivs.py
 bs_python_utils/numerical/bs_sparse_gaussian.py
 bs_python_utils/numerical/bsnputils.py
 bs_python_utils/numerical/bssputils.py
@@ -77,6 +79,7 @@ bs_python_utils/viz/bs_seaborn.py
 bs_python_utils/viz/bsmplutils.py
 bs_python_utils/viz/streamlit_utils.py
 tests/test_bivariate_quantiles.py
+tests/test_bs_derivs.py
 tests/test_bs_opt.py
 tests/test_bs_sparse_gaussian.py
 tests/test_bsnputils.py
@@ -86,4 +89,5 @@ tests/test_bsutils.py
 tests/test_chebyshev.py
 tests/test_nptri.py
 tests/test_random_draws.py
-tests/test_sklearn_utils.py
+tests/test_sklearn_utils.py
+tests/test_timer.py

{bs_python_utils-1.1 → bs_python_utils-1.1.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "bs-python-utils"
-version = "1.1"
+version = "1.1.3"
 description = "Utilities programs for my Python code"
 readme = "README.md"
 requires-python = ">=3.13"