bundle.perf_report
==================

.. py:module:: bundle.perf_report


Submodules
----------

.. toctree::
   :maxdepth: 1

   /autoapi/bundle/perf_report/cli/index
   /autoapi/bundle/perf_report/extractor/index
   /autoapi/bundle/perf_report/report/index
   /autoapi/bundle/perf_report/storage/index


Classes
-------

.. autoapisummary::

   bundle.perf_report.ProfileExtractor
   bundle.perf_report.ProfileRecord
   bundle.perf_report.ProfileStorage


Package Contents
----------------

.. py:class:: ProfileExtractor

   Extract profiling data from Tracy CSV files produced by tracy-csvexport.


   .. py:method:: extract(csv_path: pathlib.Path) -> ProfileData
      :staticmethod:


      Parse a single Tracy CSV file and return structured data.



   .. py:method:: extract_from_tracy(tracy_path: pathlib.Path) -> ProfileData
      :staticmethod:


      Run tracy-csvexport on a .tracy file, save a sibling .csv, and return ProfileData.

      Requires tracy-csvexport to be on PATH (built via: bundle tracy build csvexport).
      The CSV is saved alongside the .tracy file so it can be reused without re-exporting.



   .. py:method:: extract_all(path: pathlib.Path) -> list[ProfileData]
      :staticmethod:


      Extract from a .tracy file, a single CSV file, or all CSV files in a directory.



.. py:class:: ProfileRecord

   A single zone entry from a Tracy CSV export (tracy-csvexport).


   .. py:attribute:: name
      :type:  str


   .. py:attribute:: src_file
      :type:  str


   .. py:attribute:: src_line
      :type:  int


   .. py:attribute:: total_ns
      :type:  int


   .. py:attribute:: total_perc
      :type:  float


   .. py:attribute:: counts
      :type:  int


   .. py:attribute:: mean_ns
      :type:  int


   .. py:attribute:: min_ns
      :type:  int


   .. py:attribute:: max_ns
      :type:  int


   .. py:attribute:: std_ns
      :type:  float


.. py:class:: ProfileStorage(h5_path: pathlib.Path | str)

   Store and retrieve Tracy zone data in HDF5, keyed by version and platform.

   HDF5 layout::

       /<version>/<platform_id>/meta       (attrs: machine_id, platform_id, bundle_version, timestamp)
       /<version>/<platform_id>/profiles/<name>  (structured dataset)


   .. py:attribute:: h5_path


   .. py:method:: save(profiles: list[bundle.perf_report.extractor.ProfileData], machine_id: str, bundle_version: str, platform_id: str, platform_meta: dict | None = None)

      Write profiles under /<version>/<platform_id>/, appending to existing file.



   .. py:method:: list_versions() -> list[str]


   .. py:method:: list_platforms(version: str) -> list[str]


   .. py:method:: load_meta(version: str, platform_id: str) -> dict


   .. py:method:: load_profiles(version: str, platform_id: str) -> list[bundle.perf_report.extractor.ProfileData]

      Load all profiles for a specific version+platform.



   .. py:method:: from_directory(prof_dir: pathlib.Path, h5_path: pathlib.Path, machine_id: str, bundle_version: str, platform_id: str, platform_meta: dict | None = None) -> ProfileStorage
      :classmethod:


      Extract all Tracy CSV files from a path and save to HDF5.