pyquerytracker 0.1.0__tar.gz → 0.1.1__tar.gz

{pyquerytracker-0.1.0/pyquerytracker.egg-info → pyquerytracker-0.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyquerytracker
-Version: 0.1.0
+Version: 0.1.1
 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
@@ -20,6 +20,16 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Dynamic: license-file
 
+
+![GitHub Release](https://img.shields.io/github/v/release/MuddyHope/pyquerytracker)
+![GitHub Issues or Pull Requests](https://img.shields.io/github/issues/MuddyHope/pyquerytracker)
+
+![PyPI - Downloads](https://img.shields.io/pypi/dm/pyquerytracker)
+![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/MuddyHope/pyquerytracker/.github%2Fworkflows%2Fpublish.yml)
+![GitHub forks](https://img.shields.io/github/forks/MuddyHope/pyquerytracker)
+
+![PyPI - License](https://img.shields.io/pypi/l/pyquerytracker)
+
 # 🐍 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.
@@ -46,8 +56,24 @@ Dynamic: license-file
 pip install pyquerytracker
 ```
 
-## Usage
+## 🔧 Configuration
+
+```python
+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
+)
+```
+
+---
+
+## ⚙️ Usage
+
 ### Basic Usage
+
 ```python
 import time
 from pyquerytracker import TrackQuery
@@ -59,26 +85,81 @@ def run_query():
 
 run_query()
 ```
-### Output
-```bash
+
+**Output:**
+```
 2025-06-14 14:23:00,123 - pyquerytracker - INFO - Function run_query executed successfully in 305.12ms
 ```
 
-### With Configure
+---
+
+### 🧩 Async Support
+
+Use the same decorator with `async` functions or class methods:
+
+```python
+import asyncio
+from pyquerytracker import TrackQuery
+
+@TrackQuery()
+async def fetch_data():
+    await asyncio.sleep(0.2)
+    return "fetched"
+
+class MyService:
+    @TrackQuery()
+    async def do_work(self, x, y):
+        await asyncio.sleep(0.1)
+        return x + y
+
+asyncio.run(fetch_data())
 ```
-import logging
+
+---
+
+### 🌐 Run the FastAPI Server
+
+To view tracked query logs via REST, WebSocket, or a Web-based dashboard, start the built-in FastAPI server:
+
+```bash
+uvicorn pyquerytracker.api:app --reload
+```
+
+- ⚠️ If your project or file structure is different, replace `pyquerytracker.api` with your own module path, like `<your_project_name>.<your_server(file)_name>`.
+
+- Open docs at [http://localhost:8000/docs](http://localhost:8000/docs)
+- **Query Dashboard UI:** [http://localhost:8000/dashboard](http://localhost:8000/dashboard)
+- REST endpoint: `GET /queries`
+- WebSocket stream: `ws://localhost:8000/ws`
+
+Then run your tracked functions in another terminal or script:
+
+```python
+@TrackQuery()
+def insert_query():
+    time.sleep(0.4)
+    return "INSERT INTO users ..."
+```
+
+You’ll see logs live on the server via API/WebSocket.
+
+---
+
+## 📤 Export Logs
+
+Enable exporting to CSV or JSON by setting config:
+
+```python
 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
+    export_type="json",
+    export_path="./query_logs.json"
 )
 ```
 
-### Output
-```bash
-2025-06-14 14:24:45,456 - pyquerytracker - WARNING - Slow execution: run_query took 501.87ms
-```
+---
 
+Let us know how you’re using `pyquerytracker` and feel free to contribute!
 
 

pyquerytracker-0.1.1/README.md

@@ -0,0 +1,143 @@
+
+![GitHub Release](https://img.shields.io/github/v/release/MuddyHope/pyquerytracker)
+![GitHub Issues or Pull Requests](https://img.shields.io/github/issues/MuddyHope/pyquerytracker)
+
+![PyPI - Downloads](https://img.shields.io/pypi/dm/pyquerytracker)
+![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/MuddyHope/pyquerytracker/.github%2Fworkflows%2Fpublish.yml)
+![GitHub forks](https://img.shields.io/github/forks/MuddyHope/pyquerytracker)
+
+![PyPI - License](https://img.shields.io/pypi/l/pyquerytracker)
+
+# 🐍 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
+```
+
+## 🔧 Configuration
+
+```python
+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
+)
+```
+
+---
+
+## ⚙️ 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:**
+```
+2025-06-14 14:23:00,123 - pyquerytracker - INFO - Function run_query executed successfully in 305.12ms
+```
+
+---
+
+### 🧩 Async Support
+
+Use the same decorator with `async` functions or class methods:
+
+```python
+import asyncio
+from pyquerytracker import TrackQuery
+
+@TrackQuery()
+async def fetch_data():
+    await asyncio.sleep(0.2)
+    return "fetched"
+
+class MyService:
+    @TrackQuery()
+    async def do_work(self, x, y):
+        await asyncio.sleep(0.1)
+        return x + y
+
+asyncio.run(fetch_data())
+```
+
+---
+
+### 🌐 Run the FastAPI Server
+
+To view tracked query logs via REST, WebSocket, or a Web-based dashboard, start the built-in FastAPI server:
+
+```bash
+uvicorn pyquerytracker.api:app --reload
+```
+
+- ⚠️ If your project or file structure is different, replace `pyquerytracker.api` with your own module path, like `<your_project_name>.<your_server(file)_name>`.
+
+- Open docs at [http://localhost:8000/docs](http://localhost:8000/docs)
+- **Query Dashboard UI:** [http://localhost:8000/dashboard](http://localhost:8000/dashboard)
+- REST endpoint: `GET /queries`
+- WebSocket stream: `ws://localhost:8000/ws`
+
+Then run your tracked functions in another terminal or script:
+
+```python
+@TrackQuery()
+def insert_query():
+    time.sleep(0.4)
+    return "INSERT INTO users ..."
+```
+
+You’ll see logs live on the server via API/WebSocket.
+
+---
+
+## 📤 Export Logs
+
+Enable exporting to CSV or JSON by setting config:
+
+```python
+from pyquerytracker.config import configure
+
+configure(
+    export_type="json",
+    export_path="./query_logs.json"
+)
+```
+
+---
+
+Let us know how you’re using `pyquerytracker` and feel free to contribute!
+
+

pyquerytracker-0.1.1/examples/async_example.py

@@ -0,0 +1,63 @@
+import asyncio
+import os
+import sys
+
+from pyquerytracker import TrackQuery
+
+sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), "..")))
+
+
+# Example 1: Basic async function
+@TrackQuery()
+async def fetch_data():
+    await asyncio.sleep(0.2)
+    return "fetched data"
+
+
+# Example 2: Async function with parameters
+@TrackQuery()
+async def compute_sum(a, b):
+    await asyncio.sleep(0.1)
+    return a + b
+
+
+# Example 3: Class method async tracking
+class DatabaseService:
+    @TrackQuery()
+    async def query_users(self):
+        await asyncio.sleep(0.3)
+        return ["Alice", "Bob", "Charlie"]
+
+
+# Example 4: Async function that raises an error
+@TrackQuery()
+async def fail_fast():
+    await asyncio.sleep(0.05)
+    raise RuntimeError("Database failure simulation")
+
+
+# Example 5: Async function with slow duration to trigger logging thresholds
+@TrackQuery()
+async def slow_operation():
+    await asyncio.sleep(0.5)
+    return "slow complete"
+
+
+# Run all examples
+async def main():
+    print("Example 1: fetch_data →", await fetch_data())
+    print("Example 2: compute_sum(5, 7) →", await compute_sum(5, 7))
+
+    service = DatabaseService()
+    print("Example 3: query_users →", await service.query_users())
+
+    try:
+        await fail_fast()
+    except RuntimeError as e:
+        print("Example 4: fail_fast → raised:", e)
+
+    print("Example 5: slow_operation →", await slow_operation())
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

pyquerytracker-0.1.1/examples/core/async_usage.py

@@ -0,0 +1,53 @@
+import asyncio
+import logging
+
+from pyquerytracker import TrackQuery, configure
+
+# Configure logging to see the output
+logging.basicConfig(
+    level=logging.INFO, format="%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+)
+
+# Set a low threshold to easily see "slow" logs
+configure(slow_log_threshold_ms=150, slow_log_level=logging.WARNING)
+
+
+@TrackQuery()
+async def fast_async_query():
+    """An async function that executes quickly."""
+    await asyncio.sleep(0.1)
+    return "Fast async query completed"
+
+
+@TrackQuery()
+async def slow_async_query():
+    """An async function that takes longer to execute."""
+    await asyncio.sleep(0.2)
+    return "Slow async query completed"
+
+
+@TrackQuery()
+async def failing_async_query():
+    """An async function that raises an error."""
+    await asyncio.sleep(0.1)
+    raise ConnectionError("Could not connect to async database")
+
+
+async def main():
+    print("--- Testing fast async query (should be INFO log) ---")
+    result1 = await fast_async_query()
+    print(f"Result: {result1}\n")
+
+    print("--- Testing slow async query (should be WARNING log) ---")
+    result2 = await slow_async_query()
+    print(f"Result: {result2}\n")
+
+    print("--- Testing failing async query (should be ERROR log) ---")
+    try:
+        await failing_async_query()
+    except ConnectionError as e:
+        print(f"Caught expected error: {e}\n")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

pyquerytracker-0.1.1/examples/core/basic_usage.py

@@ -0,0 +1,17 @@
+from pyquerytracker import TrackQuery, configure
+
+configure(slow_log_threshold_ms=1000, slow_log_level=20)
+
+
+@TrackQuery()
+def simple_query():
+    """A simple function that simulates a database query."""
+    import time
+
+    time.sleep(0.5)  # Simulate some work
+    return "Query completed successfully"
+
+
+if __name__ == "__main__":
+    result = simple_query()
+    print(f"Result: {result}")

pyquerytracker-0.1.1/examples/core/error_handling.py

@@ -0,0 +1,24 @@
+import logging
+
+from pyquerytracker import TrackQuery
+
+# Configure logging
+logging.basicConfig(
+    level=logging.INFO, format="%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+)
+
+
+@TrackQuery()
+def failing_query():
+    """A function that simulates a failed database query."""
+    import time
+
+    time.sleep(0.3)  # Simulate some work
+    raise ValueError("Database connection failed")
+
+
+if __name__ == "__main__":
+    try:
+        failing_query()
+    except ValueError as e:
+        print(f"Caught expected error: {e}")

pyquerytracker-0.1.1/examples/core/quick_test.py

@@ -0,0 +1,39 @@
+import time
+
+from pyquerytracker import TrackQuery
+
+
+@TrackQuery()
+def fast_query():
+    """A function that executes quickly."""
+    return "Fast query completed"
+
+
+@TrackQuery()
+def slow_query():
+    """A function that takes some time to execute."""
+    time.sleep(0.5)  # Simulate some work
+    return "Slow query completed"
+
+
+@TrackQuery()
+def failing_query():
+    """A function that raises an error."""
+    time.sleep(0.2)  # Simulate some work
+    raise ValueError("Query failed!")
+
+
+if __name__ == "__main__":
+    print("\nTesting fast query:")
+    result1 = fast_query()
+    print(f"Result: {result1}")
+
+    print("\nTesting slow query:")
+    result2 = slow_query()
+    print(f"Result: {result2}")
+
+    print("\nTesting failing query:")
+    try:
+        failing_query()
+    except ValueError as e:
+        print(f"Caught expected error: {e}")

pyquerytracker-0.1.1/examples/core/with_arguments.py

@@ -0,0 +1,27 @@
+import logging
+
+from pyquerytracker import TrackQuery
+
+# Configure logging
+logging.basicConfig(
+    level=logging.INFO, format="%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+)
+
+
+@TrackQuery()
+def complex_query(user_id: int, query_type: str, limit: int = 10):
+    """A function that simulates a complex database query with arguments."""
+    import time
+
+    time.sleep(0.2)  # Simulate some work
+    return f"Retrieved {limit} {query_type} records for user {user_id}"
+
+
+if __name__ == "__main__":
+    # Test with positional arguments
+    result1 = complex_query(123, "posts")
+    print(f"Result 1: {result1}")
+
+    # Test with keyword arguments
+    result2 = complex_query(user_id=456, query_type="comments", limit=5)
+    print(f"Result 2: {result2}")

pyquerytracker-0.1.1/examples/core/with_config.py

@@ -0,0 +1,30 @@
+import logging
+import time
+
+from pyquerytracker import TrackQuery
+from pyquerytracker.config import configure
+
+configure(slow_log_threshold_ms=640, slow_log_level=logging.ERROR)
+
+
+@TrackQuery()
+def fast_query():
+    """A function that executes quickly."""
+    return "Fast query completed"
+
+
+@TrackQuery()
+def slow_query():
+    """A function that takes some time to execute."""
+    time.sleep(0.3)  # Simulate some work
+    return "Slow query completed"
+
+
+if __name__ == "__main__":
+    # Test with positional arguments
+    result1 = fast_query()
+    print(f"Result 1: {result1}")
+
+    # Test with keyword arguments
+    result2 = slow_query()
+    print(f"Result 2: {result2}")

pyquerytracker-0.1.1/examples/exporter/csv_exporter_1.py

@@ -0,0 +1,36 @@
+import os
+import time
+
+from pyquerytracker import TrackQuery
+from pyquerytracker.config import ExportType, configure
+
+os.makedirs("logs-csv", exist_ok=True)
+
+configure(
+    slow_log_threshold_ms=50.0,
+    slow_log_level=20,  # INFO
+    export_type=ExportType.CSV,
+    export_path="logs-csv/query_logs_2.csv",
+)
+
+
+@TrackQuery()
+def process_data(x, y):
+    time.sleep(8)
+    return x + y
+
+
+@TrackQuery()
+def failing_task():
+    time.sleep(0.03)  # not slow
+    raise RuntimeError("This failed intentionally.")
+
+
+# Run tasks
+print("Result:", process_data(5, 7))
+print("Result:", process_data(1, 2))
+
+try:
+    failing_task()
+except Exception:
+    pass

pyquerytracker-0.1.1/examples/exporter/json_exporter.py

@@ -0,0 +1,36 @@
+import os
+import time
+
+from pyquerytracker import TrackQuery
+from pyquerytracker.config import ExportType, configure
+
+os.makedirs("logs-json", exist_ok=True)
+
+configure(
+    slow_log_threshold_ms=50.0,
+    slow_log_level=20,  # INFO
+    export_type=ExportType.JSON,
+    export_path="logs-json/query_logs.json",
+)
+
+
+@TrackQuery()
+def process_data(x, y):
+    time.sleep(0.08)  # triggers slow log
+    return x + y
+
+
+@TrackQuery()
+def failing_task():
+    time.sleep(0.03)  # not slow
+    raise RuntimeError("This failed intentionally.")
+
+
+# Run tasks
+print("Result:", process_data(5, 7))
+print("Result:", process_data(1, 2))
+
+try:
+    failing_task()
+except Exception:
+    pass