ocalc 0.1.0__tar.gz

ocalc-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ocalc contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ocalc-0.1.0/PKG-INFO

@@ -0,0 +1,61 @@
+Metadata-Version: 2.4
+Name: ocalc
+Version: 0.1.0
+Summary: Measure a Python function and comment its time and space complexity.
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Anuj-Attri/ocalc
+Project-URL: Documentation, https://anuj-attri.github.io/ocalc/
+Project-URL: Repository, https://github.com/Anuj-Attri/ocalc
+Project-URL: Issues, https://github.com/Anuj-Attri/ocalc/issues
+Keywords: complexity,benchmark,big-o,profiling
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Provides-Extra: mcp
+Requires-Dist: mcp<3,>=2; extra == "mcp"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: sphinx<8,>=7.2; extra == "docs"
+Requires-Dist: pytorch-sphinx-theme2==0.4.13; extra == "docs"
+Dynamic: license-file
+
+# ocalc
+
+`ocalc` measures a Python function and writes a one-line estimate of its time and space complexity.
+
+```python
+# ocalc: Time: O(n); Space: O(1); Worst: 0.42 s at n=100000; Median: 0.31 s; Confidence: high; Protocol: min_n=100,max_n=100000,measures=8,budget=5,repeats=5
+def two_sum(nums, target):
+    ...
+```
+
+## Install
+
+```bash
+pip install ocalc
+pip install "ocalc[mcp]"
+```
+
+## Use
+
+```bash
+ocalc measure FILE -f two_sum --sample "[1, 2, 3], 9"
+ocalc annotate FILE -f two_sum --sample "[1, 2, 3], 9"
+```
+
+![ocalc annotate writes the measured comment above the function](https://raw.githubusercontent.com/Anuj-Attri/ocalc/main/docs/images/annotate.png)
+
+Try a snippet on the [demo](https://anuj-attri.github.io/ocalc/demo.html). The page reports the worst case in the file. The guide and API reference are at [anuj-attri.github.io/ocalc](https://anuj-attri.github.io/ocalc/).
+
+## Development
+
+```bash
+pip install -e ".[dev,docs]"
+pytest
+sphinx-build -b html docs docs/_build/html
+```

ocalc-0.1.0/README.md

@@ -0,0 +1,35 @@
+# ocalc
+
+`ocalc` measures a Python function and writes a one-line estimate of its time and space complexity.
+
+```python
+# ocalc: Time: O(n); Space: O(1); Worst: 0.42 s at n=100000; Median: 0.31 s; Confidence: high; Protocol: min_n=100,max_n=100000,measures=8,budget=5,repeats=5
+def two_sum(nums, target):
+    ...
+```
+
+## Install
+
+```bash
+pip install ocalc
+pip install "ocalc[mcp]"
+```
+
+## Use
+
+```bash
+ocalc measure FILE -f two_sum --sample "[1, 2, 3], 9"
+ocalc annotate FILE -f two_sum --sample "[1, 2, 3], 9"
+```
+
+![ocalc annotate writes the measured comment above the function](https://raw.githubusercontent.com/Anuj-Attri/ocalc/main/docs/images/annotate.png)
+
+Try a snippet on the [demo](https://anuj-attri.github.io/ocalc/demo.html). The page reports the worst case in the file. The guide and API reference are at [anuj-attri.github.io/ocalc](https://anuj-attri.github.io/ocalc/).
+
+## Development
+
+```bash
+pip install -e ".[dev,docs]"
+pytest
+sphinx-build -b html docs docs/_build/html
+```

ocalc-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ocalc"
+version = "0.1.0"
+description = "Measure a Python function and comment its time and space complexity."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = ["complexity", "benchmark", "big-o", "profiling"]
+dependencies = ["numpy"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+    "Topic :: Software Development :: Testing",
+]
+
+[project.urls]
+Homepage = "https://github.com/Anuj-Attri/ocalc"
+Documentation = "https://anuj-attri.github.io/ocalc/"
+Repository = "https://github.com/Anuj-Attri/ocalc"
+Issues = "https://github.com/Anuj-Attri/ocalc/issues"
+
+[project.optional-dependencies]
+mcp = ["mcp>=2,<3"]
+dev = ["pytest"]
+docs = ["sphinx>=7.2,<8", "pytorch-sphinx-theme2==0.4.13"]
+
+[project.scripts]
+ocalc = "ocalc.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

ocalc-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

ocalc-0.1.0/src/ocalc/__init__.py

@@ -0,0 +1,216 @@
+"""Measure a Python function and estimate its time and space complexity."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+import numpy as np
+
+from ocalc.bench import BenchResult, Point, benchmark
+from ocalc.comment import (
+    Protocol,
+    apply_comment,
+    existing_comment,
+    format_comment,
+    format_table,
+)
+from ocalc.fit import FitResult, fit_curve
+from ocalc.generate import (
+    FunctionNotFound,
+    NeedSample,
+    callable_location,
+    load_function,
+    parse_sample,
+    plan_inputs,
+)
+from ocalc.static import FunctionEstimate, SourceAnalysis, analyze_source
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "FunctionEstimate",
+    "FunctionNotFound",
+    "NeedSample",
+    "Report",
+    "SourceAnalysis",
+    "analyze_source",
+    "annotate_file",
+    "measure",
+    "parse_sample",
+]
+
+
+@dataclass(frozen=True)
+class Report:
+    comment: str
+    points: list[Point]
+    time: FitResult
+    space: FitResult
+    worst_s: float
+    median_s: float
+    worst_n: int | None
+    protocol: Protocol
+
+
+def measure(
+    func,
+    *sample_args,
+    budget: float | None = None,
+    min_n: int | None = None,
+    max_n: int | None = None,
+    measures: int | None = None,
+    repeats: int | None = None,
+    file: str | None = None,
+    qualname: str | None = None,
+    protocol: Protocol | None = None,
+    previous_s: float | None = None,
+    **sample_kwargs,
+) -> Report:
+    """Measure a function and return its complexity report.
+
+    Args:
+        func: The callable to measure.
+        sample_args: Example positional arguments. The first collection grows with ``n``.
+        budget: Seconds to spend measuring. The default is 5.
+        min_n: Smallest input size.
+        max_n: Largest input size.
+        measures: How many sizes to try.
+        repeats: Timed calls at each size.
+        file: Source file, when the callable should be re-imported for the timed run.
+        qualname: Qualname used to re-import ``file``.
+        protocol: Stored sizes and budget from an earlier comment.
+        previous_s: Worst time from that earlier comment.
+        sample_kwargs: Example keyword arguments.
+
+    Returns:
+        The comment, the size table, and the fitted time and space classes.
+    """
+    plan = plan_inputs(func, sample_args, sample_kwargs)
+    if protocol is not None and protocol.constant and plan.mode == "constant":
+        if budget is None:
+            budget = protocol.budget
+        if repeats is None:
+            repeats = protocol.repeats
+    elif protocol is not None and not protocol.constant and plan.mode != "constant":
+        if budget is None:
+            budget = protocol.budget
+        if min_n is None:
+            min_n = protocol.min_n
+        if max_n is None:
+            max_n = protocol.max_n
+        if measures is None:
+            measures = protocol.measures
+        if repeats is None:
+            repeats = protocol.repeats
+
+    located_file, located_name = callable_location(func)
+    file = file or located_file
+    qualname = qualname or located_name
+    result = benchmark(
+        func,
+        plan,
+        budget=5.0 if budget is None else budget,
+        min_n=min_n,
+        max_n=max_n,
+        measures=measures,
+        repeats=repeats,
+        file=file,
+        qualname=qualname,
+    )
+    time_fit, space_fit = _fits(result)
+    comment = format_comment(
+        time=time_fit,
+        space=space_fit,
+        worst_s=result.worst_s,
+        worst_n=result.worst_n,
+        median_s=result.median_s,
+        protocol=result.protocol,
+        previous_s=previous_s,
+    )
+    return Report(
+        comment=comment,
+        points=result.points,
+        time=time_fit,
+        space=space_fit,
+        worst_s=result.worst_s,
+        median_s=result.median_s,
+        worst_n=result.worst_n,
+        protocol=result.protocol,
+    )
+
+
+def annotate_file(
+    path,
+    qualname: str,
+    *sample_args,
+    budget: float | None = None,
+    min_n: int | None = None,
+    max_n: int | None = None,
+    measures: int | None = None,
+    repeats: int | None = None,
+    **sample_kwargs,
+) -> Report:
+    """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.
+
+    Args:
+        path: Python file that defines the function.
+        qualname: Function qualname, such as ``two_sum`` or ``Box.run``.
+        sample_args: Example positional arguments.
+        budget: Seconds to spend measuring.
+        min_n: Smallest input size.
+        max_n: Largest input size.
+        measures: How many sizes to try.
+        repeats: Timed calls at each size.
+        sample_kwargs: Example keyword arguments.
+
+    Returns:
+        The report that was written into the file.
+    """
+    file_path = Path(path)
+    source = file_path.read_text(encoding="utf-8")
+    previous = existing_comment(source, qualname)
+    protocol = previous.protocol if previous is not None else None
+    previous_s = previous.worst_s if previous is not None else None
+    func = load_function(file_path, qualname)
+    report = measure(
+        func,
+        *sample_args,
+        budget=budget,
+        min_n=min_n,
+        max_n=max_n,
+        measures=measures,
+        repeats=repeats,
+        file=str(file_path.resolve()),
+        qualname=qualname,
+        protocol=protocol,
+        previous_s=previous_s,
+        **sample_kwargs,
+    )
+    updated = apply_comment(source, qualname, report.comment)
+    with file_path.open("w", encoding="utf-8", newline="") as handle:
+        handle.write(updated)
+    return report
+
+
+def _fits(result: BenchResult) -> tuple[FitResult, FitResult]:
+    if result.constant:
+        done = FitResult("1", "O(1)", "high")
+        return done, done
+    sizes = [point.n for point in result.points]
+    times = [point.time_s for point in result.points]
+    time_fit = fit_curve(sizes, times, exponential=result.exponential)
+    return time_fit, _space_fit(sizes, [point.memory_bytes for point in result.points])
+
+
+def _space_fit(sizes, memory) -> FitResult:
+    used = np.asarray(memory, dtype=float)
+    if used.size == 0 or np.nanmax(used) <= 0:
+        return FitResult("1", "O(1)", "high")
+    positive = used[used > 0]
+    floor = float(positive.min()) if positive.size else 1.0
+    used = np.where(used > 0, used, floor)
+    return fit_curve(sizes, used)

ocalc-0.1.0/src/ocalc/bench.py

@@ -0,0 +1,287 @@
+"""Time a function across a size grid and record peak Python allocations."""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+import math
+import multiprocessing
+import time
+import tracemalloc
+from dataclasses import dataclass
+from statistics import median
+
+from ocalc.comment import Protocol
+from ocalc.generate import InputPlan, load_function
+
+DEFAULT_BUDGET = 5.0
+DEFAULT_MEASURES = 8
+DEFAULT_MIN_N = 100
+DEFAULT_MAX_N = 100_000
+DEFAULT_MIN_N_INT = 8
+_REPEATS = 5
+
+
+@dataclass(frozen=True)
+class Point:
+    n: int | None
+    time_s: float
+    memory_bytes: float
+
+
+@dataclass
+class BenchResult:
+    points: list[Point]
+    protocol: Protocol
+    exponential: bool
+    constant: bool
+    timed_out: bool
+    worst_s: float
+    median_s: float
+    worst_n: int | None
+
+
+def geometric_sizes(min_n: int, max_n: int, measures: int) -> list[int]:
+    """Evenly spaced sizes on a log scale, including both ends."""
+    if measures < 1:
+        raise ValueError("measures must be at least 1")
+    if min_n > max_n:
+        raise ValueError("min_n cannot be greater than max_n")
+    if measures == 1 or min_n == max_n:
+        return [int(max_n)]
+    ratio = (max_n / min_n) ** (1 / (measures - 1))
+    raw = [int(round(min_n * ratio**i)) for i in range(measures)]
+    raw[0] = int(min_n)
+    raw[-1] = int(max_n)
+    sizes: list[int] = []
+    for size in raw:
+        size = max(int(min_n), size)
+        if not sizes or size > sizes[-1]:
+            sizes.append(size)
+    if sizes[-1] != int(max_n):
+        sizes.append(int(max_n))
+    return sizes
+
+
+def benchmark(
+    func,
+    plan: InputPlan,
+    *,
+    budget: float,
+    min_n: int | None,
+    max_n: int | None,
+    measures: int | None,
+    repeats: int | None,
+    file: str | None,
+    qualname: str | None,
+) -> BenchResult:
+    measures = DEFAULT_MEASURES if measures is None else measures
+    budget = DEFAULT_BUDGET if budget is None else budget
+    repeats = _REPEATS if repeats is None else max(1, int(repeats))
+    if plan.mode == "constant":
+        return _benchmark_constant(func, plan, budget, repeats, file, qualname)
+
+    if plan.mode == "int_n":
+        min_n = DEFAULT_MIN_N_INT if min_n is None else min_n
+        max_n = DEFAULT_MAX_N if max_n is None else max_n
+    else:
+        min_n = DEFAULT_MIN_N if min_n is None else min_n
+        max_n = DEFAULT_MAX_N if max_n is None else max_n
+    protocol = Protocol(int(min_n), int(max_n), int(measures), float(budget), repeats=repeats)
+    sizes = geometric_sizes(protocol.min_n, protocol.max_n, protocol.measures)
+    points: list[Point] = []
+    exponential = False
+    timed_out = False
+    started = time.perf_counter()
+
+    for size in sizes:
+        remaining = budget - (time.perf_counter() - started)
+        if remaining <= 0.05:
+            break
+        if len(points) >= 2 and _explosive(
+            points[-2].n, points[-2].time_s, points[-1].n, points[-1].time_s
+        ):
+            exponential = True
+            break
+        if points:
+            ratio = size / points[-1].n
+            predicted = points[-1].time_s * max(ratio, 1.0) ** 2
+            if predicted > remaining:
+                break
+        args, kwargs = plan.build(size)
+        status, times, peak = _measure_call(
+            func,
+            args,
+            kwargs,
+            file=file,
+            qualname=qualname,
+            repeats=repeats,
+            timeout=max(0.2, remaining),
+        )
+        if status == "timeout":
+            timed_out = True
+            if points and (
+                points[-1].n <= 40
+                and points[-1].time_s > 1e-4
+                or (
+                    len(points) >= 2
+                    and _explosive(points[-2].n, points[-2].time_s, points[-1].n, points[-1].time_s)
+                )
+            ):
+                exponential = True
+            break
+        if status == "error":
+            raise RuntimeError(times)
+        point = Point(size, float(median(times)), float(peak))
+        points.append(point)
+        if len(points) >= 2 and _explosive(
+            points[-2].n, points[-2].time_s, points[-1].n, points[-1].time_s
+        ):
+            exponential = True
+            break
+
+    if not points:
+        raise RuntimeError(
+            "No measurement finished within the budget. Raise --budget or lower --min-n."
+        )
+    slowest = max(points, key=lambda item: item.time_s)
+    return BenchResult(
+        points=points,
+        protocol=protocol,
+        exponential=exponential,
+        constant=False,
+        timed_out=timed_out,
+        worst_s=slowest.time_s,
+        median_s=float(median(item.time_s for item in points)),
+        worst_n=slowest.n,
+    )
+
+
+def _benchmark_constant(func, plan, budget, repeats, file, qualname) -> BenchResult:
+    args, kwargs = plan.build(0)
+    status, times, peak = _measure_call(
+        func,
+        args,
+        kwargs,
+        file=file,
+        qualname=qualname,
+        repeats=repeats,
+        timeout=max(0.2, budget),
+    )
+    if status == "timeout":
+        raise RuntimeError(
+            "No measurement finished within the budget. Raise --budget or lower --min-n."
+        )
+    if status == "error":
+        raise RuntimeError(times)
+    protocol = Protocol(0, 0, 0, float(budget), constant=True, repeats=repeats)
+    point = Point(None, float(median(times)), float(peak))
+    return BenchResult(
+        points=[point],
+        protocol=protocol,
+        exponential=False,
+        constant=True,
+        timed_out=False,
+        worst_s=float(max(times)),
+        median_s=float(median(times)),
+        worst_n=None,
+    )
+
+
+def _explosive(n0, t0, n1, t1) -> bool:
+    if t0 <= 0 or t1 <= 0 or n1 <= n0:
+        return False
+    n_ratio = n1 / n0
+    t_ratio = t1 / t0
+    if n_ratio < 1.5 and t_ratio > 2 and n1 <= 64 and t1 > 1e-4:
+        return True
+    if t1 < 1e-3 or n_ratio <= 1:
+        return False
+    exponent = math.log(t_ratio) / math.log(n_ratio)
+    return exponent > 5
+
+
+def _call(func, args, kwargs):
+    result = func(*args, **kwargs)
+    if inspect.iscoroutine(result):
+        return asyncio.run(result)
+    return result
+
+
+def _measure_call(func, args, kwargs, *, file, qualname, repeats, timeout):
+    if file and qualname:
+        return _run_process(file, qualname, args, kwargs, repeats, timeout)
+    times, peak = collect_sample(func, args, kwargs, repeats)
+    return "ok", times, peak
+
+
+def collect_sample(func, args, kwargs, repeats: int = _REPEATS):
+    """Warm up, time several calls, then record one tracemalloc peak."""
+    _call(func, args, kwargs)
+    batch = 1
+
+    def once() -> float:
+        started = time.perf_counter()
+        for _ in range(batch):
+            _call(func, args, kwargs)
+        return (time.perf_counter() - started) / batch
+
+    first = once()
+    if first < 0.001:
+        batch = min(10_000, max(1, math.ceil(0.002 / max(first, 1e-9))))
+        first = once()
+    times = [first]
+    if first <= 0.2:
+        for _ in range(repeats - 1):
+            duration = once()
+            times.append(duration)
+            if duration > 0.2:
+                break
+    tracemalloc.start()
+    try:
+        _call(func, args, kwargs)
+        _current, peak = tracemalloc.get_traced_memory()
+    finally:
+        tracemalloc.stop()
+    return times, float(peak)
+
+
+def _run_process(file, qualname, args, kwargs, repeats, timeout):
+    context = multiprocessing.get_context("spawn")
+    parent, child = context.Pipe(duplex=False)
+    process = context.Process(
+        target=_worker,
+        args=(child, str(file), qualname, args, kwargs, repeats),
+        daemon=True,
+    )
+    process.start()
+    child.close()
+    try:
+        process.join(timeout)
+        if process.is_alive():
+            process.terminate()
+            process.join()
+            return "timeout", None, None
+        if not parent.poll(0.2):
+            return "error", "The measurement process stopped without a result.", None
+        message = parent.recv()
+    finally:
+        parent.close()
+    if not message or message[0] != "ok":
+        detail = message[1] if message and len(message) > 1 else "measurement failed"
+        return "error", detail, None
+    return "ok", message[1], message[2]
+
+
+def _worker(conn, file, qualname, args, kwargs, repeats):
+    try:
+        func = load_function(file, qualname)
+        times, peak = collect_sample(func, args, kwargs, repeats)
+        conn.send(("ok", times, peak))
+    except Exception as exc:
+        try:
+            conn.send(("err", f"{type(exc).__name__}: {exc}"))
+        except Exception:
+            pass
+    finally:
+        conn.close()