funcprofiler 1.2.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.
@@ -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
+ ![Python Version](https://img.shields.io/badge/python-3.8%2B-blue.svg)
43
+ [![Code Size](https://img.shields.io/github/languages/code-size/infinitode/funcprofiler)](https://github.com/infinitode/funcprofiler)
44
+ ![Downloads](https://pepy.tech/badge/funcprofiler)
45
+ ![License Compliance](https://img.shields.io/badge/license-compliance-brightgreen.svg)
46
+ ![PyPI Version](https://img.shields.io/pypi/v/funcprofiler)
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
+ ![Python Version](https://img.shields.io/badge/python-3.8%2B-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, 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
+ ]