Metadata-Version: 2.4
Name: funcmetricsx
Version: 0.1.0
Summary: Measure execution time and memory usage of Python functions
Author-email: Hossein Tajfirouz <hosseintajfirouz@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/ht21992/funcmetricsx
Project-URL: Repository, https://github.com/ht21992/funcmetricsx
Project-URL: Issues, https://github.com/ht21992/funcmetricsx/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# funcmetricsx

Lightweight Python toolkit for measuring **execution time, CPU time, memory usage, and call statistics** of functions and code blocks.
thon toolkit forhelps developers understand performance characteristics of their code with CPU time, memory usage, and caland a simple decorator or context manager.

---

# Features

- Measure execution time
- Measure CPU time
- Measure peak memory usage
- Call count summary
- Supports sync and async functions
- Decorator API
- Context manager API
- Optional arguments and result logging
- Logger integration
- Pure Python implementation
- No external runtime dependencies
- Works on Python 3.10+

---

# Installation

```bash
pip install funcmetricsx
```

⸻

## Quick Example

```
from funcmetricsx import metrics

@metrics()
def compute():
    return sum(i * i for i in range(10000))

compute()
```

### Example output:

```
[funcmetricsx] | compute | time=0.0012s | cpu=0.0011s | peak_memory=10.25 KB
[funcmetricsx] | compute summary | calls=1 | avg_time=0.0012s | last_time=0.0012s | avg_cpu=0.0011s | last_cpu=0.0011s
```

⸻

## Real World Examples

### Example 1 — Measuring an API Request

```
import requests
from funcmetricsx import metrics

@metrics()
def fetch_users():
    r = requests.get("https://jsonplaceholder.typicode.com/users")
    return r.json()

fetch_users()
```

#### Output:

```
[funcmetricsx] | fetch_users | time=0.2341s | cpu=0.0120s | peak_memory=48.00 KB
```

Useful for understanding network latency vs CPU work.

⸻

### Example 2 — Measuring Database Queries

```
import sqlite3
from funcmetricsx import metrics

conn = sqlite3.connect(":memory:")

@metrics(show_result=True)
def query_db():
    cur = conn.cursor()
    cur.execute("SELECT sqlite_version()")
    return cur.fetchone()

query_db()
```

## Output:

```
[funcmetricsx] | query_db | time=0.0003s | cpu=0.0003s | result=('3.44.0',)
```

Helpful when profiling database access speed.

⸻

### Example 3 — Detecting Slow Data Processing

```
import time
from funcmetricsx import metrics

@metrics()
def process_data():
    time.sleep(0.2)
    return "done"

process_data()
```

#### Output:

```
[funcmetricsx] | process_data | time=0.2001s | cpu=0.0001s
```

Shows that the time is mostly waiting, not CPU usage.

⸻

### Example 4 — CPU Heavy Work

```
from funcmetricsx import metrics

@metrics()
def cpu_heavy():
    total = 0
    for i in range(10_000_000):
        total += i
    return total

cpu_heavy()
```

#### Output:

```
[funcmetricsx] | cpu_heavy | time=0.45s | cpu=0.44s
```

Here CPU time ≈ wall time, meaning the function is CPU-bound.

⸻

### Example 5 — Track Multiple Calls

```
from funcmetricsx import metrics

@metrics()
def add(a, b):
    return a + b

add(1, 2)
add(3, 4)
add(5, 6)
```

#### Output:

```
[funcmetricsx] | add | time=0.0001s | cpu=0.0001s
[funcmetricsx] | add summary | calls=1 | avg_time=0.0001s

[funcmetricsx] | add | time=0.0001s | cpu=0.0001s
[funcmetricsx] | add summary | calls=2 | avg_time=0.0001s

[funcmetricsx] | add | time=0.0001s | cpu=0.0001s
[funcmetricsx] | add summary | calls=3 | avg_time=0.0001s
```

Great for profiling high-frequency functions.

⸻

## Async Function Support

```
import asyncio
from funcmetricsx import metrics

@metrics()
async def fetch_data():
    await asyncio.sleep(0.1)
    return "done"

asyncio.run(fetch_data())
```

#### Output:

```
[funcmetricsx] | fetch_data | time=0.1003s | cpu=0.0002s
```

Works automatically with async def.

⸻

## Measure Code Blocks

Sometimes you want to measure a specific block of code instead of a function.

```
import time
from funcmetricsx import measure_block

with measure_block("load-data"):
    time.sleep(0.2)
```

#### Output:

```
[funcmetricsx] | load-data | time=0.2002s | cpu=0.0001s
```

⸻

### Show Function Arguments

```
from funcmetricsx import metrics

@metrics(show_args=True)
def multiply(a, b):
    return a * b

multiply(3, 4)
```

#### Output:

```
[funcmetricsx] | multiply | time=0.0001s | args=(3, 4)
```

⸻

### Show Function Result

```
from funcmetricsx import metrics

@metrics(show_result=True)
def square(x):
    return x * x

square(5)
```

#### Output:

```
[funcmetricsx] | square | time=0.0001s | result=25
```

### Logger Integration

Send metrics to a Python logger instead of printing.

```
import logging
from funcmetricsx import metrics

logging.basicConfig(
    filename="metrics.log",
    level=logging.INFO,
    format="%(asctime)s - %(levelname)s - %(message)s",
)

logger = logging.getLogger("metrics")


@metrics(logger=logger)
def task():
    return sum(range(10000))


task()

```

you can check the output in metrics.log

---

### Configuration Options

```
@metrics(
    show_time=True,
    show_cpu_time=True,
    show_memory=True,
    show_args=False,
    show_result=False,
    track_calls=True,
)

```

| Option        | Description               |
| ------------- | ------------------------- |
| show_time     | display execution time    |
| show_cpu_time | display CPU usage time    |
| show_memory   | display peak memory usage |
| show_args     | show function arguments   |
| show_result   | show returned value       |
| track_calls   | maintain call statistics  |

### Running Tests

pytest
