atrace 0.1.5__py3-none-any.whl

atrace/__init__.py

@@ -0,0 +1,67 @@
+import atexit
+import inspect
+import signal
+import sys
+from types import FrameType
+from typing import Any, Optional
+
+from . import model, outputlogger, report, vartracer
+
+trace: model.Trace = []
+
+
+def just_kicking_off(frame: FrameType, event: str, arg: Any):
+    return None
+
+
+def get_importer_frame() -> Optional[FrameType]:
+    # Get the current call stack
+    for frame_info in inspect.stack():
+        # Filter out internal importlib frames and the current module's frame
+        filename = frame_info.filename
+        if not filename.startswith("<") and filename != __file__:
+            return frame_info.frame
+    return None
+
+
+original_stdout = sys.stdout
+
+
+def exit_handler():
+    sys.stdout = original_stdout
+    report.dump_report(trace)
+
+
+# https://stackoverflow.com/questions/23468042/the-invocation-of-signal-handler-and-atexit-handler-in-python
+def sig_handler(_signo, _frame):
+    sys.exit(0)
+
+
+def setup():
+    """See https://docs.python.org/3/library/sys.html#sys.settrace for an explanation of all the convoluted things in here"""
+
+    # This kicks off the tracing machinery (so that the lines below work)
+    sys.settrace(just_kicking_off)
+
+    # We want to only trace the module that imports us
+    importer_frame = get_importer_frame()
+    if importer_frame:
+        module_of_interest = inspect.getmodule(importer_frame)
+        if module_of_interest:
+            var_tracer = vartracer.VarTracer(trace, module_of_interest)
+
+            # Setup tracing outside of functions
+            importer_frame.f_trace = var_tracer.trace_vars
+
+            # Setup tracing inside of functions
+            sys.settrace(var_tracer.trace_vars)
+
+    sys.stdout = outputlogger.OutputLogger(trace=trace, stdout=sys.stdout)
+
+    atexit.register(exit_handler)
+    catchable_sigs = set(signal.Signals) - {signal.SIGKILL, signal.SIGSTOP}
+    for sig in catchable_sigs:
+        signal.signal(sig, sig_handler)
+
+
+setup()

atrace/model.py

@@ -0,0 +1,29 @@
+from dataclasses import dataclass
+from typing import Any, TypeAlias
+
+
+@dataclass
+class PrintEvent:
+    text: str
+
+
+@dataclass(frozen=True)
+class Variable:
+    function_name: str | None
+    name: str
+
+
+@dataclass(frozen=True)
+class VariableChangeEvent:
+    variable: Variable
+    value: Any
+
+
+@dataclass
+class TraceItem:
+    line_no: int
+    function_name: str
+    event: PrintEvent | VariableChangeEvent
+
+
+Trace: TypeAlias = list[TraceItem]

atrace/outputlogger.py

@@ -0,0 +1,35 @@
+import sys
+from typing import TextIO
+
+from . import model
+
+
+class OutputLogger:
+    """
+    OutputLogger wraps stdout, writing to it and simultaneously capturing the text to the trace.
+    """
+
+    def __init__(self, trace: model.Trace, stdout: TextIO):
+        self.trace = trace
+        self.stdout = stdout
+
+    def write(self, text: str) -> None:
+        """
+        Write to stdout and record the text in the trace
+        """
+        self.stdout.write(text)
+
+        frame = sys._getframe(1)
+        # An alternative that uses a public API, but then the type checker bothers me
+        # frame = inspect.currentframe().f_back
+
+        self.trace.append(
+            model.TraceItem(
+                line_no=frame.f_lineno,
+                function_name=frame.f_code.co_name,
+                event=model.PrintEvent(text),
+            )
+        )
+
+    def flush(self):
+        self.stdout.flush()

atrace/report.py

@@ -0,0 +1,98 @@
+from dataclasses import dataclass
+from typing import Any
+
+from tabulate import tabulate
+
+from . import model
+
+
+def collect_variable_list(trace: model.Trace) -> list[model.Variable]:
+    variable_list = []
+    for traceItem in trace:
+        match traceItem.event:
+            case model.VariableChangeEvent(variable_name, _):
+                if variable_name not in variable_list:
+                    variable_list.append(variable_name)
+    return variable_list
+
+
+def coalesce_print_events(trace: model.Trace) -> model.Trace:
+    last_print_item = None
+    for trace_item in trace:
+        match trace_item.event:
+            case model.PrintEvent(text):
+                if (
+                    last_print_item is None
+                    or trace_item.line_no != last_print_item.line_no
+                ):
+                    last_print_item = trace_item
+                else:
+                    last_print_item.event.text += text
+                    trace_item.event = None  # Mark for deletion
+            case _:
+                last_print_item = None
+
+    return [item for item in trace if item.event is not None]
+
+
+def contains_prints(trace: model.Trace) -> bool:
+    for trace_item in trace:
+        match trace_item.event:
+            case model.PrintEvent:
+                return True
+    return False
+
+
+def variable_to_column_name(var: model.Variable) -> str:
+    context = None if var.function_name == "<module>" else var.function_name
+    return "(" + context + ") " + var.name if context else var.name
+
+
+@dataclass
+class Line:
+    line_no: int
+    variable_changes: dict[str, Any]
+    output: str | None
+
+
+def dump_report(trace: model.Trace) -> None:
+    trace = coalesce_print_events(trace)
+
+    # Build intermediate "lines" datastructure, that collects all events that happen on a given line
+    lines = []
+    current_line = None
+    for trace_item in trace:
+        if current_line is None or current_line.line_no != trace_item.line_no:
+            current_line = Line(trace_item.line_no, {}, None)
+            lines.append(current_line)
+
+        match trace_item.event:
+            case model.VariableChangeEvent(variable, value):
+                # Don't clobber a new value if it changes on the same line
+                # (this happens for example in tight loops)
+                if variable in current_line.variable_changes:
+                    current_line = Line(trace_item.line_no, {}, None)
+                    lines.append(current_line)
+
+                current_line.variable_changes[variable_to_column_name(variable)] = value
+            case model.PrintEvent(text):
+                current_line.output = text
+
+    # The extra spaces so the names cannot collide with variable names
+    LINE_NO, OUTPUT = " ligne", "affichage "
+
+    variable_list = collect_variable_list(trace)
+    headers = [LINE_NO] + [variable_to_column_name(v) for v in variable_list] + [OUTPUT]
+    table = []
+    for line in lines:
+        table_row = [line.line_no]
+        for column_name in headers[1:-1]:
+            variable_value = line.variable_changes.get(column_name)
+            if variable_value:
+                table_row.append(variable_value)
+            else:
+                table_row.append(None)
+        table_row.append(line.output)
+        table.append(table_row)
+
+    print(tabulate(table, headers=headers, tablefmt="outline"))

atrace/vartracer.py

@@ -0,0 +1,69 @@
+import copy
+import inspect
+from types import FrameType, ModuleType
+from typing import Any
+
+from atrace import model
+
+
+def ignore_variable(name: str, value: Any):
+    return name.startswith("__") or callable(value) or isinstance(value, ModuleType)
+
+
+def filtered_variables(variables: dict[str, Any]) -> dict[str, Any]:
+    return {
+        name: value
+        for name, value in variables.items()
+        if not ignore_variable(name, value)
+    }
+
+
+def copy_carefully(d: dict[str, Any]):
+    res = {}
+    for k, v in d.items():
+        try:
+            v_copy = copy.deepcopy(v)
+        except Exception:
+            v_copy = v
+        res[k] = v_copy
+    return res
+
+
+class VarTracer:
+    def __init__(self, trace: model.Trace, module_of_interest: ModuleType):
+        self.trace = trace
+        self.module_of_interest = module_of_interest
+        self.last_locals = {}
+
+    def trace_vars(self, frame: FrameType, event: str, arg: Any):
+        if inspect.getmodule(frame) != self.module_of_interest:
+            return
+        if event == "return":
+            return
+
+        code = frame.f_code
+
+        if code.co_name not in self.last_locals:
+            old_locals = {}
+        else:
+            old_locals = self.last_locals[code.co_name]
+
+        locals_now = copy_carefully(filtered_variables(frame.f_locals))
+
+        for var, new_val in filtered_variables(locals_now).items():
+            if var not in old_locals or old_locals[var] != new_val:
+                self.trace.append(
+                    model.TraceItem(
+                        line_no=frame.f_lineno,
+                        function_name=frame.f_code.co_name,
+                        event=model.VariableChangeEvent(
+                            variable=model.Variable(
+                                function_name=code.co_name, name=var
+                            ),
+                            value=new_val,
+                        ),
+                    )
+                )
+
+        self.last_locals[code.co_name] = locals_now
+        return self.trace_vars

atrace-0.1.5.dist-info/METADATA

@@ -0,0 +1,86 @@
+Metadata-Version: 2.4
+Name: atrace
+Version: 0.1.5
+Summary: Generate trace tables for programs
+Project-URL: Repository, https://github.com/nwolff/atrace.git
+Author-email: Nicholas Wolff <nwolff@gmail.com>
+Requires-Python: >=3.10
+Requires-Dist: tabulate>=0.9.0
+Description-Content-Type: text/markdown
+
+# Usage
+
+Automatically prints a trace table of a program once the execution is finished.
+
+Just import the module.
+
+An animated example of a trace table: https://www.101computing.net/using-trace-tables/
+
+An idea of how things look:
+
+```
++-----------+-----+-----+---------+---------------+-----------------------+-------------------------+
+|    ligne  |   x |   y | (f) a   | (f) b         | (f) c                 |  affichage              |
++===========+=====+=====+=========+===============+=======================+=========================+
+|         5 |   1 |   3 |         |               |                       |                         |
+|         7 |   2 |     |         |               |                       |                         |
+|         5 |     |   2 |         |               |                       |                         |
+|         7 |   3 |     |         |               |                       |                         |
+|         5 |     |   1 |         |               |                       |                         |
+|         7 |   4 |     |         |               |                       |                         |
+|         5 |     |     |         |               |                       |                         |
+|         9 |     |     |         |               |                       | somme:  4               |
+|        12 |     |     | Bonjour | tout le monde |                       |                         |
+|        14 |     |     |         |               | Bonjour tout le monde | Bonjour tout le monde ! |
++-----------+-----+-----+---------+---------------+-----------------------+-------------------------+
+```
+
+Does not work with :
+
+- Multithreaded programs
+- Multi-module programs
+- Classes
+
+# TODO
+
+- Fix line numbers in trace_vars. https://discuss.python.org/t/trace-a-line-after-the-line-but-not-only-before-the-line/89475/7
+  This is a bitch
+- Thonny, which adds a lot of indirection and magic
+
+# Later
+
+- Make robust. In other words should never raise an exception.
+- mypy, unit-tests. Integrate in build pipeline
+- localize the names of the line and output columns in the report
+- Handle classes better
+
+# Possible enhancements
+
+- More details when recursive invocations
+- Think about how to show returns
+- Find if there could be a good use for colors in the trace
+
+# Done
+
+- Sets the program print to stdout unhindered (this is important for input to work properly),
+  but captures the prints at the same time to show in the trace at the end.
+- Emits the trace at the end if the application ends normally and abruptly (exception, signal, etc.)
+- Shows bindings to local variables when entering a function
+- Handles mutations to objects like lists (by copying the previous version and then comparing)
+- Parallel assignations show up properly
+
+# Build
+
+Automatically deployed to pypi every time a new tag is pushed: https://pypi.org/project/atrace/
+
+# Inspiration
+
+https://github.com/DarshanLakshman/PyTracerTool/blob/master/PyTracerTool/pytracertool.py
+
+Does almost everything I want, but has many flaws:
+
+- it chokes trying to deepcopy some objects
+- it cannot be simply imported into a module
+- it fumbles the handling of output (preventing programs with input from working properly).
+- it repeats values for no good reason
+- its line numbers are very confused

atrace-0.1.5.dist-info/RECORD

@@ -0,0 +1,9 @@
+atrace/__init__.py,sha256=MdubXhWJW6S5OqDrA3-YYOjl91EomeoCmBC4MwInPmQ,1920
+atrace/model.py,sha256=uNX2rjYOZYIATY_ZvXFYiD5FhLeQ02Bqy8ExnRFPiK8,441
+atrace/outputlogger.py,sha256=ct1jlUlK03ZI5hy45aysdb2I9UDWPLK4hxRJ_aU83Xk,901
+atrace/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+atrace/report.py,sha256=6p19dK3YWI8mn-HPiGRp55UE7ddJg7TjGgw1b2S0CCA,3350
+atrace/vartracer.py,sha256=O3FPZhWl2nHcmtQHu1HECwP1ZF8X9XGNuk9xTe7Y1Og,2041
+atrace-0.1.5.dist-info/METADATA,sha256=AtkCObDbIF95triDjCOqba1Xx93zWm7Wqb9MhKuh2Qc,3628
+atrace-0.1.5.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+atrace-0.1.5.dist-info/RECORD,,

atrace-0.1.5.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any