utils 模块

utils 提供了一些框架或插件内常用的实用方法。

获取方法

python

from tooldelta import utils

以下的所有方法都是 utils 模块中的属性。

createThread

创建一个特殊线程，这个线程受ToolDelta主框架控制和收集。和普通线程类不一样的是，它能使用 stop() 中断运行（不是很安全），并且能在重载插件的时候被自动停止。

参数：

参数名	类型	说明
func	(...) -> Any	线程函数
args	tuple	函数传入的参数组，默认为空
thread_level	int	线程权限等级，默认为 `ToolDeltaThread.PLUGIN`
usage	str	线程的用途，建议填写，默认为空
**kwargs	...	线程函数的关键字参数，默认为空

返回：
类型说明
ToolDeltaThread ToolDelta 线程对象

类型	说明
ToolDeltaThread	ToolDelta 线程对象

ToolDeltaThread 对象可以使用以下方法：

方法	说明
`.stop()`	中止线程（底层原理：在线程内下一条代码指令处引发专有异常），对于 `time.sleep()` 等阻塞函数无法中止
`.block_get_result()`	阻塞等待线程结束并返回其返回值
`.block_get_result_with_timeout(timeout)`	带超时地等待线程结果，超时返回 `None`

示例：

python

def hello_forever(greet, name):
    while 1:
        print(f"{greet}, {name}")

thread = utils.createThread(
    hello_forever, ("Hello", "ToolDelta"), "一直说 hello"
)

while 1:
    if input() == "quit":
        thread.stop()

simple_fmt

对字符串以简单的方法进行格式化替换。

参数：
参数名类型说明
kw dict[str, Any] 替换标记与替换内容的映射字典
sub str 将被格式化的字符串
返回：
类型说明
str 格式化后的字符串
示例：

参数名	类型	说明
kw	dict[str, Any]	替换标记与替换内容的映射字典
sub	str	将被格式化的字符串

类型	说明
str	格式化后的字符串

python

print(
    utils.simple_fmt(
        {
            "[arg1]": "Super",
            "[arg2]": 2
        },
        "i am [arg1] and i'm [arg2] yrs old"
    )
)
# output: i am Super and i'm 2 yrs old

thread_func

作为装饰器使用，放在任意堵塞函数上，使函数在被执行的时候自身作为一个新线程启动，不会阻塞代码的继续运行。

参数：
参数名类型说明
usage str 线程显示名
示例：

参数名	类型	说明
usage	str	线程显示名

python

@utils.thread_func("一个简单的方法")
def say_hi(name):
    for i in range(5):
        print(f"hi {name}")
        time.sleep(1)

say_hi("Super")
say_hi("Boy")

thread_gather

并行获取多个阻塞函数的返回值。

参数：
参数名类型说明
funcs_and_args list[tuple[() -> Any, tuple]] 阻塞函数及其参数的列表
返回：
类型说明
list[Any] 阻塞函数的返回值列表
示例：

参数名	类型	说明
funcs_and_args	list[tuple[() -> Any, tuple]]	阻塞函数及其参数的列表

类型	说明
list[Any]	阻塞函数的返回值列表

python

(
    baidu_resp,
    bili_resp,
    douyin_resp,
) = utils.thread_gather(
    [
        requests.get, ("https://www.baidu.com",),
        requests.get, ("https://www.bilibili.com",),
        requests.get, ("https://www.douyin.com",),
    ]
)

timer_event

作为装饰器使用，设置一个定时任务。

参数：
参数名类型说明
t int 定时间隔，单位秒
name str | None 定时任务显示名，默认为自动生成
thread_priority int 定时任务的线程优先级，默认为 TimerEventPriority.PLUGIN

参数名	类型	说明
t	int	定时间隔，单位秒
name	str \| None	定时任务显示名，默认为自动生成
thread_priority	int	定时任务的线程优先级，默认为 `TimerEventPriority.PLUGIN`

注意

被 timer_event 修饰的方法，必须手动调用一次才会开始定时任务线程。

示例：

python

@utils.timer_event(1, "一个简单的定时任务")
def say_hi(name):
    print(f"hi {name}, now is {time.time()}")

say_hi("Super")

try_int

传入任意值（e.g.字符串），尝试转换为整数并返回，否则返回 None

fill_list_index

当列表 lst 长度比 default 小时，使用 default 中的剩余内容填充 lst 的剩余部分。

参数：
参数名类型描述
lst list[Any] 待填充的列表
default list[Any] 用于填充默认值的列表
示例：

参数名	类型	描述
lst	list[Any]	待填充的列表
default	list[Any]	用于填充默认值的列表

python

>>> list_a = [1, 2]
>>> utils.fill_list_index(list_a, [1, 2, 3])
>>> list_a
[1, 2, 3]

>>> list_a = [-2, -1]
>>> utils.fill_list_index(list_a, [1, 2, 3, 4])
>>> list_a
[-2, -1, 3, 4]

>>> list_a = ["我", "的"]
>>> utils.fill_list_index(list_a, ["你", "好", "世", "界"])
>>> list_a
["我", "的", "世", "界"]

to_player_selector

将玩家名转化为目标选择器。传入目标选择器时，不会产生任何效果。

参数：
参数名类型描述
playername str 玩家名
返回：
类型描述
str 目标选择器
示例：

参数名	类型	描述
playername	str	玩家名

类型	描述
str	目标选择器

python

>>> utils.to_player_selector("SkyblueSuper")
'@a[name="SkyblueSuper"]'

>>> utils.to_player_selector("2334567")
'@a[name="2334567"]'

>>> utils.to_player_selector('@a[name="chfwd"]')
'@a[name="chfwd"]`

create_result_cb

创建一对回调锁（获取方法和设置方法）。

示例：

python

from uuid import uuid4

callback_handlers = {}

def callback_handler(uuid, data):
    callback_handlers[uuid](data)

def wait_result():
    timeout = 5 # 等待回调的超时时间
    uuid_gen = str(uuid4())
    getter, setter = utils.create_result_cb()
    callback_handlers[uuid_gen] = setter
    # 
    # 如果超时将返回None; 否则返回回调结果
    result = getter(timeout)
    del callback_handlers[uuid_gen]
    return result

set_timeout

延时执行传入的函数。

参数：
参数名类型说明
t float 延时时间（秒）
func (...) -> Any 待延时执行的函数
*args / **kwargs ... 传给函数的参数
返回：
类型说明
TimeoutFunc 延时执行对象
示例：

参数名	类型	说明
t	float	延时时间（秒）
func	(...) -> Any	待延时执行的函数
args / *kwargs	...	传给函数的参数

类型	说明
TimeoutFunc	延时执行对象

python

utils.set_timeout(3, print, "3 秒后打印")

timeout_func

作为装饰器使用，将一个函数变为延时执行（调用后延时执行并返回延时执行对象）。

参数：
参数名类型说明
t float 延时时间（秒）
usage str 函数说明
thread_level int 延时线程等级

参数名	类型	说明
t	float	延时时间（秒）
usage	str	函数说明
thread_level	int	延时线程等级

timer_event_boostrap

启动定时任务线程。通常由框架在启动时自动调用，一般无需手动调用。

safe_json 模块

utils.safe_json 提供了安全读写 json 文件的方法。获取方法：from tooldelta.utils import safe_json。

方法	说明
`safe_json_dump(obj, filepath, indent=2)`	安全地将对象写入 json 文件
`safe_json_load(fp \| str)`	安全地从文件/路径读取 json
`read_from_plugin(plugin_name, file, default=None)`	读取指定插件数据目录下的 json
`write_to_plugin(plugin_name, file, obj, indent=4)`	写入指定插件数据目录下的 json
`DataReadError`	json 读取失败时抛出的异常

ChatbarLock 与聊天栏锁

utils.ChatbarLock(playername, oth_cb=lambda _: None) 是一个上下文管理器，用于防止同一玩家同时开启多个聊天栏输入会话；若玩家已在会话中会引发 ThreadExit。 utils.players_in_chatbar_lock 是当前正处于聊天栏锁中的玩家名列表。

safe_close

utils.safe_close(close_status) 安全关闭 ToolDelta 框架。

其他 basic 工具方法

utils 还直接暴露了 tooldelta.utils.basic 中的若干工具函数：

方法	说明
`simple_assert(cond, exc)`	断言，失败时抛出给定的异常
`try_convert(arg, factory)`	尝试用给定工厂转换值，失败返回 `None`
`fuzzy_match(lst, sub, ignore_caps=True)`	在列表中模糊匹配字符串
`split_list(lst, length)`	将列表按固定长度切分
`remove_mc_color_code(string)`	移除文本中的 MC 颜色代码
`to_plain_name(name)`	转换带格式/后缀的玩家名为纯名称
`create_desperate_attr_class(class_name, attrs)`	动态创建一个属性类

已弃用的兼容对象

utils.TMPJson、utils.JsonIO、utils.Utils 为旧的兼容对象，已弃用，请分别改用 utils.tempjson、utils.safe_json 与本页所列的顶层方法。

utils.tempjson 模块

utils.tempjson 模块可以将 json 文件载入缓存区从而进行快速读写，对运行速度和磁盘使用非常友好。

此文档已独立于实用方法文档。

点此前往查看

utils 模块 ​

获取方法 ​

createThread ​

simple_fmt ​

thread_func ​

thread_gather ​

timer_event ​

try_int ​

fill_list_index ​

to_player_selector ​

create_result_cb ​

set_timeout ​

timeout_func ​

timer_event_boostrap ​

safe_json 模块 ​

ChatbarLock 与聊天栏锁 ​

safe_close ​

其他 basic 工具方法 ​

utils.tempjson 模块 ​

utils 模块

获取方法

createThread

simple_fmt

thread_func

thread_gather

timer_event

try_int

fill_list_index

to_player_selector

create_result_cb

set_timeout

timeout_func

timer_event_boostrap

safe_json 模块

ChatbarLock 与聊天栏锁

safe_close

其他 basic 工具方法

utils.tempjson 模块