diff --git a/docs/api/README.md b/docs/api/README.md new file mode 100644 index 00000000..c9dd2074 --- /dev/null +++ b/docs/api/README.md @@ -0,0 +1,13 @@ +# NoneBot Api Reference + + +* **模块索引** + + + * [nonebot](nonebot.html) + + + * [nonebot.typing](typing.html) + + + * [nonebot.config](config.html) diff --git a/docs/api/config.md b/docs/api/config.md new file mode 100644 index 00000000..6f450715 --- /dev/null +++ b/docs/api/config.md @@ -0,0 +1,32 @@ +# NoneBot.config 模块 + + +### _class_ `BaseConfig(_env_file='', _env_file_encoding=None)` + +基类:`pydantic.env_settings.BaseSettings` + + +### _class_ `Config(_env_file='', _env_file_encoding=None, *, driver='nonebot.drivers.fastapi', host=IPv4Address('127.0.0.1'), port=8080, secret=None, debug=False, api_root={}, api_timeout=60.0, access_token=None, superusers={}, nickname='', command_start={'/'}, command_sep={'.'}, session_expire_timeout=datetime.timedelta(seconds=120), **values)` + +基类:[`nonebot.config.BaseConfig`](#nonebot.config.BaseConfig) + +NoneBot Config Object + +configs: + +### driver + + +* 类型: str + + +* 默认值: "nonebot.drivers.fastapi" + + +* 说明: +nonebot 运行使用后端框架封装 Driver 。继承自 nonebot.driver.BaseDriver 。 + + +### _class_ `Env(_env_file='', _env_file_encoding=None, *, environment='prod')` + +基类:`pydantic.env_settings.BaseSettings` diff --git a/docs/api/nonebot.md b/docs/api/nonebot.md new file mode 100644 index 00000000..0d69f010 --- /dev/null +++ b/docs/api/nonebot.md @@ -0,0 +1,203 @@ +# NoneBot 模块 + + +### `get_app()` + + +* **说明** + + 获取全局 Driver 对应 Server App 对象。 + + + +* **返回** + + + * `Any`: Server App 对象 + + + +* **异常** + + + * `ValueError`: 全局 Driver 对象尚未初始化 (nonebot.init 尚未调用) + + + +* **用法** + + +```python +app = nonebot.get_app() +``` + + +### `get_asgi()` + + +* **说明** + + 获取全局 Driver 对应 Asgi 对象。 + + + +* **返回** + + + * `Any`: Asgi 对象 + + + +* **异常** + + + * `ValueError`: 全局 Driver 对象尚未初始化 (nonebot.init 尚未调用) + + + +* **用法** + + +```python +asgi = nonebot.get_asgi() +``` + + +### `get_bots()` + + +* **说明** + + 获取所有通过 ws 连接 NoneBot 的 Bot 对象。 + + + +* **返回** + + + * `Dict[str, Bot]`: 一个以字符串 ID 为键,Bot 对象为值的字典 + + + +* **异常** + + + * `ValueError`: 全局 Driver 对象尚未初始化 (nonebot.init 尚未调用) + + + +* **用法** + + +```python +bots = nonebot.get_bots() +``` + + +### `get_driver()` + + +* **说明** + + 获取全局 Driver 对象。可用于在计划任务的回调中获取当前 Driver 对象。 + + + +* **返回** + + + * `Driver`: 全局 Driver 对象 + + + +* **异常** + + + * `ValueError`: 全局 Driver 对象尚未初始化 (nonebot.init 尚未调用) + + + +* **用法** + + +```python +driver = nonebot.get_driver() +``` + + +### `init(*, _env_file=None, **kwargs)` + + +* **说明** + + 初始化 NoneBot 以及 全局 Driver 对象。 + + NoneBot 将会从 .env 文件中读取环境信息,并使用相应的 env 文件配置。 + + 你也可以传入自定义的 _env_file 来指定 NoneBot 从该文件读取配置。 + + + +* **参数** + + + * `_env_file: Optional[str]`: 配置文件名,默认从 .env.{env_name} 中读取配置 + + + * `**kwargs`: 任意变量,将会存储到 Config 对象里 + + + +* **返回** + + + * None + + + +* **用法** + + +```python +nonebot.init(database=Database(...)) +``` + + +### `run(host=None, port=None, *args, **kwargs)` + + +* **说明** + + 启动 NoneBot,即运行全局 Driver 对象。 + + + +* **参数** + + + * `host: Optional[str]`: 主机名/IP,若不传入则使用配置文件中指定的值 + + + * `port: Optional[int]`: 端口,若不传入则使用配置文件中指定的值 + + + * `*args`: 传入 Driver.run 的位置参数 + + + * `**kwargs`: 传入 Driver.run 的命名参数 + + + +* **返回** + + + * None + + + +* **用法** + + +```python +nonebot.run(host="127.0.0.1", port=8080) +``` diff --git a/docs/api/typing.md b/docs/api/typing.md new file mode 100644 index 00000000..e9e4987a --- /dev/null +++ b/docs/api/typing.md @@ -0,0 +1,128 @@ +# NoneBot.typing 模块 + +## 类型 + +下面的文档中,「类型」部分使用 Python 的 Type Hint 语法,见 [PEP 484](https://www.python.org/dev/peps/pep-0484/)、[PEP 526](https://www.python.org/dev/peps/pep-0526/) 和 [typing](https://docs.python.org/3/library/typing.html)。 + +除了 Python 内置的类型,下面还出现了如下 NoneBot 自定类型,实际上它们是 Python 内置类型的别名。 + +以下类型均可从 nonebot.typing 模块导入。 + + +### `Bot` + + +* **类型** + + BaseBot + + + +* **说明** + + 所有 Bot 的基类。 + + +alias of TypeVar('Bot') + + +### `Driver` + + +* **类型** + + BaseDriver + + + +* **说明** + + 所有 Driver 的基类。 + + +alias of TypeVar('Driver') + + +### `Event` + + +* **类型** + + BaseEvent + + + +* **说明** + + 所有 Event 的基类。 + + +alias of TypeVar('Event') + + +### `Message` + + +* **类型** + + BaseMessage + + + +* **说明** + + 所有 Message 的基类。 + + +alias of TypeVar('Message') + + +### `MessageSegment` + + +* **类型** + + BaseMessageSegment + + + +* **说明** + + 所有 MessageSegment 的基类。 + + +alias of TypeVar('MessageSegment') + + +### `PreProcessor` + + +* **类型** + + Callable[[Bot, Event, dict], Union[Awaitable[None], Awaitable[NoReturn]]] + + + +* **说明** + + 消息预处理函数 PreProcessor 类型 + + +alias of Callable[[Bot, Event, dict], Union[Awaitable[None], Awaitable[NoReturn]]] + + +### `WebSocket` + + +* **类型** + + BaseWebSocket + + + +* **说明** + + 所有 WebSocket 的基类。 + + +alias of TypeVar('WebSocket') diff --git a/docs_build/conf.py b/docs_build/conf.py index 252393fc..0afee3b1 100644 --- a/docs_build/conf.py +++ b/docs_build/conf.py @@ -10,13 +10,9 @@ # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. # -import os -import sys -# sys.path.insert( -# 0, -# os.path.join(os.path.abspath(os.path.dirname(os.path.dirname(__file__))), -# "nonebot")) -sys.path.insert(0, os.path.abspath(os.path.dirname(os.path.dirname(__file__)))) +# import os +# import sys +# sys.path.insert(0, os.path.abspath(os.path.dirname(os.path.dirname(__file__)))) # -- Project information ----------------------------------------------------- diff --git a/docs_build/config.rst b/docs_build/config.rst new file mode 100644 index 00000000..c34935d8 --- /dev/null +++ b/docs_build/config.rst @@ -0,0 +1,6 @@ +NoneBot.config 模块 +=================== + +.. automodule:: nonebot.config + :members: + :show-inheritance: diff --git a/docs_build/nonebot.rst b/docs_build/nonebot.rst index d1aba847..f921b3a5 100644 --- a/docs_build/nonebot.rst +++ b/docs_build/nonebot.rst @@ -3,5 +3,4 @@ NoneBot 模块 .. automodule:: nonebot :members: - :undoc-members: :show-inheritance: diff --git a/docs_build/typing.rst b/docs_build/typing.rst new file mode 100644 index 00000000..8b927eaa --- /dev/null +++ b/docs_build/typing.rst @@ -0,0 +1,6 @@ +NoneBot.typing 模块 +=================== + +.. automodule:: nonebot.typing + :members: + :show-inheritance: diff --git a/nonebot/__init__.py b/nonebot/__init__.py index c996affc..117dda4c 100644 --- a/nonebot/__init__.py +++ b/nonebot/__init__.py @@ -10,19 +10,19 @@ _driver: Optional[Driver] = None def get_driver() -> Union[NoReturn, Driver]: """ - - **说明**: + :说明: 获取全局 Driver 对象。可用于在计划任务的回调中获取当前 Driver 对象。 - - **返回**: + :返回: * ``Driver``: 全局 Driver 对象 - - **异常**: + :异常: * ``ValueError``: 全局 Driver 对象尚未初始化 (nonebot.init 尚未调用) - - **用法**: + :用法: .. code-block:: python @@ -36,19 +36,19 @@ def get_driver() -> Union[NoReturn, Driver]: def get_app(): """ - - **说明**: + :说明: 获取全局 Driver 对应 Server App 对象。 - - **返回**: + :返回: * ``Any``: Server App 对象 - - **异常**: + :异常: * ``ValueError``: 全局 Driver 对象尚未初始化 (nonebot.init 尚未调用) - - **用法**: + :用法: .. code-block:: python @@ -61,19 +61,19 @@ def get_app(): def get_asgi(): """ - - **说明**: + :说明: 获取全局 Driver 对应 Asgi 对象。 - - **返回**: + :返回: * ``Any``: Asgi 对象 - - **异常**: + :异常: * ``ValueError``: 全局 Driver 对象尚未初始化 (nonebot.init 尚未调用) - - **用法**: + :用法: .. code-block:: python @@ -86,19 +86,19 @@ def get_asgi(): def get_bots() -> Dict[str, Bot]: """ - - **说明**: + :说明: 获取所有通过 ws 连接 NoneBot 的 Bot 对象。 - - **返回**: + :返回: * ``Dict[str, Bot]``: 一个以字符串 ID 为键,Bot 对象为值的字典 - - **异常**: + :异常: * ``ValueError``: 全局 Driver 对象尚未初始化 (nonebot.init 尚未调用) - - **用法**: + :用法: .. code-block:: python @@ -121,22 +121,24 @@ except ImportError: def init(*, _env_file: Optional[str] = None, **kwargs): """ - - **说明:** + :说明: 初始化 NoneBot 以及 全局 Driver 对象。 + NoneBot 将会从 .env 文件中读取环境信息,并使用相应的 env 文件配置。 + 你也可以传入自定义的 _env_file 来指定 NoneBot 从该文件读取配置。 - - **参数:** + :参数: * ``_env_file: Optional[str]``: 配置文件名,默认从 .env.{env_name} 中读取配置 * ``**kwargs``: 任意变量,将会存储到 Config 对象里 - - **返回:** + :返回: - `None` - - **用法:** + :用法: .. code-block:: python @@ -168,22 +170,22 @@ def run(host: Optional[str] = None, *args, **kwargs): """ - - **说明:** + :说明: 启动 NoneBot,即运行全局 Driver 对象。 - - **参数:** + :参数: * ``host: Optional[str]``: 主机名/IP,若不传入则使用配置文件中指定的值 * ``port: Optional[int]``: 端口,若不传入则使用配置文件中指定的值 * ``*args``: 传入 Driver.run 的位置参数 * ``**kwargs``: 传入 Driver.run 的命名参数 - - **返回:** + :返回: - `None` - - **用法:** + :用法: .. code-block:: python diff --git a/nonebot/typing.py b/nonebot/typing.py index 74b0345e..78418cf7 100644 --- a/nonebot/typing.py +++ b/nonebot/typing.py @@ -1,5 +1,24 @@ #!/usr/bin/env python3 # -*- coding: utf-8 -*- +""" +类型 +==== + +下面的文档中,「类型」部分使用 Python 的 Type Hint 语法,见 `PEP 484`_、`PEP 526`_ 和 `typing`_。 + +除了 Python 内置的类型,下面还出现了如下 NoneBot 自定类型,实际上它们是 Python 内置类型的别名。 + +以下类型均可从 nonebot.typing 模块导入。 + +.. _PEP 484: + https://www.python.org/dev/peps/pep-0484/ + +.. _PEP 526: + https://www.python.org/dev/peps/pep-0526/ + +.. _typing: + https://docs.python.org/3/library/typing.html +""" from types import ModuleType from typing import NoReturn, TYPE_CHECKING @@ -26,15 +45,64 @@ def overrides(InterfaceClass: object): Driver = TypeVar("Driver", bound="BaseDriver") +""" +:类型: `BaseDriver` + +:说明: + + 所有 Driver 的基类。 +""" WebSocket = TypeVar("WebSocket", bound="BaseWebSocket") +""" +:类型: `BaseWebSocket` + +:说明: + + 所有 WebSocket 的基类。 +""" Bot = TypeVar("Bot", bound="BaseBot") +""" +:类型: `BaseBot` + +:说明: + + 所有 Bot 的基类。 +""" Event = TypeVar("Event", bound="BaseEvent") +""" +:类型: `BaseEvent` + +:说明: + + 所有 Event 的基类。 +""" Message = TypeVar("Message", bound="BaseMessage") +""" +:类型: `BaseMessage` + +:说明: + + 所有 Message 的基类。 +""" MessageSegment = TypeVar("MessageSegment", bound="BaseMessageSegment") +""" +:类型: `BaseMessageSegment` + +:说明: + + 所有 MessageSegment 的基类。 +""" PreProcessor = Callable[[Bot, Event, dict], Union[Awaitable[None], Awaitable[NoReturn]]] +""" +:类型: `Callable[[Bot, Event, dict], Union[Awaitable[None], Awaitable[NoReturn]]]` + +:说明: + + 消息预处理函数 PreProcessor 类型 +""" Matcher = TypeVar("Matcher", bound="MatcherClass") Handler = Callable[[Bot, Event, dict], Union[Awaitable[None], diff --git a/poetry.lock b/poetry.lock index de883bca..07733deb 100644 --- a/poetry.lock +++ b/poetry.lock @@ -600,10 +600,9 @@ unify = "*" yapf = "*" [package.source] -reference = "88a68ed340013067a1c673bdf7541680c581fa60" +reference = "b7ca9332c2e4c5e50110d6477dd28821c74da778" type = "git" url = "https://github.com/nonebot/sphinx-markdown-builder.git" - [[package]] category = "dev" description = "sphinxcontrib-applehelp is a sphinx extension which outputs Apple help books"