scope-profiler

This module provides a unified profiling system for Python applications, with optional integration of LIKWID markers using the pylikwid marker API for hardware performance counters.

It allows you to:

  • Configure profiling globally via a singleton ProfilingConfig.
  • Collect timing data via context-managed profiling regions.
  • Use a clean decorator syntax to profile functions.
  • Optionally record time traces in HDF5 files.
  • Automatically initialize and close LIKWID markers only when needed.
  • Print aggregated summaries of all profiling regions.

Install

Install from PyPI:

pip install scope-profiler

Usage

To set up the configuration, create an instance of ProfilingConfig and add it to the ProfileManager, this should be done once at application startup and will persist until the program exits or is explicitly finalized (see below). Note that the config applies to any profiling contexts created (even in other files) after it has been initialized.

from scope_profiler import ProfileManager

# Setup global profiling configuration
ProfileManager.setup(
    use_likwid=False,
    time_trace=True,
    flush_to_disk=True,
)

# Profile the main() function with a decorator
@ProfileManager.profile("main")
def main():
    x = 0
    for i in range(10):
        # Profile each iteration with a context manager
        with ProfileManager.profile_region(region_name="iteration"):
            x += 1

# Call main
main()

# Finalize profiler
ProfileManager.finalize()

Execution:

❯ python test.py
Region: main
  Total Calls : 1
  Total Time  : 0.001503709 s
  Avg Time    : 0.001503709 s
  Min Time    : 0.001503709 s
  Max Time    : 0.001503709 s
  Std Dev     : 0.0 s
----------------------------------------
Region: iteration
  Total Calls : 10
  Total Time  : 3.832e-06 s
  Avg Time    : 3.832e-07 s
  Min Time    : 2.08e-07 s
  Max Time    : 8.75e-07 s
  Std Dev     : 2.2431888016838885e-07 s
----------------------------------------

Overhead

The profiling overhead per call depends on the region type. The benchmark below (examples/benchmark_overhead.py) measures each mode against a bare function call:

Profiling overhead by region type

The two modes most relevant to HPC — NCallsOnly and TimeOnly — add roughly 0.09 µs and 0.75 µs per instrumented call respectively.

Profiling can also be fully deactivated at setup time (profiling_activated=False) to reduce the overhead to ~0.03 µs — barely above a bare function call — making it safe to leave instrumentation in production code and toggle it on only when needed.

The LineProfiler mode is intentionally heavier (~41 µs/call) because line_profiler traces every source line. It is designed for targeted debugging of individual functions, not for always-on use in hot loops.

Project links

Data verified by PyPI on Jul 7, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.5.0)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for max-models from gravatar.com max-models

Credits

Author: Max

GitHub Statistics

Data verified by PyPI on Jul 7, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

Requires

Python >=3.8

Provides Extra

mpi dev docs test

Tags

python

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

scope_profiler-0.1.10.tar.gz (22.5 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

scope_profiler-0.1.10-py3-none-any.whl (26.8 kB view details)

Uploaded Python 3

File details

Details for the file scope_profiler-0.1.10.tar.gz.

File metadata

  • Download URL: scope_profiler-0.1.10.tar.gz
  • Upload date:
  • Size: 22.5 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for scope_profiler-0.1.10.tar.gz
Algorithm Hash digest
SHA256 383146c13b68f8d25cdc830400b3eb989512e650cc1abba8d3fed18a32754f5b
MD5 17273bcba9ad81679a32bce5db47f569
BLAKE2b-256 39df1d20e1ee2d06d09df319cdca949ab38eafcf6bc88f42746da0b5f025dee9

See more details on using hashes here.

Provenance

The following attestation bundles were made for scope_profiler-0.1.10.tar.gz:

Publisher: publish.yml on max-models/scope-profiler

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file scope_profiler-0.1.10-py3-none-any.whl.

File metadata

File hashes

Hashes for scope_profiler-0.1.10-py3-none-any.whl
Algorithm Hash digest
SHA256 925d60f8063278dcad41586f05ce900608433b2286c07d890af4b9b83ad5c1b0
MD5 1781072884e2ece33145c30d8734946b
BLAKE2b-256 81e5f9a2b4fe7d41604850d2689e0f13cedf06d51f0acd2f501fdbc1ba89ad23

See more details on using hashes here.

Provenance

The following attestation bundles were made for scope_profiler-0.1.10-py3-none-any.whl:

Publisher: publish.yml on max-models/scope-profiler

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

0.5.0

2 files

0.4.2

2 files

0.4.1

2 files

0.4.0

2 files

0.3.6

2 files

0.3.5

2 files

0.3.4

2 files

0.3.3

2 files

0.3.2

2 files

0.3.1

2 files

0.3.0

2 files

0.2.8

2 files

0.2.7

2 files

0.2.6

2 files

0.2.5

2 files

0.2.4

2 files

0.2.3

2 files

0.2.2

2 files

0.2.1

2 files

0.2

2 files

0.1.11

2 files

This release

0.1.10 This release

2 files

0.1.9

2 files

0.1.8

2 files

0.1.7

2 files

0.1.6

2 files

0.1.5

2 files

0.1.4

2 files

0.1

2 files

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