Skip to main content

FuncProfiler

Python Version Code Size Downloads License Compliance PyPI Version

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_profile without parentheses no longer raises TypeError; both @function_profile and @function_profile(...) work.
  • 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.
  • 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.
  • 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.json used to create report.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 csv module instead of hand-wrapped quotes, and repeated exports no longer silently mix runs without a header or run marker.
  • 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.
  • 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 tracemalloc peak (which could only ever increase); it now samples the heap while the line executes.
  • Empty line-by-line reports no longer raise IndexError when exporting.

Added

  • profile_block context manager for profiling arbitrary code blocks.
  • Aggregated statistics: get_stats, reset_stats, summary_rows, print_summary and export_summary answer "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_by and top_n.
  • log_level="silent" and the ability to send console output to a logging.Logger with logger=.
  • 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.
  • Hotspot columns: line reports now include a Percent column and use human-readable units (µs, ms, s) in the console.
  • Helpers and metadata: format_duration, format_memory, EXPORT_FORMATS, __version__ and a py.typed marker.

Changed

  • Exports overwrite the target file by default; pass append=True to accumulate runs (txt, json, csv, md, html).
  • Line-by-line exports include Percent and Timestamp columns 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/html exports now overwrite instead of appending; add append=True to restore accumulation.
  • If you parsed the old console output, note that line reports are now a table with Time, % and Memory columns.
  • export_profiling_data and export_function_profile_data keep 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: yaml and toml.
  • Exports now include more information: peak memory usage, timestamp, arguments, return value, filepath, line number, and docstring.
  • Added enabled and log_level options 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 with block, not just functions.
  • Aggregated Statistics: totals, means, min/max and peak memory per function.
  • Shared Logging: log profiler output to a single .txt file.
  • 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_profile uses sys.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=False for 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 await is 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_profile traces only the calling thread. Work performed on other threads is not attributed to lines.
  • Async generators are not profiled (a RuntimeWarning is 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)

Source distribution for funcprofiler 1.3.0
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)

Table of built distributions (wheels) for funcprofiler 1.3.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page