forge.alerts

Alerts an indicator declares and raises (Forge lane 6, IN5).

An alert is words an indicator wants said when something happens. This module only decides what an indicator may say and records that it said it. It cannot send anything: it imports the standard library only, and a run of the indicator, in a backtest or on a chart, just keeps a record of every alert that would have fired.

Declaring alerts Name the conditions on the class, as a list::

alerts = [fg.AlertCondition("RSI above 70", when=hot, message="{symbol} RSI {out.rsi}")]

``when`` is an output of the same class, of kind ``state`` or ``event``, written as the output attribute (``when=hot``) or its name (``when="hot"``). A ``state`` output fires on the bar it turns on, and an ``event`` output fires on every bar where it is not 0. The first bar of a run has no bar before it and never fires. The file is checked when it is saved: an unknown placeholder in a message, a ``when`` that names no output, or more than 16 conditions is refused with its line.

Raising an alert ``self.alert("RSI crossed 70")`` raises one from ``on_bar``. From ``calculate``, which sees every bar at once, say which bar: ``self.alert("RSI crossed 70", bar=i)``. ``self.alert`` is ``forge.alerts.alert``. It takes a message, a bar and a frequency, and nothing else.

How often ``bar_close`` (the default): at most one alert per bar, and only once the bar has closed. ``bar``: at most one alert per bar, the forming bar included. ``every_time``: every alert the indicator raises. ``once``: the first alert only. An uploaded indicator updates on closed bars only, so for it ``bar`` fires as ``bar_close``.

Placeholders A message may hold ``{symbol}``, ``{timeframe}``, ``{time}``, ``{open}``, ``{high}``, ``{low}``, ``{close}``, ``{price}`` (the close) and ``{out.<output>}`` for the value of one of the indicator's outputs on the bar. ``{{`` and ``}}`` write a brace. A message is at most 500 characters, and the text that goes out is cut to 1 000.

Limits One alert fires at most 2 times a second and 10 times a minute. An alert that hits a limit in 3 different minutes within 10 minutes is muted for an hour. One run keeps its first 500 alerts. On history the clock is each bar's close time. One person's alerts together fire at most 5 a second and 60 a minute.

Who is told Only the person who armed the alert. An indicator's code can never name anyone, and a published indicator never notifies the people who view it.

In a test Nothing is sent. A backtest writes "Alert would have fired: ..." to the run log and keeps the records with the run result. A chart draws each alert that would have fired as a marker on its bar.