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

atrace/__init__.py

@@ -1,101 +1,65 @@
-import copy
+import atexit
 import inspect
+import signal
 import sys
 from types import FrameType
-from typing import Any
+from typing import Any, Optional
 
-paused = True
-last_locals = {}
+from . import model, report, tracers
 
-ignored_variables = set(
-    [
-        "tid",
-    ]
-)
+trace: model.Trace = []
 
 
-def ignore_variable(var: str):
-    return var in ignored_variables
-
-
-def copy_carefully_using_ignored_variables(d: dict[str, Any]):
-    res = {}
-    for k, v in d.items():
-        if not ignore_variable(k):
-            res[k] = copy.deepcopy(v)
-    return res
-
-
-def copy_carefully(d: dict[str, Any]):
-    res = {}
-    for k, v in d.items():
-        try:
-            v_copy = copy.deepcopy(v)
-        except:
-            v_copy = v
-        res[k] = v_copy
-    return res
+def just_kicking_off(frame: FrameType, event: str, arg: Any):
+    return None
 
 
-def trace_vars(frame: FrameType, event: str, arg: Any):
-    if paused:
-        return
-    # print(frame.f_lineno, frame.f_code.co_name, frame.f_locals, event)
-    if event != "line":
-        return trace_vars
-    code = frame.f_code
-    lineno = frame.f_lineno
-    locals_now = copy_carefully(frame.f_locals)
-    global last_locals
+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
 
-    if last_locals is None:  # We're being unloaded, it's the end of the program
-        return None
 
-    if code.co_name not in last_locals:
-        last_locals[code.co_name] = locals_now
-        return trace_vars
+original_stdout = sys.stdout
 
-    old_locals = last_locals[code.co_name]
 
-    for var, new_val in locals_now.items():
-        if not ignore_variable(var):
-            if var not in old_locals:
-                print(f"[{lineno}] NEW {var} = {new_val}")
-            elif old_locals[var] != new_val:
-                print(f"[{lineno}] MODIFIED {var}: {old_locals[var]} → {new_val}")
+def exit_handler():
+    sys.stdout = original_stdout
+    report.dump_report(trace)
 
-    for var in old_locals:
-        if not ignore_variable(var):
-            if var not in locals_now:
-                print(f"[{lineno}] DELETED {var}")
 
-    last_locals[code.co_name] = locals_now
-    return trace_vars
+def sig_handler(_signo, _frame):
+    sys.exit(0)
 
 
-def just_kicking_off(frame: FrameType, event: str, arg: Any):
-    return None
+def setup():
+    # 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 = tracers.VarTracer(
+                trace=trace, module_of_interest=module_of_interest
+            )
+            # Setup tracing outside of functions
+            importer_frame.f_trace = var_tracer.trace_vars
 
-def get_importer_frame():
-    # 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
+            # Setup tracing inside of functions
+            sys.settrace(var_tracer.trace_vars)
 
+    sys.stdout = tracers.OutputLogger(trace=trace, stdout=sys.stdout)
 
-# This will work next time we enter a function.
-# It also kicks off the tracing machinery (so that the lines below work)
-sys.settrace(trace_vars)
+    atexit.register(exit_handler)
+    catchable_sigs = set(signal.Signals) - {signal.SIGKILL, signal.SIGSTOP}
+    for sig in catchable_sigs:
+        signal.signal(sig, sig_handler)
 
 
-# This reaches into the importing module's frame to setup tracing
-importer_frame = get_importer_frame()
-if importer_frame:
-    importer_frame.f_trace = trace_vars
-    paused = False
-else:
-    print("Cannot trace")
+setup()

atrace/model.py

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

atrace/report.py

@@ -0,0 +1,38 @@
+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
+
+    return [i for i in trace if i.event is not None]
+
+
+def dump_report(trace: model.Trace) -> None:
+    trace = coalesce_print_events(trace)
+
+    variable_list = collect_variable_list(trace)
+    print("vars:", variable_list)
+
+    for trace_item in trace:
+        print(trace_item.line_no, trace_item.event)

atrace/tracers.py

@@ -0,0 +1,102 @@
+import copy
+import inspect
+import sys
+from types import FrameType, ModuleType
+from typing import Any, TextIO
+
+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:
+            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
+        # print("####", event, frame.f_lineno, frame.f_code)
+
+        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))
+        # 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),
+                            value=new_val,
+                        ),
+                    )
+                )
+
+        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.3.dist-info/METADATA

@@ -0,0 +1,77 @@
+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

@@ -0,0 +1,8 @@
+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,,

atrace-0.1.1.dist-info/METADATA

@@ -1,65 +0,0 @@
-Metadata-Version: 2.4
-Name: atrace
-Version: 0.1.1
-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.7
-Description-Content-Type: text/markdown
-
-# TODO:
-
-- entering a function, binding the local arguments, returning
-- ignore function definitions (look at the type of object)
-
-- display at end only
-
-# Usage and intent
-
-A package that automatically prints a trace table of a program, just by importing the module
-
-- Should not interfere with the running program (apart from capturing stdout)
-- Should display the trace at the end of execution (not while the program is interacting with the user)
-- Should display the trace even if an exception interrupts the program
-- Should display the trace even if the user interrupts the program
-- Should handle mutations to objects like lists
-- Should handle functions properly:
-  - entering the function
-  - binding the local arguments
-  - returning
-
-An animated example of a trace table: https://www.101computing.net/using-trace-tables/
-
-# Not in scope
-
-- Multithreaded programs
-
-# Implementation
-
-To trace variables :
-
-- Either https://docs.python.org/3/library/sys.html#sys.settrace
-- Or https://docs.python.org/3/library/trace.html
-
-To capture stdout :
-
-- Either https://docs.python.org/3/library/contextlib.html#contextlib.redirect_stdout
-- Or just reassign stdout
-
-To trap sigint:
-
-- https://stackoverflow.com/questions/1112343/how-do-i-capture-sigint-in-python
-
-# Build
-
-Automatically deployed to pypi every time a new tag is pushed: https://pypi.org/project/atrace/
-
-# Technical Refs
-
-- First similar thing I found, doesn't work (chokes on deep copying some variables): https://github.com/DarshanLakshman/PyTracerTool
-
-- 11 years old, doesn't work: https://github.com/mihneadb/python-execution-trace
-
-- A hot mess: https://stackoverflow.com/questions/1645028/trace-table-for-python-programs
-
-- A tutorial on the trace module: https://pymotw.com/2/trace/

atrace-0.1.1.dist-info/RECORD

@@ -1,5 +0,0 @@
-atrace/__init__.py,sha256=wUmeppysEV7VYt8ZpVnhX9IL_Pec_50FjGqHmS5gEwc,2550
-atrace/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-atrace-0.1.1.dist-info/METADATA,sha256=4oknmUUp4BvNtji0hRV121JKvtkjC2BOO6pt9zPqDgI,2026
-atrace-0.1.1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-atrace-0.1.1.dist-info/RECORD,,