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 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.
@@ -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,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,2 @@
1
+ from .tracer import SimplePyftrace
2
+
@@ -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,2 @@
1
+ [console_scripts]
2
+ pyftrace = pyftrace.main:main
@@ -0,0 +1 @@
1
+ pyftrace
@@ -0,0 +1,3 @@
1
+ [build-system]
2
+ requires = ["setuptools", "wheel"]
3
+ build-backend = "setuptools.build_meta"
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -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
+