# pyftrace
## Introduction
**pyftrace** is a lightweight Python function tracing tool designed to monitor and report on function calls within Python scripts. It leverages Python 3.12's built-in monitoring capabilities to provide insights into the execution flow of your programs. With pyftrace, you can trace function calls across multiple modules, visualize call hierarchies, and generate execution time reports.
Key features of pyftrace include:
- **Function Call Tracing**: Monitor calls to functions in your script and imported modules.
- **Built-in Function Tracing**: Optionally trace built-in functions like `print` using the `--verbose` flag.
- **Multiple Module Support**: Trace functions across multiple files within your project.
- **Execution Reports**: Generate reports detailing function execution times and call counts with the `--report` flag.
- **Customizable Output**: Use the `--path` flag to include file paths in tracing output, aiding in debugging and code analysis.
## Usage
### Requirements
- **Python Version**: pyftrace requires **Python 3.12** or higher due to its use of the new `sys.monitoring` module introduced in Python 3.12.
```bash
$ pyftrace [options] script_path
```
- `script_path`: The path to the Python script you want to trace.
### Installation
### Command-Line Options
- `--report`: Generate a report of function execution times and call counts at the end of the script's execution.
- `--verbose`: Enable tracing of built-in functions (e.g., print, len). Without this flag, pyftrace only traces user-defined functions.
- `--path`: Include file paths in the tracing output. This is particularly useful when working with multiple modules, as it shows where each function is defined and called.
- `-h` or `--help`: Display help information about pyftrace and its options.
## Examples
The `examples/` directory contains a variety of Python files that can be traced using pyftrace.
When a function is called, pyftrace displays it in the following format:
```
Called {function} @ {defined file path}:{defined line} from {called file path}:{called line}
```
- `{function}`: name of the function being called
- `{defined file path}`: file path where the function is defined (enabled with `--path` option)
- `{defined line}`" line number in the defined file
- `{called line}` line number in the calling file
- `{called file path}` path to the file that contains the calling function (enabled with `--path` option)
In this example, `main.py` imports and calls functions from `module_a.py` and `module_b.py`. We'll use pyftrace to trace these function calls and understand the flow of execution.
```python
# module_a.py
def function_a():
print("Function A is called.")
return "Result from function A"
```
```python
# module_b.py
def function_b():
print("Function B is called.")
return "Result from function B"
```
```python
# main.py
from module_a import function_a
from module_b import function_b
def main():
result_a = function_a()
result_b = function_b()
print(f"Results: {result_a}, {result_b}")
if __name__ == "__main__":
main()
```
### Basic Tracing
To trace function calls in main.py without including built-in functions or file paths:
```
$ pyftrace examples/module_trace/main.py
```
output:
```
Running script: examples/module_trace/main.py
Called main:4 from line 10
Called function_a:1 from line 5
Function A is called.
Returning function_a-> Result from function A
Called function_b:1 from line 6
Function B is called.
Returning function_b-> Result from function B
Results: Result from function A, Result from function B
Returning main-> None
Returning <module>-> None
```
### Including Built-in Functions with `--verbose`
```
$ pyftrace --verbose examples/module_trace/main.py
```
output:
```
Running script: examples/module_trace/main.py
Called main:4 from line 10
Called function_a:1 from line 5
Called print from line 2
Function A is called.
Returning print
Returning function_a-> Result from function A
Called function_b:1 from line 6
Called print from line 2
Function B is called.
Returning print
Returning function_b-> Result from function B
Called print from line 7
Results: Result from function A, Result from function B
Returning print
Returning main-> None
Returning <module>-> None
```
### Showing File Paths with `--path`
```
$ pyftrace --path examples/module_trace/main.py
```
output:
```
Running script: examples/module_trace/main.py
Called main@/path/to/examples/module_trace/main.py:4 from line 10 @ examples/module_trace/main.py
Called function_a@/path/to/examples/module_trace/module_a.py:1 from line 5 @ examples/module_trace/main.py
Function A is called.
Returning function_a-> Result from function A @ /path/to/examples/module_trace/module_a.py
Called function_b@/path/to/examples/module_trace/module_b.py:1 from line 6 @ examples/module_trace/main.py
Function B is called.
Returning function_b-> Result from function B @ /path/to/examples/module_trace/module_b.py
Results: Result from function A, Result from function B
Returning main-> None @ /path/to/examples/module_trace/main.py
Returning <module>-> None @ /path/to/examples/module_trace/main.py
```
### Generating an Execution Report
To generate a summary report of function execution times and call counts:
```
$ pyftrace --report examples/module_trace/main.py
```
output:
```
Running script: examples/module_trace/main.py
Returning <module>-> None
Function Name | Total Execution Time | Call Count
---------------------------------------------------------
main | 0.000123 seconds | 1
function_a | 0.000456 seconds | 1
function_b | 0.000789 seconds | 1
```
### Combining `--verbose` and `--path`
To trace built-in functions and include file paths:
```
$ pyftrace --verbose --path examples/module_trace/main.py
```
output:
```
Running script: examples/module_trace/main.py
Called main@/path/to/examples/module_trace/main.py:4 from line 10 @ examples/module_trace/main.py
Called function_a@/path/to/examples/module_trace/module_a.py:1 from line 5 @ examples/module_trace/main.py
Called print@<builtin> from line 2 @ /path/to/examples/module_trace/module_a.py
Function A is called.
Returning print @ /path/to/examples/module_trace/module_a.py
Returning function_a-> Result from function A @ /path/to/examples/module_trace/module_a.py
Called function_b@/path/to/examples/module_trace/module_b.py:1 from line 6 @ examples/module_trace/main.py
Called print@<builtin> from line 2 @ /path/to/examples/module_trace/module_b.py
Function B is called.
Returning print @ /path/to/examples/module_trace/module_b.py
Returning function_b-> Result from function B @ /path/to/examples/module_trace/module_b.py
Called print@<builtin> from line 7 @ examples/module_trace/main.py
Results: Result from function A, Result from function B
Returning print @ examples/module_trace/main.py
Returning main-> None @ /path/to/examples/module_trace/main.py
Returning <module>-> None @ /path/to/examples/module_trace/main.py
```
### Notes
- simple-pyftrace.py is a simplified pyftrace script for the [Pycon Korea 2024](https://2024.pycon.kr/) presentation. It is about 100 lines of code, but has limited functionality.
- Indentation: The indentation in the output represents the call hierarchy, making it easier to visualize which functions are calling others.
- Returning Statements: When a function returns, pyftrace logs the return value.
- File Paths: File paths are absolute paths. You can modify the code to display relative paths if preferred.
## LICENESE
MIT
See [LICENSE](./LICENSE) for more infomation
## See Also
pyftrace is heavily inspired by:
- [ftrace](https://www.kernel.org/doc/Documentation/trace/ftrace.txt): Ftrace is an internal tracer for linux kernel.
- [uftrace](https://github.com/namhyung/uftrace): uftrace is a function call graph tracer for C, C++, Rust and Python programs.
Raw data
{
"_id": null,
"home_page": "https://github.com/kangtegong/pyftrace",
"name": "pyftrace",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": null,
"author": "Kang Minchul",
"author_email": "tegongkang@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/a1/90/8f9df9de663b38e8b28e88bfcc18c8c2d6c849bd82a10b2fa1cb9bc86543/pyftrace-0.1.0.tar.gz",
"platform": null,
"description": "# pyftrace\n\n## Introduction\n\n**pyftrace** is a lightweight Python function tracing tool designed to monitor and report on function calls within Python scripts. It leverages Python 3.12's built-in monitoring capabilities to provide insights into the execution flow of your programs. With pyftrace, you can trace function calls across multiple modules, visualize call hierarchies, and generate execution time reports.\n\nKey features of pyftrace include:\n\n- **Function Call Tracing**: Monitor calls to functions in your script and imported modules.\n- **Built-in Function Tracing**: Optionally trace built-in functions like `print` using the `--verbose` flag.\n- **Multiple Module Support**: Trace functions across multiple files within your project.\n- **Execution Reports**: Generate reports detailing function execution times and call counts with the `--report` flag.\n- **Customizable Output**: Use the `--path` flag to include file paths in tracing output, aiding in debugging and code analysis.\n\n## Usage\n\n### Requirements\n\n- **Python Version**: pyftrace requires **Python 3.12** or higher due to its use of the new `sys.monitoring` module introduced in Python 3.12.\n\n```bash\n$ pyftrace [options] script_path\n```\n\n- `script_path`: The path to the Python script you want to trace.\n\n\n### Installation\n\n\n\n\n### Command-Line Options\n\n- `--report`: Generate a report of function execution times and call counts at the end of the script's execution.\n- `--verbose`: Enable tracing of built-in functions (e.g., print, len). Without this flag, pyftrace only traces user-defined functions.\n- `--path`: Include file paths in the tracing output. This is particularly useful when working with multiple modules, as it shows where each function is defined and called.\n- `-h` or `--help`: Display help information about pyftrace and its options.\n\n## Examples\n\nThe `examples/` directory contains a variety of Python files that can be traced using pyftrace. \n\nWhen a function is called, pyftrace displays it in the following format:\n\n```\nCalled {function} @ {defined file path}:{defined line} from {called file path}:{called line}\n```\n\n- `{function}`: name of the function being called \n- `{defined file path}`: file path where the function is defined (enabled with `--path` option)\n- `{defined line}`\" line number in the defined file\n- `{called line}` line number in the calling file\n- `{called file path}` path to the file that contains the calling function (enabled with `--path` option)\n\nIn this example, `main.py` imports and calls functions from `module_a.py` and `module_b.py`. We'll use pyftrace to trace these function calls and understand the flow of execution.\n\n```python\n# module_a.py\ndef function_a():\n print(\"Function A is called.\")\n return \"Result from function A\"\n```\n\n```python\n# module_b.py\ndef function_b():\n print(\"Function B is called.\")\n return \"Result from function B\"\n```\n\n```python\n# main.py\nfrom module_a import function_a\nfrom module_b import function_b\n\ndef main():\n result_a = function_a()\n result_b = function_b()\n print(f\"Results: {result_a}, {result_b}\")\n\nif __name__ == \"__main__\":\n main()\n```\n\n### Basic Tracing\n\nTo trace function calls in main.py without including built-in functions or file paths:\n\n\n```\n$ pyftrace examples/module_trace/main.py\n```\n\noutput:\n```\nRunning script: examples/module_trace/main.py\nCalled main:4 from line 10\n Called function_a:1 from line 5\nFunction A is called.\n Returning function_a-> Result from function A\n Called function_b:1 from line 6\nFunction B is called.\n Returning function_b-> Result from function B\nResults: Result from function A, Result from function B\n Returning main-> None\nReturning <module>-> None\n```\n\n### Including Built-in Functions with `--verbose`\n\n```\n$ pyftrace --verbose examples/module_trace/main.py\n```\n\noutput:\n```\nRunning script: examples/module_trace/main.py\nCalled main:4 from line 10\n Called function_a:1 from line 5\n Called print from line 2\nFunction A is called.\n Returning print\n Returning function_a-> Result from function A\n Called function_b:1 from line 6\n Called print from line 2\nFunction B is called.\n Returning print\n Returning function_b-> Result from function B\n Called print from line 7\nResults: Result from function A, Result from function B\n Returning print\n Returning main-> None\nReturning <module>-> None\n```\n\n### Showing File Paths with `--path`\n\n```\n$ pyftrace --path examples/module_trace/main.py\n```\n\noutput:\n```\nRunning script: examples/module_trace/main.py\nCalled main@/path/to/examples/module_trace/main.py:4 from line 10 @ examples/module_trace/main.py\n Called function_a@/path/to/examples/module_trace/module_a.py:1 from line 5 @ examples/module_trace/main.py\nFunction A is called.\n Returning function_a-> Result from function A @ /path/to/examples/module_trace/module_a.py\n Called function_b@/path/to/examples/module_trace/module_b.py:1 from line 6 @ examples/module_trace/main.py\nFunction B is called.\n Returning function_b-> Result from function B @ /path/to/examples/module_trace/module_b.py\nResults: Result from function A, Result from function B\n Returning main-> None @ /path/to/examples/module_trace/main.py\nReturning <module>-> None @ /path/to/examples/module_trace/main.py\n```\n\n### Generating an Execution Report\n\nTo generate a summary report of function execution times and call counts:\n\n```\n$ pyftrace --report examples/module_trace/main.py\n```\n\noutput:\n```\nRunning script: examples/module_trace/main.py\nReturning <module>-> None\n\nFunction Name | Total Execution Time | Call Count\n---------------------------------------------------------\nmain | 0.000123 seconds | 1\nfunction_a | 0.000456 seconds | 1\nfunction_b | 0.000789 seconds | 1\n```\n\n### Combining `--verbose` and `--path`\n\nTo trace built-in functions and include file paths:\n\n```\n$ pyftrace --verbose --path examples/module_trace/main.py\n```\n\noutput:\n```\nRunning script: examples/module_trace/main.py\nCalled main@/path/to/examples/module_trace/main.py:4 from line 10 @ examples/module_trace/main.py\n Called function_a@/path/to/examples/module_trace/module_a.py:1 from line 5 @ examples/module_trace/main.py\n Called print@<builtin> from line 2 @ /path/to/examples/module_trace/module_a.py\nFunction A is called.\n Returning print @ /path/to/examples/module_trace/module_a.py\n Returning function_a-> Result from function A @ /path/to/examples/module_trace/module_a.py\n Called function_b@/path/to/examples/module_trace/module_b.py:1 from line 6 @ examples/module_trace/main.py\n Called print@<builtin> from line 2 @ /path/to/examples/module_trace/module_b.py\nFunction B is called.\n Returning print @ /path/to/examples/module_trace/module_b.py\n Returning function_b-> Result from function B @ /path/to/examples/module_trace/module_b.py\n Called print@<builtin> from line 7 @ examples/module_trace/main.py\nResults: Result from function A, Result from function B\n Returning print @ examples/module_trace/main.py\n Returning main-> None @ /path/to/examples/module_trace/main.py\nReturning <module>-> None @ /path/to/examples/module_trace/main.py\n```\n\n### Notes\n- simple-pyftrace.py is a simplified pyftrace script for the [Pycon Korea 2024](https://2024.pycon.kr/) presentation. It is about 100 lines of code, but has limited functionality. \n- Indentation: The indentation in the output represents the call hierarchy, making it easier to visualize which functions are calling others.\n- Returning Statements: When a function returns, pyftrace logs the return value.\n- File Paths: File paths are absolute paths. You can modify the code to display relative paths if preferred.\n\n## LICENESE\n\nMIT \n\nSee [LICENSE](./LICENSE) for more infomation\n\n## See Also\n\npyftrace is heavily inspired by:\n\n- [ftrace](https://www.kernel.org/doc/Documentation/trace/ftrace.txt): Ftrace is an internal tracer for linux kernel.\n- [uftrace](https://github.com/namhyung/uftrace): uftrace is a function call graph tracer for C, C++, Rust and Python programs. \n",
"bugtrack_url": null,
"license": null,
"summary": "Python function tracing tool.",
"version": "0.1.0",
"project_urls": {
"Homepage": "https://github.com/kangtegong/pyftrace"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "39977d85700a5bf2a372d986d33f332ddcc7ab69034becaf36d379c7d1f69298",
"md5": "b95cd7f625cbdf9385ed4606f00fcad4",
"sha256": "96a49c6cfcd4e9b8b155f37365fc2f2d595a126cf5450583b084616b1542f6af"
},
"downloads": -1,
"filename": "pyftrace-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b95cd7f625cbdf9385ed4606f00fcad4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 7942,
"upload_time": "2024-10-26T14:10:44",
"upload_time_iso_8601": "2024-10-26T14:10:44.363533Z",
"url": "https://files.pythonhosted.org/packages/39/97/7d85700a5bf2a372d986d33f332ddcc7ab69034becaf36d379c7d1f69298/pyftrace-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a1908f9df9de663b38e8b28e88bfcc18c8c2d6c849bd82a10b2fa1cb9bc86543",
"md5": "34b5696a6c9ebe227d2157d11efeff4d",
"sha256": "134e8c956740149554fe24ccdb914aaa7519f0af66c8d55c1d776190269afe73"
},
"downloads": -1,
"filename": "pyftrace-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "34b5696a6c9ebe227d2157d11efeff4d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 8862,
"upload_time": "2024-10-26T14:10:46",
"upload_time_iso_8601": "2024-10-26T14:10:46.315360Z",
"url": "https://files.pythonhosted.org/packages/a1/90/8f9df9de663b38e8b28e88bfcc18c8c2d6c849bd82a10b2fa1cb9bc86543/pyftrace-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-26 14:10:46",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "kangtegong",
"github_project": "pyftrace",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "pyftrace"
}
JSON
