ds_provider_mock_py_lib.dataset.engines
=======================================

.. py:module:: ds_provider_mock_py_lib.dataset.engines

.. autoapi-nested-parse::

   **File:** ``__init__.py``
   **Region:** ``ds_provider_mock_py_lib/dataset/engines``

   Dataset execution engines.



Submodules
----------

.. toctree::
   :maxdepth: 1

   /autoapi/ds_provider_mock_py_lib/dataset/engines/_read_checkpoint/index
   /autoapi/ds_provider_mock_py_lib/dataset/engines/_read_rows/index
   /autoapi/ds_provider_mock_py_lib/dataset/engines/read/index


Classes
-------

.. autoapisummary::

   ds_provider_mock_py_lib.dataset.engines.ReadEngine


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

.. py:class:: ReadEngine

   Execute mock reads including pagination, resume, and failure injection.


   .. py:attribute:: connection
      :type:  ds_provider_mock_py_lib.linked_service.mock.MockBackend


   .. py:attribute:: settings
      :type:  ds_provider_mock_py_lib.dataset.settings.MockDatasetSettings


   .. py:attribute:: dataset_name
      :type:  str


   .. py:attribute:: provider_type
      :type:  str


   .. py:attribute:: output
      :type:  pandas.DataFrame


   .. py:attribute:: checkpoint
      :type:  ds_provider_mock_py_lib.dataset.engines._read_checkpoint.Checkpoint


   .. py:attribute:: metadata
      :type:  dict[str, Any]


   .. py:attribute:: _emitted_ops
      :type:  list[str]
      :value: []



   .. py:method:: execute(checkpoint: dict[str, Any] | None = None) -> None

      Execute read flow and update ``output`` / ``checkpoint`` state.

      :param checkpoint: Existing checkpoint state to continue from.

      :raises ReadError: If settings are invalid or a wrapped backend failure occurs.
      :raises ConnectionError: If dataset-level injection is configured as a connection error.
      :raises MockBackendError: If the mock backend raises and the caller must wrap it.



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

      Raise when settings cannot fulfil a read.



   .. py:method:: _resolve_start() -> tuple[int, int, bool]

      Resolve batch, first page, and whether this call is a resume.

      :returns: ``(batch, first_page, resumed)``.

      :raises ReadError: If a stored pagination cursor cannot be decoded.



   .. py:method:: _save_pagination(*, batch: int, page: int) -> None

      Persist pagination resume state without advancing the watermark.



   .. py:method:: _assign_output(pages: list[pandas.DataFrame]) -> None

      Assign concatenated pages to ``output``, including rows already read on failure.

      :param pages: Pages collected so far in this read.



   .. py:method:: _finish_complete(*, batch: int, pages: list[pandas.DataFrame], total_pages: int, resumed: bool) -> None

      Complete a successful read of the configured scope.

      :param batch: Completed batch number written to the incremental watermark.
      :param pages: Pages collected during this read.
      :param total_pages: Page count for the current batch.
      :param resumed: Whether this call continued from a pagination cursor.



   .. py:method:: _set_metadata(*, batch: int, total_pages: int, resumed: bool) -> None

      Populate engine metadata used by ``self.operation.metadata``.

      :param batch: Batch number that was read.
      :param total_pages: Page count for the current batch.
      :param resumed: Whether this call continued from a pagination cursor.



   .. py:method:: _inject_failure(details: dict[str, Any]) -> None

      Raise the configured dataset-level contract exception.

      :param details: Page context attached to the raised exception.

      :raises ConnectionError: When ``raise_as`` is ``connection_error``.
      :raises ReadError: When ``raise_as`` is ``read_error``.