plesty.lib.test.analyzer_pipeline
=================================

.. py:module:: plesty.lib.test.analyzer_pipeline

.. autoapi-nested-parse::

   Standard analyzer contract test pipeline for PLESTY analyzer modules.

   Import ``AnalyzerPipeline`` in an analyzer module's test suite and call the
   individual gate methods from pytest test functions, or call
   ``run_mock_pipeline()`` to run all gates in one shot. No hardware and no real
   data are needed: synthetic inputs are generated from the declared
   ``input_schema`` (override any of them via ``mock_inputs`` when a transform
   needs realistic values).

   Typical usage in an analyzer module::

       # tests/test_pipeline.py
       from plesty.lib.test.analyzer_pipeline import AnalyzerPipeline

       PIPELINE = AnalyzerPipeline(MyAnalyzer)

       def test_analyzer_subclass():
           PIPELINE.test_analyzer_subclass()

       def test_schema_integrity():
           PIPELINE.test_schema_integrity()

       def test_analyze_signature():
           PIPELINE.test_analyze_signature()

       def test_mock_roundtrip():
           PIPELINE.test_mock_roundtrip()

       def test_provenance_stamped():
           PIPELINE.test_provenance_stamped()

   Gate summary
   ------------

   * Gate 1 ``test_analyzer_subclass`` — public Analyzer subclass, instantiable
     with the provided parameters.
   * Gate 2 ``test_schema_integrity`` — both schemas non-empty, dtype tokens
     resolvable, shapes well-formed.
   * Gate 3 ``test_analyze_signature`` — ``analyze()`` accepts exactly the
     schema-declared input names.
   * Gate 4 ``test_mock_roundtrip`` — synthetic inputs produce outputs matching
     ``output_schema`` through the validating ``__call__``.
   * Gate 5 ``test_provenance_stamped`` — results carry the provenance stamp
     (analyzer identity, version, parameters).



Attributes
----------

.. autoapisummary::

   plesty.lib.test.analyzer_pipeline._MOCK_ARRAY_LENGTH


Classes
-------

.. autoapisummary::

   plesty.lib.test.analyzer_pipeline.AnalyzerPipeline


Functions
---------

.. autoapisummary::

   plesty.lib.test.analyzer_pipeline._mock_value


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

.. py:data:: _MOCK_ARRAY_LENGTH
   :value: 8


.. py:class:: AnalyzerPipeline(analyzer_cls: type[plesty.lib.analyzer.Analyzer], *args: Any, mock_inputs: dict[str, Any] | None = None, **kwargs: Any)

   Standard test pipeline for a PLESTY analyzer module.

   :param analyzer_cls: The analyzer class under test. Must be instantiable with the given
                        arguments — analysis parameters and calibration handles belong to the
                        constructor by contract.
   :param \*args: Positional arguments forwarded to ``analyzer_cls.__init__``.
   :param mock_inputs: Optional overrides for the synthetic inputs of the round-trip gates,
                       keyed by input name. Inputs not overridden are generated from the
                       ``input_schema`` (zeros of the declared shape, neutral scalars).
   :param \*\*kwargs: Keyword arguments forwarded to ``analyzer_cls.__init__``.
   :param Store the analyzer class:
   :param its construction arguments:
   :param and overrides.:


   .. py:attribute:: analyzer_cls


   .. py:attribute:: args
      :value: ()



   .. py:attribute:: kwargs


   .. py:attribute:: mock_inputs


   .. py:method:: _instantiate() -> plesty.lib.analyzer.Analyzer

      Construct the analyzer under test with the stored arguments.



   .. py:method:: _generate_inputs() -> dict[str, Any]

      Build synthetic inputs from the schema, applying ``mock_inputs``.



   .. py:method:: test_analyzer_subclass() -> None

      Gate 1: the class is a public, instantiable Analyzer subclass.

      Verifies inheritance from :class:`plesty.lib.analyzer.Analyzer`, a
      public class name, and that construction succeeds with the pipeline's
      parameters (an abstract subclass cannot be instantiated — ``analyze``
      must be implemented).



   .. py:method:: test_schema_integrity() -> None

      Gate 2: both schemas are non-empty with resolvable dtypes and shapes.

      Instantiation already runs the base declaration checks (allowed keys,
      resolvable ``dtype``, well-formed ``shape``); this gate additionally
      requires that an analyzer declares at least one input and one output —
      an undeclared interface cannot be validated or documented.



   .. py:method:: test_analyze_signature() -> None

      Gate 3: analyze() accepts exactly the schema-declared input names.

      Each declared input must be addressable as a keyword argument (or the
      implementation takes ``**kwargs``), and ``analyze`` must not require
      parameters that the schema does not declare — the validating
      ``__call__`` forwards schema inputs only.



   .. py:method:: test_mock_roundtrip() -> dict[str, Any]

      Gate 4: synthetic inputs produce outputs matching the output schema.

      Runs the validating ``__call__`` with inputs generated from
      ``input_schema`` (or the pipeline's ``mock_inputs`` overrides), so
      input validation, the transform, and output validation are exercised
      together. Returns the outputs for reuse by gate 5.



   .. py:method:: test_provenance_stamped() -> None

      Gate 5: results carry the provenance stamp.

      The analyzer's :meth:`provenance` must record its identity and
      parameters, and every array/table output of a mock round-trip must
      carry that stamp as its ``provenance`` attribute.



   .. py:method:: run_mock_pipeline() -> None

      Run Gates 1–5 in sequence and raise if any gate fails.

      Intended for use in a single pytest test function when individual
      gates do not need to be reported separately.



.. py:function:: _mock_value(name: str, entry: dict[str, Any]) -> Any

   Generate a neutral synthetic value for one input schema entry.