Metadata-Version: 2.4
Name: masoumi
Version: 0.2.2
Summary: Python developer toolkit — performance analyzer and more
License: MIT
Project-URL: Homepage, https://github.com/mohammadmehdimasoumi/masoumi
Keywords: performance,profiling,static-analysis,linter,developer-tools,ast
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: MIT License
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Intended Audience :: Developers
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# masoumi

**Python developer toolkit** — performance analyzer and more.

[▶️ Watch demo on GitHub](https://github.com/mohammadmehdimasoumi/masoumi-py/blob/main/assets/demo.gif)

## Install

```bash
pip install masoumi
```

## Usage

```python
import masoumi

code = open("my_script.py").read()

# Analyze full file
issues = masoumi.analyze(code)

# Analyze specific line range
issues = masoumi.analyze(code, start=10, end=50)

# Analyze a file directly
issues = masoumi.analyze_file("my_script.py", start=1, end=100)

# Use in CI/CD — no print, just data
issues = masoumi.analyze(code, print_report=False)
high = [i for i in issues if i.severity == "HIGH"]
if high:
    raise SystemExit(f"{len(high)} high severity issue(s) found.")

# Get results as plain dicts (for JSON, logging, etc.)
data = masoumi.issues_as_dicts(issues)

# Enable runtime profiling (executes your code — use on trusted scripts only)
issues = masoumi.analyze(code, runtime=True)
```

## What it detects

| Severity | Issue |
|----------|-------|
| 🔴 HIGH   | String concatenation `+=` inside loops |
| 🔴 HIGH   | Mutable default argument (`list`, `dict`, `set`) |
| 🟡 MEDIUM | Nested loops (O(n²) complexity warning) |
| 🟡 MEDIUM | `list.append()` inside loop (use comprehension) |
| 🟡 MEDIUM | `in` lookup on list/tuple instead of set |
| 🟡 MEDIUM | Bare `except:` clause |
| 🟡 MEDIUM | Recursive function without clear base case |
| 🟡 MEDIUM | `global` variable usage |
| 🔵 LOW    | Unnecessary `pass` statements |
| 🔵 LOW    | Imports inside functions |
| 🔵 LOW    | Functions with too many parameters (>7) |
| 🟣 PROFILE | Slow functions — runtime profiling (`runtime=True`) |

## Return value

`analyze()` and `analyze_file()` return a `list[Issue]`.  
Each `Issue` has:

```python
issue.line      # int — line number
issue.severity  # str — "HIGH" / "MEDIUM" / "LOW" / "PROFILE"
issue.message   # str — what was detected
issue.tip       # str — how to fix it
issue.code      # str — the offending line of code
issue.to_dict() # dict — all of the above as a plain dict
```

## CI/CD example

```bash
python -c "
import masoumi, sys
issues = masoumi.analyze_file('my_script.py', print_report=True)
if any(i.severity == 'HIGH' for i in issues):
    sys.exit(1)
"
```

## License
MIT
