moear-api-common

概览

该项目的目的为给 MoEar 服务提供接口的定义及常用工具方法的实现。

故该项目本身结构极其简单,下面分别从 接口定义常用工具 两方面进行说明。

安装方法

您可以通过 pip 进行安装,本包仅在 Python 3.X 下测试通过:

pip install moear-api-common

接口定义

为了增强 MoEar 的可扩展性,在实现时,基于 OpenStack 项目中的 stevedore 包, 实现了扩展两个扩展插件机制,分别用于实现 爬虫打包 功能的扩展。

MoEar 在运行时会根据相应逻辑,加载相应的爬虫、打包实现,从而实现松耦合、可扩展。 同时我也分别实现了一个爬虫与一个打包工具,用以使 MoEar 可以正常完成整个业务流程, 亦可作为一个例子,给有能力的小伙伴儿提供一个 DIY 的参考例程。

接口定义在 base.py 文件中,共提供两种接口,分别为

  1. 爬虫接口: SpiderBase ,用于定义一个扩展文章爬虫需要实现的所有方法
  2. 打包接口: PackageBase ,用于定义一个扩展打包工具需要实现的所有方法

爬虫接口

爬虫插件的业务流程为,当 MoEar 服务启动时,会遍历所有 setup.pyentry_points 含有 moear.spider 入口的 Python 包,并调用其 SpiderBase.register() 方法,将返回字典持久化到 DB 中。

MoEar 服务会根据具体 Spider 注册时配置中提供的爬取策略(爬取时间、随机延迟范围等) 创建计划任务,待任务触发时,调用相应 Spider 插件的 SpiderBase.crawl() 方法, 执行爬取操作,并等待结果返回后,将其持久化到 DB 中。

注意

此处 MoEar 会开启基于 Celery 的分布式消息队列,并在独立进程中调用相关接口

获取到爬取结果数据后, MoEar 会在执行打包任务前, 将从 DB 中获取相应文章数据 & 元数据,生成同 SpiderBase.crawl() 返回的相同格式的数据结构作为入参,调用 SpiderBase.format() 方法,

注解

具体数据结构,内容,格式,配置项信息,将在稍后参考例程中作详细阐述。

打包接口

打包插件的业务流程很简单,目前只提供了一个业务方法定义 PackageBase.generate() 。 该方法将完成对传入数据结构的处理,如将文章内容中的 img 下载到本地,文章内容保存到文件, 并最终打包成相应设备支持的电子书格式,如:mobiepub 等。稍后我将实现 Kindle 上最常用的 mobi 格式打包插件,用以作为参考例程。

MoEar 对打包插件的获取流程为,会遍历所有 setup.pyentry_points 含有 moear.package 入口的 Python 包。

注意

此接口的调用环境与上述 SpiderBase.crawl() SpiderBase.format() 相同,会在基于 Celery 的分布式消息队列的独立进程中调用被调用

注解

具体数据结构,内容,格式,配置项信息,将在稍后参考例程中作详细阐述。

配置说明

当前支持的配置参数主要用于控制打包行为,具体参见 配置参数

常用工具

目前提供的工具主要分三块:

  1. 系统操作
  2. kindlegen支持
  3. 图片处理

具体接口说明参见 工具包

接口定义

class moear_api_common.base.SpiderBase(*args, **kwargs)[源代码]

Bases: object

爬虫基类

用以作为抽象类定义爬虫扩展所需提供的服务接口

包括:

  1. 爬虫注册
  2. 爬虫调用
  3. 打包格式化

初始化默认配置参数,可在子类中进行覆盖

配置优先级为:用户元数据 > 具体Package配置 > Common全局默认配置

参数:usermeta (dict) – (可选,关键字参数)指定用户的package相关配置元数据, 如:定制书籍名(book_title)等
hook_custom_options()[源代码]

配置定制配置项钩子

该方法返回当前类的自定义配置项,由基类在 __init__ 方法中调用, 调用点位于,Common默认全局配置完成后,用户元数据配置前

返回:返回当前类的自定义配置项
返回类型:dict
register(*args, **kwargs)[源代码]

注册

调用方可根据主键字段进行爬虫的创建或更新操作

返回:返回符合接口定义的字典数据
返回类型:dict
crawl(*args, **kwargs)[源代码]

爬取

执行爬取操作,并阻塞直到爬取完成,返回结果数据

返回:返回符合接口定义的字典数据
返回类型:dict
format(data, *args, **kwargs)[源代码]

格式化

将传入的Post列表数据进行格式化处理

参数:data (list) – 待处理的文章列表
返回:返回符合mobi打包需求的定制化数据结构
返回类型:dict
class moear_api_common.base.PackageBase(spider, *args, **kwargs)[源代码]

Bases: object

打包基类

用以作为抽象类定义打包驱动所需提供的服务接口

初始化默认配置参数,可在子类中进行覆盖

配置优先级为:用户元数据 > Spider元数据 > 具体Package配置 > Common全局默认配置

参数:
  • spider (dict) – 指定爬虫的信息数据(包括 ‘meta’ 字段的元数据字典, 其中需包含书籍名称用的时间戳)
  • usermeta (dict) – (可选,关键字参数)指定用户的package相关配置元数据, 如:定制书籍名(book_title)等
ext

输出文件的扩展名

小技巧

可在 hook_custom_options 方法中,通过 filename_extension 键名 来设置

返回:扩展名
返回类型:str
hook_custom_options()[源代码]

配置定制配置项钩子

该方法返回当前类的自定义配置项,由基类在 __init__ 方法中调用, 调用点位于,Common默认全局配置完成后,Spider元数据、用户元数据配置前

返回:返回当前类的自定义配置项
返回类型:dict
generate(data, *args, **kwargs)[源代码]

生成

根据传入的数据结构生成最终用于推送的文件字节字符串(bytes), MoEar会将其持久化并用于之后的推送任务

参数:data (dict) – 待打包的数据结构
返回:返回生成的书籍打包输出字节
返回类型:bytes

配置参数

moear_api_common.config.filename_extension = 'mobi'

打包输出文件的扩展名

moear_api_common.config.icons_path = '/path/to/icons'

icon路径

moear_api_common.config.img_cover = '/path/to/img_cover'

封面图片,留空则不会为书籍增加封面,size: 600*800。 默认为随 moear-api-common 包附带的 cv_default.jpg 文件

moear_api_common.config.img_masthead = '/path/to/img_masthead'

报头图片,size: 600*60。 默认为随 moear-api-common 包附带的 mh_default.jpg 文件

moear_api_common.config.img_max_thumb_size = 16384

合并图书的封面图片,留空则将所有书籍封面贴在一起 缩略图处理约束条件,小于等于 16KB

moear_api_common.config.img_max_thumb_dimen = (180, 240)

缩略图处理约束条件,尺寸小于等于 180*240

moear_api_common.config.img_reduce_to = (600, 800)

缩小图片尺寸到 (Width, Height)

moear_api_common.config.img_convert_to_gray = True

是否将图片转换为灰度图,这将有利于显著减小输出文件的大小,建议在电纸书上阅读时开启

moear_api_common.config.css_base = '/path/to/base.css'

基础样式文件。默认为随 moear-api-common 包附带的 base.css 文件

moear_api_common.config.toc_desc_generate = True

是否为TOC条目生成简述

moear_api_common.config.toc_desc_word_limit = 500

TOC条目简述的字数限制

moear_api_common.config.toc_thumbnail_generate = False

TOC描述是否包含图片,此功能暂未实现

工具包

moear_api_common.utils.mkdirp(path)[源代码]

创建传入的路径

该方法为一个串联调用方法,仅对 os.makedirs() 做了简单封装。

推荐用法:

path_created = mkdirp(path)  # 赋值路径的同时确保其已被创建

用例:

>>> from moear_api_common.utils import mkdirp
>>> mkdirp('build/doctest/test_path')
'build/doctest/test_path'
参数:path (str) – 待创建路径
返回:创建完成的路径
返回类型:str
引发:OSError – 调用 os.makedirs() 时发生的异常,若路径已存在则不抛出异常
moear_api_common.utils.get_config_dict(config)[源代码]

获取配置数据字典

对传入的配置包进行格式化处理,生成一个字典对象

参数:config (object) – 配置模块
返回:配置数据字典
返回类型:dict
moear_api_common.utils.img.rescale_image(data, maxsizeb=4000000, dimen=None, png2jpg=False, graying=True, reduceto=(600, 800))[源代码]

png2jpgTrue 则将图片转换为 JPEG 格式,所有透明像素被设置为 白色 。确保结果图片尺寸小于 maxsizeb 的约束限制。

如果 dimen 不为空,则生成一个相应约束的缩略图。依据 dimen 的类型,设置约束为 width=dimen, height=dimen 或者 width, height = dimen

参数:
  • data (bytes or io.BytesIO) – 原始图片字节数据
  • maxsizeb (int) – 文件大小约束,单位:字节
  • dimen (int or (int, int)) – 缩略图尺寸约束,宽&高
  • png2jpg (bool) – 是否将图片转换为 JPG 格式
  • graying (bool) – 是否将图片进行灰度处理
  • reduceto ((int, int)) – 若图片大于此约束则进行相应缩小处理,宽&高
返回:

处理后的图片字节数据,可直接以 wb 模式输出到文件中

返回类型:

bytes

moear_api_common.utils.img.gray_image(data)[源代码]

灰度化图片

将传入的图片数据转换为灰度图后返回

参数:bytes (data) – 图片字节数据,可通过以 rb 模式读取图片文件获得
返回:处理后的图片字节数据,可直接以 wb 模式输出到文件中
返回类型:bytes
moear_api_common.utils.kindlegen.find_kindlegen_prog(path=None)[源代码]

获取kindlegen程序路径

该方法会检索系统 PATH 路径,查找包含 kindlegen 文件的路径, 并返回该文件的绝对路径。若不存在则返回 None

注意

检索 PATH 路径前,会优先寻找指定路径,并在检索到第一个符合文件后立刻返回

参数:path (str) – 关键字参数,若传入,则优先检测该路径下是否存在 kindlegen 程序
返回:kindlegen的绝对路径
返回类型:str

代办事项

  1. 当前 options 基于 dict 的实现过于简陋,既不方便调用,也不方便赋值。考虑通过 Python 特有的魔术方法特性,实现独立的设置接口,以及只读的点语法调用支持, 避免由于误输入造成的错误调用
  2. 工具包整体定义感觉还不够规整,主要由于都是按需实现,没有整体规划,待有一定工具数量后, 进行整体结构规划,并提供相应的 shortcut

发布说明

v1.0.0 (2018-04-08 11:08:15)

  1. 定义爬虫接口
  2. 定义打包接口
  3. 实现基础工具包,包含:路径操作、图片处理、Kindlegen支持