pdstools.utils.streamlit_utils
==============================

.. py:module:: pdstools.utils.streamlit_utils


Functions
---------

.. autoapisummary::

   pdstools.utils.streamlit_utils.is_launcher_mode
   pdstools.utils.streamlit_utils.set_active_app
   pdstools.utils.streamlit_utils.standard_page_config
   pdstools.utils.streamlit_utils.show_sidebar_branding
   pdstools.utils.streamlit_utils.show_version_header
   pdstools.utils.streamlit_utils.ensure_session_data
   pdstools.utils.streamlit_utils.get_data_path
   pdstools.utils.streamlit_utils.get_sample_limit
   pdstools.utils.streamlit_utils.get_filter_specs
   pdstools.utils.streamlit_utils.get_temp_dir
   pdstools.utils.streamlit_utils.get_full_embed
   pdstools.utils.streamlit_utils.parse_sample_spec
   pdstools.utils.streamlit_utils.get_current_index
   pdstools.utils.streamlit_utils.cached_sample
   pdstools.utils.streamlit_utils.cached_datamart
   pdstools.utils.streamlit_utils.cached_sample_prediction
   pdstools.utils.streamlit_utils.cached_prediction_table
   pdstools.utils.streamlit_utils.model_selection_df
   pdstools.utils.streamlit_utils.filter_dataframe
   pdstools.utils.streamlit_utils.model_and_row_counts
   pdstools.utils.streamlit_utils.convert_df
   pdstools.utils.streamlit_utils.st_get_latest_pdstools_version
   pdstools.utils.streamlit_utils.show_about_page


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

.. py:function:: is_launcher_mode() -> bool

   True when the app is running inside the cross-app launcher.

   The CLI sets ``PDSTOOLS_LAUNCHER_MODE=1`` when invoking the launcher
   so per-app helpers (sidebar branding, navigation) can adapt their
   behaviour without each call site needing to know.


.. py:function:: set_active_app(app_key: str) -> None

   Mark the named app as currently active in the launcher sidebar.

   Each app's home page calls this on render. In launcher mode the
   cross-app entry script reads the flag to decide which app's
   sub-pages to register in ``st.navigation``, keeping the sidebar
   short until the user has actually entered an app. A no-op (other
   than the session_state write) in standalone tool launches.

   Triggers ``st.rerun()`` when the active app actually changes so
   the new sub-pages appear in the sidebar without a manual click.


.. py:function:: standard_page_config(page_title: str, layout: Literal['centered', 'wide'] = 'wide', **kwargs)

   Apply a consistent ``st.set_page_config`` across all pdstools apps.

   Idempotent: when called more than once in the same script run (e.g. an
   ``st.navigation()`` entry script calls it before routing, and the routed
   page calls it again), the second call is a no-op rather than the
   ``StreamlitAPIException`` Streamlit normally raises. This lets the same
   page module work both standalone (direct ``AppTest.from_file`` /
   ``streamlit run pages/X.py``) and inside a navigation router.

   :param page_title: The browser-tab title for the page.
   :type page_title: str
   :param layout: Streamlit layout mode.
   :type layout: str, default "wide"
   :param \*\*kwargs: Extra keyword arguments forwarded to ``st.set_page_config``.


.. py:function:: show_sidebar_branding(title: str)

   Display the Pega logo and an app title at the top of the sidebar.

   Uses ``st.logo`` for the logo and CSS injection for the title, so both
   render above the page navigation. Call once from the Home page; sub-pages
   re-apply automatically via ``standard_page_config`` or ``ensure_data``.

   In launcher mode (``PDSTOOLS_LAUNCHER_MODE=1``) the brand is forced to
   ``"pdstools"`` and the supplied *title* is rendered as a subtitle, so
   every page in the multi-app launcher shows a consistent top-level brand
   even when the active sub-app re-applies its own title.

   :param title: Application title shown below the logo in the sidebar.
   :type title: str


.. py:function:: show_version_header(check_latest: bool = True)

   Display the pdstools version, an upgrade hint, and optionally a staleness warning.

   :param check_latest: If *True*, queries PyPI for the latest version and shows an upgrade
                        warning when the installed version is outdated.
   :type check_latest: bool, default True


.. py:function:: ensure_session_data(key: str, message: str | None = None)

   Guard that stops page execution when *key* is missing from session state.

   :param key: The ``st.session_state`` key to check.
   :type key: str
   :param message: Custom warning text. Falls back to a generic "Please load data on the Home page."
   :type message: str or None


.. py:function:: get_data_path() -> str | None

   Return the data path set via ``--data-path`` CLI flag.

   Returns ``None`` when no path was configured.


.. py:function:: get_sample_limit() -> str | None

   Return the raw sample limit string set via ``--sample`` CLI flag.

   Returns ``None`` when no sampling was requested.


.. py:function:: get_filter_specs() -> list[str] | None

   Return the filter specs set via ``--filter`` CLI flags.

   Returns ``None`` when no filters were configured.


.. py:function:: get_temp_dir() -> str | None

   Return the temp directory set via ``--temp-dir`` CLI flag.

   Returns ``None`` when no temp directory was configured.


.. py:function:: get_full_embed() -> bool | None

   Return the full-embed setting set via ``--full-embed`` / ``--no-full-embed`` CLI flag.

   Returns ``None`` when the flag was not provided (caller should apply its
   own default).


.. py:function:: parse_sample_spec(value: str) -> dict[str, int | float]

   Parse a ``--sample`` flag value into keyword arguments.

   Supports absolute counts (``"100000"``), percentages (``"10%"``),
   and human-readable notation (``"100k"``, ``"1M"``).

   :returns: Either ``{"n": <int>}`` or ``{"fraction": <float>}``.
   :rtype: dict


.. py:function:: get_current_index(options, key, default=0)

   Get index from session state if key exists and value is in options, else return default.


.. py:function:: cached_sample()

   Cached sample.


.. py:function:: cached_datamart(**kwargs)

   Load ADMDatamart with caching.

   :param \*\*kwargs: Arguments passed to ADMDatamart.from_ds_export


.. py:function:: cached_sample_prediction()

   Cached sample prediction.


.. py:function:: cached_prediction_table(**kwargs)

   Load Prediction with caching.

   :param \*\*kwargs: Arguments passed to Prediction.from_ds_export


.. py:function:: model_selection_df(df: polars.LazyFrame, context_keys: list)

   Model selection df.


.. py:function:: filter_dataframe(df: polars.LazyFrame, schema: dict | None = None, queries: list[polars.Expr] | None = None) -> list[polars.Expr]

   Adds a UI on top of a dataframe to let viewers filter columns

   :param df: Original dataframe
   :type df: pl.LazyFrame
   :param schema: Optional column-name to dtype mapping used to pick the right filter
                  widget per column. Inferred from ``df`` when not given.
   :type schema: dict, optional
   :param queries: Existing filter expressions to append to, by default None
   :type queries: list[pl.Expr], optional

   :returns: Filter expressions collected from the UI.
   :rtype: list[pl.Expr]


.. py:function:: model_and_row_counts(df: pdstools.utils.types.ANY_FRAME)

   Returns unique model id count and row count from a dataframe

   :param df: The input dataframe
   :type df: Union[pl.DataFrame, pl.LazyFrame]

   :returns: unique model count
             row count
   :rtype: Tuple[int, int]


.. py:function:: convert_df(df)

   Convert df.


.. py:function:: st_get_latest_pdstools_version()

   St get latest pdstools version.


.. py:function:: show_about_page()

   Render a standardised About page with version and dependency information.

   Mirrors the Credits section of the Quarto ADM Health Check report.
   Call this from a Streamlit page to display pdstools version info,
   platform details, and an expandable dependency listing.