funcprofiler 1.1.0__tar.gz → 1.3.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.
- funcprofiler-1.3.0/PKG-INFO +313 -0
- funcprofiler-1.3.0/README.md +273 -0
- funcprofiler-1.3.0/funcprofiler/__init__.py +69 -0
- funcprofiler-1.3.0/funcprofiler/_utils.py +378 -0
- funcprofiler-1.3.0/funcprofiler/core.py +1119 -0
- funcprofiler-1.3.0/funcprofiler/exporters.py +568 -0
- funcprofiler-1.3.0/funcprofiler/py.typed +0 -0
- funcprofiler-1.3.0/funcprofiler/stats.py +279 -0
- funcprofiler-1.3.0/funcprofiler.egg-info/PKG-INFO +313 -0
- funcprofiler-1.3.0/funcprofiler.egg-info/SOURCES.txt +14 -0
- funcprofiler-1.3.0/pyproject.toml +7 -0
- funcprofiler-1.3.0/setup.py +54 -0
- funcprofiler-1.1.0/PKG-INFO +0 -118
- funcprofiler-1.1.0/README.md +0 -87
- funcprofiler-1.1.0/funcprofiler/__init__.py +0 -481
- funcprofiler-1.1.0/funcprofiler.egg-info/PKG-INFO +0 -118
- funcprofiler-1.1.0/funcprofiler.egg-info/SOURCES.txt +0 -8
- funcprofiler-1.1.0/setup.py +0 -30
- {funcprofiler-1.1.0 → funcprofiler-1.3.0}/LICENSE +0 -0
- {funcprofiler-1.1.0 → funcprofiler-1.3.0}/funcprofiler.egg-info/dependency_links.txt +0 -0
- {funcprofiler-1.1.0 → funcprofiler-1.3.0}/funcprofiler.egg-info/top_level.txt +0 -0
- {funcprofiler-1.1.0 → funcprofiler-1.3.0}/setup.cfg +0 -0
|
@@ -0,0 +1,313 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: funcprofiler
|
|
3
|
+
Version: 1.3.0
|
|
4
|
+
Summary: 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.
|
|
5
|
+
Home-page: https://github.com/infinitode/funcprofiler
|
|
6
|
+
Author: Infinitode Pty Ltd
|
|
7
|
+
Author-email: infinitode.ltd@gmail.com
|
|
8
|
+
License: LicenseRef-MIT-Modified
|
|
9
|
+
Project-URL: Source, https://github.com/Infinitode/FuncProfiler
|
|
10
|
+
Project-URL: Documentation, https://github.com/Infinitode/FuncProfiler#readme
|
|
11
|
+
Project-URL: Issue Tracker, https://github.com/Infinitode/FuncProfiler/issues
|
|
12
|
+
Project-URL: Changelog, https://github.com/Infinitode/FuncProfiler#changelog-v130
|
|
13
|
+
Keywords: profiler,profiling,performance,bottleneck,benchmark,memory,line-profiler,timing,optimization
|
|
14
|
+
Classifier: Development Status :: 5 - Production/Stable
|
|
15
|
+
Classifier: Intended Audience :: Developers
|
|
16
|
+
Classifier: Operating System :: OS Independent
|
|
17
|
+
Classifier: Programming Language :: Python :: 3
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.8
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.9
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
22
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
23
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
24
|
+
Classifier: Typing :: Typed
|
|
25
|
+
Requires-Python: >=3.8
|
|
26
|
+
Description-Content-Type: text/markdown
|
|
27
|
+
License-File: LICENSE
|
|
28
|
+
Dynamic: author
|
|
29
|
+
Dynamic: author-email
|
|
30
|
+
Dynamic: classifier
|
|
31
|
+
Dynamic: description
|
|
32
|
+
Dynamic: description-content-type
|
|
33
|
+
Dynamic: home-page
|
|
34
|
+
Dynamic: keywords
|
|
35
|
+
Dynamic: license
|
|
36
|
+
Dynamic: license-file
|
|
37
|
+
Dynamic: project-url
|
|
38
|
+
Dynamic: requires-python
|
|
39
|
+
Dynamic: summary
|
|
40
|
+
|
|
41
|
+
# FuncProfiler
|
|
42
|
+

|
|
43
|
+
[](https://github.com/infinitode/funcprofiler)
|
|
44
|
+

|
|
45
|
+

|
|
46
|
+

|
|
47
|
+
|
|
48
|
+
An open-source Python library for identifying bottlenecks in code. It includes function profiling, line-by-line profiling, aggregated statistics, logging and report exports — with no third-party dependencies.
|
|
49
|
+
|
|
50
|
+
## Changelog (v1.3.0)
|
|
51
|
+
|
|
52
|
+
### Fixed
|
|
53
|
+
|
|
54
|
+
- **`@function_profile` without parentheses** no longer raises `TypeError`; both `@function_profile` and `@function_profile(...)` work.
|
|
55
|
+
- **Exceptions no longer leak profiling state.** Previously a raised exception skipped `tracemalloc.stop()` and `sys.settrace(None)`, so tracing stayed enabled for the rest of the process and every later measurement was wrong. Cleanup now always happens.
|
|
56
|
+
- **Nested and recursive profiled calls no longer corrupt measurements.** A nested call used to stop the outer call's `tracemalloc` session (reporting `0.0 MB`), and a caller-owned `tracemalloc` session was silently stopped. Nested calls now join the existing session and report "not attributable" (`n/a`) instead of a fake zero.
|
|
57
|
+
- **Line-by-line tracing only instruments the profiled function.** Unrelated frames (libraries, comprehensions, helpers, the standard library) are no longer traced. Tracing overhead drops to roughly 1.2× when memory tracking is disabled, against roughly 5× before.
|
|
58
|
+
- **Recursion is aggregated into one line-by-line report** instead of re-instrumenting and printing a separate report for each recursive call.
|
|
59
|
+
- **Existing trace hooks are preserved.** Coverage tools and debuggers that set a trace function no longer have it destroyed; the previous tracer is restored.
|
|
60
|
+
- **Export filenames no longer double their extension** (`report.json` used to create `report.json.json`), and missing target directories are created automatically.
|
|
61
|
+
- **HTML reports escape profiled values**, so return values, arguments, source code and docstrings can no longer break or inject into the report. Markdown exports escape `|`.
|
|
62
|
+
- **YAML/TOML/XML exports are valid documents.** Keys containing spaces are quoted, multi-line values use proper block scalars, XML uses legal element names and a declaration.
|
|
63
|
+
- **Functions without retrievable source** (`exec`, frozen apps, some REPL sessions) no longer crash line-by-line exports; their source is shown as `???`.
|
|
64
|
+
- **CSV output uses the `csv` module** instead of hand-wrapped quotes, and repeated exports no longer silently mix runs without a header or run marker.
|
|
65
|
+
- **`export_format` and `log_level` are validated when the decorator is created**, so a typo fails immediately instead of after the profiled function has already run.
|
|
66
|
+
- **Shared logs are actually shared**: one file per process rather than one per function (the filename used to be derived from the clock at decoration time).
|
|
67
|
+
- **Per-line memory is no longer the cumulative `tracemalloc` peak** (which could only ever increase); it now samples the heap while the line executes.
|
|
68
|
+
- Empty line-by-line reports no longer raise `IndexError` when exporting.
|
|
69
|
+
|
|
70
|
+
### Added
|
|
71
|
+
|
|
72
|
+
- **`profile_block`** context manager for profiling arbitrary code blocks.
|
|
73
|
+
- **Aggregated statistics**: `get_stats`, `reset_stats`, `summary_rows`, `print_summary` and `export_summary` answer "which function is slow overall?" without parsing reports.
|
|
74
|
+
- **New decorator options**: `track_memory`, `sample_every`, `include_args`, `include_return_value`, `max_value_length`, `append`, `export_dir`, `logger`, `sort_by` and `top_n`.
|
|
75
|
+
- **`log_level="silent"`** and the ability to send console output to a `logging.Logger` with `logger=`.
|
|
76
|
+
- **Async and generator support.** Coroutines are timed across their whole awaited lifetime and generators from first `next()` to exhaustion. Async generators emit a `RuntimeWarning` instead of silently reporting ~0 s.
|
|
77
|
+
- **Hotspot columns**: line reports now include a `Percent` column and use human-readable units (`µs`, `ms`, `s`) in the console.
|
|
78
|
+
- **Helpers and metadata**: `format_duration`, `format_memory`, `EXPORT_FORMATS`, `__version__` and a `py.typed` marker.
|
|
79
|
+
|
|
80
|
+
### Changed
|
|
81
|
+
|
|
82
|
+
- Exports overwrite the target file by default; pass `append=True` to accumulate runs (`txt`, `json`, `csv`, `md`, `html`).
|
|
83
|
+
- Line-by-line exports include `Percent` and `Timestamp` columns so appended rows stay distinguishable.
|
|
84
|
+
- Exporters no longer print; the decorators report `Report exported to: …` instead.
|
|
85
|
+
- The console line-by-line report is aligned and unit-aware (see examples below).
|
|
86
|
+
- Minimum supported Python is now 3.8; CI tests every supported version.
|
|
87
|
+
- Releases are published with PyPI trusted publishing (OIDC) and PEP 740 attestations — no API token secret — from a build job that is separate from the publishing job.
|
|
88
|
+
|
|
89
|
+
### Migrating from 1.2.0
|
|
90
|
+
|
|
91
|
+
- Nothing has to change for typical usage. Line-by-line `csv`/`html` exports now overwrite instead of appending; add `append=True` to restore accumulation.
|
|
92
|
+
- If you parsed the old console output, note that line reports are now a table with `Time`, `%` and `Memory` columns.
|
|
93
|
+
- `export_profiling_data` and `export_function_profile_data` keep their signatures and now return the written path.
|
|
94
|
+
|
|
95
|
+
## Changelog (v.1.2.0):
|
|
96
|
+
- Significant performance improvements for both function and line-by-line profiling.
|
|
97
|
+
- Cached function metadata at decoration time to reduce overhead during execution.
|
|
98
|
+
- Optimized line-by-line tracing using code object identity comparison.
|
|
99
|
+
- Implemented buffered logging for shared logs to minimize frequent file I/O.
|
|
100
|
+
- Improved trace accuracy by properly capturing the final line's execution time.
|
|
101
|
+
- Refactored export logic for more efficient report generation.
|
|
102
|
+
|
|
103
|
+
## Changelog (v.1.1.0):
|
|
104
|
+
- Added support for 2 new export formats: `yaml` and `toml`.
|
|
105
|
+
- Exports now include more information: peak memory usage, timestamp, arguments, return value, filepath, line number, and docstring.
|
|
106
|
+
- Added `enabled` and `log_level` options to the decorators.
|
|
107
|
+
- Improved export formats for better readability.
|
|
108
|
+
|
|
109
|
+
## Installation
|
|
110
|
+
|
|
111
|
+
You can install FuncProfiler using pip:
|
|
112
|
+
|
|
113
|
+
```bash
|
|
114
|
+
pip install funcprofiler
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
## Supported Python Versions
|
|
118
|
+
|
|
119
|
+
FuncProfiler supports Python 3.8 and later (tested on 3.8 – 3.13).
|
|
120
|
+
|
|
121
|
+
## Features
|
|
122
|
+
|
|
123
|
+
- **Function Profiling**: monitor a function's execution time and memory usage.
|
|
124
|
+
- **Line-by-Line Profiling**: execution time, percentage of total, and memory for every line.
|
|
125
|
+
- **Block Profiling**: profile any `with` block, not just functions.
|
|
126
|
+
- **Aggregated Statistics**: totals, means, min/max and peak memory per function.
|
|
127
|
+
- **Shared Logging**: log profiler output to a single `.txt` file.
|
|
128
|
+
- **File Exports**: eight report formats.
|
|
129
|
+
- **Async & Generators**: coroutine and generator functions are measured correctly.
|
|
130
|
+
- **Low-overhead options**: `sample_every`, `track_memory=False`, `enabled=False`.
|
|
131
|
+
|
|
132
|
+
## Export Formats
|
|
133
|
+
|
|
134
|
+
| Format | `function_profile` | `line_by_line_profile` | `append=True` |
|
|
135
|
+
|--------|--------------------|------------------------|---------------|
|
|
136
|
+
| `txt` | ✅ | ✅ | ✅ |
|
|
137
|
+
| `json` | ✅ | ✅ | ✅ |
|
|
138
|
+
| `csv` | ✅ | ✅ | ✅ |
|
|
139
|
+
| `html` | ✅ | ✅ | ✅ |
|
|
140
|
+
| `xml` | ✅ | ✅ | ❌ |
|
|
141
|
+
| `md` | ✅ | ✅ | ✅ |
|
|
142
|
+
| `yaml` | ✅ | ✅ | ✅ |
|
|
143
|
+
| `toml` | ✅ | ✅ | ✅ |
|
|
144
|
+
|
|
145
|
+
## Usage
|
|
146
|
+
|
|
147
|
+
### Function Profiling
|
|
148
|
+
|
|
149
|
+
```python
|
|
150
|
+
from funcprofiler import function_profile
|
|
151
|
+
|
|
152
|
+
@function_profile(export_format="html", shared_log=True, log_level="debug")
|
|
153
|
+
def some_function():
|
|
154
|
+
return "Hello World."
|
|
155
|
+
|
|
156
|
+
message = some_function()
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
A bare `@function_profile` (without parentheses) also works.
|
|
160
|
+
|
|
161
|
+
### Line-by-Line Profiling
|
|
162
|
+
|
|
163
|
+
```python
|
|
164
|
+
from funcprofiler import line_by_line_profile
|
|
165
|
+
|
|
166
|
+
@line_by_line_profile(shared_log=True, enabled=True)
|
|
167
|
+
def some_complicated_function(n):
|
|
168
|
+
total = 0
|
|
169
|
+
for i in range(n):
|
|
170
|
+
for j in range(i):
|
|
171
|
+
total += (i * j) ** 0.5
|
|
172
|
+
return total
|
|
173
|
+
|
|
174
|
+
total = some_complicated_function(1000)
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
Console output is a compact table of hotspots:
|
|
178
|
+
|
|
179
|
+
```
|
|
180
|
+
[FUNCPROFILER] Line-by-line profile for 'some_complicated_function' (6 line(s), total 82.13 ms, peak 0.0060 MB)
|
|
181
|
+
Line Source Time % Memory
|
|
182
|
+
4 total = 0 1.20 µs 0.00% 0.0021 MB
|
|
183
|
+
5 for i in range(n): 21.44 ms 26.10% 0.0024 MB
|
|
184
|
+
7 total += (i * j) ** 0.5 60.02 ms 73.07% 0.0024 MB
|
|
185
|
+
8 return total 3.37 µs 0.00% 0.0024 MB
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
Use `sort_by="time"` to order by cost and `top_n=10` to keep the output short.
|
|
189
|
+
|
|
190
|
+
### Block Profiling
|
|
191
|
+
|
|
192
|
+
```python
|
|
193
|
+
from funcprofiler import profile_block
|
|
194
|
+
|
|
195
|
+
with profile_block("load-data", export_format="json", filename="load") as block:
|
|
196
|
+
rows = expensive_io()
|
|
197
|
+
|
|
198
|
+
print(block.execution_time, block.peak_memory_usage)
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
### Aggregated Statistics
|
|
202
|
+
|
|
203
|
+
Every profiled call is accumulated in a process-wide registry (disable with
|
|
204
|
+
`capture_stats=False`):
|
|
205
|
+
|
|
206
|
+
```python
|
|
207
|
+
from funcprofiler import function_profile, get_stats, print_summary, export_summary
|
|
208
|
+
|
|
209
|
+
@function_profile(log_level="silent")
|
|
210
|
+
def parse_row(row):
|
|
211
|
+
...
|
|
212
|
+
|
|
213
|
+
for row in rows:
|
|
214
|
+
parse_row(row)
|
|
215
|
+
|
|
216
|
+
print_summary(sort_by="total_time", top_n=10)
|
|
217
|
+
export_summary("csv", "profile_summary")
|
|
218
|
+
|
|
219
|
+
stats = get_stats() # {"myapp.parse_row": {"calls": 10_000, ...}}
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
```
|
|
223
|
+
[FUNCPROFILER] Profile summary
|
|
224
|
+
Function Calls Errors Total Mean Min Max Peak Mem
|
|
225
|
+
------------------ ----- ------ -------- -------- -------- -------- ---------
|
|
226
|
+
myapp.parse_row 10000 0 1.204 s 120.40 µs 96.10 µs 1.201 ms 0.0210 MB
|
|
227
|
+
```
|
|
228
|
+
|
|
229
|
+
### Options
|
|
230
|
+
|
|
231
|
+
| Option | Applies to | Description |
|
|
232
|
+
|--------|-----------|-------------|
|
|
233
|
+
| `export_format` | both | `txt`, `json`, `csv`, `html`, `xml`, `md`, `yaml`, `toml` (case-insensitive). |
|
|
234
|
+
| `filename` | both | Output filename, with or without extension. |
|
|
235
|
+
| `shared_log` | both | Append to one process-wide `.txt` log. |
|
|
236
|
+
| `enabled` | both | `False` disables profiling entirely. |
|
|
237
|
+
| `log_level` | both | `"info"`, `"debug"` or `"silent"`. |
|
|
238
|
+
| `logger` | both | Send console output to a `logging.Logger`. |
|
|
239
|
+
| `capture_stats` | both | Accumulate results in `get_stats()` (default `True`). |
|
|
240
|
+
| `track_memory` | both | Measure memory with `tracemalloc` (default `True`). |
|
|
241
|
+
| `sample_every` | both | Profile only every Nth call. |
|
|
242
|
+
| `include_args` | both | Include call arguments in logs/exports. |
|
|
243
|
+
| `include_return_value` | both | Include the return value in logs/exports. |
|
|
244
|
+
| `max_value_length` | both | Truncate recorded reprs (default 500 chars). |
|
|
245
|
+
| `append` | both | Append a run to an existing export. |
|
|
246
|
+
| `export_dir` | both | Directory for relative export filenames. |
|
|
247
|
+
| `sort_by` | line-by-line | `"line"` (default) or `"time"` for the console table. |
|
|
248
|
+
| `top_n` | line-by-line | Show only the N slowest lines in the console. |
|
|
249
|
+
|
|
250
|
+
### Notes and limitations
|
|
251
|
+
|
|
252
|
+
- `line_by_line_profile` uses `sys.settrace`, so it slows the profiled function
|
|
253
|
+
down considerably. Use it on suspicious functions, not production hot paths.
|
|
254
|
+
- Memory tracking is the most expensive part of profiling. Pass
|
|
255
|
+
`track_memory=False` for timing-only measurements.
|
|
256
|
+
- Line timings are wall-clock samples: time spent inside calls is attributed to
|
|
257
|
+
the calling line, and time spent suspended inside an `await` is not attributed
|
|
258
|
+
to any line.
|
|
259
|
+
- Recursive calls are aggregated into the outermost profile; the time spent in
|
|
260
|
+
recursion is attributed to the recursive line.
|
|
261
|
+
- `line_by_line_profile` traces only the calling thread. Work performed on other
|
|
262
|
+
threads is not attributed to lines.
|
|
263
|
+
- Async generators are not profiled (a `RuntimeWarning` is emitted); wrap the
|
|
264
|
+
body in a regular coroutine instead.
|
|
265
|
+
|
|
266
|
+
## Releasing
|
|
267
|
+
|
|
268
|
+
Releases are published to PyPI from GitHub Actions using
|
|
269
|
+
[PyPI trusted publishing](https://docs.pypi.org/trusted-publishers/) (OpenID
|
|
270
|
+
Connect). No API token or password is stored in the repository.
|
|
271
|
+
|
|
272
|
+
One-time setup — on PyPI, open the project (or *Publishing* → *Add a new
|
|
273
|
+
pending publisher* for a brand new project) and fill in:
|
|
274
|
+
|
|
275
|
+
| Field | Value |
|
|
276
|
+
|-------|-------|
|
|
277
|
+
| Owner | `Infinitode` |
|
|
278
|
+
| Repository name | `FuncProfiler` |
|
|
279
|
+
| Workflow name | `build_and_publish.yml` |
|
|
280
|
+
| Environment name | *(leave blank)* |
|
|
281
|
+
|
|
282
|
+
The publisher is configured without a GitHub environment, so the `publish` job
|
|
283
|
+
does not declare one either. The two must always agree: an environment name on
|
|
284
|
+
PyPI requires a matching `environment:` block in the workflow, and a workflow
|
|
285
|
+
`environment:` block requires a matching name on PyPI — otherwise the OIDC
|
|
286
|
+
token's claim does not match and PyPI rejects the upload. To add deployment
|
|
287
|
+
protection later, create the environment on both sides at the same time.
|
|
288
|
+
|
|
289
|
+
To cut a release:
|
|
290
|
+
|
|
291
|
+
```bash
|
|
292
|
+
git tag v1.3.0
|
|
293
|
+
git push origin v1.3.0
|
|
294
|
+
```
|
|
295
|
+
|
|
296
|
+
A leading `v` is stripped, so the tag `v1.3.0` publishes version `1.3.0`.
|
|
297
|
+
The workflow validates the tag, runs the tests, stamps the version into
|
|
298
|
+
`setup.py` and `funcprofiler/__init__.py`, builds the sdist and wheel, checks
|
|
299
|
+
the metadata with `twine check`, and publishes with OIDC. PEP 740 digital
|
|
300
|
+
attestations are generated automatically. The `PYPI_API_TOKEN` secret is no
|
|
301
|
+
longer used and can be deleted.
|
|
302
|
+
|
|
303
|
+
## Contributing
|
|
304
|
+
|
|
305
|
+
Contributions are welcome! Please open an issue or submit a pull request on [GitHub](https://github.com/infinitode/funcprofiler). Run the test suite with:
|
|
306
|
+
|
|
307
|
+
```bash
|
|
308
|
+
python -m unittest test -v
|
|
309
|
+
```
|
|
310
|
+
|
|
311
|
+
## License
|
|
312
|
+
|
|
313
|
+
FuncProfiler is released under the **MIT License (Modified)**. See the [LICENSE](https://github.com/infinitode/funcprofiler/blob/main/LICENSE) file for details.
|
|
@@ -0,0 +1,273 @@
|
|
|
1
|
+
# FuncProfiler
|
|
2
|
+

|
|
3
|
+
[](https://github.com/infinitode/funcprofiler)
|
|
4
|
+

|
|
5
|
+

|
|
6
|
+

|
|
7
|
+
|
|
8
|
+
An open-source Python library for identifying bottlenecks in code. It includes function profiling, line-by-line profiling, aggregated statistics, logging and report exports — with no third-party dependencies.
|
|
9
|
+
|
|
10
|
+
## Changelog (v1.3.0)
|
|
11
|
+
|
|
12
|
+
### Fixed
|
|
13
|
+
|
|
14
|
+
- **`@function_profile` without parentheses** no longer raises `TypeError`; both `@function_profile` and `@function_profile(...)` work.
|
|
15
|
+
- **Exceptions no longer leak profiling state.** Previously a raised exception skipped `tracemalloc.stop()` and `sys.settrace(None)`, so tracing stayed enabled for the rest of the process and every later measurement was wrong. Cleanup now always happens.
|
|
16
|
+
- **Nested and recursive profiled calls no longer corrupt measurements.** A nested call used to stop the outer call's `tracemalloc` session (reporting `0.0 MB`), and a caller-owned `tracemalloc` session was silently stopped. Nested calls now join the existing session and report "not attributable" (`n/a`) instead of a fake zero.
|
|
17
|
+
- **Line-by-line tracing only instruments the profiled function.** Unrelated frames (libraries, comprehensions, helpers, the standard library) are no longer traced. Tracing overhead drops to roughly 1.2× when memory tracking is disabled, against roughly 5× before.
|
|
18
|
+
- **Recursion is aggregated into one line-by-line report** instead of re-instrumenting and printing a separate report for each recursive call.
|
|
19
|
+
- **Existing trace hooks are preserved.** Coverage tools and debuggers that set a trace function no longer have it destroyed; the previous tracer is restored.
|
|
20
|
+
- **Export filenames no longer double their extension** (`report.json` used to create `report.json.json`), and missing target directories are created automatically.
|
|
21
|
+
- **HTML reports escape profiled values**, so return values, arguments, source code and docstrings can no longer break or inject into the report. Markdown exports escape `|`.
|
|
22
|
+
- **YAML/TOML/XML exports are valid documents.** Keys containing spaces are quoted, multi-line values use proper block scalars, XML uses legal element names and a declaration.
|
|
23
|
+
- **Functions without retrievable source** (`exec`, frozen apps, some REPL sessions) no longer crash line-by-line exports; their source is shown as `???`.
|
|
24
|
+
- **CSV output uses the `csv` module** instead of hand-wrapped quotes, and repeated exports no longer silently mix runs without a header or run marker.
|
|
25
|
+
- **`export_format` and `log_level` are validated when the decorator is created**, so a typo fails immediately instead of after the profiled function has already run.
|
|
26
|
+
- **Shared logs are actually shared**: one file per process rather than one per function (the filename used to be derived from the clock at decoration time).
|
|
27
|
+
- **Per-line memory is no longer the cumulative `tracemalloc` peak** (which could only ever increase); it now samples the heap while the line executes.
|
|
28
|
+
- Empty line-by-line reports no longer raise `IndexError` when exporting.
|
|
29
|
+
|
|
30
|
+
### Added
|
|
31
|
+
|
|
32
|
+
- **`profile_block`** context manager for profiling arbitrary code blocks.
|
|
33
|
+
- **Aggregated statistics**: `get_stats`, `reset_stats`, `summary_rows`, `print_summary` and `export_summary` answer "which function is slow overall?" without parsing reports.
|
|
34
|
+
- **New decorator options**: `track_memory`, `sample_every`, `include_args`, `include_return_value`, `max_value_length`, `append`, `export_dir`, `logger`, `sort_by` and `top_n`.
|
|
35
|
+
- **`log_level="silent"`** and the ability to send console output to a `logging.Logger` with `logger=`.
|
|
36
|
+
- **Async and generator support.** Coroutines are timed across their whole awaited lifetime and generators from first `next()` to exhaustion. Async generators emit a `RuntimeWarning` instead of silently reporting ~0 s.
|
|
37
|
+
- **Hotspot columns**: line reports now include a `Percent` column and use human-readable units (`µs`, `ms`, `s`) in the console.
|
|
38
|
+
- **Helpers and metadata**: `format_duration`, `format_memory`, `EXPORT_FORMATS`, `__version__` and a `py.typed` marker.
|
|
39
|
+
|
|
40
|
+
### Changed
|
|
41
|
+
|
|
42
|
+
- Exports overwrite the target file by default; pass `append=True` to accumulate runs (`txt`, `json`, `csv`, `md`, `html`).
|
|
43
|
+
- Line-by-line exports include `Percent` and `Timestamp` columns so appended rows stay distinguishable.
|
|
44
|
+
- Exporters no longer print; the decorators report `Report exported to: …` instead.
|
|
45
|
+
- The console line-by-line report is aligned and unit-aware (see examples below).
|
|
46
|
+
- Minimum supported Python is now 3.8; CI tests every supported version.
|
|
47
|
+
- Releases are published with PyPI trusted publishing (OIDC) and PEP 740 attestations — no API token secret — from a build job that is separate from the publishing job.
|
|
48
|
+
|
|
49
|
+
### Migrating from 1.2.0
|
|
50
|
+
|
|
51
|
+
- Nothing has to change for typical usage. Line-by-line `csv`/`html` exports now overwrite instead of appending; add `append=True` to restore accumulation.
|
|
52
|
+
- If you parsed the old console output, note that line reports are now a table with `Time`, `%` and `Memory` columns.
|
|
53
|
+
- `export_profiling_data` and `export_function_profile_data` keep their signatures and now return the written path.
|
|
54
|
+
|
|
55
|
+
## Changelog (v.1.2.0):
|
|
56
|
+
- Significant performance improvements for both function and line-by-line profiling.
|
|
57
|
+
- Cached function metadata at decoration time to reduce overhead during execution.
|
|
58
|
+
- Optimized line-by-line tracing using code object identity comparison.
|
|
59
|
+
- Implemented buffered logging for shared logs to minimize frequent file I/O.
|
|
60
|
+
- Improved trace accuracy by properly capturing the final line's execution time.
|
|
61
|
+
- Refactored export logic for more efficient report generation.
|
|
62
|
+
|
|
63
|
+
## Changelog (v.1.1.0):
|
|
64
|
+
- Added support for 2 new export formats: `yaml` and `toml`.
|
|
65
|
+
- Exports now include more information: peak memory usage, timestamp, arguments, return value, filepath, line number, and docstring.
|
|
66
|
+
- Added `enabled` and `log_level` options to the decorators.
|
|
67
|
+
- Improved export formats for better readability.
|
|
68
|
+
|
|
69
|
+
## Installation
|
|
70
|
+
|
|
71
|
+
You can install FuncProfiler using pip:
|
|
72
|
+
|
|
73
|
+
```bash
|
|
74
|
+
pip install funcprofiler
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
## Supported Python Versions
|
|
78
|
+
|
|
79
|
+
FuncProfiler supports Python 3.8 and later (tested on 3.8 – 3.13).
|
|
80
|
+
|
|
81
|
+
## Features
|
|
82
|
+
|
|
83
|
+
- **Function Profiling**: monitor a function's execution time and memory usage.
|
|
84
|
+
- **Line-by-Line Profiling**: execution time, percentage of total, and memory for every line.
|
|
85
|
+
- **Block Profiling**: profile any `with` block, not just functions.
|
|
86
|
+
- **Aggregated Statistics**: totals, means, min/max and peak memory per function.
|
|
87
|
+
- **Shared Logging**: log profiler output to a single `.txt` file.
|
|
88
|
+
- **File Exports**: eight report formats.
|
|
89
|
+
- **Async & Generators**: coroutine and generator functions are measured correctly.
|
|
90
|
+
- **Low-overhead options**: `sample_every`, `track_memory=False`, `enabled=False`.
|
|
91
|
+
|
|
92
|
+
## Export Formats
|
|
93
|
+
|
|
94
|
+
| Format | `function_profile` | `line_by_line_profile` | `append=True` |
|
|
95
|
+
|--------|--------------------|------------------------|---------------|
|
|
96
|
+
| `txt` | ✅ | ✅ | ✅ |
|
|
97
|
+
| `json` | ✅ | ✅ | ✅ |
|
|
98
|
+
| `csv` | ✅ | ✅ | ✅ |
|
|
99
|
+
| `html` | ✅ | ✅ | ✅ |
|
|
100
|
+
| `xml` | ✅ | ✅ | ❌ |
|
|
101
|
+
| `md` | ✅ | ✅ | ✅ |
|
|
102
|
+
| `yaml` | ✅ | ✅ | ✅ |
|
|
103
|
+
| `toml` | ✅ | ✅ | ✅ |
|
|
104
|
+
|
|
105
|
+
## Usage
|
|
106
|
+
|
|
107
|
+
### Function Profiling
|
|
108
|
+
|
|
109
|
+
```python
|
|
110
|
+
from funcprofiler import function_profile
|
|
111
|
+
|
|
112
|
+
@function_profile(export_format="html", shared_log=True, log_level="debug")
|
|
113
|
+
def some_function():
|
|
114
|
+
return "Hello World."
|
|
115
|
+
|
|
116
|
+
message = some_function()
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
A bare `@function_profile` (without parentheses) also works.
|
|
120
|
+
|
|
121
|
+
### Line-by-Line Profiling
|
|
122
|
+
|
|
123
|
+
```python
|
|
124
|
+
from funcprofiler import line_by_line_profile
|
|
125
|
+
|
|
126
|
+
@line_by_line_profile(shared_log=True, enabled=True)
|
|
127
|
+
def some_complicated_function(n):
|
|
128
|
+
total = 0
|
|
129
|
+
for i in range(n):
|
|
130
|
+
for j in range(i):
|
|
131
|
+
total += (i * j) ** 0.5
|
|
132
|
+
return total
|
|
133
|
+
|
|
134
|
+
total = some_complicated_function(1000)
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
Console output is a compact table of hotspots:
|
|
138
|
+
|
|
139
|
+
```
|
|
140
|
+
[FUNCPROFILER] Line-by-line profile for 'some_complicated_function' (6 line(s), total 82.13 ms, peak 0.0060 MB)
|
|
141
|
+
Line Source Time % Memory
|
|
142
|
+
4 total = 0 1.20 µs 0.00% 0.0021 MB
|
|
143
|
+
5 for i in range(n): 21.44 ms 26.10% 0.0024 MB
|
|
144
|
+
7 total += (i * j) ** 0.5 60.02 ms 73.07% 0.0024 MB
|
|
145
|
+
8 return total 3.37 µs 0.00% 0.0024 MB
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
Use `sort_by="time"` to order by cost and `top_n=10` to keep the output short.
|
|
149
|
+
|
|
150
|
+
### Block Profiling
|
|
151
|
+
|
|
152
|
+
```python
|
|
153
|
+
from funcprofiler import profile_block
|
|
154
|
+
|
|
155
|
+
with profile_block("load-data", export_format="json", filename="load") as block:
|
|
156
|
+
rows = expensive_io()
|
|
157
|
+
|
|
158
|
+
print(block.execution_time, block.peak_memory_usage)
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
### Aggregated Statistics
|
|
162
|
+
|
|
163
|
+
Every profiled call is accumulated in a process-wide registry (disable with
|
|
164
|
+
`capture_stats=False`):
|
|
165
|
+
|
|
166
|
+
```python
|
|
167
|
+
from funcprofiler import function_profile, get_stats, print_summary, export_summary
|
|
168
|
+
|
|
169
|
+
@function_profile(log_level="silent")
|
|
170
|
+
def parse_row(row):
|
|
171
|
+
...
|
|
172
|
+
|
|
173
|
+
for row in rows:
|
|
174
|
+
parse_row(row)
|
|
175
|
+
|
|
176
|
+
print_summary(sort_by="total_time", top_n=10)
|
|
177
|
+
export_summary("csv", "profile_summary")
|
|
178
|
+
|
|
179
|
+
stats = get_stats() # {"myapp.parse_row": {"calls": 10_000, ...}}
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
```
|
|
183
|
+
[FUNCPROFILER] Profile summary
|
|
184
|
+
Function Calls Errors Total Mean Min Max Peak Mem
|
|
185
|
+
------------------ ----- ------ -------- -------- -------- -------- ---------
|
|
186
|
+
myapp.parse_row 10000 0 1.204 s 120.40 µs 96.10 µs 1.201 ms 0.0210 MB
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
### Options
|
|
190
|
+
|
|
191
|
+
| Option | Applies to | Description |
|
|
192
|
+
|--------|-----------|-------------|
|
|
193
|
+
| `export_format` | both | `txt`, `json`, `csv`, `html`, `xml`, `md`, `yaml`, `toml` (case-insensitive). |
|
|
194
|
+
| `filename` | both | Output filename, with or without extension. |
|
|
195
|
+
| `shared_log` | both | Append to one process-wide `.txt` log. |
|
|
196
|
+
| `enabled` | both | `False` disables profiling entirely. |
|
|
197
|
+
| `log_level` | both | `"info"`, `"debug"` or `"silent"`. |
|
|
198
|
+
| `logger` | both | Send console output to a `logging.Logger`. |
|
|
199
|
+
| `capture_stats` | both | Accumulate results in `get_stats()` (default `True`). |
|
|
200
|
+
| `track_memory` | both | Measure memory with `tracemalloc` (default `True`). |
|
|
201
|
+
| `sample_every` | both | Profile only every Nth call. |
|
|
202
|
+
| `include_args` | both | Include call arguments in logs/exports. |
|
|
203
|
+
| `include_return_value` | both | Include the return value in logs/exports. |
|
|
204
|
+
| `max_value_length` | both | Truncate recorded reprs (default 500 chars). |
|
|
205
|
+
| `append` | both | Append a run to an existing export. |
|
|
206
|
+
| `export_dir` | both | Directory for relative export filenames. |
|
|
207
|
+
| `sort_by` | line-by-line | `"line"` (default) or `"time"` for the console table. |
|
|
208
|
+
| `top_n` | line-by-line | Show only the N slowest lines in the console. |
|
|
209
|
+
|
|
210
|
+
### Notes and limitations
|
|
211
|
+
|
|
212
|
+
- `line_by_line_profile` uses `sys.settrace`, so it slows the profiled function
|
|
213
|
+
down considerably. Use it on suspicious functions, not production hot paths.
|
|
214
|
+
- Memory tracking is the most expensive part of profiling. Pass
|
|
215
|
+
`track_memory=False` for timing-only measurements.
|
|
216
|
+
- Line timings are wall-clock samples: time spent inside calls is attributed to
|
|
217
|
+
the calling line, and time spent suspended inside an `await` is not attributed
|
|
218
|
+
to any line.
|
|
219
|
+
- Recursive calls are aggregated into the outermost profile; the time spent in
|
|
220
|
+
recursion is attributed to the recursive line.
|
|
221
|
+
- `line_by_line_profile` traces only the calling thread. Work performed on other
|
|
222
|
+
threads is not attributed to lines.
|
|
223
|
+
- Async generators are not profiled (a `RuntimeWarning` is emitted); wrap the
|
|
224
|
+
body in a regular coroutine instead.
|
|
225
|
+
|
|
226
|
+
## Releasing
|
|
227
|
+
|
|
228
|
+
Releases are published to PyPI from GitHub Actions using
|
|
229
|
+
[PyPI trusted publishing](https://docs.pypi.org/trusted-publishers/) (OpenID
|
|
230
|
+
Connect). No API token or password is stored in the repository.
|
|
231
|
+
|
|
232
|
+
One-time setup — on PyPI, open the project (or *Publishing* → *Add a new
|
|
233
|
+
pending publisher* for a brand new project) and fill in:
|
|
234
|
+
|
|
235
|
+
| Field | Value |
|
|
236
|
+
|-------|-------|
|
|
237
|
+
| Owner | `Infinitode` |
|
|
238
|
+
| Repository name | `FuncProfiler` |
|
|
239
|
+
| Workflow name | `build_and_publish.yml` |
|
|
240
|
+
| Environment name | *(leave blank)* |
|
|
241
|
+
|
|
242
|
+
The publisher is configured without a GitHub environment, so the `publish` job
|
|
243
|
+
does not declare one either. The two must always agree: an environment name on
|
|
244
|
+
PyPI requires a matching `environment:` block in the workflow, and a workflow
|
|
245
|
+
`environment:` block requires a matching name on PyPI — otherwise the OIDC
|
|
246
|
+
token's claim does not match and PyPI rejects the upload. To add deployment
|
|
247
|
+
protection later, create the environment on both sides at the same time.
|
|
248
|
+
|
|
249
|
+
To cut a release:
|
|
250
|
+
|
|
251
|
+
```bash
|
|
252
|
+
git tag v1.3.0
|
|
253
|
+
git push origin v1.3.0
|
|
254
|
+
```
|
|
255
|
+
|
|
256
|
+
A leading `v` is stripped, so the tag `v1.3.0` publishes version `1.3.0`.
|
|
257
|
+
The workflow validates the tag, runs the tests, stamps the version into
|
|
258
|
+
`setup.py` and `funcprofiler/__init__.py`, builds the sdist and wheel, checks
|
|
259
|
+
the metadata with `twine check`, and publishes with OIDC. PEP 740 digital
|
|
260
|
+
attestations are generated automatically. The `PYPI_API_TOKEN` secret is no
|
|
261
|
+
longer used and can be deleted.
|
|
262
|
+
|
|
263
|
+
## Contributing
|
|
264
|
+
|
|
265
|
+
Contributions are welcome! Please open an issue or submit a pull request on [GitHub](https://github.com/infinitode/funcprofiler). Run the test suite with:
|
|
266
|
+
|
|
267
|
+
```bash
|
|
268
|
+
python -m unittest test -v
|
|
269
|
+
```
|
|
270
|
+
|
|
271
|
+
## License
|
|
272
|
+
|
|
273
|
+
FuncProfiler is released under the **MIT License (Modified)**. See the [LICENSE](https://github.com/infinitode/funcprofiler/blob/main/LICENSE) file for details.
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
"""FuncProfiler - find the bottlenecks in your Python code.
|
|
2
|
+
|
|
3
|
+
The package exposes two decorators, one context manager and a handful of
|
|
4
|
+
helpers:
|
|
5
|
+
|
|
6
|
+
* :func:`function_profile` - measure a function's execution time and memory.
|
|
7
|
+
* :func:`line_by_line_profile` - attribute time and memory to individual lines.
|
|
8
|
+
* :func:`profile_block` - profile an arbitrary ``with`` block.
|
|
9
|
+
* :func:`get_stats`, :func:`print_summary`, :func:`export_summary` - aggregate
|
|
10
|
+
statistics across every profiled call.
|
|
11
|
+
* :func:`export_function_profile_data`, :func:`export_profiling_data`,
|
|
12
|
+
:func:`export_table` - write reports by hand.
|
|
13
|
+
|
|
14
|
+
Quick start::
|
|
15
|
+
|
|
16
|
+
from funcprofiler import function_profile, print_summary
|
|
17
|
+
|
|
18
|
+
@function_profile(export_format="html", log_level="info")
|
|
19
|
+
def expensive(n):
|
|
20
|
+
return sum(i * i for i in range(n))
|
|
21
|
+
|
|
22
|
+
expensive(100_000)
|
|
23
|
+
print_summary()
|
|
24
|
+
"""
|
|
25
|
+
|
|
26
|
+
from ._utils import VALID_FORMATS, format_duration, format_memory, normalise_format
|
|
27
|
+
from .core import ProfileBlock, function_profile, line_by_line_profile, profile_block
|
|
28
|
+
from .exporters import (
|
|
29
|
+
export_function_profile_data,
|
|
30
|
+
export_profiling_data,
|
|
31
|
+
export_table,
|
|
32
|
+
)
|
|
33
|
+
from .stats import (
|
|
34
|
+
FunctionStats,
|
|
35
|
+
export_summary,
|
|
36
|
+
get_stats,
|
|
37
|
+
print_summary,
|
|
38
|
+
profile_summary,
|
|
39
|
+
reset_stats,
|
|
40
|
+
summary_rows,
|
|
41
|
+
)
|
|
42
|
+
|
|
43
|
+
#: Version of the package. Kept in sync with the published distribution.
|
|
44
|
+
__version__ = "1.3.0"
|
|
45
|
+
|
|
46
|
+
#: Convenience alias so users can validate a format without importing internals.
|
|
47
|
+
EXPORT_FORMATS = VALID_FORMATS
|
|
48
|
+
|
|
49
|
+
__all__ = [
|
|
50
|
+
"EXPORT_FORMATS",
|
|
51
|
+
"FunctionStats",
|
|
52
|
+
"ProfileBlock",
|
|
53
|
+
"__version__",
|
|
54
|
+
"export_function_profile_data",
|
|
55
|
+
"export_profiling_data",
|
|
56
|
+
"export_summary",
|
|
57
|
+
"export_table",
|
|
58
|
+
"format_duration",
|
|
59
|
+
"format_memory",
|
|
60
|
+
"function_profile",
|
|
61
|
+
"get_stats",
|
|
62
|
+
"line_by_line_profile",
|
|
63
|
+
"normalise_format",
|
|
64
|
+
"print_summary",
|
|
65
|
+
"profile_block",
|
|
66
|
+
"profile_summary",
|
|
67
|
+
"reset_stats",
|
|
68
|
+
"summary_rows",
|
|
69
|
+
]
|