API

ocalc.analyze_source(source, language=None)

Estimate worst-case time and space from a source snippet.

The reported class is the worst function in the snippet. Loops, recursion, and calls such as matrix products and sorts set that class.

Parameters:

• source (str) – The program text.

• language (str | None) – A language name such as python or go. Detected when omitted.

Returns:

The detected language, the worst-case classes, and one row per function.

Return type:

SourceAnalysis

class ocalc.SourceAnalysis(language: 'str', time: 'str', space: 'str', detail: 'str', functions: 'tuple[FunctionEstimate, ...]' = ())

Parameters:

• language (str) –

• time (str) –

• space (str) –

• detail (str) –

• functions (tuple[FunctionEstimate, ...]) –

class ocalc.FunctionEstimate(name: 'str', time: 'str', space: 'str', reason: 'str')

Parameters:

• name (str) –

• time (str) –

• space (str) –

• reason (str) –

ocalc.measure(func, *sample_args, budget=None, min_n=None, max_n=None, measures=None, repeats=None, file=None, qualname=None, protocol=None, previous_s=None, **sample_kwargs)

Measure a function and return its complexity report.

Parameters:

• func – The callable to measure.

• sample_args – Example positional arguments. The first collection grows with n.

• budget (float | None) – Seconds to spend measuring. The default is 5.

• min_n (int | None) – Smallest input size.

• max_n (int | None) – Largest input size.

• measures (int | None) – How many sizes to try.

• repeats (int | None) – Timed calls at each size.

• file (str | None) – Source file, when the callable should be re-imported for the timed run.

• qualname (str | None) – Qualname used to re-import file.

• protocol (Protocol | None) – Stored sizes and budget from an earlier comment.

• previous_s (float | None) – Worst time from that earlier comment.

• sample_kwargs – Example keyword arguments.

Returns:

The comment, the size table, and the fitted time and space classes.

Return type:

Report

ocalc.annotate_file(path, qualname, *sample_args, budget=None, min_n=None, max_n=None, measures=None, repeats=None, **sample_kwargs)

Benchmark a function in a file and write the comment above it.

A later call reuses the protocol stored in the existing comment and records the previous worst time.

Parameters:

• path – Python file that defines the function.

• qualname (str) – Function qualname, such as two_sum or Box.run.

• sample_args – Example positional arguments.

• budget (float | None) – Seconds to spend measuring.

• min_n (int | None) – Smallest input size.

• max_n (int | None) – Largest input size.

• measures (int | None) – How many sizes to try.

• repeats (int | None) – Timed calls at each size.

• sample_kwargs – Example keyword arguments.

Returns:

The report that was written into the file.

Return type:

Report

class ocalc.Report(comment: 'str', points: 'list[Point]', time: 'FitResult', space: 'FitResult', worst_s: 'float', median_s: 'float', worst_n: 'int | None', protocol: 'Protocol')

Parameters:

• comment (str) –

• points (list[Point]) –

• time (FitResult) –

• space (FitResult) –

• worst_s (float) –

• median_s (float) –

• worst_n (int | None) –

• protocol (Protocol) –

ocalc.parse_sample(text)

Parse literal arguments, including keyword arguments such as factor=3.

Parameters:

text (str) –

Return type:

tuple[tuple, dict]

exception ocalc.NeedSample

The function needs an example call before it can be measured.

exception ocalc.FunctionNotFound

The named function is not in the file.