Add documentation and clarity for send_msg

docs/strategy-customization.md

@@ -731,6 +731,23 @@ if self.dp:
 !!! Warning "Warning about backtesting"
     This method will always return up-to-date values - so usage during backtesting / hyperopt will lead to wrong results.
 
+### Send Notification
+
+The dataprovider `.send_msg()` function allows you to send custom notifications from your strategy.
+Identical notifications will only be sent once per candle, unless the 2nd argument (`always_send`) is set to True.
+
+``` python
+    self.dp.send_msg(f"{metadata['pair']} just got hot!")
+
+    # Force send this notification, avoid caching (Please read warning below!)
+    self.dp.send_msg(f"{metadata['pair']} just got hot!", always_send=True)
+```
+
+Notifications will only be sent in trading modes (Live/Dry-run) - so this method can be called without conditions for backtesting.
+
+!!! Warning "Spamming"
+    You can spam yourself pretty good by setting `always_send=True` in this method. Use this with great care and only in conditions you know will not happen throughout a candle to avoid a message every 5 seconds.
+
 ### Complete Data-provider sample
 
 ```python

docs/telegram-usage.md

@@ -98,6 +98,7 @@ Example configuration showing the different settings:
         "exit_fill": "off",
         "protection_trigger": "off",
         "protection_trigger_global": "on",
+        "strategy_msg": "off",
         "show_candle": "off"
     },
     "reload": true,
@@ -109,7 +110,8 @@ Example configuration showing the different settings:
 `exit` notifications are sent when the order is placed, while `exit_fill` notifications are sent when the order is filled on the exchange.
 `*_fill` notifications are off by default and must be explicitly enabled.
 `protection_trigger` notifications are sent when a protection triggers and `protection_trigger_global` notifications trigger when global protections are triggered.
-`show_candle` - show candle values as part of entry/exit messages. Only possible value is "ohlc".
+`strategy_msg` - Receive notifications from the strategy, sent via `self.dp.send_msg()` from the strategy [more details](strategy-customization.md#send-notification).
+`show_candle` - show candle values as part of entry/exit messages. Only possible values are `"ohlc"` or `"off"`.
 
 `balance_dust_level` will define what the `/balance` command takes as "dust" - Currencies with a balance below this will be shown.
 `reload` allows you to disable reload-buttons on selected messages.

freqtrade/constants.py

@@ -317,6 +317,10 @@ CONF_SCHEMA = {
                             'type': 'string',
                             'enum': ['off', 'ohlc'],
                         },
+                        'strategy_msg': {
+                            'type': 'string',
+                            'enum': TELEGRAM_SETTING_OPTIONS,
+                        },
                     }
                 },
                 'reload': {'type': 'boolean'},

freqtrade/data/dataprovider.py

@@ -36,8 +36,9 @@ class DataProvider:
         self.__slice_index: Optional[int] = None
         self.__cached_pairs_backtesting: Dict[PairWithTimeframe, DataFrame] = {}
         self._msg_queue: deque = deque()
+
         self.__msg_cache = PeriodicCache(
-            maxsize=1000, ttl=timeframe_to_seconds(self._config['timeframe']))
+            maxsize=1000, ttl=timeframe_to_seconds(self._config.get('timeframe', '1h')))
 
     def _set_dataframe_max_index(self, limit_index: int):
         """
@@ -271,9 +272,10 @@ class DataProvider:
             raise OperationalException(NO_EXCHANGE_EXCEPTION)
         return self._exchange.fetch_l2_order_book(pair, maximum)
 
-    def send_msg(self, message: str, always_send: bool = False) -> None:
+    def send_msg(self, message: str, *, always_send: bool = False) -> None:
         """
-        TODO: Document me
+        Send custom RPC Notifications from your bot.
+        Will not send any bot in modes other than Dry-run or Live.
         :param message: Message to be sent. Must be below 4096.
         :param always_send: If False, will send the message only once per candle, and surpress
                             identical messages.