软件源脚本编写

TIP

请先了解贡献准则,若已查看请忽略。

开发环境及库

Python 版本:Python 3.8.2open in new window(版本不同时应注意兼容性问题)

Python 库:

相关文件介绍

/app/server/hubs/library/hub_list.pyopen in new window

Python 脚本列表。Server 通过该文件实现软件源的类的实例化。
因此,在你新增或删除软件源脚本后,应当修改该文件中的 hub_dict 对象。具体格式为:

from .github import Github
from .fdroid import FDroid
from .coolapk import CoolApk

hub_dict = {
    "fd9b2602-62c5-4d55-bd1e-0d6537714ca0": Github(),
    "6a6d590b-1809-41bf-8ce3-7e3f6c8da945": FDroid(),
    "1c010cc9-cff8-4461-8993-a86cd190d377": CoolApk()"<软件源的 UUID(应与软件源配置文件相同)>": <对应的软件源的实例化的类>
}

/app/server/hubs/base_hub.pyopen in new window

此文件为 Python 脚本应该继承的抽象基类。
基类规定了你的 Python 脚本应该实现的供 Server 调用的接口,函数实现方法不做限制,接口函数的注释详细地说明了这些函数的输入输出值。

你编写的 Python 脚本

文件名与类名:相应软件源的英文名称。
文件路径:/app/server/hubs/library/<your_script_name>.py

TIP

你需要在这个文件中继承 base_hub 并实现它。
脚本文件内部结构不做要求,能够正常实例化就行。
理论上来说,你可以为将软件源的实现拆分为多个脚本文件,但为了保持目录结构的整洁,我们非常希望您不要这样做。

Python 脚本接口函数

get_release

批量获取更新版本信息

  • 输入
  1. app_id(dict) 客户端上传的需要检查的软件信息

    TIP

    你可以通过软件源配置文件指定你所需要的属性值。

    # Github 源
    {
      "user": "DUpdateSystem",
      "repo": "UpgradeAll"
    }
    
    # CoolApk 源
    {
      "android_app_package": "net.xzos.upgradeall",
    }
    
  2. auth(dict) 软件源身份验证信息

  • 输出

Python 数组

这是一个包含多个相同格式的字典的数组。
每个字典的格式是固定的,它表示了一个版本的信息(版本号、更新日志、安装文件)。

[{
   "version_number": "1.0",
   "change_log": "这是更新日志(咕咕咕)",
   "assets": [
       {
           "name": "example.apk",
           "download_url": "example.com/download",
           "file_type": "application/vnd.android.package-archive"
       }
   ]
}]

get_download_info

  • 输入
  1. app_id(dict) 客户端上传的需要检查的软件信息 与 get_release 函数相同

  2. asset_index(list) 请求下载的文件索引数组 这是一个由数字组成的数组,从左到右分别表示版本号索引和下载文件索引(从 0 开始数)。

    [0, 0]  # 最新版本的第二个文件
    
  3. auth(dict) 软件源身份验证信息

  • 输出

Python 数组或 JSON 数组:

[
  ({url}, {request_header_dict}),
]

包含下载下载地址与请求头。
若返回值不为 None 或空,客户端将使用这些信息下载文件; 若返回值为空,将使用 get_release 函数提供的下载地址。

get_release_list(async 函数)

批量获取更新版本信息,你可以把它视为对多次执行 get_release 函数的异步打包。

对于一些可以把所有或者多个软件信息打包返回的软件源,你可以使用重写该函数,以实现更快地向客户端返回数据。
但因为实现较为复杂,也许你需要参考 base_hub 的实现或者查看源码。

  • 输入
  1. generator_cache(GeneratorCache) 用来即时返回数据的数据类,配合 return_value 函数返回数据

  2. app_id_list(list)
    客户端上传的多个需要检查的软件的信息(每一项的格式参考 get_release 函数)

  3. auth(dict) 软件源身份验证信息

  • 输出

需要使用 return_value 函数和 generator_cache 对象返回数据

return_value(generator_cache: GeneratorCache, app_id: dict, value)

  • generator_cache: 这个函数的同名输入值
  • app_id: 返回的 value 对应的 app_id
  • value: get_release 函数 函数的返回值

预置函数

UpgradeAll 目前提供了一些简单封装的常用操作,以函数的形式提供。

打印日志(loggingopen in new window

函数位置:app.server.utilsopen in new window

  • logging.debug(msg, *args, **kwargs)
  • logging.info(msg, *args, **kwargs)
  • logging.warning(msg, *args, **kwargs)
  • logging.error(msg, *args, **kwargs)
  • logging.critical(msg, *args, **kwargs)

函数使用参考 Python logging 官方文档open in new window

TIP

一般来说,你只需要根据日志等级选择需要的函数,并输入需要打印的日志字符串即可。
建议:如果你不习惯使用 logging 函数,直接使用 print 函数也是不错的选择。

DANGER

因服务端暂未实现日志分类,为了保持服务端日志清晰,当您调试完成提交之后,请注释在软件源脚本中的所有日志函数

数据处理

函数位置:app.server.hubs.hub_script_utilsopen in new window

parsing_http_page

简易包装的获取并解析网页操作。

  • 输入
  1. uri(字符串),目标网页的网址。
  2. payload(字典),使用 Git 方法访问时的请求头。
  • 输出

由 BeautifulSoup4 解析的网页节点树
使用参考 BeautifulSoup4 官方文档open in new window一些常用方法介绍

get_response

简易包装的 get 方法。

  • 输入
  1. uri(字符串),访问的网址。
  2. payload(字典),请求头。
  3. throw_error(布尔值),是否抛出 HTTP 状态码异常。
  • 输出

包装网站响应的 Request 对象。
大部分情况下,你可能用到 Request 对象的 text()、json()open in new window
使用参考 requests 官方文档open in new window

  • 异常处理

仅当 throw_error 为 True(默认值)时,函数可能抛出错误。
其行为参考 parsing_http_page 中异常处理。

get_session

获取默认 Session 对象。

  • 输入

  • 输出

默认的全局 Session 对象。
如果你需要使用除了 GET 方法外的其他方法,或是需要进行身份认证等高级功能时,你需要通过该函数获得 Session。
使用参考 requests 官方文档open in new window

search_version_number_string

在字符串中匹配 x.y.z 版本号。

  • 输入

string:需匹配的字符串。

  • 输出

匹配到的字符串。
若输入不为 None,使用 re 库匹配输入字符串。
若匹配成功不为空,返回符合正则表达式的字符串。
若未找到满足条件的字符串,返回 None。

TIP

该函数一般用于 校验 获取的数据是否正确。

search_url_string

在字符串中匹配网址。

  • 输入

string:需匹配的字符串。

  • 输出

匹配到的字符串。
若输入不为 None,使用 re 库匹配输入字符串。
若匹配成功不为空,返回符合正则表达式的字符串。
若未找到满足条件的字符串,返回 None。

TIP

该函数一般用于过滤下载地址。

add_tmp_cache

添加临时缓存

  • 输入

key:缓存的键值。 value:缓存的字符串。(对于其他数据,你可以尝试自己转换一下)

  • 输出

None

TIP

该函数一般用于缓存大量数据,比如 xp 模块仓库的 api 返回的软件仓库数据。
该缓存方法将同时将你的数据缓存到内存和 redis 数据库,便于软件快速调用。

get_tmp_cache

获取临时缓存

  • 输入

key:缓存的键值。

  • 输出

缓存的字符串或 None

NOTE

大部分预置函数位于 hub_script_utils.pyopen in new window
只包含了一些预测会经常使用的数据操作模式,它非常有可能不能满足你的需求。
如果你认为某种数据的操作模式是通用的,请给我们发送 issueopen in new window 与我们讨论。
然后,提交你的 Pull requestsopen in new window 或 让我们来实现它 😃