From b9de8baac4e62537586d15144fb4d94ea7a73fab Mon Sep 17 00:00:00 2001
From: midori <cleoold@gmail.com>
Date: Sun, 27 Jun 2021 02:03:54 -0400
Subject: [PATCH] New: get_bot function (#419)

Co-authored-by: nonebot <nonebot@users.noreply.github.com>
Co-authored-by: Ju4tCode <42488585+yanyongyu@users.noreply.github.com>
---
 docs/api/config.md         |  2 ++
 docs/api/drivers/README.md | 10 ++-------
 docs/api/nonebot.md        | 46 ++++++++++++++++++++++++++++++++++++++
 nonebot/__init__.py        | 38 +++++++++++++++++++++++++++++++
 4 files changed, 88 insertions(+), 8 deletions(-)

diff --git a/docs/api/config.md b/docs/api/config.md
index 4b67620b..cf7ef369 100644
--- a/docs/api/config.md
+++ b/docs/api/config.md
@@ -59,6 +59,8 @@ NoneBot 主要配置。大小写不敏感。
 
     NoneBot 运行所使用的 `Driver` 。继承自 `nonebot.driver.BaseDriver` 。
 
+    配置格式为 `<module>[:<class>]`，默认类名为 `Driver`。
+
 
 
 ### `host`
diff --git a/docs/api/drivers/README.md b/docs/api/drivers/README.md
index abce7047..057a1903 100644
--- a/docs/api/drivers/README.md
+++ b/docs/api/drivers/README.md
@@ -62,7 +62,7 @@ Driver 基类。
 
 
 
-### _abstract_ `__init__(env, config)`
+### `__init__(env, config)`
 
 
 * **参数**
@@ -164,7 +164,7 @@ Driver 基类。
 驱动专属 logger 日志记录器
 
 
-### _abstract_ `run(host=None, port=None, *args, **kwargs)`
+### _abstract_ `run(*args, **kwargs)`
 
 
 * **说明**
@@ -176,12 +176,6 @@ Driver 基类。
 * **参数**
 
     
-    * `host: Optional[str]`: 驱动绑定 IP
-
-
-    * `post: Optional[int]`: 驱动绑定端口
-
-
     * `*args`
 
 
diff --git a/docs/api/nonebot.md b/docs/api/nonebot.md
index 6ecd5e9d..b7384bf6 100644
--- a/docs/api/nonebot.md
+++ b/docs/api/nonebot.md
@@ -169,6 +169,52 @@ asgi = nonebot.get_asgi()
 ```
 
 
+## `get_bot(self_id=None)`
+
+
+* **说明**
+
+    当提供 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 可用
+
+
+
+* **用法**
+
+
+```python
+assert nonebot.get_bot('12345') == nonebot.get_bots()['12345']
+
+another_unspecified_bot = nonebot.get_bot()
+```
+
+
 ## `get_bots()`
 
 
diff --git a/nonebot/__init__.py b/nonebot/__init__.py
index 604f7326..ae0401fa 100644
--- a/nonebot/__init__.py
+++ b/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]:
     """
     :说明: