timer-sentinel 1.0.1__py3-none-any.whl

timer_sentinel/core.py

@@ -0,0 +1,215 @@
+import inspect
+import time
+from collections.abc import Callable
+from functools import wraps
+from logging import WARNING, Logger, getLogger
+from typing import Any
+from uuid import uuid4
+
+DEFAULT_TIMER_NAME = "TimerSentinel"
+default_logger = getLogger("TimerSentinel")
+
+
+class TimerSentinel:
+    """Monitor execution time and log when threshold is exceeded.
+
+    Can be used as a context manager, decorator, or called manually.
+    Supports both sync and async functions.
+
+    Examples:
+        # As context manager
+        with TimerSentinel(threshold=1.0, name="task"):
+            do_work()
+
+        # As decorator (sync)
+        @TimerSentinel(threshold=1.0, name="task")
+        def do_work():
+            pass
+
+        # As decorator (async)
+        @TimerSentinel(threshold=1.0, name="task")
+        async def do_work():
+            await async_task()
+
+        # Manual usage
+        timer = TimerSentinel(threshold=1.0, name="task")
+        timer.start()
+        do_work()
+        timer.end()
+        timer.report()
+    """
+
+    __slots__ = (
+        "threshold",
+        "name",
+        "_logger",
+        "_on_exceed_keyword",
+        "_on_exceed_level",
+        "_on_exceed_callback",
+        "_callback_args",
+        "_execution_id",
+        "_timer",
+        "_total_time",
+        "_use_func_name",
+    )
+
+    def __init__(
+        self,
+        threshold: float,
+        name: str | None = None,
+        logger: Logger | None = None,
+        on_exceed_keyword: str = "OVERTIME",
+        on_exceed_level: int = WARNING,
+        on_exceed_callback: Callable[[], None] | None = None,
+        callback_args: dict[str, Any] | None = None,
+    ) -> None:
+        """Initialize the timer sentinel.
+
+        Args:
+            threshold: Maximum allowed execution time in seconds.
+            name: Name identifier for the timer. Empty string by default.
+                If empty or used as decorator, will use "TimerSentinel"
+                or the function name respectively.
+            logger: Logger instance to use. If None, uses default
+                TimerSentinel logger.
+            on_exceed_keyword: Keyword to include in log message when
+                threshold exceeded. Default is "OVERTIME".
+            on_exceed_level: Logging level (integer) to use when threshold
+                exceeded. Default is WARNING (30).
+            on_exceed_callback: Optional callback function to execute when
+                threshold exceeded. Must be callable without arguments.
+            callback_args: Optional keyword arguments to pass to the
+                callback function when invoked.
+        """
+        self.threshold = threshold
+        self._use_func_name = not name
+        self.name = name or DEFAULT_TIMER_NAME
+        self._logger = logger or default_logger
+        self._on_exceed_keyword = on_exceed_keyword
+        self._on_exceed_level = on_exceed_level
+        self._on_exceed_callback = on_exceed_callback
+        self._callback_args = callback_args or {}
+        self._execution_id = uuid4().hex[:8]
+        self._timer = None
+        self._total_time = None
+
+    def __call__(self, func: Callable) -> Callable:
+        """Enable TimerSentinel to be used as a decorator.
+
+        Automatically detects async functions and wraps appropriately.
+
+        Args:
+            func: The function to wrap and time.
+
+        Returns:
+            Wrapped function that automatically times execution.
+
+        Example:
+            @TimerSentinel(threshold=1.0)
+            def my_function():
+                pass
+
+            @TimerSentinel(threshold=1.0)
+            async def my_async_function():
+                await something()
+        """
+        # Check if function is async
+        if inspect.iscoroutinefunction(func):
+            return self._wrap_async(func)
+        return self._wrap_sync(func)
+
+    def _wrap_sync(self, func: Callable) -> Callable:
+        """Wrap a synchronous function."""
+
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            if self._use_func_name:
+                self.name = func.__name__
+
+            self.start()
+            try:
+                return func(*args, **kwargs)
+            finally:
+                self.end()
+                self.report()
+
+        return wrapper
+
+    def _wrap_async(self, func: Callable) -> Callable:
+        """Wrap an asynchronous function."""
+
+        @wraps(func)
+        async def wrapper(*args, **kwargs):
+            if self._use_func_name:
+                self.name = func.__name__
+
+            self.start()
+            try:
+                return await func(*args, **kwargs)
+            finally:
+                self.end()
+                self.report()
+
+        return wrapper
+
+    def __enter__(self) -> "TimerSentinel":
+        """Enter the context manager and start timing.
+
+        Returns:
+            Self instance for use in with statement.
+        """
+        self.start()
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        """Exit the context manager, stop timing and report.
+
+        Args:
+            exc_type: Exception type if an exception occurred.
+            exc_val: Exception value if an exception occurred.
+            exc_tb: Exception traceback if an exception occurred.
+
+        Note:
+            Exceptions are propagated (not suppressed).
+        """
+        self.end()
+        self.report()
+
+    def start(self) -> None:
+        """Start the timer.
+
+        Records the current time using perf_counter for high precision.
+        """
+        self._timer = time.perf_counter()
+
+    def end(self) -> None:
+        """Stop the timer and calculate total execution time.
+
+        Raises:
+            RuntimeError: If start() was not called before end().
+        """
+        if self._timer is None:
+            raise RuntimeError("Timer not started")
+        self._total_time = time.perf_counter() - self._timer
+
+    def report(self) -> None:
+        """Log a message and execute callback if threshold was exceeded.
+
+        Logs a message with execution time details if the threshold was
+        exceeded. Executes the configured callback function if provided.
+
+        Raises:
+            RuntimeError: If end() was not called before report().
+        """
+        if self._total_time is None:
+            raise RuntimeError("Timer not ended")
+
+        if self._total_time > self.threshold:
+            msg = (
+                f"{self._on_exceed_keyword} | {self.name}.{self._execution_id}"
+                f" | {self._total_time:.4f}s > {self.threshold:.4f}s"
+            )
+            self._logger.log(self._on_exceed_level, msg)
+
+            if self._on_exceed_callback:
+                self._on_exceed_callback(**self._callback_args)

timer_sentinel-1.0.1.dist-info/METADATA

@@ -0,0 +1,140 @@
+Metadata-Version: 2.4
+Name: timer-sentinel
+Version: 1.0.1
+Summary: A simple, efficient timer for monitoring execution time and logging threshold violations
+License: MIT
+License-File: LICENSE
+Keywords: timer,monitoring,performance,logging,decorator
+Author: Aaron Ojeda
+Requires-Python: >=3.10,<3.15
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Project-URL: Issues, https://github.com/aaronojedait/timer-sentinel/issues
+Project-URL: Repository, https://github.com/aaronojedait/timer-sentinel
+Description-Content-Type: text/markdown
+
+# Timer Sentinel
+
+[![PyPI version](https://badge.fury.io/py/timer-sentinel.svg)](https://badge.fury.io/py/timer-sentinel)
+[![Python Support](https://img.shields.io/pypi/pyversions/timer-sentinel.svg)](https://pypi.org/project/timer-sentinel/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A dead-simple, **fast**, and **lightweight** Python timer for catching slow code. Zero dependencies, optimized performance, just pure Python doing one thing well.
+
+## Why?
+
+I built this after spending too much time debugging inconsistent latency in complex systems. Sometimes a function that should take 100ms randomly takes 5 seconds, and you need to know **when** and **where**.
+
+This timer helped me catch those issues. Works great with **Grafana + Loki** for analyzing logs and creating alerts, or use the callback for whatever custom logic you need.
+
+## What it does
+
+- ⏱️ Times your code with high precision
+- 📊 Logs when it's too slow
+- 🔔 Runs callbacks when thresholds are exceeded
+- 🎯 Works as decorator, context manager, or manual timer
+- 🔀 Supports async functions
+- 🚀 **Fast** - optimized with `__slots__`, minimal overhead
+- 🪶 **Lightweight** - zero dependencies, tiny footprint
+- ⚡ **Efficient** - uses `time.perf_counter()` for microsecond precision
+
+## Install
+
+```bash
+pip install timer-sentinel
+```
+
+## Usage
+
+```python
+from timer_sentinel import TimerSentinel
+
+# Context manager
+with TimerSentinel(threshold=1.0, name="db_query"):
+    slow_database_call()
+
+# Decorator
+@TimerSentinel(threshold=0.5)
+def api_call():
+    return requests.get(url)
+
+# Async
+@TimerSentinel(threshold=0.5)
+async def async_operation():
+    await some_io()
+```
+
+## Real-world Examples
+
+### Catch slow database queries
+
+```python
+@TimerSentinel(threshold=0.1, name="db_query")
+def get_user(user_id):
+    return db.query(f"SELECT * FROM users WHERE id={user_id}")
+```
+
+### Integration with Grafana + Loki
+
+Just log to your standard logger and ship logs to Loki:
+
+```python
+import logging
+
+logger = logging.getLogger("production")
+
+with TimerSentinel(threshold=1.0, logger=logger, name="api_call"):
+    call_external_api()
+```
+
+Create alerts in Grafana based on the "OVERTIME" keyword or parse execution times. Good for catching performance regressions in production.
+
+## API
+
+```python
+TimerSentinel(
+    threshold: float,              # Max time in seconds
+    name: str = "",                # Timer name (uses function name if decorator)
+    logger: Logger | None = None,  # Custom logger
+    on_exceed_keyword: str = "OVERTIME",     # Log keyword
+    on_exceed_level: int = WARNING,          # Log level
+    on_exceed_callback: Callable = None,     # Callback function
+    callback_args: dict = None,              # Args for callback
+)
+```
+
+**Methods:**
+- `start()` - Start timing
+- `end()` - Stop timing
+- `report()` - Log if threshold exceeded
+
+**Use as:**
+- Decorator: `@TimerSentinel(...)`
+- Context manager: `with TimerSentinel(...)`
+- Manual: `timer.start()` → `timer.end()` → `timer.report()`
+
+## Requirements
+
+- Python 3.10+
+- No external dependencies
+
+## Contributing
+
+Found a bug? Want a feature? Open an issue or PR on [GitHub](https://github.com/aaronojedait/timer-sentinel).
+
+## License
+
+MIT License - do whatever you want with it.
+
+## Author
+
+**Aaron Ojeda** · [GitHub](https://github.com/aaronojedait)
+
+

timer_sentinel-1.0.1.dist-info/RECORD

@@ -0,0 +1,6 @@
+timer_sentinel/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+timer_sentinel/core.py,sha256=OyPH7nn6GG7OlWNghVmDdcLCHzXM9TBulF7HZbissB0,6717
+timer_sentinel-1.0.1.dist-info/METADATA,sha256=E9qG7LllSr5DvXup_k-B22uQjsHou2NhdlxTje0doCo,4322
+timer_sentinel-1.0.1.dist-info/WHEEL,sha256=kJCRJT_g0adfAJzTx2GUMmS80rTJIVHRCfG0DQgLq3o,88
+timer_sentinel-1.0.1.dist-info/licenses/LICENSE,sha256=M78NOSIjiIj0bhd_AasXH3CJUoljIUJ8yFWbLno7NDo,1068
+timer_sentinel-1.0.1.dist-info/RECORD,,

timer_sentinel-1.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 2.3.1
+Root-Is-Purelib: true
+Tag: py3-none-any

timer_sentinel-1.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aaron Ojeda
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.