Cctime

Introduction

cctime is a Python library designed for precise measurement of code execution time. The package offers a set of high‑resolution timers that can be used as context managers, decorators, or callable objects. It supports nested timing, concurrent measurement in multithreaded environments, and flexible reporting formats. The design philosophy prioritizes minimal dependencies, ease of integration, and compatibility with both CPython and PyPy implementations. The library is distributed under the BSD‑3 Clause license and is maintained on a public repository hosted by a well‑known open‑source platform.

History and Background

Origins

The first public release of cctime appeared in early 2018 as a response to a demand within the scientific computing community for a lightweight profiling tool that could be embedded directly into scripts and notebooks. The original author, a researcher working in computational physics, combined the Python standard library’s time.perf_counter with a simple context‑manager pattern to create a reusable construct. The initial commit was tagged v0.1.0 and introduced the core CCTimer class.

Evolution of Features

Subsequent releases expanded the functionality to include support for named timers, hierarchical nesting, and automatic aggregation of results. Version 0.3.0 added a decorator interface for quick instrumentation of functions. In 2020, the library adopted an asynchronous context manager to accommodate coroutines in modern Python applications. The 2021 release integrated support for multi‑threaded timing by utilizing thread‑local storage to isolate timer instances across threads.

Community Adoption

Since its inception, cctime has garnered a modest but active user base. The community contributed several patches: a JSON report generator, a simple graphical summary, and an extension that integrates with the popular pytest framework. Contributions were managed through pull requests and issue tracking on the project’s public repository. The maintainers regularly review code for consistency with the project’s style guidelines and for adherence to the performance benchmarks defined in the documentation.

Key Concepts and Architecture

Timer Interface

The core abstraction of cctime is the CCTimer class. Instances of this class expose the following methods:

start() – records the current high‑resolution time and marks the timer as active.
stop() – calculates the elapsed time since the most recent start() call and stores it in an internal list.
elapsed() – returns the cumulative elapsed time across all intervals recorded for the timer.
reset() – clears the recorded intervals and sets the internal state to idle.

Each timer instance is thread‑local by default, ensuring that measurements in one thread do not interfere with those in another. Thread safety is achieved by wrapping the internal state with a lock that serializes access to the start‑stop cycle.

Context‑Manager Protocol

cctime implements the enter and exit methods to allow timers to be used with the with statement. This design reduces boilerplate code and guarantees that stop() is called even if an exception occurs within the block. The context‑manager returns the timer instance itself, enabling immediate inspection of elapsed time after the block finishes.

Nesting and Aggregation

Timers can be nested arbitrarily deep. Each nested timer maintains its own interval list; however, the library provides an aggregation helper that can summarize the hierarchy. The aggregation function produces a nested dictionary where keys represent timer names and values contain cumulative times and child timers. This structure facilitates the generation of human‑readable reports and graphical visualizations.

Decorators

For convenience, cctime offers a @timeit decorator that can be applied to any callable. The decorator automatically starts a timer before the function runs and stops it after the function returns. The decorator accepts an optional name argument that is used in reports and when nesting is required. When multiple decorated functions are called concurrently, each receives its own timer instance, again ensuring isolation.

Reporting and Output

The library includes a lightweight reporting module. The ReportGenerator class can render results in plain text, CSV, or JSON. For JSON output, the module preserves the nested structure described above, making it suitable for ingestion by downstream analysis tools. Plain‑text reports are formatted with indentation to reflect timer hierarchy, and include both elapsed times and percentages of total runtime for each section.

API and Features

Core Classes

CCTimer – Represents an individual timer with start, stop, and elapsed methods.

TimerGroup – Manages a collection of timers, allowing collective start/stop operations and combined reporting.

ReportGenerator – Produces formatted output from a TimerGroup or individual timers.

Convenience Functions

timeit(func, name=None) – Decorator for timing functions.
with_timer(name, group=None) – Context‑manager factory that returns a CCTimer instance, optionally adding it to a group.
measure(block, name=None) – Executes a callable within a timer context and returns elapsed time.

Threading and Async Support

Timers are designed to work seamlessly in threaded programs. Each thread has its own timer stack, preventing cross‑thread interference. For asynchronous code, cctime implements aenter and aexit methods on the CCTimer class, allowing timers to be used with async with statements. The asynchronous interface uses the same high‑resolution counter as its synchronous counterpart.

Extensibility

Users can subclass CCTimer to modify the measurement source. For example, a subclass could override _get_now to read from a custom high‑resolution clock or to integrate with a system‑specific timing API. The reporting module accepts user‑provided formatters, enabling the generation of custom output styles without altering the core library.

Configuration

The library exposes a global configuration object that controls formatting options, default reporting format, and thread‑local behavior. Configuration values include:

format_precision – Number of decimal places in time output.
default_format – Default report format (plain, csv, json).
thread_local – Boolean flag to enable or disable thread‑local timer storage.

Configuration can be modified at runtime, and changes affect subsequent timer creations.

Usage Patterns

Basic Timing

To measure a code block, a developer can instantiate a timer and use it as a context manager:

with cctime.with_timer("load_data") as timer:
    data = load_data_from_disk()
print(f"Data loaded in {timer.elapsed():.3f} seconds")

Here, the timer automatically records the start time on entering the block and stops on exit. The elapsed time is then formatted and printed.

Function Decoration

When profiling multiple functions, the decorator can be applied directly:

@cctime.timeit(name="compute")
def compute(values):
    # intensive computation
    return sum(v * v for v in values)

The decorated function returns its original result, while the timer records execution time under the name “compute.”

Nested Timing

Nested timing can be achieved by creating a timer group and adding timers to it:

group = cctime.TimerGroup()
with cctime.with_timer("pipeline", group=group) as pipeline_timer:
    with cctime.with_timer("step1", group=group):
        step1()
    with cctime.with_timer("step2", group=group):
        step2()
report = cctime.ReportGenerator(group)
print(report.text())

The resulting report displays a hierarchical view of elapsed times for the pipeline and its steps.

Async Profiling

In an asynchronous context, the timer can be used with async with:

async def async_task():
    async with cctime.with_timer("async_step"):
        await perform_io()

This pattern ensures that the timer measures the actual time spent awaiting I/O operations.

Threaded Measurement

When launching multiple threads, each thread creates its own timers. The following pattern demonstrates isolated measurement:

def worker():
    with cctime.with_timer("worker_task"):
        perform_heavy_computation()

threads = [threading.Thread(target=worker) for _ in range(4)]
for t in threads:
    t.start()
for t in threads:
    t.join()

Each worker thread records its own time, and the results can be aggregated post‑execution if desired.

Performance and Implementation Details

Timer Precision

cctime relies on time.perf_counter for measuring elapsed time. This function provides the highest available resolution on the platform and is unaffected by system clock changes. On CPython, perf_counter typically offers microsecond precision, while on PyPy the underlying implementation is similar. The library's internal state stores timestamps as floating‑point seconds relative to an arbitrary reference point, minimizing the risk of overflow for long‑running programs.

Overhead Analysis

Benchmarks conducted on a commodity laptop reveal that a single start–stop cycle incurs approximately 2–3 microseconds of overhead on CPython. In a tight loop with 10,000 iterations, the cumulative overhead remains under 30 milliseconds. For asynchronous timers, the overhead increases modestly due to the coroutine protocol, but remains negligible relative to typical I/O durations.

Memory Footprint

The timer objects store only a small list of intervals, each consisting of a pair of timestamps. For a timer with 1,000 intervals, memory consumption is roughly 80 kilobytes. The overhead scales linearly with the number of recorded intervals, making it suitable for profiling large, long‑running tasks without significant memory impact.

Thread‑Local Storage Mechanism

cctime employs the threading.local construct to maintain separate timer stacks per thread. When start() is invoked, the current thread’s local stack is pushed onto. Upon stop(), the stack is popped, ensuring that timers are correctly matched even in nested scenarios. The lock around stack manipulation guarantees that concurrent starts and stops in the same thread do not corrupt state.

Platform Compatibility

Because the library depends only on the Python standard library, it runs on all platforms that ship with CPython or PyPy: Linux, macOS, Windows, and even embedded Python distributions. The minimal dependencies reduce the risk of binary incompatibilities. The library includes a small test suite that runs on multiple Python versions, from 3.6 to 3.12, ensuring compatibility across the ecosystem.

cProfile and Profile

The built‑in cProfile module offers comprehensive function‑level profiling, recording call counts and cumulative times. cctime, by contrast, is lightweight and focused on explicit timing of code blocks. While cProfile is suitable for post‑mortem analysis of entire applications, cctime is ideal for instrumentation of selected sections or for use in interactive environments where overhead must remain minimal.

timeit Module

The standard library’s timeit module provides a command‑line utility for measuring execution time of small code snippets. It handles multiple repetitions and statistical analysis but lacks support for nested timers or reporting of hierarchies. cctime’s context‑manager and decorator patterns make it easier to embed timing directly into the source code.

pyinstrument and line_profiler

Tools like pyinstrument perform line‑by‑line profiling and produce flame‑graph visualizations. While these tools are powerful, they require additional instrumentation and generate large output files. cctime remains minimalistic, offering a developer‑controlled granularity without extra tooling overhead.

Why Choose cctime

Developers who require explicit, low‑overhead timing, especially in notebooks or scripts, find cctime attractive. Its API is straightforward, and it integrates cleanly with existing code bases. The ability to nest timers and aggregate results is a distinctive feature that distinguishes it from simpler wrappers.

Community and Development

Project Governance

The repository follows a typical open‑source model with a clear contribution guide, code of conduct, and issue templates. All contributors must sign a contributor license agreement that permits reuse of their code under the BSD‑3 Clause license. The maintainers perform code reviews and merge requests weekly.

Testing and Continuous Integration

Unit tests cover over 90% of the codebase. Continuous integration pipelines run tests on multiple operating systems and Python versions, using services such as GitHub Actions and GitLab CI. Coverage reports are posted to the repository’s dashboard, ensuring that new features do not regress existing functionality.

Documentation

Official documentation is generated with Sphinx and is hosted on a static site. The docs include tutorial sections, API references, and examples. Importantly, the documentation contains a “best‑practice” guide for using timers in various contexts (sync, async, threading, etc.).

Issue Tracker

Active issues include bug reports, feature requests, and performance improvement tickets. The community has requested integration with external metrics systems (e.g., Prometheus) and support for custom clock sources, both of which are in discussion. The response time for issues is typically under three business days.

Release Cycle

Releases are made on an as‑needed basis. Semantic versioning is followed: major changes increment the first digit, backward‑compatible feature additions increment the second, and patches increment the third. Release notes enumerate new features, bug fixes, and any deprecation warnings.

Future Directions

Metrics Export

Planned enhancements include exporters that can send timing data to monitoring systems like Prometheus or StatsD. This would enable real‑time dashboards in production environments.

Automated Flame‑Graph Generation

Integration with pyprof2calltree or similar libraries could allow the creation of flame‑graphs from nested timers, providing visual insight into execution flow.

Extended Clock Sources

Future versions may support system‑specific high‑resolution clocks, such as time.clock_gettime on Linux, for platforms where perf_counter is not sufficient.

Hybrid Profiling

Combining cctime with cProfile in a single run could provide both coarse and fine‑grained insight. The design already allows grouping timers in a TimerGroup that could be passed to other profilers.

License

cctime is distributed under the BSD‑3 Clause license. The license text is included in the repository and is reproduced below:

BSD 3‑Clause License

Copyright (c) 2023, cctime Contributors
All rights reserved.

Feel free to incorporate the library into commercial or open‑source projects.

Conclusion

cctime offers a clean, low‑overhead API for explicit timing in Python programs. Its support for nested contexts, threading, asynchronous operations, and extensible reporting make it a versatile tool for developers. By staying within the standard library, it achieves broad platform compatibility while remaining easy to integrate. For those needing precise, developer‑controlled timing without the complexity of full‑stack profilers, cctime is a solid choice.

```

Search

Table of Contents