calibre的recipe接口(API)之一参数设置
calibre可以实现抓取网页,生成各种格式的电子书,实现方式可以使用GUI,通过输入一些数据,实现比较简单的页面自动抓取。主要针对RSS。也以使用高级功能,实现复杂一些的网页抓取。但要对一些比较复杂的网页内容的抓取,还是要自动编写一个PYTHON程序,即编写一个recipe。calibre网站的在线帮助文档无疑是最基本的学习资源。
学习资料主要有三个,即Adding yourfavorite news website介绍了基本的抓取网页的方法。API Documentation for recipes介绍了基本的recipe编写接口(API),包括参数设置和方法调用。其实是对calibre.web.feeds.news.BasicNewsRecipe子类的接口的学习,再就是对一些recipe例子的学习,学会了这些内容,应该可以完成对recipe的编写。当然,因为recipe是用python编写的,学会python必不可少。这里只想介绍一下自己学习接口的体会:
要编写recipe,学会设置接口的参数是第一步,其实通过参数设置,已经可以实现对一些简单网页的抓取,可以生成有一定质量的电子书了。
API中列出了所有的接口参数,共48个,并做了一些说明,更详细一些,可以看.BasicNewsRecipe源码,源码的前部,定义了这48个参数,并有比较详细的说明。这些参数有的是独立可设置的,有些是相互排斥的,设置一个,另一个就不起作用。有些如果设置为真,就需要实现一个方法。大致如下:
1、title = _('UnknownNews Source')
为所生成电子书的标题,通常肯定会设置的。
2、description = u''
用几行文字对这个recipe所抓取的内容进行描述。最初是在GUI界面下一系列recipe的作用说明。
3、__author__ = __appname__
本recipe的作者
4、requires_version = (0, 6, 0)
执行这个recipe所需要的calibre的最低版本,默认是0.6.0
5、language = 'und'
网页内容所使用的语言,必须符合ISO-639编码,长度为2-3个字符。
6、max_articles_per_feed = 100
每个feed可以下载的最大文章数,用在没有文章日期的情况下。默认是100篇。文章有日期时通常是使用oldest_article参数。
7、oldest_article = 7.0
下载的最旧的文章是几天前的。默认是7天,单位是天。如果文章有日期,这个参数起作用。
8、recursions = 0
web页面中链接的递归级数,默认不递归下载。
9、delay = 0
连续下载时,两次下载中的时间间隔,以浮点数表示,单位为秒。
10、publication_type = 'unknown'
出版类型,抓取内容的类型,有报纸(newspaper)、杂志(magazine)、博客(blog)等。如果设为None,则无类型,该参数会做为metadata数据,写入opf文件中。
11、simultaneous_downloads = 5
同时下载的数量,如果服务器有限制时设为1时。当delay` > 0时,自动降为1,缺省值为5
12、timeout = 120.0
从服务器下载的最长时间限制,超过这个时间为超时。单位为秒,缺省为120秒。
13、timefmt = '[%a, %d %b %Y]
在首页所显示的日期格式,缺省格式为日,月,年
14、feeds = None
下载时用的feed,可以为``[url1,url2, ...]`` 或者 ``[('title1', url1), ('title2',url2),...]`` 两种形式。
15、summary_length = 500
简短描述时最多字符数,缺省为500个字符。
16、no_stylesheets = False
标识是否下载和使用原来网页的样式表,缺省为下载和使用,设为True时,原样式表将不下载和使用。
17、remove_javascript = True
是否在下载的网页中去除掉javascript脚本。缺省为去除脚本。
18、needs_subscription = False
下载时是否需要登录,如果为True,GUI界面下会寻问登录用户名和密码。如果设置为"optional",则登录名和密码为可选的。
19、center_navbar = True
生成的电子书的目录列表是否居中对齐。缺省为中间对齐,False时为左对齐。
20、encoding = None
如果网页的字符集编码不正确时设置的字符集编码,通常为``latin1`` 和``cp1252``。如果设置为None时,自动探测编码。如果它为可调用的,调用时有两个参数,recipe对象和被解码的源文件,返回被解码的源文件。
21、use_embedded_content = None
正常情况下,我们会基于内嵌内容的长度猜测feed会内嵌全部文章的内容。参数有三个值,设为None时,将会进行猜测;设为True时假设feed包含内嵌的所有文章内容;设为False时,feed不包含内嵌的文章内容。
22、articles_are_obfuscated = False
缺省为False,文章比较方便抓取。如果设为True时,表示文章不太方便抓取,将会通过实现get_obfuscated_article方法处理比较难以抓取的文章页面。
23、reverse_article_order = False
设为True时,将会反转feed中的文章排序。
顺便说一下,根据calibre网站的说明,calibre是用带有C/C++的python语言开发的,大家可以在GitHub上找到calibre的python源代码,如果有不了解的用法,可以去读.py文件。
接上文:
24、auto_cleanup= False
在下载的文章页面中自动提取文本内容。使用可读能力工程算法。如果这个参数设为True,意味着你不需要手动清理下载的html文档内容(手工清理总是优先)。
25、auto_cleanup_keep= None
设置自动清理算法不需要处理的元素。语法符合XPath表达式,例如:
auto_cleanup_keep = '//div[@id="article-image"]' #将会保留所有id="article-image"的div标签
auto_cleanup_keep = '//*[@class="important"]' #将保留所有class="important"的元素
auto_cleanup_keep ='//div[@id="article-image"]|//span[@class="important"]'
#将保留所有id="article-image"的div元素和class="important"的span元素
26、extra_css= None
这个参数设定了另外要加入到下载的html文件中的css样式,它们将被插入下载的html文件中的</head>标签前的<style>标签之中,因此,它将覆盖除了直接在html标签中由单独的style属性指定的样式之外的其它css样式。例:
extra_css = '.heading { font: serif x-large }'
*好像只能是标签或者.属性选择器,#选择器,标签[属性=XXX]都不支持,有谁知道如何设置这样的css,可以告知我一下。
27、remove_empty_feeds= False
如果设置为True,将会在输出中删除空的feed。如果在子类中覆盖了parse_index方法,则这个参数无效。也就是说,只对使用feeds设置,或者通过覆盖get_feeds方法,返回一个feeds列表时参数有效。本参数也使用在设置了ignore_duplicate_articles参数的情况。
28、match_regexps = []
该参数为正则表达列表,用来决定哪些链接是有用的。如果设置为空,则忽略本参数。只有在没有实现is_link_wanted方法时,本参数才起作用。例:
match_regexps = [r'page=[0-9]+']
将匹配所有包含"page=数值"的URL。注意:match_regexps和filter_regexps参数只能设置一个,不能同时设置。
29、filter_regexps = []
该参数也是正则表达式的列表,与match_regexps相反,该参数用来决定哪些链接将被过滤掉,不被采用,同样,如果为空忽略本参数,只有在没有实现is_link_wanted方法时,本参数才起作用。例:
match_regexps = [r'page=[0-9]+']
将过滤掉所有包含"page=数值"的URL。注意:filter_regexps和match_regexps参数只能设置一个,不能同时设置。
30、conversion_options= {}
recipe的说明参数,用来控制下载内容生成电子书的会话。这些说明将覆盖任何用户或者插件的设置,所以如果不是绝对需要,不要设置这个参数。例:
conversion_options = {
'base_font_size' : 16,
'tags' : 'mytag1,mytag2',
'title' : 'My Title',
'linearize_tables' : True,
}
31、remove_tags = []
一些将要被删除的标签的列表,用来说明在下载的HTML文件中要删除的标签。每个标签都被以一个字典的形式来表示:
{
name : 'tag name', #e.g. 'div'
attrs : a dictionary, #e.g. {class:'advertisment'}
}
所有的关键字都是可选项。对搜索判据的解释,参见`Beautiful Soup<http://www.crummy.com/software/BeautifulSoup/bs3/documentation.html#Searching%20the%20Parse%20Tree>`,一个常见的例子如下:
remove_tags = [dict(name='div', attrs={'class':'advert'})]
将会在下载的HTML文档中删除含有形如'<div class="dvert">'的标签及其了类标签。
32、remove_tags_after = None
在下载的HTML文档中删除第一次出现说明的这个标签以后的所有标签及其子标签,说明的格式同remove_tags,例:
remove_tags_after = [dict(id='content')]
将会删除第一次出现带有id='content'属性的标签以后的所有标签,注意不删除带有id='content'属性的标签本身。
33、remove_tags_before= None
在下载的HTML文档中删除第一次出现说明的这个标签以前的所有标签及其子标签,说明的格式同remove_tags,例:
remove_tags_after = [dict(id='content')]
将会删除第一次出现带有id='content'属性的标签以前的所有标签,注意不删除带有id='content'属性的标签本身。
34、remove_attributes= []
为属性的列表,说明需要删除所有包含这些属性的标签,例:
remove_attributes = ['style', 'font']
则会删除所有属性包含'style'或者 'font'的标签。
35、keep_only_tags= []
说明只需要保留的标签及其子类标签,格式见remove_tags。本参数如果没有设置设置为空,则'<body>'标签将清空,并填以本参数列表条目所匹配的标签。例:
keep_only_tags = [dict(id=['content','heading'])]
将仅仅会保留id属性值为'content'或者'heading'的标签。
36、preprocess_regexps= []
设置为正则表达式的列表,用以说明下载HTML文档时的替换规则。列表的每一个元素为一个有两个元素的元组,元组的第一个元素为编辑(compiled)的正则表达式,第二个元素为一个调用(lambda),匹配单一的对象,返回一个替换匹配部分的字符串。例:
preprocess_regexps = [
(re.compile(r'<!--Article ends here-->.*</body>', re.DOTALL|re.IGNORECASE),
lambda match: '</body>'),
]
把所有的`<!--Article ends here-->`替换为`</body>`。
37、template_css= u'''
.article_date {
color: gray;font-family: monospace;
}
.article_description {
text-indent: 0pt;
}
a.article {
font-weight: bold;text-align:left;
}
a.feed {
font-weight: bold;
}
.calibre_navbar {
font-family:monospace;
}
'''
本css做为一个样式表的模板,仅在浏览条与目录中,与其重写这个参数,不如在recipe中定义extra_css参数,定制浏览内容的外观和式样。
38、masthead_url= None
缺省的情况下calibre将使用一个默认的图片文件来做为标题图片(masthead仅在kindle下使用),重写这个参数,可以使用一个url指向的图片来替换标题图片(masthead)。
39、cover_margins= (0, 0, '#ffffff')
缺省情况下,书籍的封面是由get_cover_url()返回的图片。在recipe中重写覆盖这个方法,calibre将会下载封面图片,并处理成为一个帧,它的调试和宽度都设置为百分比。cover_margins= (10, 15, '#ffffff')参数表示,封面是白底的左右边框为10像素,上下边框为15像素。颜色的定义见http://www.imagemagick.org/script/color.php。因为一些原因,白色在windows系统中不一定有效,可以用#ffffff来代替。
40、recipe_disabled= None
如果设置为非空的字符串,将会禁用这个recipe,字符串将会作为返回的信息。
41、ignore_duplicate_articles= None
忽略一次或者多次重复的文章。重复的文章指标题,链接(URL)都相同的文章。
仅指明标题的设置方式,例如: ignore_duplicate_articles ={'title'}
仅指明URL的设置方式,例如: ignore_duplicate_articles = {'url'}
同时指明标题和URL的设置方式,例如: ignore_duplicate_articles = {'title', 'url'}
42、use_javascript_to_login= False
如果设置为True,calibre将使用javascript登录网站,主要用于一些需要使用javascript登录的网站的情况,如果设置该参数为True,同时必须实现javascript_login方法,完成实际的登录。
下面几个参数是recipe用来控制怎样让图片的尺寸最小化的:
43、compress_news_images= False
如果设置为False,则忽略图片的压缩参数,保持图片的原始大小。而如果设置为True,则其它压缩参数均保持为缺省情况,jpeg将按屏幕的情况按比例缩放,并被压缩至(w*h)/16标定的最大尺寸。这里w*h是按比例缩放的因子。
44、compress_news_images_auto_size= 16
用来自动压缩jpeg图片的比例因子。如果设置为None,则禁止自动压缩。否则,如果可以降低图片质量级别的情况下,图片将被压缩到
(w*h)/ compress_news_images_auto_size个字节,这里(w*h)为图片在每个维度上的像素数的乘积。因为最小的jpeg图片质量为5/100,所以一般不会达到这个极限。这个参数将被compress_news_images_auto_size覆盖,它定义了图片固定的最大尺寸。
注意,如果你设置了scale_news_images_to_device为True,则图片首先将按比例缩放,然后直到它的质量下载到差于(w*h)/因子,这里w和h为当前图片在每个维度上的像素。,换言之,压缩在按比例缩放后才发生。
45、compress_news_images_max_size= None
设定jpeg的质量,图片不超过的给定的字节。如果设置了这个参数,则覆盖由compress_news_images_auto_size指定的自动压缩。最小的jpeg图片质量为5/100,所以这个参数不容易达到的限制。
46、scale_news_images_to_device= True
重新按比例缩放图片,以适应由输出设置屏幕的大小。如果不管输出设备的情况,则设为False。
47、scale_news_images= None
按比例把图片缩放到(w,h)中最大的可能大小。如果scale_news_images_to_device= True不管有没有设置设备的大小,图片都会按屏幕大小来显示。
48、resolve_internal_links= False
如果设置为True,则原来的指向文章的下载链接(URL),将不再直接指向原始的下载地址,而改为指向下载文章的拷贝。设置为True的同时,你必须实现canonicalize_internal_url方法,自己特别指定网站上这些文章拷贝的下载链接列表,来对应替换掉原始文章的URL。