alerts
======

.. py:module:: alerts

.. autoapi-nested-parse::

   Warnings (e.g. NINA) that replace the tiles while one is active.

   Data sources report active warnings from the configured source IDs as
   [{"id", "title", "text", "severity", "sender", "expires"}]: "severity" is
   one of SEVERITY_LABELS or "", "expires" an ISO 8601 time or None.

   The source IDs to watch are stored in ALERTS_FILE (edited through the web
   interface); config.DEFAULT_ALERTS applies until then.



Attributes
----------

.. autoapisummary::

   alerts.ALERTS_FILE
   alerts.MAX_SOURCES
   alerts.MAX_SOURCE
   alerts.SEVERITY_LABELS
   alerts.CACHED_TITLE
   alerts.CACHED_TEXT
   alerts.CACHED_MORE


Functions
---------

.. autoapisummary::

   alerts.validate
   alerts.load
   alerts.save
   alerts.by_severity
   alerts.footer
   alerts.for_cache
   alerts.not_expired


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

.. py:data:: ALERTS_FILE
   :value: 'alerts.json'


.. py:data:: MAX_SOURCES
   :value: 20


.. py:data:: MAX_SOURCE
   :value: 100


.. py:data:: SEVERITY_LABELS
   :value: (('extreme', 'extrem'), ('severe', 'hoch'), ('moderate', 'mittel'), ('minor', 'gering'))


.. py:function:: validate(sources)

   Checked copy of the source ID list; ValueError with a German message.


.. py:function:: load(default, path=ALERTS_FILE)

   Load the saved warning sources.

   :param default: Sources to use if none are saved or the file is invalid.
   :param path: File to read.

   :returns: The validated list of source IDs.


.. py:function:: save(sources, path=ALERTS_FILE)

   Validate and store the warning sources.

   The file is written under a temporary name and renamed, so a power cut
   keeps the old list.

   :param sources: List of source IDs.
   :param path: File to write.

   :returns: The stored, validated list.

   :raises ValueError: If `sources` is invalid (message in German).


.. py:function:: by_severity(alerts)

   Active alerts, most severe first (stable for equal severity).


.. py:function:: footer(alert)

   One line of facts, e.g. "Warnstufe hoch · bis 26.09. 18:00 · DWD".


.. py:data:: CACHED_TITLE
   :value: 120


.. py:data:: CACHED_TEXT
   :value: 400


.. py:data:: CACHED_MORE
   :value: 5


.. py:function:: for_cache(active)

   Shrink active alerts so that they fit into RTC memory.

   The most severe alert is kept with shortened texts, the others only
   as placeholders so that the layout can still count them ("+N weitere").

   :param active: Active alerts, most severe first.

   :returns: The shortened list.


.. py:function:: not_expired(cached, now_utc)

   Drop cached alerts that have expired.

   Used while the data source cannot be reached.

   :param cached: Alerts from the RTC state, or None.
   :param now_utc: The current time as a `time.gmtime()` tuple.

   :returns: The alerts without expiry or with an expiry after `now_utc`.