add nonebot.typing docs

This commit is contained in:
yanyongyu 2020-08-19 20:29:37 +08:00
parent e523aa8d89
commit 5e3d1c76cc
11 changed files with 486 additions and 34 deletions

13
docs/api/README.md Normal file
View File

@ -0,0 +1,13 @@
# NoneBot Api Reference
* **模块索引**
* [nonebot](nonebot.html)
* [nonebot.typing](typing.html)
* [nonebot.config](config.html)

32
docs/api/config.md Normal file
View File

@ -0,0 +1,32 @@
# NoneBot.config 模块
### _class_ `BaseConfig(_env_file='<objectobject>', _env_file_encoding=None)`
基类:`pydantic.env_settings.BaseSettings`
### _class_ `Config(_env_file='<objectobject>', _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='<objectobject>', _env_file_encoding=None, *, environment='prod')`
基类:`pydantic.env_settings.BaseSettings`

203
docs/api/nonebot.md Normal file
View File

@ -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)
```

128
docs/api/typing.md Normal file
View File

@ -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')

View File

@ -10,13 +10,9 @@
# add these directories to sys.path here. If the directory is relative to the # 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. # documentation root, use os.path.abspath to make it absolute, like shown here.
# #
import os # import os
import sys # import sys
# sys.path.insert( # sys.path.insert(0, os.path.abspath(os.path.dirname(os.path.dirname(__file__))))
# 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__))))
# -- Project information ----------------------------------------------------- # -- Project information -----------------------------------------------------

6
docs_build/config.rst Normal file
View File

@ -0,0 +1,6 @@
NoneBot.config 模块
===================
.. automodule:: nonebot.config
:members:
:show-inheritance:

View File

@ -3,5 +3,4 @@ NoneBot 模块
.. automodule:: nonebot .. automodule:: nonebot
:members: :members:
:undoc-members:
:show-inheritance: :show-inheritance:

6
docs_build/typing.rst Normal file
View File

@ -0,0 +1,6 @@
NoneBot.typing 模块
===================
.. automodule:: nonebot.typing
:members:
:show-inheritance:

View File

@ -10,19 +10,19 @@ _driver: Optional[Driver] = None
def get_driver() -> Union[NoReturn, Driver]: def get_driver() -> Union[NoReturn, Driver]:
""" """
- **说明**: :说明:
获取全局 Driver 对象可用于在计划任务的回调中获取当前 Driver 对象 获取全局 Driver 对象可用于在计划任务的回调中获取当前 Driver 对象
- **返回**: :返回:
* ``Driver``: 全局 Driver 对象 * ``Driver``: 全局 Driver 对象
- **异常**: :异常:
* ``ValueError``: 全局 Driver 对象尚未初始化 (nonebot.init 尚未调用) * ``ValueError``: 全局 Driver 对象尚未初始化 (nonebot.init 尚未调用)
- **用法**: :用法:
.. code-block:: python .. code-block:: python
@ -36,19 +36,19 @@ def get_driver() -> Union[NoReturn, Driver]:
def get_app(): def get_app():
""" """
- **说明**: :说明:
获取全局 Driver 对应 Server App 对象 获取全局 Driver 对应 Server App 对象
- **返回**: :返回:
* ``Any``: Server App 对象 * ``Any``: Server App 对象
- **异常**: :异常:
* ``ValueError``: 全局 Driver 对象尚未初始化 (nonebot.init 尚未调用) * ``ValueError``: 全局 Driver 对象尚未初始化 (nonebot.init 尚未调用)
- **用法**: :用法:
.. code-block:: python .. code-block:: python
@ -61,19 +61,19 @@ def get_app():
def get_asgi(): def get_asgi():
""" """
- **说明**: :说明:
获取全局 Driver 对应 Asgi 对象 获取全局 Driver 对应 Asgi 对象
- **返回**: :返回:
* ``Any``: Asgi 对象 * ``Any``: Asgi 对象
- **异常**: :异常:
* ``ValueError``: 全局 Driver 对象尚未初始化 (nonebot.init 尚未调用) * ``ValueError``: 全局 Driver 对象尚未初始化 (nonebot.init 尚未调用)
- **用法**: :用法:
.. code-block:: python .. code-block:: python
@ -86,19 +86,19 @@ def get_asgi():
def get_bots() -> Dict[str, Bot]: def get_bots() -> Dict[str, Bot]:
""" """
- **说明**: :说明:
获取所有通过 ws 连接 NoneBot Bot 对象 获取所有通过 ws 连接 NoneBot Bot 对象
- **返回**: :返回:
* ``Dict[str, Bot]``: 一个以字符串 ID 为键Bot 对象为值的字典 * ``Dict[str, Bot]``: 一个以字符串 ID 为键Bot 对象为值的字典
- **异常**: :异常:
* ``ValueError``: 全局 Driver 对象尚未初始化 (nonebot.init 尚未调用) * ``ValueError``: 全局 Driver 对象尚未初始化 (nonebot.init 尚未调用)
- **用法**: :用法:
.. code-block:: python .. code-block:: python
@ -121,22 +121,24 @@ except ImportError:
def init(*, _env_file: Optional[str] = None, **kwargs): def init(*, _env_file: Optional[str] = None, **kwargs):
""" """
- **说明:** :说明:
初始化 NoneBot 以及 全局 Driver 对象 初始化 NoneBot 以及 全局 Driver 对象
NoneBot 将会从 .env 文件中读取环境信息并使用相应的 env 文件配置 NoneBot 将会从 .env 文件中读取环境信息并使用相应的 env 文件配置
你也可以传入自定义的 _env_file 来指定 NoneBot 从该文件读取配置 你也可以传入自定义的 _env_file 来指定 NoneBot 从该文件读取配置
- **参数:** :参数:
* ``_env_file: Optional[str]``: 配置文件名默认从 .env.{env_name} 中读取配置 * ``_env_file: Optional[str]``: 配置文件名默认从 .env.{env_name} 中读取配置
* ``**kwargs``: 任意变量将会存储到 Config 对象里 * ``**kwargs``: 任意变量将会存储到 Config 对象里
- **返回:** :返回:
- `None` - `None`
- **用法:** :用法:
.. code-block:: python .. code-block:: python
@ -168,22 +170,22 @@ def run(host: Optional[str] = None,
*args, *args,
**kwargs): **kwargs):
""" """
- **说明:** :说明:
启动 NoneBot即运行全局 Driver 对象 启动 NoneBot即运行全局 Driver 对象
- **参数:** :参数:
* ``host: Optional[str]``: 主机名IP若不传入则使用配置文件中指定的值 * ``host: Optional[str]``: 主机名IP若不传入则使用配置文件中指定的值
* ``port: Optional[int]``: 端口若不传入则使用配置文件中指定的值 * ``port: Optional[int]``: 端口若不传入则使用配置文件中指定的值
* ``*args``: 传入 Driver.run 的位置参数 * ``*args``: 传入 Driver.run 的位置参数
* ``**kwargs``: 传入 Driver.run 的命名参数 * ``**kwargs``: 传入 Driver.run 的命名参数
- **返回:** :返回:
- `None` - `None`
- **用法:** :用法:
.. code-block:: python .. code-block:: python

View File

@ -1,5 +1,24 @@
#!/usr/bin/env python3 #!/usr/bin/env python3
# -*- coding: utf-8 -*- # -*- 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 types import ModuleType
from typing import NoReturn, TYPE_CHECKING from typing import NoReturn, TYPE_CHECKING
@ -26,15 +45,64 @@ def overrides(InterfaceClass: object):
Driver = TypeVar("Driver", bound="BaseDriver") Driver = TypeVar("Driver", bound="BaseDriver")
"""
:类型: `BaseDriver`
:说明:
所有 Driver 的基类
"""
WebSocket = TypeVar("WebSocket", bound="BaseWebSocket") WebSocket = TypeVar("WebSocket", bound="BaseWebSocket")
"""
:类型: `BaseWebSocket`
:说明:
所有 WebSocket 的基类
"""
Bot = TypeVar("Bot", bound="BaseBot") Bot = TypeVar("Bot", bound="BaseBot")
"""
:类型: `BaseBot`
:说明:
所有 Bot 的基类
"""
Event = TypeVar("Event", bound="BaseEvent") Event = TypeVar("Event", bound="BaseEvent")
"""
:类型: `BaseEvent`
:说明:
所有 Event 的基类
"""
Message = TypeVar("Message", bound="BaseMessage") Message = TypeVar("Message", bound="BaseMessage")
"""
:类型: `BaseMessage`
:说明:
所有 Message 的基类
"""
MessageSegment = TypeVar("MessageSegment", bound="BaseMessageSegment") MessageSegment = TypeVar("MessageSegment", bound="BaseMessageSegment")
"""
:类型: `BaseMessageSegment`
:说明:
所有 MessageSegment 的基类
"""
PreProcessor = Callable[[Bot, Event, dict], Union[Awaitable[None], PreProcessor = Callable[[Bot, Event, dict], Union[Awaitable[None],
Awaitable[NoReturn]]] Awaitable[NoReturn]]]
"""
:类型: `Callable[[Bot, Event, dict], Union[Awaitable[None], Awaitable[NoReturn]]]`
:说明:
消息预处理函数 PreProcessor 类型
"""
Matcher = TypeVar("Matcher", bound="MatcherClass") Matcher = TypeVar("Matcher", bound="MatcherClass")
Handler = Callable[[Bot, Event, dict], Union[Awaitable[None], Handler = Callable[[Bot, Event, dict], Union[Awaitable[None],

3
poetry.lock generated
View File

@ -600,10 +600,9 @@ unify = "*"
yapf = "*" yapf = "*"
[package.source] [package.source]
reference = "88a68ed340013067a1c673bdf7541680c581fa60" reference = "b7ca9332c2e4c5e50110d6477dd28821c74da778"
type = "git" type = "git"
url = "https://github.com/nonebot/sphinx-markdown-builder.git" url = "https://github.com/nonebot/sphinx-markdown-builder.git"
[[package]] [[package]]
category = "dev" category = "dev"
description = "sphinxcontrib-applehelp is a sphinx extension which outputs Apple help books" description = "sphinxcontrib-applehelp is a sphinx extension which outputs Apple help books"