Metadata-Version: 2.1
Name: lprof_ext
Version: 0.1.1
Summary: A Python script profiler using @profile decorators
Author: Ruprof
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: libcst>=1.0.0
Requires-Dist: line-profiler>=4.0.0
Requires-Dist: pandas>=2.0.3

# Line Profiler Extension for Python (`lprof_ext`)

`lprof_ext` is a lightweight Python script profiler that seamlessly integrates with the `line_profiler` library. It simplifies performance analysis by automatically adding `@profile` decorators to your Python code and collecting detailed line-by-line performance statistics. This tool is ideal for developers looking to identify bottlenecks and optimize their Python scripts efficiently.


## Features
- Automatic Profiling: Adds `@profile` decorators to your code without manual intervention.
- Line-by-Line Analysis: Leverages line_profiler to provide granular performance metrics for each line of code.
- Easy Integration: Works with any Python script via a simple command-line interface.
- Lightweight: Minimal dependencies and straightforward setup.
- Open Source: Freely available for contributions and customization.

## Installation
### From PyPI

Install the latest stable version of `lprof_ext` using `pip`:
```bash
pip3 install --no-cache-dir lprof_ext
```

### Prerequisites
 - Python 3.8 or higher
 - `line_profiler` (automatically installed as a dependency)

### Usage
To profile a Python script, run the following command, replacing `<entrypoint.py>` with the path to your script:
```bash
# [Important] - You must run at project root for *.py file scanning.
lprof_ext <entrypoint.py>
```

### Example
Suppose you have a script named `example.py`:
```python

def compute_fibonacci(n):
    if n <= 1:
        return n
    return compute_fibonacci(n-1) + compute_fibonacci(n-2)

def main():
    result = compute_fibonacci(30)
    print(f"Result: {result}")

if __name__ == "__main__":
    main()
```

Run the profiler:
```bash
lprof_ext example.py
```

After execution, `lprof_ext` will output performance statistics into `profile.json`, showing execution time, number of calls, and percentage of time spent on each line of code in the profiled functions.

## Output
The output will be store in JSON format. You can visualize it using our GUI tool [`prof_gui`](https://github.com/RuProf/prof_gui)

```bash
docker run --rm -d --name prof_gui \
           -v ./profile.json:/profile.json \
           -p 8080:8080 \
           ruprof/prof_gui:rs
```



## Build from Source
If you prefer to build lprof_ext from source (e.g., to use the latest development version or contribute), follow these steps:
1. Clone the repository (replace <repository-url> with the actual URL):
```bash

git clone https://github.com/RuProf/lprof_ext
cd lprof_ext
```
2. Set up a virtual environment (optional but recommended):
```bash
python3 -m venv .venv
source .venv/bin/activate
```

3. Install dependencies and build the package using uv (or pip if uv is unavailable):
```bash
uv sync
pip3 install .
```

4. Verify the installation:
```bash
lprof_ext -h
```

### Requirements for Building
- uv (optional, for dependency management; install via pip install uv)
- setuptools and wheel (for building the package)

## Reference
`lprof_ext` is built on top of the excellent `line_profiler` library. For more details on how line-by-line profiling works, refer to the official documentation:

[line_profiler](https://github.com/pyutils/line_profiler)
