Modules API

下面仅列出可能有用的部分

钩子管理类

class libs.hook.HookManager(app=None, hooks_dir='hooks', reload_time=600, third_hooks=None)[源代码]

Receive initialization parameters and pass options to init_app() method.

add_third_hook(third_hook_module_name)[源代码]

添加第三方钩子

参数:: third_hook_module_name (str) – 钩子可直接导入的模块名

call(_funcname, _include=None, _exclude=None, _every=None, _mode=None, _args=None, _kwargs=None)[源代码]: Try to execute the func method in all enabled hooks.

在 1.7.0 版本发生变更: add param _mode and _every

在 1.9.0 版本发生变更: _mode add any_false

自 1.8.0 版本弃用: _callback replaced by _every; args replaced by _args; kwargs replaced by _kwargs

call_intpl(_tplname, _include=None, _exclude=None, **context)[源代码]

在模板中渲染

参数:

_tplname (str or function) – 扩展点名称
_include (list) – 仅查找哪些钩子
_exclude (list) – 排除哪些钩子

Kerword context:

渲染模板时传递的变量

返回:

Markup HTML

disable(name)[源代码]: 禁用钩子

emit_assets(hook_name, filename, _raw=False, _external=False)[源代码]

在模板中快速构建出扩展中静态文件的地址。

当然，可以用 flask.url_for() 代替。

如果文件以 .css 结尾，那么将返回 <link> ，例如:

<link rel="stylesheet" href="/assets/hook/hi.css">

如果文件以 .js 结尾，那么将返回 <script> ，例如:

<script type="text/javascript" src="/assets/hook/hi.js"></script>

其他类型文件，仅仅返回文件地址，例如:

/assets/hook/img/logo.png
/assets/hook/attachment/test.zip

以下是一个完整的使用示例：

<!DOCTYPE html>
<html>
<head>
    <title>Hello World</title>
    {{ emit_assets('demo','css/demo.css') }}
</head>
<body>
    <div class="logo">
        <img src="{{ emit_assets('demo', 'img/logo.png') }}">
    </div>
    <div class="showJsPath">
        <scan>
            {{ emit_assets('demo', 'js/demo.js', _raw=True) }}
        </scan>
    </div>
</body>
</html>

参数:

hook_name – 钩子名
filename (path) – 钩子包下static目录中的文件
_raw (bool) – True则只生成文件地址，不解析css、js，默认False
_external (bool) – 转发到url_for的_external

返回:

html code with Markup

在 1.9.0 版本加入.

enable(name)[源代码]: 启用钩子

property get_all_hooks: Get all hooks, enabled and disabled, returns list

property get_all_hooks_for_api: query hook for admin api

get_call_list(_callname, _include=None, _exclude=None, _type='all')[源代码]: 获取所有启用钩子的某个类型对应的方法/变量

property get_enabled_hooks: Get all enabled hooks, return list

property get_enabled_map_hooks: Get map enabled hooks, return dict

property get_map_hooks: Get all hooks, enabled and disabled, returns dict

init_app(app)[源代码]

proxy(name, is_enabled=True)[源代码]

代理到钩子中执行方法

参数:

name (str) – 钩子名称（__hookname__），非其模块名
is_enabled (bool) – True表示仅从已启用钩子中查找方法，否则查找所有

reload()[源代码]

remove_third_hook(third_hook_name)[源代码]

移除第三方钩子

参数:: third_hook_name (str) – 钩子名（非模块名）

通用方法

utils.tool.logger

utils.tool.err_logger

utils.tool.ALLOWED_EXTS: 默认允许上传的图片后缀

utils.tool.ALLOWED_VIDEO: 允许上传的视频后缀

utils.tool.rsp(*args)[源代码]: 使用 picbed: 前缀生成redis key

utils.tool.md5(text)[源代码]

utils.tool.sha1(text)[源代码]

utils.tool.sha256(text)[源代码]

utils.tool.hmac_sha256(key, text)[源代码]

utils.tool.get_current_timestamp(is_float=False)[源代码]

获取当前时间戳

参数:: is_float (bool) – True则获取10位秒级时间戳，否则原样返回

utils.tool.create_redis_engine(redis_url=None) → Redis[源代码]: 创建redis连接的入口

utils.tool.parse_valid_comma(s)[源代码]

utils.tool.parse_valid_verticaline(s)[源代码]

utils.tool.parse_valid_colon(s)[源代码]: 解析形如 a:b,x:y 字符串为 dict(a=b, x=y)

utils.tool.is_true(value)[源代码]

utils.tool.generate_random(length=6)[源代码]

utils.tool.check_url(addr)[源代码]: Check whether UrlAddr is in a valid format

utils.tool.check_ip(ip_str)[源代码]

utils.tool.slash_join(*args)[源代码]: 用 / 连接参数

utils.tool.gen_ua()[源代码]: 随机生成用户代理

utils.tool.try_request(url, params=None, data=None, headers=None, timeout=5, method='post', proxy=None, num_retries=1, _is_retry=False) → Response[源代码]

参数:

params (dict) – 请求查询参数
data (dict) – 提交表单数据
timeout (int) – 超时时间，单位秒
method (str) – 请求方法，get、post、put、delete
proxy (str) – 设置代理服务器
num_retries (int) – 超时重试次数
_is_retry (bool) – 判定为重试请求，这不应该由用户发出

utils.tool.is_all_fail(alist)[源代码]: 从list下的dict拿出code!=0的(执行失败)数量

utils.tool.bleach_html(html, tags: Optional[List[str]] = None, attrs: Optional[Dict[str, List[str]]] = None, css: Optional[CSSSanitizer] = None)[源代码]: 清洗HTML，设置中仅允许部分标签、属性和样式。

utils.tool.is_valid_verion(version)[源代码]

Semantic version number - determines whether the version is qualified. The format is MAJOR.Minor.PATCH, more with https://semver.org

参数:: version (str) – 版本号

utils.tool.b64size(b64string)[源代码]: 获取base64内容大小，单位bytes

class utils.tool.Mailbox(user, passwd, smtp_server, smtp_port=25)[源代码]

初始化邮箱客户端配置。

参数:

user – 邮箱地址
passwd – 邮箱密码或可登录的授权码
smtp_server – 邮箱的SMTP服务器地址

property debug: 是否开启debug模式，支持setter

send(subject, message, to_addrs, from_name=None)[源代码]

Sendmail

参数:

subject – 邮件主题
message – 内容，支持HTML
to_addrs – 收件人，支持多个

返回:

send result

返回类型:

dict

property ssl: 是否使用加密连接，支持setter

utils.tool.raise_version()[源代码]

适用Web环境的方法

utils.web.rc: redis连接实例

在 1.9.0 版本加入.

@utils.web.login_required[源代码]: 页面要求登录装饰器

@utils.web.anonymous_required[源代码]: 页面要求匿名装饰器

@utils.web.apilogin_required[源代码]: 接口要求登录装饰器

@utils.web.admin_apilogin_required[源代码]: 接口要求管理员级别登录装饰器

utils.web.get_site_config() → dict[源代码]: 获取站点配置

utils.web.set_site_config(mapping)[源代码]: 设置站点信息

utils.web.sendmail(subject, message, to)[源代码]

调用钩子中发送邮件函数（任意钩子发送成功即停止），要求用于Web上下文环境

参数:

subject (str) – 主题
message (str) – 正文（支持HTML）
to (str) – 收件人，可用逗号添加多个

utils.web.async_sendmail(subject, message, to)[源代码]: 异步邮件发送，可用于多线程及非Web上下文环境

utils.web.make_email_tpl(tpl, **data)[源代码]

制作邮件模板

参数:

tpl – 模板文件（位于templates/email/下）
data – 模板所用变量

返回:

jinja2渲染好的html内容

utils.web.try_proxy_request(url, **kwargs)[源代码]

自动调用代理服务的try_request

参数:

url (str) – 请求地址
kwars – utils.tool.try_request() 要求的其他参数

在 1.9.0 版本加入.

utils.web.set_page_msg(text, level='info')[源代码]

给管理员的控制台消息（任意环境均可）

参数:

text (str) – 消息内容
level (str) – 级别，info(默认)、success、error、warn

在 1.9.0 版本加入.

utils.web.get_page_msg()[源代码]: 生成消息Js，仅在管理员控制台页面闪现消息（仅Web环境调用）

utils.web.push_user_msg(to, text, level='info', time=3, align='right')[源代码]

给用户推送消息（任意环境均可）

参数:

to (str) – 用户名
text (str) – 消息内容
level (str) – 级别，info(默认)、success、error、warn
time (int) – 超时时间，单位秒
align (str) – 消息显示位置，right右上角、center顶部中间、left左上角

在 1.10.0 版本加入.

utils.web.get_push_msg()[源代码]: 生成消息Js，仅在个人中心页面闪现消息（仅Web环境调用）

utils.web.get_user_ip()[源代码]: 首先从HTTP标头的X-Forwarded-For获取代理IP，其次获取X-Real-IP，最后是客户端IP

utils.web.has_image(sha)[源代码]: 是否存在图片

utils.web.guess_filename_from_url(url, allowed_exts=None)[源代码]

从url中猜测图片文件名，其后缀符合控制台设定或默认予以返回。

首先尝试从url path猜测，比如http://example.com/upload/abc.png，这合法。

如果猜测失败，则从url query查找filename查询参数。

参数:

url (str) – 图片地址
allowed_exts (list) – 允许的图片后缀，比如[‘png’, ‘jpg’]，如未设置，则使用控制台设定或默认

返回:

当图片合法时返回filename，否则None

在 1.10.0 版本加入.

utils.web.get_allowed_suffix()[源代码]: 获取允许上传的后缀（允许视频，后缀无点）

utils.web.allowed_suffix(filename)[源代码]

判断filename是否匹配控制台配置的上传后缀（及默认）

参数:: filename (str) – 图片文件名
返回类型:: boolean

在 1.10.0 版本加入.

class utils.web.Base64FileStorage(b64str, filename=None)[源代码]

上传接口中接受base64编码的图片。

允许来自前端的Data URI形式:: https://developer.mozilla.org/docs/Web/HTTP/data_URIs

property filename

property is_base64

property mimetype

property size: return bytes

property stream

class utils.web.ImgUrlFileStorage(imgurl, filename=None)[源代码]

上传接口中接受远程图片地址，会自动调用代理下载图片。

property Headers

property filename: 定义url图片文件名：如果给定文件名，则用，否则从url path猜测。猜测失败，从url query查找filename参数。未果，则读取图片二进制猜测格式。未果，从返回标头Content-Type判断。未果，文件名后缀可能是None，将不合要求。

property getObj

property size: return bytes

property stream

class utils.web.FormFileStorage(fp)[源代码]

通过表单上传文件

property filename

property mimetype

property size: return bytes

property stream

异常类

exception utils.exceptions.PicbedError[源代码]: 异常基类

exception utils.exceptions.ApiError(message, code=-1, status_code=200)[源代码]

触发Api异常，直接中止后续执行并返回JSON格式错误。

触发异常:

@app.route("/test")
def test():
    raise ApiError("Some message")

应用自动捕获ApiError异常并返回JSON类型响应:

{"code": -1, "msg": "Some message"}

参数:

message (str) – 错误信息
code (int) – 非0错误码
status_code (int) – 请求响应码，如200、403、404

在 1.9.0 版本加入.

exception utils.exceptions.PageError(message, code=-1, status_code=200)[源代码]: 触发页面异常，直接中止后续执行并返回错误页面，区别ApiError的是，处理PageError是显示一个错误页面。

在 1.9.0 版本加入.