annie.pages.dataset
===================

.. py:module:: annie.pages.dataset

.. autoapi-nested-parse::

   Dataset tab — define the dataset by adding data sources; see live metrics.

   Annie is dataset-agnostic: instead of fixed folder fields, you build the dataset
   from a list of **data sources** (the ``+`` box). A videos folder is the mandatory
   spine; vdet/track folders, a protagonist CSV, and any number of label CSVs
   attach to it. There is no Scan button — adding or removing a source re-scans in
   place, and every metric and Browse row updates immediately. Each source shows an
   Available / Unavailable chip and a live item count.

   Each browser tab maintains its own scan-in-progress flag and database-mode
   selection via a per-client :class:`_DatasetState` keyed by
   :attr:`nicegui.Client.id`.



Attributes
----------

.. autoapisummary::

   annie.pages.dataset.CarryAction


Classes
-------

.. autoapisummary::

   annie.pages.dataset.MetricCard
   annie.pages.dataset.LayoutCommit


Functions
---------

.. autoapisummary::

   annie.pages.dataset.metric_rows
   annie.pages.dataset.layout_from_input
   annie.pages.dataset.layout_commit
   annie.pages.dataset.layout_summary
   annie.pages.dataset.render


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

.. py:data:: CarryAction

   What saving a config should do with the progress in the currently open database.

.. py:class:: MetricCard

   One overview metric card on the Dataset tab.

   .. attribute:: title

      The card's caption.

   .. attribute:: key

      The :attr:`ScanResult.counts` key it shows.

   .. attribute:: color

      The caption colour.


.. py:function:: metric_rows(registry: annie.dataset.sources.SourceRegistry) -> list[list[MetricCard]]

   The overview cards that fit the configured sources, as rows (empty rows dropped).

   ``# videos`` is always shown; vdet and track cards appear only once that folder is a
   source, so a plain video dataset is not cluttered with face-tracking counts.

   :param registry: The configured sources.

   :returns: file counts first, then per-video coverage.
   :rtype: Rows of cards


.. py:class:: LayoutCommit

   What committing the Layout text boxes should do.

   .. attribute:: layout

      The valid layout to apply, or ``None`` when there is nothing to apply.

   .. attribute:: error

      A user-readable validation message, or ``None``.


.. py:function:: layout_from_input(pattern: str) -> annie.dataset.layout.VideoLayout

   Build and validate a :class:`VideoLayout` from the Pattern box.

   :param pattern: The pattern box (path relative to the folder, with ``{field}`` placeholders).

   :returns: The validated layout.

   :raises ValueError: With a user-readable message if the layout is unusable.


.. py:function:: layout_commit(pattern: str, current: annie.dataset.layout.VideoLayout | None) -> LayoutCommit

   Decide what to do when the Pattern box is committed (blur / Enter).

   :param pattern: The pattern box text.
   :param current: The layout already applied to the source, if any.

   :returns: ``LayoutCommit(layout=...)`` to apply a new valid layout; ``LayoutCommit(error=...)``
             for an invalid one (nothing is applied); an empty ``LayoutCommit()`` when the box
             still describes the applied layout, or is still empty (nothing to do yet).


.. py:function:: layout_summary(source: annie.dataset.sources.DataSource, scan: annie.dataset.scanning.ScanResult | None) -> str | None

   Describe what a nested layout found, from the last scan (no extra filesystem walk).

   :param source: The Videos-folder source.
   :param scan: The last scan result.

   :returns: A one-line summary such as ``"278 videos · a ×70 · b ×4 · 0 collisions · e.g. …"``,
             or ``None`` when the source has no layout or nothing was scanned.


.. py:function:: render() -> None

   Build the Dataset tab body; register per-client state.