FuncProfiler
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.
Changelog (v1.3.0)
Fixed
@function_profilewithout parentheses no longer raisesTypeError; both@function_profileand@function_profile(...)work.- Exceptions no longer leak profiling state. Previously a raised exception skipped
tracemalloc.stop()andsys.settrace(None), so tracing stayed enabled for the rest of the process and every later measurement was wrong. Cleanup now always happens. - Nested and recursive profiled calls no longer corrupt measurements. A nested call used to stop the outer call's
tracemallocsession (reporting0.0 MB), and a caller-ownedtracemallocsession was silently stopped. Nested calls now join the existing session and report "not attributable" (n/a) instead of a fake zero. - 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.
- Recursion is aggregated into one line-by-line report instead of re-instrumenting and printing a separate report for each recursive call.
- Existing trace hooks are preserved. Coverage tools and debuggers that set a trace function no longer have it destroyed; the previous tracer is restored.
- Export filenames no longer double their extension (
report.jsonused to createreport.json.json), and missing target directories are created automatically. - 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
|. - 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.
- Functions without retrievable source (
exec, frozen apps, some REPL sessions) no longer crash line-by-line exports; their source is shown as???. - CSV output uses the
csvmodule instead of hand-wrapped quotes, and repeated exports no longer silently mix runs without a header or run marker. export_formatandlog_levelare validated when the decorator is created, so a typo fails immediately instead of after the profiled function has already run.- 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).
- Per-line memory is no longer the cumulative
tracemallocpeak (which could only ever increase); it now samples the heap while the line executes. - Empty line-by-line reports no longer raise
IndexErrorwhen exporting.
Added
profile_blockcontext manager for profiling arbitrary code blocks.- Aggregated statistics:
get_stats,reset_stats,summary_rows,print_summaryandexport_summaryanswer "which function is slow overall?" without parsing reports. - New decorator options:
track_memory,sample_every,include_args,include_return_value,max_value_length,append,export_dir,logger,sort_byandtop_n. log_level="silent"and the ability to send console output to alogging.Loggerwithlogger=.- Async and generator support. Coroutines are timed across their whole awaited lifetime and generators from first
next()to exhaustion. Async generators emit aRuntimeWarninginstead of silently reporting ~0 s. - Hotspot columns: line reports now include a
Percentcolumn and use human-readable units (µs,ms,s) in the console. - Helpers and metadata:
format_duration,format_memory,EXPORT_FORMATS,__version__and apy.typedmarker.
Changed
- Exports overwrite the target file by default; pass
append=Trueto accumulate runs (txt,json,csv,md,html). - Line-by-line exports include
PercentandTimestampcolumns so appended rows stay distinguishable. - Exporters no longer print; the decorators report
Report exported to: …instead. - The console line-by-line report is aligned and unit-aware (see examples below).
- Minimum supported Python is now 3.8; CI tests every supported version.
- 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.
Migrating from 1.2.0
- Nothing has to change for typical usage. Line-by-line
csv/htmlexports now overwrite instead of appending; addappend=Trueto restore accumulation. - If you parsed the old console output, note that line reports are now a table with
Time,%andMemorycolumns. export_profiling_dataandexport_function_profile_datakeep their signatures and now return the written path.
Changelog (v.1.2.0):
- Significant performance improvements for both function and line-by-line profiling.
- Cached function metadata at decoration time to reduce overhead during execution.
- Optimized line-by-line tracing using code object identity comparison.
- Implemented buffered logging for shared logs to minimize frequent file I/O.
- Improved trace accuracy by properly capturing the final line's execution time.
- Refactored export logic for more efficient report generation.
Changelog (v.1.1.0):
- Added support for 2 new export formats:
yamlandtoml. - Exports now include more information: peak memory usage, timestamp, arguments, return value, filepath, line number, and docstring.
- Added
enabledandlog_leveloptions to the decorators. - Improved export formats for better readability.
Installation
You can install FuncProfiler using pip:
pip install funcprofiler
Supported Python Versions
FuncProfiler supports Python 3.8 and later (tested on 3.8 – 3.13).
Features
- Function Profiling: monitor a function's execution time and memory usage.
- Line-by-Line Profiling: execution time, percentage of total, and memory for every line.
- Block Profiling: profile any
withblock, not just functions. - Aggregated Statistics: totals, means, min/max and peak memory per function.
- Shared Logging: log profiler output to a single
.txtfile. - File Exports: eight report formats.
- Async & Generators: coroutine and generator functions are measured correctly.
- Low-overhead options:
sample_every,track_memory=False,enabled=False.
Export Formats
| Format | function_profile |
line_by_line_profile |
append=True |
|---|---|---|---|
txt |
✅ | ✅ | ✅ |
json |
✅ | ✅ | ✅ |
csv |
✅ | ✅ | ✅ |
html |
✅ | ✅ | ✅ |
xml |
✅ | ✅ | ❌ |
md |
✅ | ✅ | ✅ |
yaml |
✅ | ✅ | ✅ |
toml |
✅ | ✅ | ✅ |
Usage
Function Profiling
from funcprofiler import function_profile
@function_profile(export_format="html", shared_log=True, log_level="debug")
def some_function():
return "Hello World."
message = some_function()
A bare @function_profile (without parentheses) also works.
Line-by-Line Profiling
from funcprofiler import line_by_line_profile
@line_by_line_profile(shared_log=True, enabled=True)
def some_complicated_function(n):
total = 0
for i in range(n):
for j in range(i):
total += (i * j) ** 0.5
return total
total = some_complicated_function(1000)
Console output is a compact table of hotspots:
[FUNCPROFILER] Line-by-line profile for 'some_complicated_function' (6 line(s), total 82.13 ms, peak 0.0060 MB)
Line Source Time % Memory
4 total = 0 1.20 µs 0.00% 0.0021 MB
5 for i in range(n): 21.44 ms 26.10% 0.0024 MB
7 total += (i * j) ** 0.5 60.02 ms 73.07% 0.0024 MB
8 return total 3.37 µs 0.00% 0.0024 MB
Use sort_by="time" to order by cost and top_n=10 to keep the output short.
Block Profiling
from funcprofiler import profile_block
with profile_block("load-data", export_format="json", filename="load") as block:
rows = expensive_io()
print(block.execution_time, block.peak_memory_usage)
Aggregated Statistics
Every profiled call is accumulated in a process-wide registry (disable with
capture_stats=False):
from funcprofiler import function_profile, get_stats, print_summary, export_summary
@function_profile(log_level="silent")
def parse_row(row):
...
for row in rows:
parse_row(row)
print_summary(sort_by="total_time", top_n=10)
export_summary("csv", "profile_summary")
stats = get_stats() # {"myapp.parse_row": {"calls": 10_000, ...}}
[FUNCPROFILER] Profile summary
Function Calls Errors Total Mean Min Max Peak Mem
------------------ ----- ------ -------- -------- -------- -------- ---------
myapp.parse_row 10000 0 1.204 s 120.40 µs 96.10 µs 1.201 ms 0.0210 MB
Options
| Option | Applies to | Description |
|---|---|---|
export_format |
both | txt, json, csv, html, xml, md, yaml, toml (case-insensitive). |
filename |
both | Output filename, with or without extension. |
shared_log |
both | Append to one process-wide .txt log. |
enabled |
both | False disables profiling entirely. |
log_level |
both | "info", "debug" or "silent". |
logger |
both | Send console output to a logging.Logger. |
capture_stats |
both | Accumulate results in get_stats() (default True). |
track_memory |
both | Measure memory with tracemalloc (default True). |
sample_every |
both | Profile only every Nth call. |
include_args |
both | Include call arguments in logs/exports. |
include_return_value |
both | Include the return value in logs/exports. |
max_value_length |
both | Truncate recorded reprs (default 500 chars). |
append |
both | Append a run to an existing export. |
export_dir |
both | Directory for relative export filenames. |
sort_by |
line-by-line | "line" (default) or "time" for the console table. |
top_n |
line-by-line | Show only the N slowest lines in the console. |
Notes and limitations
line_by_line_profileusessys.settrace, so it slows the profiled function down considerably. Use it on suspicious functions, not production hot paths.- Memory tracking is the most expensive part of profiling. Pass
track_memory=Falsefor timing-only measurements. - Line timings are wall-clock samples: time spent inside calls is attributed to
the calling line, and time spent suspended inside an
awaitis not attributed to any line. - Recursive calls are aggregated into the outermost profile; the time spent in recursion is attributed to the recursive line.
line_by_line_profiletraces only the calling thread. Work performed on other threads is not attributed to lines.- Async generators are not profiled (a
RuntimeWarningis emitted); wrap the body in a regular coroutine instead.
Releasing
Releases are published to PyPI from GitHub Actions using PyPI trusted publishing (OpenID Connect). No API token or password is stored in the repository.
One-time setup — on PyPI, open the project (or Publishing → Add a new pending publisher for a brand new project) and fill in:
| Field | Value |
|---|---|
| Owner | Infinitode |
| Repository name | FuncProfiler |
| Workflow name | build_and_publish.yml |
| Environment name | (leave blank) |
The publisher is configured without a GitHub environment, so the publish job
does not declare one either. The two must always agree: an environment name on
PyPI requires a matching environment: block in the workflow, and a workflow
environment: block requires a matching name on PyPI — otherwise the OIDC
token's claim does not match and PyPI rejects the upload. To add deployment
protection later, create the environment on both sides at the same time.
To cut a release:
git tag v1.3.0
git push origin v1.3.0
A leading v is stripped, so the tag v1.3.0 publishes version 1.3.0.
The workflow validates the tag, runs the tests, stamps the version into
setup.py and funcprofiler/__init__.py, builds the sdist and wheel, checks
the metadata with twine check, and publishes with OIDC. PEP 740 digital
attestations are generated automatically. The PYPI_API_TOKEN secret is no
longer used and can be deleted.
Contributing
Contributions are welcome! Please open an issue or submit a pull request on GitHub. Run the test suite with:
python -m unittest test -v
License
FuncProfiler is released under the MIT License (Modified). See the LICENSE file for details.
Metadata
Release files for funcprofiler 1.3.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| funcprofiler-1.3.0.tar.gz | 31.2 kB | With provenance | Details for funcprofiler-1.3.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| funcprofiler-1.3.0-py3-none-any.whl | Python 3 | none | any | Details for funcprofiler-1.3.0-py3-none-any.whl |
Total release size: 58.9 kB
Release files / funcprofiler-1.3.0.tar.gz
| Download URL | funcprofiler-1.3.0.tar.gz |
|---|---|
| Size | 31.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
7f2bb3ee9f627f1f85cccc94b8a48438498702db01ac04657df77344dbf2b192
|
|
BLAKE2b-256 checksum How to use checksums |
8bd2eb4f78f8a1cdd788d52b331d41be783f89d1cc26a88dad5f690745b4300c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.
Transparency logRelease files / funcprofiler-1.3.0-py3-none-any.whl
| Download URL | funcprofiler-1.3.0-py3-none-any.whl |
|---|---|
| Size | 27.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
7b9ea964171f1b84fb5ac239ede7ebfbc60d3e4ab547cac2c88f68db80c5e42f
|
|
BLAKE2b-256 checksum How to use checksums |
dd19074d54916d92f43a6a26ac8736aa19e517c4e490831ebac3aebb5997e907
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.
Transparency logSecurity for funcprofiler 1.3.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for funcprofiler-1.3.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.