bs-python-utils 1.1.1__py3-none-any.whl → 1.1.3__py3-none-any.whl

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/bs_derivs.py

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

bs_python_utils/core/Timer.py

@@ -6,13 +6,30 @@ Utilities to time code:
 """
 
 import time
+from collections.abc import Callable, Iterable
+from dataclasses import dataclass, field
 from functools import wraps
-from typing import Any, Callable, Iterable
+from typing import Any, ClassVar, Self
 
 
 def timeit(func: Callable) -> Callable:
-    """
-    Decorator to time a function
+    """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)
@@ -26,56 +43,134 @@ def timeit(func: Callable) -> Callable:
     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}
     """
-    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")
+    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)
 
-    use `Timer(time.process_time)` to get only CPU time.
+    def __post_init__(self):
+        """Initialize the timer and register it if named.
 
-    can also do:
+        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)
 
-    Examples:
-        >>> t = Timer()
-        >>> t.start()
-        >>> t.stop()
-        >>> t.start()   # will add to the same counter
-        >>> t.stop()
-        >>> print(f"{t.elapsed} seconds total")
-    """
+    def start(self):
+        """Start the timer.
 
-    def __init__(self, func: Callable = time.perf_counter) -> None:
-        self.elapsed = 0.0
-        self._func = func
-        self._start = None
+        Records the current time using perf_counter() for high precision.
 
-    def start(self) -> None:
-        if self._start is not None:
-            raise RuntimeError("Already started")
-        self._start = self._func()
+        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")
 
-    def stop(self) -> None:
-        if self._start is None:
-            raise RuntimeError("Not started")
-        end = self._func()
-        self.elapsed += end - self._start
-        self._start = None
+        self._start_time = time.perf_counter()
 
-    def reset(self) -> None:
-        self.elapsed = 0.0
+    def stop(self) -> float:
+        """Stop the timer and report elapsed time.
 
-    @property
-    def running(self) -> bool:
-        return self._start is not None
+        Calculates elapsed time since start() was called, sends output to the logger
+        if configured, and accumulates the time if this is a named timer.
 
-    def __enter__(self) -> Any:
+        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, *args: Iterable) -> None:
+    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/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.1.dist-info → bs_python_utils-1.1.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bs-python-utils
-Version: 1.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,10 @@ 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.
 

{bs_python_utils-1.1.1.dist-info → bs_python_utils-1.1.3.dist-info}/RECORD

@@ -1,7 +1,8 @@
 bs_python_utils/Timer.py,sha256=ozGneYNy-P9hKG71Q_Uu0aZfbGSilpUNVXIPglCNqhw,61
-bs_python_utils/__init__.py,sha256=XJ62LhKlvBaZH5ItthEpR7W6Sb9FEKi1d-6TZhP8DLc,1353
+bs_python_utils/__init__.py,sha256=1ozvLCSGvCGRIEgqdBD6ejQdk_JPs_ainW3k_mssVE0,1404
 bs_python_utils/bivariate_quantiles.py,sha256=juI48flnsTs8TJYLRi5DwGIfQv-q5ZxN3TXyvtUeDRI,76
 bs_python_utils/bs_altair.py,sha256=jt5z4QDYVzg4lt5QlX8CZDbpOJrn4YDFpQavZNrKXC8,64
+bs_python_utils/bs_derivs.py,sha256=q3sZpeiCJMZ0jPZrpnk2pfOKGJ799hCpnw3mUSdgo7o,70
 bs_python_utils/bs_logging.py,sha256=RrC9LLK6ih0P043SxgltxLvRFDKcNMD-UBKHPCK9pMk,66
 bs_python_utils/bs_mathstr.py,sha256=WoqjCDYQw0ifVLR3BfxrnN0UMMyConADeVeMAtUHNkI,66
 bs_python_utils/bs_mem.py,sha256=iZAFquRisPQoSt0UsIQsECrDuL2TIYpOk6Fsn45jk2Y,62
@@ -34,7 +35,7 @@ bs_python_utils/GaussHermiteSparseGrids/GHsparseGrid4prec9.txt,sha256=pK_J0YgoWC
 bs_python_utils/GaussHermiteSparseGrids/GHsparseGrid5prec13.txt,sha256=M-Zq5ZMvjIRYPbbepZ-aDgcoiZeLjtSLuhBDjrRBod4,849182
 bs_python_utils/GaussHermiteSparseGrids/GHsparseGrid5prec17.txt,sha256=7cRuNAccbj66EJgLUyJ63CnBcVbIuNaL5HStdu05o4w,4341422
 bs_python_utils/GaussHermiteSparseGrids/GHsparseGrid5prec9.txt,sha256=GmfUSKpvepIuy66zHgz-cB0Et-2DRR1f195zkg6a-HA,118330
-bs_python_utils/core/Timer.py,sha256=Rwj0Gec6VUq9Y6Rmykc5wL3Xd9dIj7Un_QgbJc2cTxo,1966
+bs_python_utils/core/Timer.py,sha256=rTJ9R-0sgnc2IkPwBItyTxFTjc0AXAJiYneGUaduPvg,5708
 bs_python_utils/core/__init__.py,sha256=4NJk4JmeQXwVre55ttL0Zo3x3qCkPYaUESiR8n4_ZEA,77
 bs_python_utils/core/bs_logging.py,sha256=CGi_pLeBSVd7FXsoafCI9xDu9eXLMnJebgY8Ku3-qP8,5050
 bs_python_utils/core/bs_mathstr.py,sha256=zW2ECxDD-29H81s_PNE1UKbIXJZtuhReJwcYim_4YTg,3595
@@ -52,6 +53,7 @@ bs_python_utils/examples/examples_seaborn.py,sha256=HsFWYhXVZAkqCabTGihpUEi95QjE
 bs_python_utils/examples/examples_sklearn.py,sha256=nzvMREqNFf2oq32aEQLm1Bz8DbdcTvHfhJNKy2NlI38,802
 bs_python_utils/examples/examples_sparse_gaussian.py,sha256=hVnN_p7Dfj3CQWp51bZlwQeqvhJ6VaFMyFeQ48j-pqo,922
 bs_python_utils/numerical/__init__.py,sha256=T1I8g5rx19p8zLxo3_jr7fHf3LqTxPVwFMRF2HUR808,75
+bs_python_utils/numerical/bs_derivs.py,sha256=m-LQJxzlWOaBpXhAu3rUGKGdQY3yizXKeKBkZGwwjiE,1515
 bs_python_utils/numerical/bs_sparse_gaussian.py,sha256=DzfBEQmaTY2XjxqMx3suzQ4FalD-OhoyQhZ2g2t3ztg,2241
 bs_python_utils/numerical/bsnputils.py,sha256=px5EL0M5YAY6oexzZpaJq9uH085ADRwa178E8zVReEA,38581
 bs_python_utils/numerical/bssputils.py,sha256=JnmN-9ZMRQDNc0W_XIC-on4lKnzDhkp2YAOZNMcH404,2475
@@ -68,8 +70,8 @@ bs_python_utils/viz/bs_plots.py,sha256=-yBJ-8y4Ni8LqqQi5ceMjqOcpvLWYngkY1_FKqWTM
 bs_python_utils/viz/bs_seaborn.py,sha256=wzlsByJivHLBOi_p9RLLRaXD6WhJbAfmuQPKQDheMss,5684
 bs_python_utils/viz/bsmplutils.py,sha256=g61VrRlHW4jDSvvyfTZF_XYtrGTIV3F4FP9umIc6oOI,2900
 bs_python_utils/viz/streamlit_utils.py,sha256=eoelTwicHPcWxC6KbGFBnofwEomGjxIcMnnp3rSsqYU,2703
-bs_python_utils-1.1.1.dist-info/licenses/LICENSE,sha256=J03S1L_wQN4qquuluScbRUE09on78nCnNRpaUpOvHcw,1073
-bs_python_utils-1.1.1.dist-info/METADATA,sha256=Ipm7rjFDvVID5fRghn5yiioRUF4o-sgGKE9GxEBFewE,4446
-bs_python_utils-1.1.1.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
-bs_python_utils-1.1.1.dist-info/top_level.txt,sha256=4sbCpeuqAsdWmoAmZju1vf1ZFMJrSx310eS5SCyrAeQ,16
-bs_python_utils-1.1.1.dist-info/RECORD,,
+bs_python_utils-1.1.3.dist-info/licenses/LICENSE,sha256=J03S1L_wQN4qquuluScbRUE09on78nCnNRpaUpOvHcw,1073
+bs_python_utils-1.1.3.dist-info/METADATA,sha256=mf9EQxTeoHDLiclWTCxU6fhVKnImO0tN34w9LOygmC4,4567
+bs_python_utils-1.1.3.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+bs_python_utils-1.1.3.dist-info/top_level.txt,sha256=4sbCpeuqAsdWmoAmZju1vf1ZFMJrSx310eS5SCyrAeQ,16
+bs_python_utils-1.1.3.dist-info/RECORD,,