New: get_bot function (#419)

Co-authored-by: nonebot <nonebot@users.noreply.github.com>
Co-authored-by: Ju4tCode <42488585+yanyongyu@users.noreply.github.com>

nonebot/__init__.py

@@ -132,6 +132,44 @@ def get_asgi() -> Any:
     return driver.asgi
 
 
+def get_bot(self_id: Optional[str] = None) -> Bot:
+    """
+    :说明:
+
+      当提供 self_id 时，此函数是 get_bots()[self_id] 的简写；当不提供时，返回一个 Bot。
+
+    :参数:
+
+      * ``self_id: Optional[str]``: 用来识别 Bot 的 ID
+
+    :返回:
+
+      * ``Bot``: Bot 对象
+
+    :异常:
+
+      * ``KeyError``: 对应 ID 的 Bot 不存在
+      * ``ValueError``: 全局 Driver 对象尚未初始化 (nonebot.init 尚未调用)
+      * ``ValueError``: 没有传入 ID 且没有 Bot 可用
+
+    :用法:
+
+    .. code-block:: python
+
+        assert nonebot.get_bot('12345') == nonebot.get_bots()['12345']
+
+        another_unspecified_bot = nonebot.get_bot()
+    """
+    bots = get_bots()
+    if self_id is not None:
+        return bots[self_id]
+
+    for bot in bots.values():
+        return bot
+
+    raise ValueError("There are no bots to get.")
+
+
 def get_bots() -> Dict[str, Bot]:
     """
     :说明: