pyftrace 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- pyftrace-0.1.0/LICENSE +21 -0
- pyftrace-0.1.0/PKG-INFO +235 -0
- pyftrace-0.1.0/README.md +224 -0
- pyftrace-0.1.0/pyftrace/__init__.py +2 -0
- pyftrace-0.1.0/pyftrace/main.py +35 -0
- pyftrace-0.1.0/pyftrace/tracer.py +234 -0
- pyftrace-0.1.0/pyftrace/utils.py +35 -0
- pyftrace-0.1.0/pyftrace.egg-info/PKG-INFO +235 -0
- pyftrace-0.1.0/pyftrace.egg-info/SOURCES.txt +13 -0
- pyftrace-0.1.0/pyftrace.egg-info/dependency_links.txt +1 -0
- pyftrace-0.1.0/pyftrace.egg-info/entry_points.txt +2 -0
- pyftrace-0.1.0/pyftrace.egg-info/top_level.txt +1 -0
- pyftrace-0.1.0/pyproject.toml +3 -0
- pyftrace-0.1.0/setup.cfg +4 -0
- pyftrace-0.1.0/setup.py +20 -0
pyftrace-0.1.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2024 Kang Minchul
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
pyftrace-0.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,235 @@
|
|
|
1
|
+
Metadata-Version: 2.1
|
|
2
|
+
Name: pyftrace
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Python function tracing tool.
|
|
5
|
+
Home-page: https://github.com/kangtegong/pyftrace
|
|
6
|
+
Author: Kang Minchul
|
|
7
|
+
Author-email: tegongkang@gmail.com
|
|
8
|
+
Requires-Python: >=3.12
|
|
9
|
+
Description-Content-Type: text/markdown
|
|
10
|
+
License-File: LICENSE
|
|
11
|
+
|
|
12
|
+
# pyftrace
|
|
13
|
+
|
|
14
|
+
## Introduction
|
|
15
|
+
|
|
16
|
+
**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.
|
|
17
|
+
|
|
18
|
+
Key features of pyftrace include:
|
|
19
|
+
|
|
20
|
+
- **Function Call Tracing**: Monitor calls to functions in your script and imported modules.
|
|
21
|
+
- **Built-in Function Tracing**: Optionally trace built-in functions like `print` using the `--verbose` flag.
|
|
22
|
+
- **Multiple Module Support**: Trace functions across multiple files within your project.
|
|
23
|
+
- **Execution Reports**: Generate reports detailing function execution times and call counts with the `--report` flag.
|
|
24
|
+
- **Customizable Output**: Use the `--path` flag to include file paths in tracing output, aiding in debugging and code analysis.
|
|
25
|
+
|
|
26
|
+
## Usage
|
|
27
|
+
|
|
28
|
+
### Requirements
|
|
29
|
+
|
|
30
|
+
- **Python Version**: pyftrace requires **Python 3.12** or higher due to its use of the new `sys.monitoring` module introduced in Python 3.12.
|
|
31
|
+
|
|
32
|
+
```bash
|
|
33
|
+
$ pyftrace [options] script_path
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
- `script_path`: The path to the Python script you want to trace.
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
### Installation
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
### Command-Line Options
|
|
45
|
+
|
|
46
|
+
- `--report`: Generate a report of function execution times and call counts at the end of the script's execution.
|
|
47
|
+
- `--verbose`: Enable tracing of built-in functions (e.g., print, len). Without this flag, pyftrace only traces user-defined functions.
|
|
48
|
+
- `--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.
|
|
49
|
+
- `-h` or `--help`: Display help information about pyftrace and its options.
|
|
50
|
+
|
|
51
|
+
## Examples
|
|
52
|
+
|
|
53
|
+
The `examples/` directory contains a variety of Python files that can be traced using pyftrace.
|
|
54
|
+
|
|
55
|
+
When a function is called, pyftrace displays it in the following format:
|
|
56
|
+
|
|
57
|
+
```
|
|
58
|
+
Called {function} @ {defined file path}:{defined line} from {called file path}:{called line}
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
- `{function}`: name of the function being called
|
|
62
|
+
- `{defined file path}`: file path where the function is defined (enabled with `--path` option)
|
|
63
|
+
- `{defined line}`" line number in the defined file
|
|
64
|
+
- `{called line}` line number in the calling file
|
|
65
|
+
- `{called file path}` path to the file that contains the calling function (enabled with `--path` option)
|
|
66
|
+
|
|
67
|
+
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.
|
|
68
|
+
|
|
69
|
+
```python
|
|
70
|
+
# module_a.py
|
|
71
|
+
def function_a():
|
|
72
|
+
print("Function A is called.")
|
|
73
|
+
return "Result from function A"
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
```python
|
|
77
|
+
# module_b.py
|
|
78
|
+
def function_b():
|
|
79
|
+
print("Function B is called.")
|
|
80
|
+
return "Result from function B"
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
```python
|
|
84
|
+
# main.py
|
|
85
|
+
from module_a import function_a
|
|
86
|
+
from module_b import function_b
|
|
87
|
+
|
|
88
|
+
def main():
|
|
89
|
+
result_a = function_a()
|
|
90
|
+
result_b = function_b()
|
|
91
|
+
print(f"Results: {result_a}, {result_b}")
|
|
92
|
+
|
|
93
|
+
if __name__ == "__main__":
|
|
94
|
+
main()
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
### Basic Tracing
|
|
98
|
+
|
|
99
|
+
To trace function calls in main.py without including built-in functions or file paths:
|
|
100
|
+
|
|
101
|
+
|
|
102
|
+
```
|
|
103
|
+
$ pyftrace examples/module_trace/main.py
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
output:
|
|
107
|
+
```
|
|
108
|
+
Running script: examples/module_trace/main.py
|
|
109
|
+
Called main:4 from line 10
|
|
110
|
+
Called function_a:1 from line 5
|
|
111
|
+
Function A is called.
|
|
112
|
+
Returning function_a-> Result from function A
|
|
113
|
+
Called function_b:1 from line 6
|
|
114
|
+
Function B is called.
|
|
115
|
+
Returning function_b-> Result from function B
|
|
116
|
+
Results: Result from function A, Result from function B
|
|
117
|
+
Returning main-> None
|
|
118
|
+
Returning <module>-> None
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
### Including Built-in Functions with `--verbose`
|
|
122
|
+
|
|
123
|
+
```
|
|
124
|
+
$ pyftrace --verbose examples/module_trace/main.py
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
output:
|
|
128
|
+
```
|
|
129
|
+
Running script: examples/module_trace/main.py
|
|
130
|
+
Called main:4 from line 10
|
|
131
|
+
Called function_a:1 from line 5
|
|
132
|
+
Called print from line 2
|
|
133
|
+
Function A is called.
|
|
134
|
+
Returning print
|
|
135
|
+
Returning function_a-> Result from function A
|
|
136
|
+
Called function_b:1 from line 6
|
|
137
|
+
Called print from line 2
|
|
138
|
+
Function B is called.
|
|
139
|
+
Returning print
|
|
140
|
+
Returning function_b-> Result from function B
|
|
141
|
+
Called print from line 7
|
|
142
|
+
Results: Result from function A, Result from function B
|
|
143
|
+
Returning print
|
|
144
|
+
Returning main-> None
|
|
145
|
+
Returning <module>-> None
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
### Showing File Paths with `--path`
|
|
149
|
+
|
|
150
|
+
```
|
|
151
|
+
$ pyftrace --path examples/module_trace/main.py
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
output:
|
|
155
|
+
```
|
|
156
|
+
Running script: examples/module_trace/main.py
|
|
157
|
+
Called main@/path/to/examples/module_trace/main.py:4 from line 10 @ examples/module_trace/main.py
|
|
158
|
+
Called function_a@/path/to/examples/module_trace/module_a.py:1 from line 5 @ examples/module_trace/main.py
|
|
159
|
+
Function A is called.
|
|
160
|
+
Returning function_a-> Result from function A @ /path/to/examples/module_trace/module_a.py
|
|
161
|
+
Called function_b@/path/to/examples/module_trace/module_b.py:1 from line 6 @ examples/module_trace/main.py
|
|
162
|
+
Function B is called.
|
|
163
|
+
Returning function_b-> Result from function B @ /path/to/examples/module_trace/module_b.py
|
|
164
|
+
Results: Result from function A, Result from function B
|
|
165
|
+
Returning main-> None @ /path/to/examples/module_trace/main.py
|
|
166
|
+
Returning <module>-> None @ /path/to/examples/module_trace/main.py
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
### Generating an Execution Report
|
|
170
|
+
|
|
171
|
+
To generate a summary report of function execution times and call counts:
|
|
172
|
+
|
|
173
|
+
```
|
|
174
|
+
$ pyftrace --report examples/module_trace/main.py
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
output:
|
|
178
|
+
```
|
|
179
|
+
Running script: examples/module_trace/main.py
|
|
180
|
+
Returning <module>-> None
|
|
181
|
+
|
|
182
|
+
Function Name | Total Execution Time | Call Count
|
|
183
|
+
---------------------------------------------------------
|
|
184
|
+
main | 0.000123 seconds | 1
|
|
185
|
+
function_a | 0.000456 seconds | 1
|
|
186
|
+
function_b | 0.000789 seconds | 1
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
### Combining `--verbose` and `--path`
|
|
190
|
+
|
|
191
|
+
To trace built-in functions and include file paths:
|
|
192
|
+
|
|
193
|
+
```
|
|
194
|
+
$ pyftrace --verbose --path examples/module_trace/main.py
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
output:
|
|
198
|
+
```
|
|
199
|
+
Running script: examples/module_trace/main.py
|
|
200
|
+
Called main@/path/to/examples/module_trace/main.py:4 from line 10 @ examples/module_trace/main.py
|
|
201
|
+
Called function_a@/path/to/examples/module_trace/module_a.py:1 from line 5 @ examples/module_trace/main.py
|
|
202
|
+
Called print@<builtin> from line 2 @ /path/to/examples/module_trace/module_a.py
|
|
203
|
+
Function A is called.
|
|
204
|
+
Returning print @ /path/to/examples/module_trace/module_a.py
|
|
205
|
+
Returning function_a-> Result from function A @ /path/to/examples/module_trace/module_a.py
|
|
206
|
+
Called function_b@/path/to/examples/module_trace/module_b.py:1 from line 6 @ examples/module_trace/main.py
|
|
207
|
+
Called print@<builtin> from line 2 @ /path/to/examples/module_trace/module_b.py
|
|
208
|
+
Function B is called.
|
|
209
|
+
Returning print @ /path/to/examples/module_trace/module_b.py
|
|
210
|
+
Returning function_b-> Result from function B @ /path/to/examples/module_trace/module_b.py
|
|
211
|
+
Called print@<builtin> from line 7 @ examples/module_trace/main.py
|
|
212
|
+
Results: Result from function A, Result from function B
|
|
213
|
+
Returning print @ examples/module_trace/main.py
|
|
214
|
+
Returning main-> None @ /path/to/examples/module_trace/main.py
|
|
215
|
+
Returning <module>-> None @ /path/to/examples/module_trace/main.py
|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
### Notes
|
|
219
|
+
- 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.
|
|
220
|
+
- Indentation: The indentation in the output represents the call hierarchy, making it easier to visualize which functions are calling others.
|
|
221
|
+
- Returning Statements: When a function returns, pyftrace logs the return value.
|
|
222
|
+
- File Paths: File paths are absolute paths. You can modify the code to display relative paths if preferred.
|
|
223
|
+
|
|
224
|
+
## LICENESE
|
|
225
|
+
|
|
226
|
+
MIT
|
|
227
|
+
|
|
228
|
+
See [LICENSE](./LICENSE) for more infomation
|
|
229
|
+
|
|
230
|
+
## See Also
|
|
231
|
+
|
|
232
|
+
pyftrace is heavily inspired by:
|
|
233
|
+
|
|
234
|
+
- [ftrace](https://www.kernel.org/doc/Documentation/trace/ftrace.txt): Ftrace is an internal tracer for linux kernel.
|
|
235
|
+
- [uftrace](https://github.com/namhyung/uftrace): uftrace is a function call graph tracer for C, C++, Rust and Python programs.
|
pyftrace-0.1.0/README.md
ADDED
|
@@ -0,0 +1,224 @@
|
|
|
1
|
+
# pyftrace
|
|
2
|
+
|
|
3
|
+
## Introduction
|
|
4
|
+
|
|
5
|
+
**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.
|
|
6
|
+
|
|
7
|
+
Key features of pyftrace include:
|
|
8
|
+
|
|
9
|
+
- **Function Call Tracing**: Monitor calls to functions in your script and imported modules.
|
|
10
|
+
- **Built-in Function Tracing**: Optionally trace built-in functions like `print` using the `--verbose` flag.
|
|
11
|
+
- **Multiple Module Support**: Trace functions across multiple files within your project.
|
|
12
|
+
- **Execution Reports**: Generate reports detailing function execution times and call counts with the `--report` flag.
|
|
13
|
+
- **Customizable Output**: Use the `--path` flag to include file paths in tracing output, aiding in debugging and code analysis.
|
|
14
|
+
|
|
15
|
+
## Usage
|
|
16
|
+
|
|
17
|
+
### Requirements
|
|
18
|
+
|
|
19
|
+
- **Python Version**: pyftrace requires **Python 3.12** or higher due to its use of the new `sys.monitoring` module introduced in Python 3.12.
|
|
20
|
+
|
|
21
|
+
```bash
|
|
22
|
+
$ pyftrace [options] script_path
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
- `script_path`: The path to the Python script you want to trace.
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
### Installation
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
### Command-Line Options
|
|
34
|
+
|
|
35
|
+
- `--report`: Generate a report of function execution times and call counts at the end of the script's execution.
|
|
36
|
+
- `--verbose`: Enable tracing of built-in functions (e.g., print, len). Without this flag, pyftrace only traces user-defined functions.
|
|
37
|
+
- `--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.
|
|
38
|
+
- `-h` or `--help`: Display help information about pyftrace and its options.
|
|
39
|
+
|
|
40
|
+
## Examples
|
|
41
|
+
|
|
42
|
+
The `examples/` directory contains a variety of Python files that can be traced using pyftrace.
|
|
43
|
+
|
|
44
|
+
When a function is called, pyftrace displays it in the following format:
|
|
45
|
+
|
|
46
|
+
```
|
|
47
|
+
Called {function} @ {defined file path}:{defined line} from {called file path}:{called line}
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
- `{function}`: name of the function being called
|
|
51
|
+
- `{defined file path}`: file path where the function is defined (enabled with `--path` option)
|
|
52
|
+
- `{defined line}`" line number in the defined file
|
|
53
|
+
- `{called line}` line number in the calling file
|
|
54
|
+
- `{called file path}` path to the file that contains the calling function (enabled with `--path` option)
|
|
55
|
+
|
|
56
|
+
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.
|
|
57
|
+
|
|
58
|
+
```python
|
|
59
|
+
# module_a.py
|
|
60
|
+
def function_a():
|
|
61
|
+
print("Function A is called.")
|
|
62
|
+
return "Result from function A"
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
```python
|
|
66
|
+
# module_b.py
|
|
67
|
+
def function_b():
|
|
68
|
+
print("Function B is called.")
|
|
69
|
+
return "Result from function B"
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
```python
|
|
73
|
+
# main.py
|
|
74
|
+
from module_a import function_a
|
|
75
|
+
from module_b import function_b
|
|
76
|
+
|
|
77
|
+
def main():
|
|
78
|
+
result_a = function_a()
|
|
79
|
+
result_b = function_b()
|
|
80
|
+
print(f"Results: {result_a}, {result_b}")
|
|
81
|
+
|
|
82
|
+
if __name__ == "__main__":
|
|
83
|
+
main()
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
### Basic Tracing
|
|
87
|
+
|
|
88
|
+
To trace function calls in main.py without including built-in functions or file paths:
|
|
89
|
+
|
|
90
|
+
|
|
91
|
+
```
|
|
92
|
+
$ pyftrace examples/module_trace/main.py
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
output:
|
|
96
|
+
```
|
|
97
|
+
Running script: examples/module_trace/main.py
|
|
98
|
+
Called main:4 from line 10
|
|
99
|
+
Called function_a:1 from line 5
|
|
100
|
+
Function A is called.
|
|
101
|
+
Returning function_a-> Result from function A
|
|
102
|
+
Called function_b:1 from line 6
|
|
103
|
+
Function B is called.
|
|
104
|
+
Returning function_b-> Result from function B
|
|
105
|
+
Results: Result from function A, Result from function B
|
|
106
|
+
Returning main-> None
|
|
107
|
+
Returning <module>-> None
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
### Including Built-in Functions with `--verbose`
|
|
111
|
+
|
|
112
|
+
```
|
|
113
|
+
$ pyftrace --verbose examples/module_trace/main.py
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
output:
|
|
117
|
+
```
|
|
118
|
+
Running script: examples/module_trace/main.py
|
|
119
|
+
Called main:4 from line 10
|
|
120
|
+
Called function_a:1 from line 5
|
|
121
|
+
Called print from line 2
|
|
122
|
+
Function A is called.
|
|
123
|
+
Returning print
|
|
124
|
+
Returning function_a-> Result from function A
|
|
125
|
+
Called function_b:1 from line 6
|
|
126
|
+
Called print from line 2
|
|
127
|
+
Function B is called.
|
|
128
|
+
Returning print
|
|
129
|
+
Returning function_b-> Result from function B
|
|
130
|
+
Called print from line 7
|
|
131
|
+
Results: Result from function A, Result from function B
|
|
132
|
+
Returning print
|
|
133
|
+
Returning main-> None
|
|
134
|
+
Returning <module>-> None
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
### Showing File Paths with `--path`
|
|
138
|
+
|
|
139
|
+
```
|
|
140
|
+
$ pyftrace --path examples/module_trace/main.py
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
output:
|
|
144
|
+
```
|
|
145
|
+
Running script: examples/module_trace/main.py
|
|
146
|
+
Called main@/path/to/examples/module_trace/main.py:4 from line 10 @ examples/module_trace/main.py
|
|
147
|
+
Called function_a@/path/to/examples/module_trace/module_a.py:1 from line 5 @ examples/module_trace/main.py
|
|
148
|
+
Function A is called.
|
|
149
|
+
Returning function_a-> Result from function A @ /path/to/examples/module_trace/module_a.py
|
|
150
|
+
Called function_b@/path/to/examples/module_trace/module_b.py:1 from line 6 @ examples/module_trace/main.py
|
|
151
|
+
Function B is called.
|
|
152
|
+
Returning function_b-> Result from function B @ /path/to/examples/module_trace/module_b.py
|
|
153
|
+
Results: Result from function A, Result from function B
|
|
154
|
+
Returning main-> None @ /path/to/examples/module_trace/main.py
|
|
155
|
+
Returning <module>-> None @ /path/to/examples/module_trace/main.py
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
### Generating an Execution Report
|
|
159
|
+
|
|
160
|
+
To generate a summary report of function execution times and call counts:
|
|
161
|
+
|
|
162
|
+
```
|
|
163
|
+
$ pyftrace --report examples/module_trace/main.py
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
output:
|
|
167
|
+
```
|
|
168
|
+
Running script: examples/module_trace/main.py
|
|
169
|
+
Returning <module>-> None
|
|
170
|
+
|
|
171
|
+
Function Name | Total Execution Time | Call Count
|
|
172
|
+
---------------------------------------------------------
|
|
173
|
+
main | 0.000123 seconds | 1
|
|
174
|
+
function_a | 0.000456 seconds | 1
|
|
175
|
+
function_b | 0.000789 seconds | 1
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
### Combining `--verbose` and `--path`
|
|
179
|
+
|
|
180
|
+
To trace built-in functions and include file paths:
|
|
181
|
+
|
|
182
|
+
```
|
|
183
|
+
$ pyftrace --verbose --path examples/module_trace/main.py
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
output:
|
|
187
|
+
```
|
|
188
|
+
Running script: examples/module_trace/main.py
|
|
189
|
+
Called main@/path/to/examples/module_trace/main.py:4 from line 10 @ examples/module_trace/main.py
|
|
190
|
+
Called function_a@/path/to/examples/module_trace/module_a.py:1 from line 5 @ examples/module_trace/main.py
|
|
191
|
+
Called print@<builtin> from line 2 @ /path/to/examples/module_trace/module_a.py
|
|
192
|
+
Function A is called.
|
|
193
|
+
Returning print @ /path/to/examples/module_trace/module_a.py
|
|
194
|
+
Returning function_a-> Result from function A @ /path/to/examples/module_trace/module_a.py
|
|
195
|
+
Called function_b@/path/to/examples/module_trace/module_b.py:1 from line 6 @ examples/module_trace/main.py
|
|
196
|
+
Called print@<builtin> from line 2 @ /path/to/examples/module_trace/module_b.py
|
|
197
|
+
Function B is called.
|
|
198
|
+
Returning print @ /path/to/examples/module_trace/module_b.py
|
|
199
|
+
Returning function_b-> Result from function B @ /path/to/examples/module_trace/module_b.py
|
|
200
|
+
Called print@<builtin> from line 7 @ examples/module_trace/main.py
|
|
201
|
+
Results: Result from function A, Result from function B
|
|
202
|
+
Returning print @ examples/module_trace/main.py
|
|
203
|
+
Returning main-> None @ /path/to/examples/module_trace/main.py
|
|
204
|
+
Returning <module>-> None @ /path/to/examples/module_trace/main.py
|
|
205
|
+
```
|
|
206
|
+
|
|
207
|
+
### Notes
|
|
208
|
+
- 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.
|
|
209
|
+
- Indentation: The indentation in the output represents the call hierarchy, making it easier to visualize which functions are calling others.
|
|
210
|
+
- Returning Statements: When a function returns, pyftrace logs the return value.
|
|
211
|
+
- File Paths: File paths are absolute paths. You can modify the code to display relative paths if preferred.
|
|
212
|
+
|
|
213
|
+
## LICENESE
|
|
214
|
+
|
|
215
|
+
MIT
|
|
216
|
+
|
|
217
|
+
See [LICENSE](./LICENSE) for more infomation
|
|
218
|
+
|
|
219
|
+
## See Also
|
|
220
|
+
|
|
221
|
+
pyftrace is heavily inspired by:
|
|
222
|
+
|
|
223
|
+
- [ftrace](https://www.kernel.org/doc/Documentation/trace/ftrace.txt): Ftrace is an internal tracer for linux kernel.
|
|
224
|
+
- [uftrace](https://github.com/namhyung/uftrace): uftrace is a function call graph tracer for C, C++, Rust and Python programs.
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
import sys
|
|
2
|
+
import argparse
|
|
3
|
+
from .tracer import SimplePyftrace
|
|
4
|
+
|
|
5
|
+
def main():
|
|
6
|
+
if sys.version_info < (3, 12):
|
|
7
|
+
print("This tracer requires Python 3.12 or higher.")
|
|
8
|
+
sys.exit(1)
|
|
9
|
+
|
|
10
|
+
parser = argparse.ArgumentParser(
|
|
11
|
+
description=(
|
|
12
|
+
"Required Python version: 3.12+\n\n"
|
|
13
|
+
"Usage:\n"
|
|
14
|
+
" $ pyftrace [options] <script>\n"
|
|
15
|
+
),
|
|
16
|
+
formatter_class=argparse.RawTextHelpFormatter
|
|
17
|
+
)
|
|
18
|
+
|
|
19
|
+
parser.add_argument('script', help="Path to the Python script to run and trace")
|
|
20
|
+
parser.add_argument('--verbose', action='store_true', help="Enable built-in and third-party function tracing")
|
|
21
|
+
parser.add_argument('--path', action='store_true', help="Show file paths in tracing output")
|
|
22
|
+
parser.add_argument('--report', action='store_true', help="Generate a report of function execution counts & times")
|
|
23
|
+
args = parser.parse_args()
|
|
24
|
+
|
|
25
|
+
tracer = SimplePyftrace(verbose=args.verbose, show_path=args.path)
|
|
26
|
+
tracer.report_mode = args.report
|
|
27
|
+
|
|
28
|
+
tracer.run_python_script(args.script)
|
|
29
|
+
|
|
30
|
+
if tracer.report_mode:
|
|
31
|
+
tracer.print_report()
|
|
32
|
+
|
|
33
|
+
if __name__ == "__main__":
|
|
34
|
+
main()
|
|
35
|
+
|
|
@@ -0,0 +1,234 @@
|
|
|
1
|
+
import sys
|
|
2
|
+
import os
|
|
3
|
+
import time
|
|
4
|
+
import weakref
|
|
5
|
+
from .utils import get_site_packages_modules, timeit
|
|
6
|
+
|
|
7
|
+
class SimplePyftrace:
|
|
8
|
+
def __init__(self, verbose=False, show_path=False):
|
|
9
|
+
self.depth = 0
|
|
10
|
+
self.tool_id = 1
|
|
11
|
+
self.script_name = None
|
|
12
|
+
self.script_dir = None
|
|
13
|
+
self.report_mode = False
|
|
14
|
+
self.execution_report = {}
|
|
15
|
+
self.call_stack = []
|
|
16
|
+
self.verbose = verbose
|
|
17
|
+
self.show_path = show_path
|
|
18
|
+
self.tracer_script = os.path.abspath(__file__)
|
|
19
|
+
# Set tracer_dir to cover all tracer files
|
|
20
|
+
self.tracer_dir = os.path.dirname(self.tracer_script)
|
|
21
|
+
self.tracing_started = False
|
|
22
|
+
self.site_packages_modules = get_site_packages_modules()
|
|
23
|
+
|
|
24
|
+
def should_trace(self, file_name):
|
|
25
|
+
if not self.script_dir:
|
|
26
|
+
return False
|
|
27
|
+
abs_file_name = os.path.abspath(file_name)
|
|
28
|
+
if abs_file_name.startswith(self.tracer_dir):
|
|
29
|
+
return False
|
|
30
|
+
return abs_file_name.startswith(self.script_dir)
|
|
31
|
+
|
|
32
|
+
def is_tracer_code(self, file_name):
|
|
33
|
+
abs_file_name = os.path.abspath(file_name)
|
|
34
|
+
# Check if the file is within the tracer directory
|
|
35
|
+
return abs_file_name.startswith(self.tracer_dir)
|
|
36
|
+
|
|
37
|
+
def resolve_filename(self, code, callable_obj):
|
|
38
|
+
filename = ''
|
|
39
|
+
if code and code.co_filename:
|
|
40
|
+
filename = code.co_filename
|
|
41
|
+
if filename.startswith('<frozen ') and filename.endswith('>'):
|
|
42
|
+
module_name = filename[len('<frozen '):-1]
|
|
43
|
+
module = sys.modules.get(module_name)
|
|
44
|
+
if module and hasattr(module, '__file__'):
|
|
45
|
+
filename = module.__file__
|
|
46
|
+
if not filename and callable_obj:
|
|
47
|
+
if isinstance(callable_obj, weakref.ReferenceType):
|
|
48
|
+
callable_obj = callable_obj()
|
|
49
|
+
module_name = getattr(callable_obj, '__module__', None)
|
|
50
|
+
if module_name:
|
|
51
|
+
module = sys.modules.get(module_name)
|
|
52
|
+
if module and hasattr(module, '__file__'):
|
|
53
|
+
filename = module.__file__
|
|
54
|
+
return filename
|
|
55
|
+
|
|
56
|
+
def get_line_number(self, code, instruction_offset):
|
|
57
|
+
if code is None:
|
|
58
|
+
return 0
|
|
59
|
+
for start, end, lineno in code.co_lines():
|
|
60
|
+
if start <= instruction_offset < end:
|
|
61
|
+
return lineno
|
|
62
|
+
return code.co_firstlineno
|
|
63
|
+
|
|
64
|
+
@timeit
|
|
65
|
+
def monitor_call(self, code, instruction_offset, callable_obj, arg0):
|
|
66
|
+
if not self.tracing_started:
|
|
67
|
+
if code and os.path.abspath(code.co_filename) == os.path.abspath(self.script_name) and code.co_name == '<module>':
|
|
68
|
+
self.tracing_started = True
|
|
69
|
+
else:
|
|
70
|
+
return
|
|
71
|
+
|
|
72
|
+
call_lineno = self.get_line_number(code, instruction_offset)
|
|
73
|
+
call_filename = self.resolve_filename(code, None)
|
|
74
|
+
|
|
75
|
+
if isinstance(callable_obj, weakref.ReferenceType):
|
|
76
|
+
callable_obj = callable_obj()
|
|
77
|
+
|
|
78
|
+
func_name = getattr(callable_obj, '__name__', str(callable_obj))
|
|
79
|
+
module_name = getattr(callable_obj, '__module__', None)
|
|
80
|
+
is_builtin = module_name in (None, 'builtins')
|
|
81
|
+
|
|
82
|
+
trace_this = False
|
|
83
|
+
if hasattr(callable_obj, '__code__'):
|
|
84
|
+
func_def_lineno = callable_obj.__code__.co_firstlineno
|
|
85
|
+
def_filename = os.path.abspath(callable_obj.__code__.co_filename)
|
|
86
|
+
trace_this = self.should_trace(def_filename) or self.verbose
|
|
87
|
+
else:
|
|
88
|
+
def_filename = self.resolve_filename(None, callable_obj)
|
|
89
|
+
func_def_lineno = ''
|
|
90
|
+
if module_name in self.site_packages_modules or is_builtin:
|
|
91
|
+
trace_this = self.verbose
|
|
92
|
+
else:
|
|
93
|
+
trace_this = self.verbose and self.should_trace(def_filename)
|
|
94
|
+
|
|
95
|
+
if trace_this and not self.is_tracer_code(call_filename):
|
|
96
|
+
indent = " " * self.depth
|
|
97
|
+
if self.show_path:
|
|
98
|
+
if is_builtin or not def_filename:
|
|
99
|
+
func_location = f"{func_name}@{module_name or '<builtin>'}"
|
|
100
|
+
else:
|
|
101
|
+
func_location = f"{func_name}@{def_filename}:{func_def_lineno}"
|
|
102
|
+
call_location = f"from {call_filename}:{call_lineno}"
|
|
103
|
+
else:
|
|
104
|
+
func_location = func_name
|
|
105
|
+
call_location = f"from line {call_lineno}"
|
|
106
|
+
if not self.report_mode:
|
|
107
|
+
print(f"{indent}Called {func_location} {call_location}")
|
|
108
|
+
self.depth += 1
|
|
109
|
+
self.call_stack.append((func_name, is_builtin))
|
|
110
|
+
if self.report_mode:
|
|
111
|
+
start_time = time.time()
|
|
112
|
+
if func_name in self.execution_report:
|
|
113
|
+
_, total_time, call_count = self.execution_report[func_name]
|
|
114
|
+
self.execution_report[func_name] = (start_time, total_time, call_count + 1)
|
|
115
|
+
else:
|
|
116
|
+
self.execution_report[func_name] = (start_time, 0, 1)
|
|
117
|
+
|
|
118
|
+
def monitor_py_return(self, code, instruction_offset, retval):
|
|
119
|
+
if not self.tracing_started:
|
|
120
|
+
return
|
|
121
|
+
|
|
122
|
+
filename = self.resolve_filename(code, None)
|
|
123
|
+
func_name = code.co_name if code else "<unknown>"
|
|
124
|
+
|
|
125
|
+
if func_name == "<module>" and filename == self.tracer_script:
|
|
126
|
+
return
|
|
127
|
+
|
|
128
|
+
trace_this = self.should_trace(filename) or self.verbose
|
|
129
|
+
|
|
130
|
+
if trace_this and not self.is_tracer_code(filename):
|
|
131
|
+
indent = " " * self.depth
|
|
132
|
+
|
|
133
|
+
if self.call_stack:
|
|
134
|
+
stack_func_name, is_builtin = self.call_stack[-1]
|
|
135
|
+
else:
|
|
136
|
+
stack_func_name = "<unknown>"
|
|
137
|
+
is_builtin = False
|
|
138
|
+
|
|
139
|
+
# file path if --path option is used
|
|
140
|
+
if self.show_path:
|
|
141
|
+
file_info = f" @ {filename}" if filename else ""
|
|
142
|
+
else:
|
|
143
|
+
file_info = ""
|
|
144
|
+
|
|
145
|
+
if func_name != "<module>":
|
|
146
|
+
if stack_func_name == func_name:
|
|
147
|
+
self.depth -= 1
|
|
148
|
+
if not self.report_mode:
|
|
149
|
+
print(f"{indent}Returning {func_name}-> {retval}{file_info}")
|
|
150
|
+
|
|
151
|
+
if self.report_mode and func_name in self.execution_report:
|
|
152
|
+
start_time, total_time, call_count = self.execution_report[func_name]
|
|
153
|
+
exec_time = time.time() - start_time
|
|
154
|
+
self.execution_report[func_name] = (start_time, total_time + exec_time, call_count)
|
|
155
|
+
|
|
156
|
+
if self.call_stack and self.call_stack[-1][0] == func_name:
|
|
157
|
+
self.call_stack.pop()
|
|
158
|
+
else:
|
|
159
|
+
if not self.report_mode:
|
|
160
|
+
print(f"{indent}Returning {func_name}-> {retval}{file_info}")
|
|
161
|
+
|
|
162
|
+
|
|
163
|
+
def monitor_c_return(self, code, instruction_offset, callable_obj, arg0):
|
|
164
|
+
if not self.tracing_started:
|
|
165
|
+
return
|
|
166
|
+
|
|
167
|
+
func_name = getattr(callable_obj, '__name__', str(callable_obj))
|
|
168
|
+
module_name = getattr(callable_obj, '__module__', None)
|
|
169
|
+
is_builtin = module_name in (None, 'builtins')
|
|
170
|
+
filename = self.resolve_filename(code, callable_obj)
|
|
171
|
+
|
|
172
|
+
trace_this = self.verbose and (self.should_trace(filename) or is_builtin)
|
|
173
|
+
|
|
174
|
+
if trace_this and not self.is_tracer_code(filename):
|
|
175
|
+
indent = " " * self.depth
|
|
176
|
+
if self.call_stack:
|
|
177
|
+
stack_func_name, is_builtin = self.call_stack[-1]
|
|
178
|
+
else:
|
|
179
|
+
stack_func_name = "<unknown>"
|
|
180
|
+
is_builtin = True
|
|
181
|
+
if self.show_path:
|
|
182
|
+
file_info = f" @ {filename}" if filename else ""
|
|
183
|
+
else:
|
|
184
|
+
file_info = ""
|
|
185
|
+
if stack_func_name == func_name:
|
|
186
|
+
self.depth -= 1
|
|
187
|
+
if not self.report_mode:
|
|
188
|
+
print(f"{indent}Returning {func_name}{file_info}")
|
|
189
|
+
if self.report_mode and func_name in self.execution_report:
|
|
190
|
+
start_time, total_time, call_count = self.execution_report[func_name]
|
|
191
|
+
exec_time = time.time() - start_time
|
|
192
|
+
self.execution_report[func_name] = (start_time, total_time + exec_time, call_count)
|
|
193
|
+
if self.call_stack and self.call_stack[-1][0] == func_name:
|
|
194
|
+
self.call_stack.pop()
|
|
195
|
+
|
|
196
|
+
def run_python_script(self, script_path):
|
|
197
|
+
print(f"Running script: {script_path}")
|
|
198
|
+
self.script_name = script_path
|
|
199
|
+
self.script_dir = os.path.dirname(os.path.abspath(script_path))
|
|
200
|
+
|
|
201
|
+
with open(script_path, "r") as file:
|
|
202
|
+
script_code = file.read()
|
|
203
|
+
code_object = compile(script_code, script_path, 'exec')
|
|
204
|
+
|
|
205
|
+
old_sys_path = sys.path.copy()
|
|
206
|
+
sys.path.insert(0, self.script_dir)
|
|
207
|
+
|
|
208
|
+
self.setup_monitoring()
|
|
209
|
+
|
|
210
|
+
try:
|
|
211
|
+
exec(code_object, {"__file__": script_path, "__name__": "__main__"})
|
|
212
|
+
finally:
|
|
213
|
+
sys.path = old_sys_path
|
|
214
|
+
self.cleanup_monitoring()
|
|
215
|
+
|
|
216
|
+
def print_report(self):
|
|
217
|
+
print("\nFunction Name\t| Total Execution Time\t| Call Count")
|
|
218
|
+
print("---------------------------------------------------------")
|
|
219
|
+
for func_name, (_, total_time, call_count) in self.execution_report.items():
|
|
220
|
+
print(f"{func_name:<15}\t| {total_time:.6f} seconds\t| {call_count}")
|
|
221
|
+
|
|
222
|
+
def setup_monitoring(self):
|
|
223
|
+
sys.monitoring.use_tool_id(self.tool_id, "simple-pyftrace")
|
|
224
|
+
sys.monitoring.register_callback(self.tool_id, sys.monitoring.events.CALL, self.monitor_call)
|
|
225
|
+
sys.monitoring.register_callback(self.tool_id, sys.monitoring.events.PY_RETURN, self.monitor_py_return)
|
|
226
|
+
sys.monitoring.register_callback(self.tool_id, sys.monitoring.events.C_RETURN, self.monitor_c_return)
|
|
227
|
+
sys.monitoring.set_events(
|
|
228
|
+
self.tool_id,
|
|
229
|
+
sys.monitoring.events.CALL | sys.monitoring.events.PY_RETURN
|
|
230
|
+
)
|
|
231
|
+
|
|
232
|
+
def cleanup_monitoring(self):
|
|
233
|
+
sys.monitoring.free_tool_id(self.tool_id)
|
|
234
|
+
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
import sys
|
|
2
|
+
import os
|
|
3
|
+
import functools
|
|
4
|
+
import time
|
|
5
|
+
|
|
6
|
+
def get_site_packages_modules():
|
|
7
|
+
site_packages_dirs = [d for d in sys.path if 'site-packages' in d]
|
|
8
|
+
modules = set()
|
|
9
|
+
for directory in site_packages_dirs:
|
|
10
|
+
if os.path.isdir(directory):
|
|
11
|
+
for name in os.listdir(directory):
|
|
12
|
+
if os.path.isdir(os.path.join(directory, name)):
|
|
13
|
+
modules.add(name.split('-')[0])
|
|
14
|
+
elif name.endswith('.dist-info'):
|
|
15
|
+
modules.add(name.split('-')[0])
|
|
16
|
+
return modules
|
|
17
|
+
|
|
18
|
+
def timeit(method):
|
|
19
|
+
"""
|
|
20
|
+
Decorator to measure the execution time of methods.
|
|
21
|
+
|
|
22
|
+
Args:
|
|
23
|
+
method (callable): The method to be wrapped.
|
|
24
|
+
|
|
25
|
+
Returns:
|
|
26
|
+
callable: The wrapped method with timing.
|
|
27
|
+
"""
|
|
28
|
+
@functools.wraps(method)
|
|
29
|
+
def timed(*args, **kw):
|
|
30
|
+
ts = time.time()
|
|
31
|
+
result = method(*args, **kw)
|
|
32
|
+
te = time.time()
|
|
33
|
+
return result
|
|
34
|
+
return timed
|
|
35
|
+
|
|
@@ -0,0 +1,235 @@
|
|
|
1
|
+
Metadata-Version: 2.1
|
|
2
|
+
Name: pyftrace
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Python function tracing tool.
|
|
5
|
+
Home-page: https://github.com/kangtegong/pyftrace
|
|
6
|
+
Author: Kang Minchul
|
|
7
|
+
Author-email: tegongkang@gmail.com
|
|
8
|
+
Requires-Python: >=3.12
|
|
9
|
+
Description-Content-Type: text/markdown
|
|
10
|
+
License-File: LICENSE
|
|
11
|
+
|
|
12
|
+
# pyftrace
|
|
13
|
+
|
|
14
|
+
## Introduction
|
|
15
|
+
|
|
16
|
+
**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.
|
|
17
|
+
|
|
18
|
+
Key features of pyftrace include:
|
|
19
|
+
|
|
20
|
+
- **Function Call Tracing**: Monitor calls to functions in your script and imported modules.
|
|
21
|
+
- **Built-in Function Tracing**: Optionally trace built-in functions like `print` using the `--verbose` flag.
|
|
22
|
+
- **Multiple Module Support**: Trace functions across multiple files within your project.
|
|
23
|
+
- **Execution Reports**: Generate reports detailing function execution times and call counts with the `--report` flag.
|
|
24
|
+
- **Customizable Output**: Use the `--path` flag to include file paths in tracing output, aiding in debugging and code analysis.
|
|
25
|
+
|
|
26
|
+
## Usage
|
|
27
|
+
|
|
28
|
+
### Requirements
|
|
29
|
+
|
|
30
|
+
- **Python Version**: pyftrace requires **Python 3.12** or higher due to its use of the new `sys.monitoring` module introduced in Python 3.12.
|
|
31
|
+
|
|
32
|
+
```bash
|
|
33
|
+
$ pyftrace [options] script_path
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
- `script_path`: The path to the Python script you want to trace.
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
### Installation
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
### Command-Line Options
|
|
45
|
+
|
|
46
|
+
- `--report`: Generate a report of function execution times and call counts at the end of the script's execution.
|
|
47
|
+
- `--verbose`: Enable tracing of built-in functions (e.g., print, len). Without this flag, pyftrace only traces user-defined functions.
|
|
48
|
+
- `--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.
|
|
49
|
+
- `-h` or `--help`: Display help information about pyftrace and its options.
|
|
50
|
+
|
|
51
|
+
## Examples
|
|
52
|
+
|
|
53
|
+
The `examples/` directory contains a variety of Python files that can be traced using pyftrace.
|
|
54
|
+
|
|
55
|
+
When a function is called, pyftrace displays it in the following format:
|
|
56
|
+
|
|
57
|
+
```
|
|
58
|
+
Called {function} @ {defined file path}:{defined line} from {called file path}:{called line}
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
- `{function}`: name of the function being called
|
|
62
|
+
- `{defined file path}`: file path where the function is defined (enabled with `--path` option)
|
|
63
|
+
- `{defined line}`" line number in the defined file
|
|
64
|
+
- `{called line}` line number in the calling file
|
|
65
|
+
- `{called file path}` path to the file that contains the calling function (enabled with `--path` option)
|
|
66
|
+
|
|
67
|
+
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.
|
|
68
|
+
|
|
69
|
+
```python
|
|
70
|
+
# module_a.py
|
|
71
|
+
def function_a():
|
|
72
|
+
print("Function A is called.")
|
|
73
|
+
return "Result from function A"
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
```python
|
|
77
|
+
# module_b.py
|
|
78
|
+
def function_b():
|
|
79
|
+
print("Function B is called.")
|
|
80
|
+
return "Result from function B"
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
```python
|
|
84
|
+
# main.py
|
|
85
|
+
from module_a import function_a
|
|
86
|
+
from module_b import function_b
|
|
87
|
+
|
|
88
|
+
def main():
|
|
89
|
+
result_a = function_a()
|
|
90
|
+
result_b = function_b()
|
|
91
|
+
print(f"Results: {result_a}, {result_b}")
|
|
92
|
+
|
|
93
|
+
if __name__ == "__main__":
|
|
94
|
+
main()
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
### Basic Tracing
|
|
98
|
+
|
|
99
|
+
To trace function calls in main.py without including built-in functions or file paths:
|
|
100
|
+
|
|
101
|
+
|
|
102
|
+
```
|
|
103
|
+
$ pyftrace examples/module_trace/main.py
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
output:
|
|
107
|
+
```
|
|
108
|
+
Running script: examples/module_trace/main.py
|
|
109
|
+
Called main:4 from line 10
|
|
110
|
+
Called function_a:1 from line 5
|
|
111
|
+
Function A is called.
|
|
112
|
+
Returning function_a-> Result from function A
|
|
113
|
+
Called function_b:1 from line 6
|
|
114
|
+
Function B is called.
|
|
115
|
+
Returning function_b-> Result from function B
|
|
116
|
+
Results: Result from function A, Result from function B
|
|
117
|
+
Returning main-> None
|
|
118
|
+
Returning <module>-> None
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
### Including Built-in Functions with `--verbose`
|
|
122
|
+
|
|
123
|
+
```
|
|
124
|
+
$ pyftrace --verbose examples/module_trace/main.py
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
output:
|
|
128
|
+
```
|
|
129
|
+
Running script: examples/module_trace/main.py
|
|
130
|
+
Called main:4 from line 10
|
|
131
|
+
Called function_a:1 from line 5
|
|
132
|
+
Called print from line 2
|
|
133
|
+
Function A is called.
|
|
134
|
+
Returning print
|
|
135
|
+
Returning function_a-> Result from function A
|
|
136
|
+
Called function_b:1 from line 6
|
|
137
|
+
Called print from line 2
|
|
138
|
+
Function B is called.
|
|
139
|
+
Returning print
|
|
140
|
+
Returning function_b-> Result from function B
|
|
141
|
+
Called print from line 7
|
|
142
|
+
Results: Result from function A, Result from function B
|
|
143
|
+
Returning print
|
|
144
|
+
Returning main-> None
|
|
145
|
+
Returning <module>-> None
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
### Showing File Paths with `--path`
|
|
149
|
+
|
|
150
|
+
```
|
|
151
|
+
$ pyftrace --path examples/module_trace/main.py
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
output:
|
|
155
|
+
```
|
|
156
|
+
Running script: examples/module_trace/main.py
|
|
157
|
+
Called main@/path/to/examples/module_trace/main.py:4 from line 10 @ examples/module_trace/main.py
|
|
158
|
+
Called function_a@/path/to/examples/module_trace/module_a.py:1 from line 5 @ examples/module_trace/main.py
|
|
159
|
+
Function A is called.
|
|
160
|
+
Returning function_a-> Result from function A @ /path/to/examples/module_trace/module_a.py
|
|
161
|
+
Called function_b@/path/to/examples/module_trace/module_b.py:1 from line 6 @ examples/module_trace/main.py
|
|
162
|
+
Function B is called.
|
|
163
|
+
Returning function_b-> Result from function B @ /path/to/examples/module_trace/module_b.py
|
|
164
|
+
Results: Result from function A, Result from function B
|
|
165
|
+
Returning main-> None @ /path/to/examples/module_trace/main.py
|
|
166
|
+
Returning <module>-> None @ /path/to/examples/module_trace/main.py
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
### Generating an Execution Report
|
|
170
|
+
|
|
171
|
+
To generate a summary report of function execution times and call counts:
|
|
172
|
+
|
|
173
|
+
```
|
|
174
|
+
$ pyftrace --report examples/module_trace/main.py
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
output:
|
|
178
|
+
```
|
|
179
|
+
Running script: examples/module_trace/main.py
|
|
180
|
+
Returning <module>-> None
|
|
181
|
+
|
|
182
|
+
Function Name | Total Execution Time | Call Count
|
|
183
|
+
---------------------------------------------------------
|
|
184
|
+
main | 0.000123 seconds | 1
|
|
185
|
+
function_a | 0.000456 seconds | 1
|
|
186
|
+
function_b | 0.000789 seconds | 1
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
### Combining `--verbose` and `--path`
|
|
190
|
+
|
|
191
|
+
To trace built-in functions and include file paths:
|
|
192
|
+
|
|
193
|
+
```
|
|
194
|
+
$ pyftrace --verbose --path examples/module_trace/main.py
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
output:
|
|
198
|
+
```
|
|
199
|
+
Running script: examples/module_trace/main.py
|
|
200
|
+
Called main@/path/to/examples/module_trace/main.py:4 from line 10 @ examples/module_trace/main.py
|
|
201
|
+
Called function_a@/path/to/examples/module_trace/module_a.py:1 from line 5 @ examples/module_trace/main.py
|
|
202
|
+
Called print@<builtin> from line 2 @ /path/to/examples/module_trace/module_a.py
|
|
203
|
+
Function A is called.
|
|
204
|
+
Returning print @ /path/to/examples/module_trace/module_a.py
|
|
205
|
+
Returning function_a-> Result from function A @ /path/to/examples/module_trace/module_a.py
|
|
206
|
+
Called function_b@/path/to/examples/module_trace/module_b.py:1 from line 6 @ examples/module_trace/main.py
|
|
207
|
+
Called print@<builtin> from line 2 @ /path/to/examples/module_trace/module_b.py
|
|
208
|
+
Function B is called.
|
|
209
|
+
Returning print @ /path/to/examples/module_trace/module_b.py
|
|
210
|
+
Returning function_b-> Result from function B @ /path/to/examples/module_trace/module_b.py
|
|
211
|
+
Called print@<builtin> from line 7 @ examples/module_trace/main.py
|
|
212
|
+
Results: Result from function A, Result from function B
|
|
213
|
+
Returning print @ examples/module_trace/main.py
|
|
214
|
+
Returning main-> None @ /path/to/examples/module_trace/main.py
|
|
215
|
+
Returning <module>-> None @ /path/to/examples/module_trace/main.py
|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
### Notes
|
|
219
|
+
- 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.
|
|
220
|
+
- Indentation: The indentation in the output represents the call hierarchy, making it easier to visualize which functions are calling others.
|
|
221
|
+
- Returning Statements: When a function returns, pyftrace logs the return value.
|
|
222
|
+
- File Paths: File paths are absolute paths. You can modify the code to display relative paths if preferred.
|
|
223
|
+
|
|
224
|
+
## LICENESE
|
|
225
|
+
|
|
226
|
+
MIT
|
|
227
|
+
|
|
228
|
+
See [LICENSE](./LICENSE) for more infomation
|
|
229
|
+
|
|
230
|
+
## See Also
|
|
231
|
+
|
|
232
|
+
pyftrace is heavily inspired by:
|
|
233
|
+
|
|
234
|
+
- [ftrace](https://www.kernel.org/doc/Documentation/trace/ftrace.txt): Ftrace is an internal tracer for linux kernel.
|
|
235
|
+
- [uftrace](https://github.com/namhyung/uftrace): uftrace is a function call graph tracer for C, C++, Rust and Python programs.
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
LICENSE
|
|
2
|
+
README.md
|
|
3
|
+
pyproject.toml
|
|
4
|
+
setup.py
|
|
5
|
+
pyftrace/__init__.py
|
|
6
|
+
pyftrace/main.py
|
|
7
|
+
pyftrace/tracer.py
|
|
8
|
+
pyftrace/utils.py
|
|
9
|
+
pyftrace.egg-info/PKG-INFO
|
|
10
|
+
pyftrace.egg-info/SOURCES.txt
|
|
11
|
+
pyftrace.egg-info/dependency_links.txt
|
|
12
|
+
pyftrace.egg-info/entry_points.txt
|
|
13
|
+
pyftrace.egg-info/top_level.txt
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
pyftrace
|
pyftrace-0.1.0/setup.cfg
ADDED
pyftrace-0.1.0/setup.py
ADDED
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
from setuptools import setup, find_packages
|
|
2
|
+
|
|
3
|
+
setup(
|
|
4
|
+
name="pyftrace",
|
|
5
|
+
version="0.1.0",
|
|
6
|
+
description="Python function tracing tool.",
|
|
7
|
+
long_description=open("README.md").read(),
|
|
8
|
+
long_description_content_type="text/markdown",
|
|
9
|
+
author="Kang Minchul",
|
|
10
|
+
author_email="tegongkang@gmail.com",
|
|
11
|
+
url="https://github.com/kangtegong/pyftrace",
|
|
12
|
+
packages=find_packages(),
|
|
13
|
+
entry_points={
|
|
14
|
+
"console_scripts": [
|
|
15
|
+
"pyftrace=pyftrace.main:main",
|
|
16
|
+
],
|
|
17
|
+
},
|
|
18
|
+
python_requires=">=3.12",
|
|
19
|
+
)
|
|
20
|
+
|