firecrown.fctools.tracer
========================

.. py:module:: firecrown.fctools.tracer

.. autoapi-nested-parse::

   Method tracing facility.

   This module provides a facility to capture and record tracing data, using the
   `sys.settrace` method. It causes a tab-separated value file to be written, with
   one record (line) for each captured event.

   The columns in the file are:

       entry:
           a sequential entry number, for each event
       event:
           the event type (call, return, exception)
       level:
           the call nesting level
       function:
           the function name
       value:
           for a 'call' entry, the names of the arguments;
           for a 'return' entry, the return value
       extra:
           for a 'call' entry, the type self, if that is the first argument;
           for a 'return' entry, the type of the return value

   N.B.: This tracer should be used only for debugging and development purposes.
         It interferes with the pytest test coverage measurement process.



Attributes
----------

.. autoapisummary::

   firecrown.fctools.tracer.app


Classes
-------

.. autoapisummary::

   firecrown.fctools.tracer.TracerState


Functions
---------

.. autoapisummary::

   firecrown.fctools.tracer.settrace
   firecrown.fctools.tracer.untrace
   firecrown.fctools.tracer.main


Module Contents
---------------

.. py:class:: TracerState(filename = 'trace.tsv')

   Encapsulates tracing state to avoid global variables.


   .. py:attribute:: tracefile


   .. py:attribute:: level
      :value: 0



   .. py:attribute:: entry
      :value: 0



   .. py:method:: trace_call(fr, ev, arg)

      Callback used by settrace.

      :param fr: the frame object
      :param ev: the event type
      :param arg: the argument



   .. py:method:: close()

      Close the trace file.



.. py:function:: settrace(filename = 'trace.tsv')

   Start the tracer, with log being written to a new file with the given name.

   :param filename: the name of the new file to be created
   :return: TracerState instance managing the trace


.. py:function:: untrace(tracer)

   Turn off tracing, and close the specified trace file.

   :param tracer: TracerState instance, as returned by settrace.

   .. note::
       Coverage tracking doesn't work for this function due to sys.settrace()
       interaction between coverage.py and the tracer. Tests verify functionality
       without coverage enabled.

   :param tracer: TracerState instance, as returned by settrace.


.. py:data:: app

.. py:function:: main(target = typer.Argument(..., help='Python script file or module name to trace'), output = typer.Option('trace.tsv', '--output', '-o', help='Output trace file'), module = typer.Option(False, '--module', '-m', help='Run target as a module (like python -m module)'))

   Trace execution of a Python script or module.

   This tool enables method tracing for Python code, recording function
   calls, returns, and exceptions to a TSV file for analysis.