[翻译]calibre中的recipes的API文档
Contents
class calibre.web.feeds.news.BasicNewsRecipe(options, log, progress_reporter)[source]
包含所有 recipe 所需逻辑的基类. 通过逐步覆盖此类中的更多功能, 你可以逐步实现更多自定义/强大的 recipe . 有关创建 recipe 的教程, 可参考 添加你喜欢的新闻网站 .
abort_article(msg=None)
在任何预处理方法中调用此方法可以中止当前文章的下载. 用于跳过包含不当内容的文章, 例如纯视频文章.
abort_recipe_processing(msg)
使用 recipe 下载系统中止此 recipe 的下载, 并向用户显示简单的反馈消息.
add_toc_thumbnail(article, src)
使用适合用作表示目录中项目的缩略图的文章. 使用 populate_article_metadata
中的 <img>
标记的 src
属性调用此方法. 实际是否使用缩略图取决于设备(目前仅由 Kindle 使用). 请注意, 引用的图像必须是已成功下载的图像, 否则将被忽略.
classmethod adeify_images(soup)
如果转换为 EPUB 时的 recipe 在 Adobe Digital Edition 中查看时出现图像问题, 请在 postprocess_html()
中调用此方法
canonicalize_internal_url(url, is_link=True)
返回一组 url 的规范表示. 默认实现仅使用URL的服务器主机名和路径, 忽略任何查询参数, 片段等. 规范表示在此新闻源的所有URL中必须是唯一的. 如果不是, 则内部链接可能会被错误地解析.
参数 is_link
: 如果URL来自HTML文件中的内部链接, 则为 True. 如果URL是用于下载文章URL, 则返回 False.
cleanup()
在所有文章下载完成后调用. 使用它进行任何清理. 例如退出订阅站点等.
clone_browser(br)
克隆浏览器 br
. 克隆的浏览器用于多线程下载, 因为机械化不是线程安全的. 默认克隆例程捕获大多数浏览器自定义, 但如果你在 recipe 中执行了某些特殊操作, 则应在 recipe 中覆盖此方法并手动克隆.
除非你在自定义的 cookie 处理, 否则克隆的浏览器实例默认使用相同的线程安全的 CookieJar
default_cover(cover_file)
为没有封面的 recipe 创建通用的封面
download()
从此 recipe 中的 feed 中下载并预处理所有文章. 在特定的 recipe 实例上只应调用此方法一次. 多次调用它将导致未定义的行为. 返回 index.html
的路径.
extract_readable_article(html, url)
从 html
中提取主要文章内容, 清理并返回 (article_html, extracted_title)
元组. 基于 Arc90 的原始可读性算法.
get_article_url(article)
在子类中重写以自定义提取指向每篇文章的内容的URL. 返回文章网址. 它通过 article 调用, 该对象表示来自 feed 的已解析文章. 请参阅 feedparser . 默认情况下, 它会查找原始链接(对于通过feedburner 或 pheedo 等服务进行联合的订阅源). 如果找到则返回该链接, 否则返回 article.link
get_browser(*args, **kwargs)
返回用于从 Web 获取文档的浏览器实例. 默认情况下, 它返回支持 cookie 的机械化浏览器实例, 忽略 robots.txt
, 处理刷新并具有 mozilla firefox 用户代理.
如果你的 recipe 要求你先登录, 请在子类中覆盖此方法. 例如, 以下代码用于纽约时报的 recipe 中以登录以获取完全访问权限:
def get_browser(self):
br = BasicNewsRecipe.get_browser(self)
if self.username is not None and self.password is not None:
br.open('https://www.nytimes.com/auth/login')
br.select_form(name='login')
br['USERID'] = self.username
br['PASSWORD'] = self.password
br.submit()
return br
get_cover_url()
返回此 issue 的封面图片的 URL 或 None. 默认情况下, 它返回成员 self.cover_url
的值, 通常为 None
. 如果你希望你的 recipe 下载电子书的封面, 请在子类中覆盖此方法, 或者在调用此方法之前设置成员变量 self.cover_url
get_extra_css()
默认情况下返回 self.extra_css
. 如果要以编程方式生成 extra_css
, 请重写该方法.
get_feeds()
返回 RSS 提要列表以获取此配置文件. 列表的每个元素必须是表单 (title, url)
的两元素元组. 如果 title 为 None 或空字符串, 则使用 feed
中的标题. 如果你的 recipe 需要进行一些处理以确定要下载的 Feed 列表, 则此方法很有用. 如果这样, 请在子类中覆盖.
get_masthead_title()
在子类中重写以使用除 recipe 标题之外的其他内容
get_masthead_url()
将 URL 返回此 issue 的报头图像或 None. 默认情况下, 它返回成员 self.masthead_url
的值, 通常为 None
. 如果你希望 recipe 下载电子书的报头, 请在子类中覆盖此方法, 或者在调用此方法之前设置成员变量 self.masthead_url
. 报头图像用于 Kindle MOBI 文件.
get_obfuscated_article(url)
如果设置 articles_are_obfuscated
, 则会使每个文章 URL 调用此方法. 它应该返回包含文章HTML的文件系统上的文件的路径. 该文件由递归HTML提取引擎处理. 因此, 它可以包含指向 Web 上页面/图像的链接.
此方法通常对尝试使自动难以访问文章内容的网站有用.
classmethod image_url_processor(baseurl, url)
对图像 URL 执行一些处理(可能删除动态生成的图像的大小限制等), 并返回处理后的 URL.
index_to_soup(url_or_raw, raw=False, as_tree=False)
将 URL 带到索引页面并返回它的 BeautifulSoup 的便捷方法. url_or_raw
: URL 或下载的索引页面作为字符串
is_link_wanted(url, tag)
如果应该跟踪链接则返回 True, 否则返回 False. 默认情况下, 引发 NotImplementedError 会导致下载程序忽略它.
参数
url
: 要跟踪的 URL
tag
: 从中派生 URL 的tag
parse_feeds()
从 BasicNewsRecipe.get_feeds()
返回的 feed 列表中创建文章列表. 返回 Feed 对象列表.
parse_index()
此方法应在解析网站而不是订阅源以生成文章列表的 recipe 中实现. 典型用途是具有 “打印版” 网页的新闻来源, 该网页列出了当前印刷版中的所有文章. 如果实现此功能, 将优先使用 BasicNewsRecipe.parse_feeds()
它必须返回一个列表. 列表中的每个元素必须是表单的两元素元组 ('feed title', 文章列表)
每个文章列表必须包含以下形式的字典:
{
'title' : article title,
'url' : URL of print version,
'date' : The publication date of the article as a string,
'description' : A summary of the article
'content' : The full article (can be an empty string). Obsolete
do not use, instead save the content to a temporary
file and pass a file:///path/to/temp/file.html as
the URL.
}
有关示例, 参阅 下载 The Atlantic
. 此外, 你可以为文章作者添加 author
.
如果由于某种原因想要中止处理并让 caliber 向用户显示简单的消息而不是错误, 请调用 abort_recipe_processing()
populate_article_metadata(article, soup, first)
在下载属于文章的每个 HTML 页面时调用. 旨在用于获取作者/摘要/等文章元数据. 来自解析的 HTML(soup)
参数:
article
: 一个 calibre.web.feeds.Article
类的对象. 如果更改摘要, 请记住也要更改 text_summary
soup
: 属于该 article 的已解析的 HTML
first
: 如果解析的 HTML 是文章的第一页, 则为 True
postprocess_book(oeb, opts, log)
在解析的下载电子书上运行任何所需的后期处理
参数:
oeb
: 一个 OEBBook
对象
opts
: 转换选项
postprocess_html(soup, first_fetch)
在解析链接和图像之后, 使用每个下载的 HTML 文件的源调用此方法. 它可以用来对 HTML 进行任意强大的后处理. 它应该返回处理后的 soup
参数:
soup
: 一个包含已下载的 HTML 的 BeautifulSoup 实例
first_fetch
: 是否该文章的第一页
preprocess_html(soup)
在解析链接和图像之前, 使用每个下载的 HTML 文件的源调用此方法. 它是在 remove_tags
等指定的清理之后调用的. 它可以用来对 HTML 进行任意强大的预处理. 应该返回处理后的 soup.
preprocess_image(img_data, image_url)
对下载的图像数据执行一些处理. 在完成任何大小调整之前, 将在原始数据上调用此方法. 必须返回已处理的原始数据. 返回 None 表示跳过此图像
preprocess_raw_html(raw_html, url)
在将每个下载的 HTML 文件的源解析为对象树之前, 会调用此方法. raw_html
是一个 unicode 字符串, 表示从 Web 下载的原始 HTML. url
是从中下载 HTML的 URL. 请注意, 此方法在 preprocess_regexps
之前执行.
此方法必须将已处理的 raw_html
作为 unicode 对象返回.
classmethod print_version(url)
使用指向包含文章内容的网页的 URL 并返回指向文章的打印版本的 URL. 默认情况下, 什么也不做. 例如
def print_version(self, url):
return url + '?&pagewanted=print'
skip_ad_pages(soup)
在应用 remove_tags
, keep_only_tags
之类的任何清理属性之前, 使用每个下载的 HTML 文件的源调用此方法. 请注意, process_regexps
已经应用. 它指在允许 recipe 跳过广告页面. 如果 soup 代表广告页面, 则返回真实的 HTML . 否则返回 None.
sort_index_by(index, weights)
根据权重对索引中的标题进行排序的便捷方法. index 已按顺序排序. 返回 index .
index
: 标题列表.
weights
: 将权重映射到标题的字典. 如果 index 中的任何标题不是权重, 则假定它的权重为 0
classmethod tag_to_string(tag, use_alt=True, normalize_whitespace=True)
采用 BeautifulSoup 标签并以递归方式从中提取文本的便捷方法. 包括任何 CDATA 部分和 alt 标签属性. 返回一个可能为空的 unicode 字符串.
use_alt
: 如果为 True, 请尝试对没有任何文件内容的标记使用 alt 属性.
tag
: BeatifulSoup 标签
articles_are_obfuscated = False
设置为 True 并实现 get_obfuscated_article()
以处理试图使内容难以删除的网站.
auto_cleanup = False
自动从下载的文章页面中提取所有文本. 使用可读性项目中的算法. 将此设置为 True 意味着您不必担心手动清理下载的 HTML (尽管手动清理总是优先的)
auto_cleanup_keep = None
指定自动清理算法永远不应该删除的元素. 语法是 XPath 表达式. 例如
auto_cleanup_keep = '//div[@id="article-image"]' will keep all divs with
id="article-image"
auto_cleanup_keep = '//*[@class="important"]' will keep all elements
with class="important"
auto_cleanup_keep = '//div[@id="article-image"]|//span[@class="important"]'
will keep all divs with id="article-image" and spans
with class="important"
center_navbar = True
如果为 True, 则导航栏将居中对齐. 否则是左对齐.
compress_news_images = False
将此设置为 False, 以忽略所有缩放和压缩参数, 并通过未修改的方式传递图像. 如果为 True 且其他压缩参数保留默认值, 则将绽放 jpeg 图像以适合输出配置文件设置的屏幕尺寸, 并将其压缩至最大尺寸 (w * h) / 16, 其中 w * h 是绽放图像尺寸.
compress_news_images_auto_size = 16
自动压缩jpeg图像时使用的因子。 如果设置为“无”,则禁用自动压缩。 否则,如果可能的话,通过降低质量水平将图像的大小减小到 (w * h)/ compress_news_images_auto_size
字节,其中w x h是像素的图像尺寸。 最小jpeg质量将是5/100,因此可能无法满足此约束。 可以通过参数 compress_news_images_max_size
覆盖此参数,该参数为图像提供固定的最大大小。 请注意,如果启用 scale_news_images_to_device
,则首先缩放图像,然后降低其质量,直到其大小小于(w * h)/因子
,其中w和h现在是缩放的图像尺寸。 换句话说,这种压缩发生在缩放之后。
compress_news_images_max_size = None
设置jpeg质量,使图像不超过给定的大小(以KB为单位)。 如果设置,此参数将通过 compress_news_images_auto_size
覆盖自动压缩。 最小jpeg质量将是5/100,因此可能无法满足此约束。
conversion_options = {}
recipe 特定选项,用于控制将下载内容转换为电子书。 这些将覆盖任何用户或插件指定的值,因此仅在绝对必要时使用。 例如:
conversion_options = {
'base_font_size' : 16,
'tags' : 'mytag1,mytag2',
'title' : 'My Title',
'linearize_tables' : True,
}
cover_margins = (0, 0, ‘#ffffff’)
默认情况下,get_cover_url()
返回的封面图像将用作期刊的封面。 在配方中覆盖它会指示口径将下载的封面渲染到框架中,框架的宽度和高度表示为下载封面的百分比。 cover_margins =(10,15,'#fffffff')
用左边和右边的10px白色边缘填充封面,顶部和底部15px。 在 https://www.imagemagick.org/script/color.php
中定义的颜色名称请注意,由于某种原因,白色并不总是在Windows中有效。 请改用#ffffff
delay = 0
连续下载之间的延迟(秒)。 参数可以是浮点数,以指示更精确的时间。
description = u”
描述此 recipe 下载内容的几行。 这将主要用于显示 recipe 列表的 GUI 中
encoding = None
为具有不正确的字符集规范的站点指定覆盖编码。 最常见的是指定latin1并使用cp1252。 如果为None,请尝试检测编码。 如果它是可调用的,则使用两个参数调用callable:recipe 对象和要解码的源。 它必须返回已解码的源。
extra_css = None
指定应添加到下载的HTML文件的任何额外CSS。 它将被插入到<style>
标记中,就在结束</ head>
标记之前,从而覆盖除了使用各个HTML标记上的style属性声明的CSS之外的所有CSS。 请注意,如果要以编程方式生成extra_css
,请改为覆盖get_extra_css()
方法。 例如:
extra_css = '.heading { font: serif x-large }'
feeds = None
要下载的订阅源列表。 可以是[url1,url2,...]
或[('title1',url1),('title2',url2),...]
filter_regexps = []
正则表达式列表,用于确定要忽略的链接。 如果为空,则忽略它。 仅在未实现is_link_wanted
时使用。 例如:
filter_regexps = [r'ads \ .doubleclick \ .net']
将删除其中包含ads.doubleclick.net
的所有网址。
只应定义BasicNewsRecipe.match_regexps
或BasicNewsRecipe.filter_regexps
中的一个。
handle_gzip = False
如果要使用gziped传输,请设置为True。 请注意,有些旧服务器会因此而脱落,因此默认情况下它是关闭的。
ignore_duplicate_articles = None
忽略多个部分中存在的重复文章。 重复文章是具有相同标题和/或URL的文章。 要忽略具有相同标题的文章,请将其设置为:
ignore_duplicate_articles = {'title'}
要改用URL,请将其设置为:
ignore_duplicate_articles = {'url'}
要匹配标题或网址,请将其设置为:
ignore_duplicate_articles = {'title','url'}
keep_only_tags = []
仅保留指定的标签及其子项。 有关指定标记的格式,请参阅 BasicNewsRecipe.remove_tags
。 如果此列表不为空,则<body>
标记将被清空并使用与此列表中的条目匹配的标记重新填充。 例如:
keep_only_tags = [dict(id = ['content','heading'])]
将仅保留id属性为“content”或“heading”的标记。
language = ‘und’
新闻所使用的语言。必须是ISO-639代码,长度为两个或三个字符
masthead_url = None
默认情况下,caliber将使用报头的默认图像(仅限Kindle)。 在您的 recipe 中覆盖它以提供用作标头的URL
match_regexps = []
正则表达式列表,用于确定要遵循的链接。 如果为空,则忽略它。 仅在未实现 is_link_wanted
时使用。 例如:
match_regexps = [r'page = [0-9] +']
将匹配其中包含 page =某个数字
的所有网址。
只应定义 BasicNewsRecipe.match_regexps
或 BasicNewsRecipe.filter_regexps
中的一个。
max_articles_per_feed = 100
从每个Feed下载的最大文章数。 这主要适用于没有文章日期的Feed。 对于大多数Feed,您应该使用 BasicNewsRecipe.oldest_article
needs_subscription = False
如果为True,GUI将询问用户下载时使用的用户名和密码。 如果设置为“可选”,则使用用户名和密码将成为可选项
no_stylesheets = False
方便的标志,用于禁用加载样式表的样式表,这些样式表具有过于复杂的样式表,不适合转换为电子书格式。 如果为 True, 则不下载和处理样式表(css)
oldest_article = 7.0
从这个新闻来源下载的最旧文章。 单位天
preprocess_regexps = []
要在下载的HTML上运行的正则表达式替换规则列表。 列表的每个元素都应该是一个两元素元组。 元组的第一个元素应该是编译的正则表达式,第二个元素是一个可调用的,它接受一个匹配对象并返回一个字符串来替换匹配。 例如:
preprocess_regexps = [
(re.compile(r'<!--Article ends here-->.*</body>', re.DOTALL|re.IGNORECASE),
lambda match: '</body>'),
]
将删除从<! - 文章结束 - >
到</ body>
的所有内容。
publication_type = ‘unknown’
出版物类型设置为报纸,杂志或博客。 如果设置为None,则不会将发布类型元数据写入opf文件。
recipe_disabled = None
设置为非空字符串以禁用此 recipe 。 该字符串将用作禁用的消息.
recursions = 0
文章网页上要遵循的链接级别数
remove_attributes = []
要从所有标记中删除的属性列表。 例如:
remove_attributes = ['style', 'font']
remove_empty_feeds = False
如果为 True, 则从输出中删除空 Feed. 如果在子类中重写 parse_index
,则此选项无效。 它仅适用于使用feed或get_feeds()
返回Feed列表的 recipe。 如果使用 ignore_duplicate_articles
选项,也会使用它。
remove_javascript = True
方便的标记, 从下载的HTML中剥离所有javascript标记
remove_tags = []
要删除的标签列表。 从下载的HTML中删除指定的标记。 标记被指定为表单的字典:
{
name : 'tag name', #e.g. 'div'
attrs : a dictionary, #e.g. {class: 'advertisment'}
}
所有键都是可选的。 有关搜索条件的完整说明,请参阅 Beautiful Soup 一个常见示例子:
remove_tags = [dict(name='div', attrs={'class':'advert'})]
这将从下载的HTML中删除所有 <div class =“advert”>
标签及其所有子项。
remove_tags_after = None
删除指定标记之后出现的所有标记。 有关指定标记的格式,请参阅 BasicNewsRecipe.remove_tags
。 例如:
remove_tags_after = [dict(id='content')]
将删除 id =“content”
的第一个元素后的所有标记。
remove_tags_before = None
删除指定标记之前出现的所有标记。 有关指定标记的格式,请参阅 BasicNewsRecipe.remove_tags
。 例如:
remove_tags_before = dict(id='content')
将删除 id =“content”
的第一个元素之前的所有标记。
requires_version = (0, 6, 0)
使用此 recipe 所需的最低的 calibre 版本
resolve_internal_links = False
如果设置为True,则下载文章中指向其他下载文章的链接将更改为指向文章的下载副本而不是其原始Web URL。 如果将此属性设置为True,则可能还需要实现 canonicalize_internal_url()
以使用特定网站的URL方案。
reverse_article_order = False
反转每个Feed中文章的顺序
scale_news_images = None
要将图像缩放到的最大尺寸(w,h)
。 如果 scale_news_images_to_device
为True,则将其设置为输出配置文件设置的设备屏幕尺寸,除非没有配置文件集,在这种情况下,它将保留为已分配的任何值(默认为None)。
scale_news_images_to_device = True
重新缩放图像以适合输出配置文件设置的设备屏幕尺寸。 如果未设置输出配置文件,则忽略。
simultaneous_downloads = 5
同时下载的数量。 如果服务器挑剔,则设置为1。 如果BasicNewsRecipe.delay> 0,则自动减少为1
summary_length = 500
简要的最大字符串长度
template_css = u'\n .article_date {\n color: gray; font-family: monospace;\n }\n\n .article_description {\n text-indent: 0pt;\n }\n\n a.article {\n font-weight: bold; text-align:left;\n }\n\n a.feed {\n font-weight: bold;\n }\n\n .calibre_navbar {\n font-family:monospace;\n }\n '
用于设置模板样式的CSS,即导航栏和目录。 您应该在配方中使用extra_css来自定义外观,而不是覆盖此变量。
timefmt = ‘ [%a, %d %b %Y]’
第一页上显示的日期的格式字符串。 默认情况下:Day_Name,Day_Number Month_Name Year
timeout = 120.0
在几秒钟内从服务器获取文件的超时
title = u’Unknown News Source’
电子书的标题
use_embedded_content = None
通常我们会根据嵌入内容的长度来猜测Feed是否包含完整的文章。 如果为None,则使用默认猜测。 如果为True,那么我们总是假设Feed已嵌入内容,如果为False,我们始终假设Feed没有嵌入内容。