slough 0.1.0__tar.gz

slough-0.1.0/PKG-INFO

@@ -0,0 +1,31 @@
+Metadata-Version: 2.3
+Name: slough
+Version: 0.1.0
+Summary: Experimental toy library to dry-run Python code with line-by-line variable tracing
+Author: prakash S
+Author-email: prakash S <prakashsellathurai@gmail.com>
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/prakashsellathurai/slough
+Description-Content-Type: text/markdown
+
+# slough
+
+Experimental toy library to dry-run Python code traces every variable value line-by-line through execution.
+
+## Usage
+
+```bash
+slough path/to/solution.py -t test_cases.json
+```
+
+## How it works
+
+Hooks `sys.settrace` before calling your solution function, recording locals at each line. Outputs source code with live variable annotations and pass/fail for each test case.
+
+## Install
+
+```bash
+uv tool install slough
+```
+
+**Status:** Experimental. Not intended for production use.

slough-0.1.0/README.md

@@ -0,0 +1,21 @@
+# slough
+
+Experimental toy library to dry-run Python code traces every variable value line-by-line through execution.
+
+## Usage
+
+```bash
+slough path/to/solution.py -t test_cases.json
+```
+
+## How it works
+
+Hooks `sys.settrace` before calling your solution function, recording locals at each line. Outputs source code with live variable annotations and pass/fail for each test case.
+
+## Install
+
+```bash
+uv tool install slough
+```
+
+**Status:** Experimental. Not intended for production use.

slough-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[project]
+name = "slough"
+version = "0.1.0"
+description = "Experimental toy library to dry-run Python code with line-by-line variable tracing"
+readme = "README.md"
+authors = [
+    { name = "prakash S", email = "prakashsellathurai@gmail.com" }
+]
+requires-python = ">=3.12"
+dependencies = []
+
+[project.scripts]
+slough = "slough.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/prakashsellathurai/slough"
+
+[build-system]
+requires = ["uv_build>=0.9.26,<0.10.0"]
+build-backend = "uv_build"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+filterwarnings = [
+    "ignore:cannot collect test class 'TestCase'",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.3",
+]

slough-0.1.0/src/slough/__init__.py

@@ -0,0 +1,2 @@
+def main() -> None:
+    print("Hello from slough!")

slough-0.1.0/src/slough/__main__.py

@@ -0,0 +1,4 @@
+import sys
+from slough.cli import main
+
+sys.exit(main())

slough-0.1.0/src/slough/cli.py

@@ -0,0 +1,112 @@
+import argparse
+import json
+import os
+import sys
+
+from slough.formatter import format_results
+from slough.models import TestCase
+from slough.parser import parse_md_examples
+from slough.runner import run_test_cases
+
+
+def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Trace Python variable values through LeetCode-style solution execution.",
+    )
+    parser.add_argument("solution", help="Path to solution.py or directory with solution + README.md")
+    parser.add_argument(
+        "-t", "--test-cases",
+        default=None,
+        help="Path to JSON test cases file (optional if README.md exists)",
+    )
+    parser.add_argument(
+        "-o", "--output",
+        default=None,
+        help="Write output to file instead of stdout",
+    )
+    return parser.parse_args(argv)
+
+
+def _load_test_cases(path: str) -> list[TestCase]:
+    with open(path) as f:
+        raw = json.load(f)
+    test_cases = []
+    for item in raw:
+        inputs = tuple(item["inputs"])
+        expected = item.get("expected")
+        test_cases.append(TestCase(inputs=inputs, expected=expected))
+    return test_cases
+
+
+def _resolve_solution_path(solution: str) -> str | None:
+    if os.path.isdir(solution):
+        py_files = [f for f in os.listdir(solution) if f.endswith(".py")]
+        if not py_files:
+            return None
+        return os.path.join(solution, py_files[0])
+    return solution
+
+
+def _find_readme(solution_path: str) -> str | None:
+    solution_dir = solution_path if os.path.isdir(solution_path) else os.path.dirname(solution_path)
+    for name in ("README.md", "readme.md", "README", "readme"):
+        candidate = os.path.join(solution_dir, name)
+        if os.path.isfile(candidate):
+            return candidate
+    return None
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = parse_args(argv)
+    solution_path = args.solution
+
+    is_dir = os.path.isdir(solution_path)
+
+    if is_dir:
+        solution_path = _resolve_solution_path(solution_path)
+        if solution_path is None:
+            print(f"Error: No Python solution file found in directory '{args.solution}'")
+            return 1
+
+    try:
+        with open(solution_path) as f:
+            source_lines = f.readlines()
+    except FileNotFoundError as e:
+        print(f"Error: Solution file not found: {e}")
+        return 1
+
+    if args.test_cases:
+        try:
+            test_cases = _load_test_cases(args.test_cases)
+        except FileNotFoundError as e:
+            print(f"Error: Test cases file not found: {e}")
+            return 1
+        except json.JSONDecodeError as e:
+            print(f"Error: Invalid JSON in test cases file: {e}")
+            return 1
+    else:
+        readme_path = _find_readme(args.solution)
+        if readme_path:
+            with open(readme_path) as f:
+                test_cases = parse_md_examples(f.read())
+            if not test_cases:
+                print(f"Error: No test cases found in '{readme_path}'")
+                return 1
+        else:
+            print("Error: No test cases provided (use --test-cases or place README.md alongside the solution)")
+            return 1
+
+    results = run_test_cases(solution_path, test_cases)
+    output = format_results(results, source_lines)
+
+    if args.output:
+        with open(args.output, "w") as f:
+            f.write(output + "\n")
+    else:
+        print(output)
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

slough-0.1.0/src/slough/formatter.py

@@ -0,0 +1,64 @@
+from slough.models import TraceResult, TraceStep
+
+
+def _format_vars(vars_dict: dict) -> str:
+    items = []
+    for k, v in vars_dict.items():
+        if k == "self":
+            continue
+        items.append(f"{k}={repr(v)}")
+    return ", ".join(items)
+
+
+def _format_return_comparison(result: TraceResult) -> str:
+    line = f"  Returned: {repr(result.return_value)}"
+    if result.test_case.expected is not None:
+        if result.return_value == result.test_case.expected:
+            line += f"  (expected: {repr(result.test_case.expected)})"
+        else:
+            line += f"  (expected: {repr(result.test_case.expected)})  ✗ MISMATCH"
+    return line
+
+
+def format_results(results: list[TraceResult], source_lines: list[str]) -> str:
+    output_parts: list[str] = []
+
+    for idx, result in enumerate(results):
+        idx_line = f"\n{'=' * 60}"
+        output_parts.append(idx_line)
+        output_parts.append(f" Test Case {idx + 1}")
+
+        steps = result.steps
+
+        # Build step index: for each step lineno, collect var changes
+        line_vars: dict[int, list[str]] = {}
+        for step in steps:
+            if step.event in ("line", "return") and step.vars:
+                var_str = _format_vars(step.vars)
+                if var_str:
+                    line_vars.setdefault(step.lineno, []).append(var_str)
+            if step.event == "call" and step.vars:
+                var_str = _format_vars(step.vars)
+                if var_str:
+                    output_parts.append(f"\n  Call: {step.func_name}({var_str})")
+
+        # Print source with variable annotations
+        for line_no, line in enumerate(source_lines, start=1):
+            code = line.rstrip("\n")
+            output_parts.append(f"\n  {line_no:>3} │ {code}")
+            if line_no in line_vars:
+                for var_str in line_vars[line_no]:
+                    output_parts.append(f"       → {var_str}")
+
+        # Show return events
+        for step in steps:
+            if step.event == "return" and step.return_value is not None:
+                output_parts.append(f"\n  Return: {step.func_name} → {repr(step.return_value)}")
+            elif step.event == "exception":
+                output_parts.append(f"\n  Exception: {repr(step.return_value)}")
+
+        output_parts.append("")
+        output_parts.append(f"  {'─' * 58}")
+        output_parts.append(f"  {_format_return_comparison(result)}")
+
+    return "\n".join(output_parts)

slough-0.1.0/src/slough/models.py

@@ -0,0 +1,24 @@
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class TraceStep:
+    lineno: int
+    event: str
+    func_name: str
+    vars: dict[str, Any] = field(default_factory=dict)
+    return_value: Any = None
+
+
+@dataclass
+class TestCase:
+    inputs: tuple[Any, ...] = ()
+    expected: Any = None
+
+
+@dataclass
+class TraceResult:
+    test_case: TestCase
+    steps: list[TraceStep]
+    return_value: Any = None

slough-0.1.0/src/slough/parser.py

@@ -0,0 +1,119 @@
+import ast
+import html as html_module
+import re
+from typing import Any
+
+from slough.models import TestCase
+
+
+def _normalize_content(content: str) -> str:
+    """Convert HTML content to plain text with preserved line structure."""
+    if "<" not in content:
+        return content
+
+    content = re.sub(r"<br\s*/?>", "\n", content, flags=re.IGNORECASE)
+    content = re.sub(r"</pre\s*>", "\n", content, flags=re.IGNORECASE)
+    content = re.sub(r"<pre[^>]*>", "\n", content, flags=re.IGNORECASE)
+    content = re.sub(r"<[^>]+>", "", content)
+    content = html_module.unescape(content)
+    content = re.sub(r"\n{3,}", "\n\n", content)
+    return content.strip()
+
+
+def _parse_value(raw: str) -> Any:
+    raw = raw.strip()
+    if raw in ("true", "True"):
+        return True
+    if raw in ("false", "False"):
+        return False
+    if raw in ("null", "None"):
+        return None
+    try:
+        return ast.literal_eval(raw)
+    except (ValueError, SyntaxError):
+        return raw
+
+
+def _split_input_pairs(line: str) -> dict[str, Any]:
+    pairs: dict[str, Any] = {}
+    key_pattern = re.compile(r"(\w+)\s*=")
+
+    # Find positions of all '=' signs with preceding key names
+    parts: list[tuple[str, str]] = []
+    pos = 0
+    while pos < len(line):
+        m = key_pattern.search(line, pos)
+        if m is None:
+            break
+        key = m.group(1)
+        val_start = m.end()
+        # Find the value: everything until the next ',' at depth 0
+        depth = 0
+        in_quote: str | None = None
+        val_end = val_start
+        while val_end < len(line):
+            ch = line[val_end]
+            if in_quote:
+                if ch == in_quote and (val_end == 0 or line[val_end - 1] != "\\"):
+                    in_quote = None
+            elif ch in ("\"", "'"):
+                in_quote = ch
+            elif ch in ("[", "("):
+                depth += 1
+            elif ch in ("]", ")"):
+                depth -= 1
+            elif ch == "," and depth == 0:
+                break
+            val_end += 1
+
+        value_raw = line[val_start:val_end].strip().rstrip(",")
+        pairs[key] = _parse_value(value_raw)
+        pos = val_end + 1
+
+    return pairs
+
+
+def parse_example_lines(input_line: str, output_line: str | None) -> TestCase:
+    input_line = re.sub(r"^Input:\s*", "", input_line, flags=re.IGNORECASE).strip()
+    pairs = _split_input_pairs(input_line)
+    inputs = tuple(pairs.values())
+
+    expected = None
+    if output_line:
+        output_line = re.sub(r"^Output:\s*", "", output_line, flags=re.IGNORECASE).strip()
+        expected = _parse_value(output_line)
+
+    return TestCase(inputs=inputs, expected=expected)
+
+
+def parse_md_examples(md_content: str) -> list[TestCase]:
+    content = _normalize_content(md_content)
+    cases: list[TestCase] = []
+    lines = content.split("\n")
+
+    example_header = re.compile(
+        r"(?:#+\s*)?Example\s*\d*\s*:?\s*$", re.IGNORECASE,
+    )
+    example_indices = [i for i, l in enumerate(lines) if example_header.match(l.strip())]
+
+    for idx, start in enumerate(example_indices):
+        end = example_indices[idx + 1] if idx + 1 < len(example_indices) else len(lines)
+        block = lines[start:end]
+
+        input_line = None
+        output_line = None
+        for l in block:
+            stripped = l.strip()
+            if not stripped:
+                continue
+            if re.match(r"Input:", stripped, re.IGNORECASE):
+                if input_line is None:
+                    input_line = stripped
+            elif re.match(r"Output:", stripped, re.IGNORECASE):
+                if output_line is None:
+                    output_line = stripped
+
+        if input_line:
+            cases.append(parse_example_lines(input_line, output_line))
+
+    return cases

slough-0.1.0/src/slough/runner.py

@@ -0,0 +1,93 @@
+import inspect
+from typing import Any
+
+from slough.models import TestCase, TraceResult
+from slough.tracer import trace_function_call
+
+
+_COMMON_TYPING_IMPORTS = {
+    "List": __import__("typing").List,
+    "Dict": __import__("typing").Dict,
+    "Optional": __import__("typing").Optional,
+    "Tuple": __import__("typing").Tuple,
+    "Set": __import__("typing").Set,
+    "Deque": __import__("collections").deque,
+}
+
+
+def _load_solution_class(filepath: str) -> type:
+    with open(filepath) as f:
+        source = f.read()
+
+    ns: dict[str, Any] = dict(_COMMON_TYPING_IMPORTS)
+    compiled = compile(source, filepath, "exec")
+    exec(compiled, ns)
+
+    for name, obj in ns.items():
+        if inspect.isclass(obj):
+            methods = [
+                m for m in obj.__dict__.values()
+                if inspect.isfunction(m) and not m.__name__.startswith("_")
+            ]
+            if methods:
+                return obj
+
+    raise ValueError("No class with methods found in the solution file")
+
+
+def _find_method(solution_class: type, test_case: TestCase) -> str:
+    for name, method in solution_class.__dict__.items():
+        if inspect.isfunction(method) and not name.startswith("_"):
+            try:
+                sig = inspect.signature(method)
+                params = list(sig.parameters.keys())
+                if len(params) - 1 == len(test_case.inputs):
+                    return name
+            except (ValueError, NameError):
+                continue
+    for name in solution_class.__dict__:
+        if not name.startswith("_"):
+            return name
+    raise ValueError("No public method found on Solution class")
+
+
+def _is_inplace_method(solution_class: type, method_name: str) -> bool:
+    method = solution_class.__dict__.get(method_name)
+    if not method:
+        return False
+    try:
+        sig = inspect.signature(method)
+        return sig.return_annotation is None or sig.return_annotation is inspect.Parameter.empty
+    except (ValueError, NameError):
+        return False
+
+
+def run_test_cases(
+    filepath: str,
+    test_cases: list[TestCase],
+) -> list[TraceResult]:
+    results: list[TraceResult] = []
+
+    solution_class = _load_solution_class(filepath)
+
+    for tc in test_cases:
+        method_name = _find_method(solution_class, tc)
+        instance = solution_class()
+        method = getattr(instance, method_name)
+
+        # Make a mutable copy for in-place methods
+        inputs = list(tc.inputs)
+        steps, return_value = trace_function_call(
+            method, tuple(inputs), filepath
+        )
+
+        if return_value is None and _is_inplace_method(solution_class, method_name):
+            return_value = inputs[0]
+
+        results.append(TraceResult(
+            test_case=tc,
+            steps=steps,
+            return_value=return_value,
+        ))
+
+    return results

slough-0.1.0/src/slough/tracer.py

@@ -0,0 +1,41 @@
+import sys
+from typing import Any, Callable
+
+from slough.models import TraceStep
+
+
+def _make_trace_callback(target_filename: str, steps: list[TraceStep]):
+    def trace_cb(frame, event, arg):
+        if frame.f_code.co_filename != target_filename:
+            return trace_cb
+
+        if event in ("line", "call", "return", "exception"):
+            steps.append(TraceStep(
+                lineno=frame.f_lineno,
+                event=event,
+                func_name=frame.f_code.co_name,
+                vars=dict(frame.f_locals),
+                return_value=arg if event in ("return", "exception") else None,
+            ))
+
+        return trace_cb
+
+    return trace_cb
+
+
+def trace_function_call(
+    fn: Callable,
+    args: tuple,
+    target_filename: str,
+) -> tuple[list[TraceStep], Any]:
+    steps: list[TraceStep] = []
+    trace_cb = _make_trace_callback(target_filename, steps)
+
+    old_trace = sys.gettrace()
+    sys.settrace(trace_cb)
+    try:
+        result = fn(*args)
+    finally:
+        sys.settrace(old_trace)
+
+    return steps, result