pyquerytracker 0.1.0__py3-none-any.whl

pyquerytracker/__init__.py

@@ -0,0 +1,4 @@
+from .core import TrackQuery
+from .config import configure
+
+__all__ = ["TrackQuery", "configure"]

pyquerytracker/config.py

@@ -0,0 +1,66 @@
+from enum import Enum
+from dataclasses import dataclass
+from typing import Optional
+import logging
+
+
+class ExportType(str, Enum):
+    """
+    Enum representing supported export formats for query tracking logs.
+
+    Attributes:
+        JSON: Export logs in JSON format.
+        CSV: Export logs in CSV format.
+    """
+
+    JSON = "json"
+    CSV = "csv"
+
+
+@dataclass
+class Config:
+    """
+    Configuration settings for the query tracking system.
+
+    Attributes:
+        slow_log_threshold_ms (float): Threshold in milliseconds above which a query is considered slow.
+                                        Defaults to 100.0 ms.
+        slow_log_level (int): Logging level for slow query logs (e.g., logging.WARNING, logging.INFO).
+                              Defaults to logging.WARNING.
+    """
+
+    # TODO: Adding export functionality
+    slow_log_threshold_ms: float = 100.0
+    slow_log_level: int = logging.WARNING
+
+
+_config: Config = Config()
+
+
+def configure(
+    slow_log_threshold_ms: Optional[float] = None,
+    slow_log_level: Optional[int] = None,
+):
+    """
+    Configure global settings for query tracking.
+
+    Args:
+        slow_log_threshold_ms (Optional[float]): Threshold in milliseconds to log a query as "slow".
+                                                 If not provided, defaults to 100.0 ms.
+        slow_log_level (Optional[int]): Logging level for slow queries (e.g., logging.INFO, logging.WARNING).
+                                        If not provided, defaults to logging.WARNING.
+    """
+    if slow_log_threshold_ms is not None:
+        _config.slow_log_threshold_ms = slow_log_threshold_ms
+    if slow_log_level is not None:
+        _config.slow_log_level = slow_log_level
+
+
+def get_config() -> Config:
+    """
+    Retrieve the current query tracking configuration.
+
+    Returns:
+        TrackerConfig: The current configuration settings.
+    """
+    return _config

pyquerytracker/core.py

@@ -0,0 +1,102 @@
+import time
+import logging
+from functools import update_wrapper
+from typing import Any, Callable, TypeVar, Generic
+from pyquerytracker.config import get_config
+
+# Set up logger
+logger = logging.getLogger("pyquerytracker")
+if not logger.handlers:
+    handler = logging.StreamHandler()
+    formatter = logging.Formatter(
+        "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+    )
+    handler.setFormatter(formatter)
+    logger.addHandler(handler)
+    logger.setLevel(logging.INFO)
+
+T = TypeVar("T")
+
+
+class TrackQuery(Generic[T]):
+    """
+    Class-based decorator to track and log the execution time of functions or methods.
+
+    Logs include:
+    - Function name
+    - Class name (if method)
+    - Execution time (ms)
+    - Arguments
+    - Errors (if any)
+
+    Usage:
+        @TrackQuery()
+        def my_function():
+            ...
+    """
+
+    def __init__(self) -> None:
+        self.config = get_config()
+
+    def __call__(self, func: Callable[..., T]) -> Callable[..., T]:
+        def wrapped(*args: Any, **kwargs: Any) -> T:
+            start = time.perf_counter()
+            class_name = None
+
+            # Try to detect if this is an instance or class method
+            if args:
+                possible_self_or_cls = args[0]
+                if hasattr(possible_self_or_cls, "__class__"):
+                    if isinstance(possible_self_or_cls, type):
+                        # classmethod
+                        class_name = possible_self_or_cls.__name__
+                    else:
+                        # instance method
+                        class_name = possible_self_or_cls.__class__.__name__
+
+            try:
+                result = func(*args, **kwargs)
+                duration = (time.perf_counter() - start) * 1000
+                if duration > self.config.slow_log_threshold_ms:
+                    logger.log(
+                        self.config.slow_log_level,
+                        f"{class_name}.{func.__name__} -> Slow execution: took %.2fms",
+                        duration,
+                    )
+                    # logger.warning("Slow execution: %s took %.2fms", func.__name__, duration)
+                else:
+                    logger.info(
+                        "Function %s%s executed successfully in %.2fms",
+                        f"{class_name}." if class_name else "",
+                        func.__name__,
+                        duration,
+                        extra={
+                            "function_name": func.__name__,
+                            "class_name": class_name,
+                            "duration_ms": duration,
+                            "func_args": args,
+                            "func_kwargs": kwargs,
+                        },
+                    )
+                return result
+            except Exception as e:
+                duration = (time.perf_counter() - start) * 1000
+                logger.error(
+                    "Function %s%s failed after %.2fms: %s",
+                    f"{class_name}." if class_name else "",
+                    func.__name__,
+                    duration,
+                    str(e),
+                    exc_info=True,
+                    extra={
+                        "function_name": func.__name__,
+                        "class_name": class_name,
+                        "duration_ms": duration,
+                        "func_args": args,
+                        "func_kwargs": kwargs,
+                        "error": str(e),
+                    },
+                )
+                raise
+
+        return update_wrapper(wrapped, func)

pyquerytracker-0.1.0.dist-info/METADATA

@@ -0,0 +1,84 @@
+Metadata-Version: 2.4
+Name: pyquerytracker
+Version: 0.1.0
+Summary: A lightweight, decorator-based query performance tracking library for Python applications. Monitor and analyze database query performance with ease.
+Author-email: MuddyHope <daktarisun@gmail.com>
+License: MIT
+Project-URL: Repository, https://github.com/MuddyHope/pyquerytracker
+Project-URL: Issues, https://github.com/MuddyHope/pyquerytracker/issues
+Keywords: performance,database,query,decorator,tracking
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# 🐍 pyquerytracker
+
+**pyquerytracker** is a lightweight Python utility to **track and analyze database query performance** using simple decorators. It enables developers to gain visibility into SQL execution time, log metadata, and export insights in JSON format — with optional FastAPI integration and scheduled reporting.
+
+---
+
+## 🚀 Features
+
+- ✅ Easy-to-use decorator to track function execution (e.g., SQL queries)
+- ✅ Capture runtime, function name, args, return values, and more
+
+## TODO Features
+- ✅ Export logs to JSON or CSV
+- ✅ FastAPI integration to expose tracked metrics via REST API
+- ✅ Schedule periodic exports using `APScheduler`
+- ✅ Plug-and-play with any Python database client (SQLAlchemy, psycopg2, etc.)
+- ✅ Modular and extensible design
+
+---
+
+## 📦 Installation
+
+```bash
+pip install pyquerytracker
+```
+
+## Usage
+### Basic Usage
+```python
+import time
+from pyquerytracker import TrackQuery
+
+@TrackQuery()
+def run_query():
+    time.sleep(0.3)  # Simulate SQL execution
+    return "SELECT * FROM users;"
+
+run_query()
+```
+### Output
+```bash
+2025-06-14 14:23:00,123 - pyquerytracker - INFO - Function run_query executed successfully in 305.12ms
+```
+
+### With Configure
+```
+import logging
+from pyquerytracker.config import configure
+
+configure(
+    slow_log_threshold_ms=200,     # Log queries slower than 200ms
+    slow_log_level=logging.DEBUG   # Use DEBUG level for slow logs
+)
+```
+
+### Output
+```bash
+2025-06-14 14:24:45,456 - pyquerytracker - WARNING - Slow execution: run_query took 501.87ms
+```
+
+
+

pyquerytracker-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+pyquerytracker/__init__.py,sha256=pYyF2RPTTMhA0SakZTZ_dJ5dbPOIPYlacXJg7dSfsdc,98
+pyquerytracker/config.py,sha256=GuMaHx4RB77FFad4bzZTQ-EyQYkDYHRrELHD_bTjAZo,1907
+pyquerytracker/core.py,sha256=eLMfYs41ajLRjoxtxKjyi9G3NPN7tpwYkNerccL2oM4,3583
+pyquerytracker-0.1.0.dist-info/licenses/LICENSE,sha256=lXcEFZRxovixBqp9SYJRLrN5OpP6AMggc_v7eaAMWn4,1065
+pyquerytracker-0.1.0.dist-info/METADATA,sha256=RlPCS75bqssay-luqk6PuGlz_sb6NKAEKlcixWokI8E,2540
+pyquerytracker-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+pyquerytracker-0.1.0.dist-info/top_level.txt,sha256=E5kxHgMifJIw-S2IjZqA1XuAU06Vbhd7geNfRZgjZuQ,15
+pyquerytracker-0.1.0.dist-info/RECORD,,

pyquerytracker-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pyquerytracker-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 MuddyHope
+
+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.

pyquerytracker-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+pyquerytracker