funcprofiler 1.0.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.
@@ -0,0 +1,7 @@
1
+ MIT License (Modified)
2
+
3
+ Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to make derivative works based on the Software, provided that any substantial changes to the Software are clearly distinguished from the original work and are distributed under a different name.
4
+
5
+ The original copyright notice and disclaimer must be retained in all copies or substantial portions of the Software.
6
+
7
+ THE SOFTWARE IS PROVIDED "AS IS," WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
@@ -0,0 +1,22 @@
1
+ Metadata-Version: 2.1
2
+ Name: funcprofiler
3
+ Version: 1.0.0
4
+ Summary: An open-source Python library that can be used to profile functions.
5
+ Home-page: https://github.com/infinitode/valx
6
+ Author: Infinitode Pty Ltd
7
+ Author-email: infinitode.ltd@gmail.com
8
+ Classifier: Development Status :: 5 - Production/Stable
9
+ Classifier: Intended Audience :: Developers
10
+ Classifier: License :: OSI Approved :: MIT License
11
+ Classifier: Programming Language :: Python :: 3.6
12
+ Classifier: Programming Language :: Python :: 3.7
13
+ Classifier: Programming Language :: Python :: 3.8
14
+ Classifier: Programming Language :: Python :: 3.9
15
+ Classifier: Programming Language :: Python :: 3.10
16
+ Classifier: Programming Language :: Python :: 3.11
17
+ Classifier: Programming Language :: Python :: 3.12
18
+ Requires-Python: >=3.6
19
+ Description-Content-Type: text/markdown
20
+ License-File: LICENSE
21
+
22
+ An open-source Python library for finding bottlenecks in code. Includes function profiling, data exports, logging, and even line-by-line profiling, for more control.
@@ -0,0 +1,85 @@
1
+ # FuncProfiler
2
+ ![Python Version](https://img.shields.io/badge/python-3.12-blue.svg)
3
+ [![Code Size](https://img.shields.io/github/languages/code-size/infinitode/funcprofiler)](https://github.com/infinitode/funcprofiler)
4
+ ![Downloads](https://pepy.tech/badge/funcprofiler)
5
+ ![License Compliance](https://img.shields.io/badge/license-compliance-brightgreen.svg)
6
+ ![PyPI Version](https://img.shields.io/pypi/v/funcprofiler)
7
+
8
+ An open-source Python library for identifying bottlenecks in code. It includes function profiling, data exports, logging, and line-by-line profiling for more granular control.
9
+
10
+ ## Installation
11
+
12
+ You can install FuncProfiler using pip:
13
+
14
+ ```bash
15
+ pip install funcprofiler
16
+ ```
17
+
18
+ ## Supported Python Versions
19
+
20
+ FuncProfiler supports the following Python versions:
21
+
22
+ - Python 3.6
23
+ - Python 3.7
24
+ - Python 3.8
25
+ - Python 3.9
26
+ - Python 3.10
27
+ - Python 3.11 and later (preferred)
28
+
29
+ Please ensure that you have one of these Python versions installed. FuncProfiler may not function as expected on earlier versions.
30
+
31
+ ## Features
32
+
33
+ - **Function Profiling**: Monitor a function's memory usage and execution time to identify performance issues.
34
+ - **Line-by-Line Profiling**: Return execution time and memory usage for each line of any given function.
35
+ - **Shared Logging**: Log outputs of functions triggered by the line-by-line and function profilers, storing results in a `.txt` file.
36
+ - **File Exports**: Export profiling data from functions in `csv`, `json`, or `html` formats.
37
+ > [!NOTE]
38
+ > View more export types in the [official documentation](https://infinitode-docs.gitbook.io/documentation/package-documentation/funcprofiler-package-documentation).
39
+
40
+ ## Usage
41
+
42
+ ### Function Profiling
43
+
44
+ ```python
45
+ from funcprofiler import function_profile
46
+
47
+ # Exporting as `html` with logging enabled
48
+ @function_profile(export_format="html", shared_log=True)
49
+ def some_function():
50
+ return "Hello World."
51
+
52
+ # Call the function
53
+ message = some_function()
54
+ ```
55
+
56
+ ### Line-by-Line Profiling
57
+
58
+ ```python
59
+ from funcprofiler import line_by_line_profile
60
+
61
+ # Logging enabled without exports
62
+ @line_by_line_profile(shared_log=True)
63
+ def some_complicated_function(n):
64
+ total = 0
65
+ for i in range(n):
66
+ for j in range(i):
67
+ total += (i * j) ** 0.5 # Square root calculation
68
+ return total
69
+
70
+ # Call the function
71
+ total = some_complicated_function(1000)
72
+ ```
73
+
74
+ > [!NOTE]
75
+ > FuncProfiler can be added to any function using the callable format: `@funcprofiler_function_name(expected_arguments)`.
76
+
77
+ ## Contributing
78
+
79
+ Contributions are welcome! If you encounter issues, have suggestions, or wish to contribute to FuncProfiler, please open an issue or submit a pull request on [GitHub](https://github.com/infinitode/funcprofiler).
80
+
81
+ ## License
82
+
83
+ FuncProfiler is released under the terms of the **MIT License (Modified)**. Please see the [LICENSE](https://github.com/infinitode/funcprofiler/blob/main/LICENSE) file for the full text.
84
+
85
+ **Modified License Clause**: The modified license clause allows users to create derivative works based on the FuncProfiler software. However, it requires that any substantial changes to the software be clearly distinguished from the original work and distributed under a different name.
@@ -0,0 +1,336 @@
1
+ import time
2
+ import tracemalloc
3
+ import functools
4
+ import inspect
5
+ import os
6
+ import sys
7
+ import csv
8
+ import json
9
+ from typing import Callable, List, Dict, Optional
10
+
11
+ __all__ = ['function_profile', 'line_by_line_profile', 'export_function_profile_data', 'export_profiling_data']
12
+
13
+ def function_profile(export_format: Optional[str] = None, filename: Optional[str] = None, shared_log: bool = False) -> Callable:
14
+ """Decorator factory to profile the execution time and memory usage of a function.
15
+
16
+ Args:
17
+ export_format (Optional[str]): The format to export the profiling data ('txt', 'json', 'csv', 'html').
18
+ filename (Optional[str]): The name of the output file (without extension).
19
+ shared_log (Optional[bool]): If True, log to a shared file for all profiled functions.
20
+
21
+ Returns:
22
+ Callable: The profiling wrapper or decorator function.
23
+ """
24
+ log_filename = f"func_profiler_logs_{time.strftime('%Y%m%d')}_{time.strftime('%H%M%S')}.txt"
25
+
26
+ def decorator(func: Callable) -> Callable:
27
+ @functools.wraps(func)
28
+ def wrapper(*args, **kwargs):
29
+ # Start time and memory tracking
30
+ tracemalloc.start()
31
+ start_time = time.time()
32
+
33
+ # Prepare shared logging if enabled
34
+ log_file = None
35
+ if shared_log:
36
+ log_file = open(log_filename, 'a')
37
+ log_file.write(f"Profiling log for {func.__name__}\n")
38
+ log_file.write(f"Date: {time.strftime('%Y-%m-%d')}\n")
39
+ log_file.write(f"Time: {time.strftime('%H:%M:%S')}\n\n")
40
+
41
+ # Execute the function
42
+ result = func(*args, **kwargs)
43
+
44
+ # End time and memory tracking
45
+ end_time = time.time()
46
+ current, peak = tracemalloc.get_traced_memory()
47
+ tracemalloc.stop()
48
+
49
+ # Prepare data for exporting
50
+ profiling_data = {
51
+ "execution_times": end_time - start_time,
52
+ "memory_usage": current / 10**6, # Convert to MB
53
+ }
54
+
55
+ if export_format:
56
+ file = filename or f"{func.__name__}_funcprofile_report"
57
+ export_function_profile_data(profiling_data, func, export_format, file)
58
+
59
+ # Display the profiling results
60
+ print(f"[FUNCPROFILER] Function '{func.__name__}' executed in {end_time - start_time:.12f}s")
61
+ print(f"[FUNCPROFILER] Current memory usage: {current / 10**6:.12f}MB; Peak: {peak / 10**6:.12f}MB")
62
+
63
+ # Log the profiling data
64
+ if shared_log and log_file:
65
+ log_file.write(f"Function {func.__name__} called with args: {args}, kwargs: {kwargs}\n")
66
+ log_file.write(f"Execution Time: {end_time - start_time:.12f}s, Memory usage: {current / 10**6:.6f}MB; Peak: {peak / 10**6:.6f}MB\n")
67
+ log_file.write("-" * 40 + "\n") # Separator between calls
68
+
69
+ if shared_log and log_file:
70
+ log_file.close() # Close the log file after writing if shared_log is True
71
+
72
+ return result
73
+
74
+ return wrapper
75
+
76
+ return decorator
77
+
78
+ def export_function_profile_data(profiling_data: dict, func: Callable, export_format: str, filename: str) -> None:
79
+ """Export profiling data for the function profile to the specified format.
80
+
81
+ Args:
82
+ profiling_data (dict): The profiling data containing execution time and memory usage.
83
+ func (Callable): The function that was profiled.
84
+ export_format (str): The format for export ('txt', 'json', 'csv', 'html').
85
+ filename (str): The output filename without extension.
86
+ """
87
+ execution_time = profiling_data["execution_times"]
88
+ memory_usage = profiling_data["memory_usage"]
89
+
90
+ if export_format == "txt":
91
+ with open(f"{filename}.txt", 'w') as f:
92
+ f.write(f"Function: {func.__name__}\n")
93
+ f.write(f"Execution Time: {execution_time:.12f}s\n")
94
+ f.write(f"Memory Usage: {memory_usage:.6f}MB\n")
95
+
96
+ elif export_format == "json":
97
+ with open(f"{filename}.json", 'w') as f:
98
+ json.dump({
99
+ "function": func.__name__,
100
+ "execution_time": execution_time,
101
+ "memory_usage": memory_usage
102
+ }, f, indent=4)
103
+
104
+ elif export_format == "csv":
105
+ with open(f"{filename}.csv", 'w', newline='') as f:
106
+ writer = csv.writer(f)
107
+ writer.writerow(["Function", "Execution Time (s)", "Memory Usage (MB)"])
108
+ writer.writerow([func.__name__, execution_time, memory_usage])
109
+
110
+ elif export_format == "html":
111
+ with open(f"{filename}.html", 'w') as f:
112
+ f.write("<html><head><title>Function Profiling Report</title></head><body>")
113
+ f.write(f"<h1>Function: {func.__name__}</h1>")
114
+ f.write(f"<p>Execution Time: <strong>{execution_time:.12f}s</strong></p>")
115
+ f.write(f"<p>Memory Usage: <strong>{memory_usage:.6f}MB</strong></p>")
116
+ f.write("</body></html>")
117
+
118
+ else:
119
+ raise ValueError("Unsupported export format. Use 'txt', 'json', 'csv', or 'html'.")
120
+
121
+ def line_by_line_profile(
122
+ export_format: Optional[str] = None,
123
+ filename: Optional[str] = None,
124
+ shared_log: bool = False
125
+ ) -> Callable:
126
+ """Decorator for line-by-line profiling of a function with optional data export and shared logging.
127
+
128
+ Args:
129
+ export_format (Optional[str]): The format to export the profiling data ('json', 'csv', 'html').
130
+ filename (Optional[str]): The name of the output file (without extension).
131
+ shared_log (Optional[bool]): If True, log to a shared file for all profiled functions.
132
+
133
+ Returns:
134
+ Callable: The profiling wrapper or decorator function.
135
+ """
136
+ log_filename = f"lbl_profiler_logs_{time.strftime('%Y%m%d')}_{time.strftime('%H%M%S')}.txt"
137
+
138
+ def decorator(func: Callable) -> Callable:
139
+ @functools.wraps(func)
140
+ def wrapper(*args, **kwargs):
141
+ line_execution_times: Dict[int, float] = {}
142
+ line_memory_usage: Dict[int, float] = {}
143
+ current_line_start_time: Optional[float] = None
144
+ timer = time.perf_counter
145
+ tracemalloc.start()
146
+
147
+ # Prepare shared logging if enabled
148
+ log_file = None
149
+ if shared_log:
150
+ log_file = open(log_filename, 'a')
151
+ log_file.write(f"Profiling log for {func.__name__}\n")
152
+ log_file.write(f"Date: {time.strftime('%Y-%m-%d')}\n")
153
+ log_file.write(f"Time: {time.strftime('%H:%M:%S')}\n\n")
154
+
155
+ def trace_lines(frame, event, arg):
156
+ nonlocal current_line_start_time
157
+ if frame.f_code.co_name == func.__name__:
158
+ lineno = frame.f_lineno
159
+ if event == 'line':
160
+ current_memory = tracemalloc.get_traced_memory()[1] / 10**6 # Convert to MB
161
+ if current_line_start_time is not None:
162
+ elapsed_time = timer() - current_line_start_time
163
+ if lineno in line_execution_times:
164
+ line_execution_times[lineno] += elapsed_time
165
+ else:
166
+ line_execution_times[lineno] = elapsed_time
167
+ line_memory_usage[lineno] = current_memory
168
+
169
+ # Log the profiling data
170
+ if shared_log and log_file:
171
+ log_file.write(f"Line {lineno}: Execution Time: {elapsed_time:.12f}s, Memory Usage: {current_memory:.12f}MB\n")
172
+
173
+ current_line_start_time = timer()
174
+ return trace_lines
175
+
176
+ sys.settrace(trace_lines)
177
+ try:
178
+ result = func(*args, **kwargs)
179
+ finally:
180
+ sys.settrace(None)
181
+ tracemalloc.stop()
182
+
183
+ # Print profiling data
184
+ print(f"\nLine-by-Line Profiling for '{func.__name__}':")
185
+ source_lines, starting_line = inspect.getsourcelines(func)
186
+ for line_no in sorted(line_execution_times.keys()):
187
+ actual_line = line_no - starting_line + 1
188
+ source_line = source_lines[actual_line - 1].strip()
189
+ exec_time = line_execution_times[line_no]
190
+ mem_usage = line_memory_usage.get(line_no, 0)
191
+ print(f"Line {line_no} ({source_line}): "
192
+ f"Execution Time: {exec_time:.12f}s, "
193
+ f"Memory Usage: {mem_usage:.12f}MB")
194
+
195
+ # Collect the profiling data for the report
196
+ profiling_data = {
197
+ "line_execution_times": line_execution_times,
198
+ "line_memory_usage": line_memory_usage
199
+ }
200
+
201
+ if export_format:
202
+ file = filename or f"{func.__name__}_lblprofile_report"
203
+ export_profiling_data(profiling_data, func, export_format, file)
204
+
205
+ # Close the log file if shared logging was enabled
206
+ if shared_log and log_file:
207
+ log_file.write("\n") # Add a new line for separation
208
+ log_file.write("-" * 40 + "\n") # Separator between calls
209
+ log_file.write("\n") # Add a new line for separation
210
+ log_file.close()
211
+
212
+ return result
213
+
214
+ return wrapper
215
+
216
+ # If no arguments are provided, it means func is passed directly
217
+ if callable(export_format):
218
+ actual_func = export_format
219
+ export_format = None
220
+ return decorator(actual_func)
221
+
222
+ return decorator
223
+
224
+ def export_profiling_data(
225
+ profiling_data: Dict[str, Dict[int, float]],
226
+ func: Callable,
227
+ export_format: str,
228
+ filename: str
229
+ ) -> None:
230
+ """Export the profiling data to the specified format (JSON, CSV, HTML).
231
+
232
+ Args:
233
+ profiling_data (Dict[str, Dict[int, float]]): Profiling data to be exported.
234
+ func (Callable): The function that was profiled.
235
+ export_format (str): The format for export ('json', 'csv', 'html').
236
+ filename (str): The output filename without extension.
237
+ """
238
+ line_execution_times = profiling_data["line_execution_times"]
239
+ line_memory_usage = profiling_data["line_memory_usage"]
240
+
241
+ # Get the source code of the function
242
+ source_lines, starting_line = inspect.getsourcelines(func)
243
+
244
+ # Prepare data for export
245
+ export_data: List[Dict[str, str]] = []
246
+ for line_no in sorted(line_execution_times.keys()):
247
+ actual_line = line_no - starting_line + 1
248
+ source_line = source_lines[actual_line - 1].strip()
249
+ exec_time = line_execution_times[line_no]
250
+ mem_usage = line_memory_usage.get(line_no, 0)
251
+
252
+ # Conditional wrapping based on the export format
253
+ wrapped_source_code = f'"{source_line}"' if export_format == 'csv' else source_line
254
+
255
+ export_data.append({
256
+ 'Function Name': func.__name__,
257
+ 'Line Number': str(line_no),
258
+ 'Source Code': wrapped_source_code, # Use wrapped source code
259
+ 'Execution Time (s)': f"{exec_time:.12f}",
260
+ 'Memory Usage (MB)': f"{mem_usage:.12f}"
261
+ })
262
+
263
+ # Handle different export formats
264
+ if export_format == 'json':
265
+ output_path = f"{filename}.json"
266
+ # Check if the file exists to append or create
267
+ if os.path.exists(output_path):
268
+ with open(output_path, 'r') as json_file:
269
+ existing_data = json.load(json_file)
270
+ existing_data.extend(export_data)
271
+ else:
272
+ existing_data = export_data
273
+
274
+ with open(output_path, 'w') as json_file:
275
+ json.dump(existing_data, json_file, indent=4)
276
+ print(f"[PROFILER] JSON report generated at: {output_path}")
277
+
278
+ elif export_format == 'csv':
279
+ output_path = f"{filename}.csv"
280
+ # Check if the file exists to determine write mode
281
+ file_mode = 'a' if os.path.exists(output_path) else 'w'
282
+
283
+ with open(output_path, mode=file_mode, newline='') as csvfile:
284
+ writer = csv.DictWriter(csvfile, fieldnames=['Function Name', 'Line Number', 'Source Code', 'Execution Time (s)', 'Memory Usage (MB)'])
285
+ if file_mode == 'w':
286
+ writer.writeheader() # Write header only for new file
287
+ for data in export_data:
288
+ writer.writerow(data)
289
+ print(f"[PROFILER] CSV report generated at: {output_path}")
290
+
291
+ elif export_format == 'html':
292
+ output_path = f"{filename}.html"
293
+ file_mode = 'a' if os.path.exists(output_path) else 'w'
294
+
295
+ if file_mode == 'w':
296
+ html_content = """
297
+ <html>
298
+ <head><title>Line-by-Line Profiling Report</title></head>
299
+ <body>
300
+ <h2>Line-by-Line Profiling Report</h2>
301
+ <table border="1">
302
+ <tr>
303
+ <th>Function Name</th>
304
+ <th>Line Number</th>
305
+ <th>Source Code</th>
306
+ <th>Execution Time (s)</th>
307
+ <th>Memory Usage (MB)</th>
308
+ </tr>
309
+ """
310
+ else:
311
+ html_content = ""
312
+
313
+ for data in export_data:
314
+ html_content += f"""
315
+ <tr>
316
+ <td>{data['Function Name']}</td>
317
+ <td>{data['Line Number']}</td>
318
+ <td>{data['Source Code']}</td>
319
+ <td>{data['Execution Time (s)']}</td>
320
+ <td>{data['Memory Usage (MB)']}</td>
321
+ </tr>
322
+ """
323
+
324
+ if file_mode == 'w':
325
+ html_content += """
326
+ </table>
327
+ </body>
328
+ </html>
329
+ """
330
+
331
+ with open(output_path, mode='a') as f:
332
+ f.write(html_content)
333
+ print(f"[PROFILER] HTML report generated at: {output_path}")
334
+
335
+ else:
336
+ print(f"[PROFILER] Unsupported export format: {export_format}")
@@ -0,0 +1,22 @@
1
+ Metadata-Version: 2.1
2
+ Name: funcprofiler
3
+ Version: 1.0.0
4
+ Summary: An open-source Python library that can be used to profile functions.
5
+ Home-page: https://github.com/infinitode/valx
6
+ Author: Infinitode Pty Ltd
7
+ Author-email: infinitode.ltd@gmail.com
8
+ Classifier: Development Status :: 5 - Production/Stable
9
+ Classifier: Intended Audience :: Developers
10
+ Classifier: License :: OSI Approved :: MIT License
11
+ Classifier: Programming Language :: Python :: 3.6
12
+ Classifier: Programming Language :: Python :: 3.7
13
+ Classifier: Programming Language :: Python :: 3.8
14
+ Classifier: Programming Language :: Python :: 3.9
15
+ Classifier: Programming Language :: Python :: 3.10
16
+ Classifier: Programming Language :: Python :: 3.11
17
+ Classifier: Programming Language :: Python :: 3.12
18
+ Requires-Python: >=3.6
19
+ Description-Content-Type: text/markdown
20
+ License-File: LICENSE
21
+
22
+ An open-source Python library for finding bottlenecks in code. Includes function profiling, data exports, logging, and even line-by-line profiling, for more control.
@@ -0,0 +1,8 @@
1
+ LICENSE
2
+ README.md
3
+ setup.py
4
+ funcprofiler/__init__.py
5
+ funcprofiler.egg-info/PKG-INFO
6
+ funcprofiler.egg-info/SOURCES.txt
7
+ funcprofiler.egg-info/dependency_links.txt
8
+ funcprofiler.egg-info/top_level.txt
@@ -0,0 +1 @@
1
+ funcprofiler
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,26 @@
1
+ from setuptools import setup, find_packages
2
+
3
+ setup(
4
+ name='funcprofiler',
5
+ version='1.0.0',
6
+ author='Infinitode Pty Ltd',
7
+ author_email='infinitode.ltd@gmail.com',
8
+ description='An open-source Python library that can be used to profile functions.',
9
+ long_description='An open-source Python library for finding bottlenecks in code. Includes function profiling, data exports, logging, and even line-by-line profiling, for more control.',
10
+ long_description_content_type='text/markdown',
11
+ url='https://github.com/infinitode/valx',
12
+ packages=find_packages(),
13
+ classifiers=[
14
+ 'Development Status :: 5 - Production/Stable',
15
+ 'Intended Audience :: Developers',
16
+ 'License :: OSI Approved :: MIT License',
17
+ 'Programming Language :: Python :: 3.6',
18
+ 'Programming Language :: Python :: 3.7',
19
+ 'Programming Language :: Python :: 3.8',
20
+ 'Programming Language :: Python :: 3.9',
21
+ 'Programming Language :: Python :: 3.10',
22
+ 'Programming Language :: Python :: 3.11',
23
+ 'Programming Language :: Python :: 3.12',
24
+ ],
25
+ python_requires='>=3.6',
26
+ )