atrace 0.1.3__py3-none-any.whl → 0.1.6__py3-none-any.whl

atrace/__init__.py

@@ -3,27 +3,13 @@ import inspect
 import signal
 import sys
 from types import FrameType
-from typing import Any, Optional
+from typing import Optional
 
-from . import model, report, tracers
+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
 
 
@@ -32,29 +18,39 @@ def exit_handler():
     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 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
+
+
 def setup():
-    # This kicks off the tracing machinery (so that the lines below work)
-    sys.settrace(just_kicking_off)
+    """See https://docs.python.org/3/library/sys.html#sys.settrace for an explanation of all the convoluted things in here"""
 
     # 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 = tracers.VarTracer(
-                trace=trace, module_of_interest=module_of_interest
-            )
-            # Setup tracing outside of functions
-            importer_frame.f_trace = var_tracer.trace_vars
+            var_tracer = vartracer.VarTracer(trace, module_of_interest)
 
-            # Setup tracing inside of functions
+            # Setup tracing inside of functions.
+            # Order is important. This must be called before seting the trace function for the current frame
             sys.settrace(var_tracer.trace_vars)
 
-    sys.stdout = tracers.OutputLogger(trace=trace, stdout=sys.stdout)
+            # Setup tracing outside of functions
+            importer_frame.f_trace = 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}
@@ -62,4 +58,21 @@ def setup():
         signal.signal(sig, sig_handler)
 
 
-setup()
+def var_trace_for_code(code: str) -> model.Trace:
+    trace: model.Trace = []
+    # 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)
+            try:
+                sys.settrace(var_tracer.trace_vars)
+                exec(code)
+            finally:
+                sys.settrace(None)
+    return trace
+
+
+if "pytest" not in sys.modules:
+    setup()

atrace/model.py

@@ -2,28 +2,34 @@ from dataclasses import dataclass
 from typing import Any, TypeAlias
 
 
-@dataclass
+@dataclass(frozen=True)
 class PrintEvent:
     text: str
 
 
-@dataclass
+@dataclass(frozen=True)
 class Variable:
-    module: str | None
+    scope: str
     name: str
 
 
-@dataclass
+@dataclass(frozen=True)
+class ReturnEvent:
+    function_name: str
+    return_value: Any
+
+
+@dataclass(frozen=True)
 class VariableChangeEvent:
     variable: Variable
     value: Any
 
 
-@dataclass
+@dataclass(frozen=True)
 class TraceItem:
     line_no: int
     function_name: str
-    event: PrintEvent | VariableChangeEvent | None
+    event: PrintEvent | VariableChangeEvent | ReturnEvent
 
 
 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, passing down writes and flushes to it, while 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

@@ -1,38 +1,74 @@
+from dataclasses import dataclass
+from typing import Any, TypeAlias
+
+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
+@dataclass
+class Instant:
+    line_no: int
+    variable_changes: dict[model.Variable, Any]
+    output: str
+
+
+Instants: TypeAlias = list[Instant]
 
 
-def coalesce_print_events(trace: model.Trace) -> model.Trace:
-    last_print_item = None
+def trace_to_instants(trace: model.Trace) -> Instants:
+    instants = []
+    instant = None
     for trace_item in trace:
+        if instant is None or instant.line_no != trace_item.line_no:
+            instant = Instant(trace_item.line_no, {}, "")
+            instants.append(instant)
+
         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
+                instant.output += text
+            case model.VariableChangeEvent(variable, value):
+                # Don't clobber an existing value a variable if it changes again on the same line
+                # (this happens for example in tight loops)
+                if variable in instant.variable_changes:
+                    instant = Instant(trace_item.line_no, {}, "")
+                    instants.append(instant)
+                instant.variable_changes[variable] = value
+            case model.ReturnEvent():
+                pass  # XXX
 
-    return [i for i in trace if i.event is not None]
+    return instants
 
 
-def dump_report(trace: model.Trace) -> None:
-    trace = coalesce_print_events(trace)
+def variable_to_column_name(var: model.Variable) -> str:
+    return var.name if var.scope == "<module>" else f"({var.scope}) {var.name}"
 
-    variable_list = collect_variable_list(trace)
-    print("vars:", variable_list)
 
-    for trace_item in trace:
-        print(trace_item.line_no, trace_item.event)
+def formatted_table_from_instants(instants: Instants) -> str:
+    variables = []
+
+    for instant in instants:
+        for variable in instant.variable_changes:
+            if variable not in variables:
+                variables.append(variable)
+
+    LINE_NO, OUTPUT = "ligne", "affichage"
+
+    table = []
+    for instant in instants:
+        row: dict[str, Any] = {}
+        table.append(row)
+
+        row[LINE_NO] = instant.line_no
+        for variable in variables:
+            cell_for_variable = instant.variable_changes.get(variable, "")
+            row[variable_to_column_name(variable)] = cell_for_variable
+        row[OUTPUT] = instant.output
+
+    return tabulate(table, headers="keys", tablefmt="simple_outline")
+
+
+def dump_report(trace: model.Trace) -> None:
+    instants = trace_to_instants(trace)
+    formatted_table = formatted_table_from_instants(instants)
+    print(formatted_table)

atrace/{tracers.py → vartracer.py}

@@ -1,8 +1,7 @@
 import copy
 import inspect
-import sys
 from types import FrameType, ModuleType
-from typing import Any, TextIO
+from typing import Any
 
 from atrace import model
 
@@ -24,7 +23,7 @@ def copy_carefully(d: dict[str, Any]):
     for k, v in d.items():
         try:
             v_copy = copy.deepcopy(v)
-        except:
+        except Exception:
             v_copy = v
         res[k] = v_copy
     return res
@@ -34,14 +33,21 @@ 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 = {}
+        self.last_locals: dict[str, Any] = {}
 
     def trace_vars(self, frame: FrameType, event: str, arg: Any):
         if inspect.getmodule(frame) != self.module_of_interest:
             return
         if event == "return":
-            return
-        # print("####", event, frame.f_lineno, frame.f_code)
+            self.trace.append(
+                model.TraceItem(
+                    line_no=frame.f_lineno,
+                    function_name=frame.f_code.co_name,
+                    event=model.ReturnEvent(
+                        function_name=frame.f_code.co_name, return_value=arg  # XXX
+                    ),
+                )
+            )
 
         code = frame.f_code
 
@@ -51,17 +57,15 @@ class VarTracer:
             old_locals = self.last_locals[code.co_name]
 
         locals_now = copy_carefully(filtered_variables(frame.f_locals))
-        # print("locals_now", locals_now)
 
         for var, new_val in filtered_variables(locals_now).items():
             if var not in old_locals or old_locals[var] != new_val:
-                # print("çççç", frame.f_lineno, var)
                 self.trace.append(
                     model.TraceItem(
                         line_no=frame.f_lineno,
                         function_name=frame.f_code.co_name,
                         event=model.VariableChangeEvent(
-                            variable=model.Variable(module=code.co_name, name=var),
+                            variable=model.Variable(scope=code.co_name, name=var),
                             value=new_val,
                         ),
                     )
@@ -69,34 +73,3 @@ class VarTracer:
 
         self.last_locals[code.co_name] = locals_now
         return self.trace_vars
-
-
-class OutputLogger(object):
-    """
-    OutputLogger captures and logs the output produced by print statements during code execution.
-    """
-
-    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 it 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-0.1.6.dist-info/METADATA

@@ -0,0 +1,67 @@
+Metadata-Version: 2.4
+Name: atrace
+Version: 0.1.6
+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 idea of how things look:
+
+```
+
+```
+
+Does not work with :
+
+- Multithreaded programs
+- Multi-module programs
+- Classes
+
+# TODO
+
+- Unit tests for the capture part (because the line numbers are so hard). If pytest adds too much magic, then revert to UnitTest
+- 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 might not even be possible. Start solving it without functions in the scope.
+
+- Handle returns (with and without return statements)
+
+- Thonny, which adds a lot of indirection and magic. Try and find a way to edit the package directly when running in thonny
+
+# Later
+
+- localize the names of the line and output columns in the report
+
+# 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
+- Changes to variables in other scopes (for instance global)
+
+# 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.6.dist-info/RECORD

@@ -0,0 +1,9 @@
+atrace/__init__.py,sha256=FBVbvNBcU8agaIv62OT0PjhccY2-bhe0mkWOKT1H2fg,2406
+atrace/model.py,sha256=yhBJuciqRc4X_10QuHv18y4lB2N35m39DvpIpYYtiIQ,556
+atrace/outputlogger.py,sha256=gAM15WF7DOVxc6ZDBnMmutUJ7okeRoc9JUC4iqJaN9I,928
+atrace/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+atrace/report.py,sha256=P6fgj-dJUZYk1wbW_Q-MATXoedXUvZ28VR3RdBjU8dA,2240
+atrace/vartracer.py,sha256=bmENaHoSnh8-kdlJMaopWj5W8kPHjKC2E4k2Rx03f0k,2316
+atrace-0.1.6.dist-info/METADATA,sha256=vHaImexdGhE25FbLMO7e3vN3gyskzuub90fY6RIw9ZU,2200
+atrace-0.1.6.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+atrace-0.1.6.dist-info/RECORD,,

atrace-0.1.3.dist-info/METADATA

@@ -1,77 +0,0 @@
-Metadata-Version: 2.4
-Name: atrace
-Version: 0.1.3
-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:
-
-```
-+--------+-------------+-------------+----------------------------+-----------+-----------+----------+
-|   Line | (double)a   | (double)b   | (main)l                    | (main)x   | (main)y   | OUTPUT   |
-+========+=============+=============+============================+===========+===========+==========+
-|      2 |             |             |                            | 0         |           |          |
-+--------+-------------+-------------+----------------------------+-----------+-----------+----------+
-|      3 |             |             |                            | 0         | 10        |          |
-+--------+-------------+-------------+----------------------------+-----------+-----------+----------+
-|      5 |             |             |                            | 0         | 10        |    10    |
-+--------+-------------+-------------+----------------------------+-----------+-----------+----------+
-```
-
-Does not work with :
-
-- Multithreaded programs
-- Multi-module programs
-
-# Requirements/TODO
-
-- Build the goddam table
-- Fix line numbers in trace_vars
-- Parallel assignations show up properly
-- Thonny, which adds a shitload of indirection and magic
-
-# Later
-
-- Make robust. In other words should never raise an exception. ruff check, mypy, unit-tests.
-- Handle classes better
-- 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)
-
-# Build
-
-Automatically deployed to pypi every time a new tag is pushed: https://pypi.org/project/atrace/
-
-# Refs
-
-- https://stackoverflow.com/questions/16258553/how-can-i-define-algebraic-data-types-in-python To model the events in the trace
-
-- https://docs.python.org/3/library/sys.html#sys.settrace The python doc for settrace
-
-- https://stackoverflow.com/questions/23468042/the-invocation-of-signal-handler-and-atexit-handler-in-python to dump the trace when the program stops, no matter how.
-
-# Inspiration
-
-- https://github.com/DarshanLakshman/PyTracerTool Does almost everything I want, but has flaws: it chokes trying to deepcopy some objects, it cannot be simply imported into a module.
-
-- https://stackoverflow.com/questions/1645028/trace-table-for-python-programs Some ideas in there

atrace-0.1.3.dist-info/RECORD

@@ -1,8 +0,0 @@
-atrace/__init__.py,sha256=qFhpaphaeyb40MQKk-N2AC17HsZyg8sjOCN__ukhSnY,1715
-atrace/model.py,sha256=_Fd1XWH5CThBjpZJEWm7rBkxP79IcKDPB8JQq_ksa6Y,415
-atrace/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-atrace/report.py,sha256=c5H8EVhyoHLygI3DVkSv96Mn_bZxPcdmHt1TcY8HFqI,1218
-atrace/tracers.py,sha256=TxTxZGe6Oxn-RKoI5nDFT71kA3Aa1oGxnWMbRrsELtE,2987
-atrace-0.1.3.dist-info/METADATA,sha256=iGTG8NhZ7ZGsW8WtsEZzSaZcXWJbhInL-8HIuYNAHoo,3212
-atrace-0.1.3.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-atrace-0.1.3.dist-info/RECORD,,