[Core] Dispatch on_red_api_tokens_update event on api keys update (#…

…3146)

* feat: dispatch `on_red_api_tokens_update` event on api keys update

* docs: add event reference in Shared API Keys docs

* chore(changelog): add tonwcrier entries

* fix: wrap dispatched api tokens in MappingProxyType

* docs: reflect change of type change to read-only Mapping

changelog.d/3134.docs.rst

@@ -0,0 +1 @@
+Add event reference for ``on_red_api_tokens_update`` event in Shared API Keys docs.

changelog.d/3134.feature.rst

@@ -0,0 +1 @@
+New event ``on_red_api_tokens_update`` is now dispatched when shared api keys for the service are updated.

docs/framework_apikeys.rst

@@ -46,3 +46,17 @@ Basic Usage
             if youtube_keys.get("api_key") is None:
                 return await ctx.send("The YouTube API key has not been set.")
             # Use the API key to access content as you normally would
+
+
+***************
+Event Reference
+***************
+
+.. function:: on_red_api_tokens_update(service_name, api_tokens)
+
+    Dispatched when service's api keys are updated.
+
+    :param service_name: Name of the service.
+    :type service_name: :class:`str`
+    :param api_tokens: New Mapping of token names to tokens. This contains api tokens that weren't changed too.
+    :type api_tokens: Mapping[:class:`str`, :class:`str`]

redbot/core/bot.py

@@ -8,6 +8,7 @@
 from importlib.machinery import ModuleSpec
 from pathlib import Path
 from typing import Optional, Union, List, Dict, NoReturn
+from types import MappingProxyType
 
 import discord
 from discord.ext.commands import when_mentioned_or
@@ -582,6 +583,7 @@ async def set_shared_api_tokens(self, service_name: str, **tokens: str):
 
         async with self._config.custom(SHARED_API_TOKENS, service_name).all() as group:
             group.update(tokens)
+        self.dispatch("red_api_tokens_update", service_name, MappingProxyType(group))
 
     async def remove_shared_api_tokens(self, service_name: str, *token_names: str):
         """