pyquerytracker 0.1.0__tar.gz

pyquerytracker-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,62 @@
+# 🐍 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/pyproject.toml

@@ -0,0 +1,27 @@
+[project]
+name = "pyquerytracker"
+version = "0.1.0"
+description = "A lightweight, decorator-based query performance tracking library for Python applications. Monitor and analyze database query performance with ease."
+authors = [
+    {name = "MuddyHope", email = "daktarisun@gmail.com"}
+]
+license = {text = "MIT"}
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+]
+keywords = ["performance", "database", "query", "decorator", "tracking"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules"
+]
+
+[project.urls]
+Repository = "https://github.com/MuddyHope/pyquerytracker"
+Issues = "https://github.com/MuddyHope/pyquerytracker/issues"

pyquerytracker-0.1.0/pyquerytracker/__init__.py

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

pyquerytracker-0.1.0/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-0.1.0/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/pyquerytracker.egg-info/PKG-INFO

@@ -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/pyquerytracker.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+LICENSE
+README.md
+pyproject.toml
+pyquerytracker/__init__.py
+pyquerytracker/config.py
+pyquerytracker/core.py
+pyquerytracker.egg-info/PKG-INFO
+pyquerytracker.egg-info/SOURCES.txt
+pyquerytracker.egg-info/dependency_links.txt
+pyquerytracker.egg-info/top_level.txt
+tests/test_config.py
+tests/test_core.py

pyquerytracker-0.1.0/pyquerytracker.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

pyquerytracker-0.1.0/pyquerytracker.egg-info/top_level.txt

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

pyquerytracker-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pyquerytracker-0.1.0/tests/test_config.py

@@ -0,0 +1,44 @@
+import logging
+
+from pyquerytracker import TrackQuery, configure
+
+
+def test_configure_basic(caplog):
+    configure(slow_log_threshold_ms=250)
+
+    class MyClass:
+        @TrackQuery()
+        def do_work(self, a, b):
+            import time
+
+            time.sleep(0.5)
+            return a * b
+
+    res = MyClass().do_work(2, 3)  # noqa: F841
+    assert len(caplog.records) == 1
+    record = caplog.records[0]
+    assert record.levelname == "WARNING"
+    assert "MyClass" in record.message
+    assert "do_work" in record.message
+    assert "ms" in record.message
+
+
+def test_configure_basic_with_loglevel(caplog):
+
+    configure(slow_log_threshold_ms=100, slow_log_level=logging.ERROR)
+
+    class MyClass:
+        @TrackQuery()
+        def do_slow_work(self, a, b):
+            import time
+
+            time.sleep(0.2)
+            return a * b
+
+    res = MyClass().do_slow_work(2, 3)  # noqa: F841
+    assert len(caplog.records) == 1
+    record = caplog.records[0]
+    assert record.levelname == "ERROR"
+    assert "MyClass" in record.message
+    assert "do_slow_work" in record.message
+    assert "ms" in record.message

pyquerytracker-0.1.0/tests/test_core.py

@@ -0,0 +1,72 @@
+from pyquerytracker import TrackQuery
+import pytest
+
+
+def test_tracking_output(capsys):
+    @TrackQuery()
+    def fake_db_query():
+        return "done"
+
+    assert fake_db_query() == "done"
+
+
+import logging  # noqa: E402
+
+logging.basicConfig(
+    level=logging.INFO, format="%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+)
+
+
+def test_tracking_output_with_logging(caplog):
+    caplog.set_level("INFO")
+
+    @TrackQuery()
+    def fake_db_query():
+        return "done"
+
+    result = fake_db_query()
+    assert result == "done"
+
+    # Check the log records
+    assert len(caplog.records) == 1
+    record = caplog.records[0]
+    assert record.levelname == "INFO"
+    assert "Function fake_db_query executed successfully" in record.message
+    assert "ms" in record.message
+
+
+def test_tracking_output_with_error(caplog):
+    caplog.set_level("ERROR")
+
+    @TrackQuery()
+    def failing_query():
+        raise ValueError("Test error")
+
+    with pytest.raises(ValueError):
+        failing_query()
+
+    # Check the log records
+    assert len(caplog.records) == 1
+    record = caplog.records[0]
+    assert record.levelname == "ERROR"
+    assert "Function failing_query failed" in record.message
+    assert "Test error" in record.message
+    assert "ms" in record.message
+
+
+def test_tracking_with_class(caplog):
+    class MyClass:
+        @TrackQuery()
+        def do_work(self, a, b):
+            import time
+
+            time.sleep(0.09)
+            return a * b
+
+    res = MyClass().do_work(2, 3)  # noqa: F841
+    assert len(caplog.records) == 1
+    record = caplog.records[0]
+    assert record.levelname == "INFO"
+    assert "MyClass" in record.message
+    assert "do_work" in record.message
+    assert "ms" in record.message