asp_plot.asp_log
================

.. py:module:: asp_plot.asp_log

.. autoapi-nested-parse::

   Versioned adapter for parsing NASA Ames Stereo Pipeline (ASP) log files.

   ASP writes one plain-text log per tool invocation (``bundle_adjust``,
   ``stereo_pprc`` ... ``stereo_tri``, ``point2dem``). Each log starts with a
   version banner, then the literal command line that was run, then timestamped
   ``console`` lines. The exact layout has been stable across ASP 3.x but is not
   guaranteed to stay fixed.

   Rather than scatter hardcoded regexes and ``line.split()[0]`` indexing through
   the call sites (which fail silently when the format drifts), all format
   knowledge lives here behind a small adapter that is *keyed by ASP version*. A
   new ASP log layout becomes a new :class:`AspLogFormat` subclass registered in
   ``ASP_LOG_FORMATS``; everything downstream keeps working through the stable
   :class:`AspLog` interface.

   When a field cannot be parsed the adapter returns ``None`` and logs a warning
   (at ``logger`` level) so format drift surfaces instead of being swallowed.



Attributes
----------

.. autoapisummary::

   asp_plot.asp_log.ASP_LOG_FORMATS
   asp_plot.asp_log.ASP_TOOL_NAMES
   asp_plot.asp_log.DEFAULT_FORMAT
   asp_plot.asp_log.STEREO_STEP_ORDER
   asp_plot.asp_log.logger


Classes
-------

.. autoapisummary::

   asp_plot.asp_log.AspLog
   asp_plot.asp_log.AspLogFormat


Functions
---------

.. autoapisummary::

   asp_plot.asp_log.register_format
   asp_plot.asp_log.select_format


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

.. py:class:: AspLog(path)

   A single ASP log file, parsed through the matching versioned adapter.

   Reads the file once on construction and exposes the parsed fields as
   properties. Selecting the adapter from the version banner means a caller
   never needs to know which ASP version produced the log.


   .. py:method:: canonical_command(tool_name)

      Return the command line with its executable replaced by ``tool_name``.

      ASP logs the executable as an absolute path (or a stage-specific name
      like ``stereo_tri``); reports want a canonical, path-free invocation
      such as ``bundle_adjust ...`` or ``stereo ...``. Returns ``None`` if no
      command line was found.



   .. py:property:: asp_version

      The ASP version string, or ``None`` if the banner is absent.


   .. py:property:: command

      The full command line (tool + args), or ``None`` if not found.


   .. py:property:: first_timestamp

      The earliest console timestamp, or ``None``.


   .. py:attribute:: format


   .. py:property:: last_timestamp

      The latest console timestamp, or ``None``.


   .. py:attribute:: path


   .. py:property:: reference_dem

      The reference-DEM path announced in the log, or ``None``.


   .. py:property:: timestamps

      All parsed console timestamps, in file order.


   .. py:property:: tool

      The executable basename of the invocation (e.g. ``stereo_tri``).


.. py:class:: AspLogFormat

   Adapter describing how to read one ASP log layout.

   The base class implements the ASP 3.x layout. To support a drifted format,
   subclass it, override the class attributes (or methods) that changed, give
   it a distinguishing :meth:`supports`, and register the subclass in
   ``ASP_LOG_FORMATS`` ahead of the default.


   .. py:method:: parse_command_line(lines)

      Locate the tool invocation line in ``lines``.

      Returns ``(tool, command)`` where ``tool`` is the executable basename
      (e.g. ``stereo_tri``) and ``command`` is the full stripped command
      line, or ``None`` if no known ASP tool invocation is found.

      The line is found by matching the basename of its first token against
      :data:`ASP_TOOL_NAMES`, skipping the banner, build metadata and
      timestamped console lines -- robust against substring collisions in
      later log output.



   .. py:method:: parse_reference_dem(lines)

      Return the last reference-DEM path announced in ``lines``, or ``None``.

      The last match wins to mirror the historical behavior (ASP re-announces
      the DEM and the final mention is the one used).



   .. py:method:: parse_timestamp(line)

      Return the :class:`datetime` from a leading timestamp, or ``None``.



   .. py:method:: parse_version(banner_line)

      Return the ASP version string from the banner, or ``None``.



   .. py:method:: supports(banner_line)
      :classmethod:


      Whether this adapter handles a log with the given first line.

      The default ASP 3.x adapter claims any ``ASP 3.*`` banner.



   .. py:attribute:: name
      :value: 'asp-3.x'



   .. py:attribute:: reference_dem_re


   .. py:attribute:: timestamp_fmt
      :value: '%Y-%m-%d %H:%M:%S'



   .. py:attribute:: timestamp_re


   .. py:attribute:: version_banner_re


.. py:function:: register_format(fmt, prepend=True)

   Register an :class:`AspLogFormat` subclass for adapter selection.

   The extension point for ASP format drift: when a future ASP version
   changes the log layout, subclass :class:`AspLogFormat`, override what
   changed and its :meth:`~AspLogFormat.supports`, then register it here.
   Registered formats are consulted by :func:`select_format` in order, so by
   default a new (more specific) format is prepended ahead of the permissive
   ASP 3.x default.


.. py:function:: select_format(banner_line)

   Return an adapter instance for a log whose first line is ``banner_line``.

   Falls back to the default ASP 3.x adapter (with a warning) when no
   registered format claims the banner, so an unrecognized version degrades
   gracefully instead of dropping all fields.


.. py:data:: ASP_LOG_FORMATS

.. py:data:: ASP_TOOL_NAMES

.. py:data:: DEFAULT_FORMAT

.. py:data:: STEREO_STEP_ORDER
   :value: ('stereo_pprc', 'stereo_corr', 'stereo_blend', 'stereo_rfne', 'stereo_fltr', 'stereo_tri')


.. py:data:: logger