calibre的recipe接口(API)之——参数设置

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。