清单的API文档

编写清单的API由"BasicNewsRecipe"定义

class calibre.web.feeds.news.BasicNewsRecipe(options, log, progress_reporter)

包含所有新闻源所需逻辑的基类。 通过逐渐覆盖此类中的更多功能，您可以逐渐制作更加定制/强大的新闻源。 有关创建新闻源的教程介绍，请参阅“新闻”。

abort_article(msg=None)

在任何预处理方法中调用此方法可中止当前文章的下载。 有助于跳过包含不当内容的文章，例如纯视频文章。

abort_recipe_processing(msg)

导致新闻源下载系统中止此新闻源的下载，并向用户显示一条简单的反馈消息。

add_toc_thumbnail(article, src)

从 populate_article_metadata 调用此方法，并使用文章中 <img>标记的 src 属性，该标记适合用作代表目录中文章的缩略图。 缩略图是否实际使用取决于设备（目前仅由 Kindle 使用）。 注意，引用的图片必须是已成功下载的图片，否则会被忽略。

classmethod adeify_images(soup)

如果您的新闻在转换为 EPUB 后在 Adobe Digital Editions 中查看时出现图像问题，请从“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。 克隆浏览器用于多线程下载，因为 mechanize 不是线程安全的。 默认克隆例程应该捕获大多数浏览器自定义，但如果您在新闻源中做了一些奇怪的事情，则应该在新闻源中覆盖此方法并手动克隆。

默认情况下，克隆的浏览器实例使用相同的线程安全 CookieJar，除非您自定义了 cookie 处理。

default_cover(cover_file)

为没有封面的新闻源创建通用封面

download()

下载并预处理本新闻源中提要中的所有文章。 该方法只能在特定的 Recipe 实例上调用一次。 多次调用它会导致未定义的行为。 index.html 的路径

extract_readable_article(html, url)

从“html”中提取主要文章内容，进行清理并以（article_html，extracted_title）元组形式返回。 基于Arc90原创的可读性算法。

get_article_url(article)

在子类中重写以自定义指向每篇文章内容的“URL”的提取。 返回文章网址。 它通过“article”来调用，“article”是一个表示来自提要的已解析文章的对象。 请参阅“feedparser <https://pythonhosted.org/feedparser/>”_。 默认情况下，它会查找原始链接（通过 FeedBurner 或 Pheedo 等服务联合供稿），如果找到，则返回该链接，否则返回“https://pythonhosted.org/feedparser/reference-entry-link.html>`_。

get_browser(*args, **kwargs)

返回用于从Web获取文档的浏览器实例。默认情况下，它返回一个'机械化<https://mechanize.readthedocs.io/en/latest/>'_浏览器实例，该实例支持cookie、忽略robots. text、处理刷新并具有随机的公共用户代理。

要自定义浏览器，请在您的子类别中重写此方法：

def get_browser(self, *a, **kw):
    br = super().get_browser(*a, **kw)
    # Add some headers
    br.addheaders += [
        ('My-Header', 'one'),
        ('My-Header2', 'two'),
    ]
    # Set some cookies
    br.set_cookie('name', 'value')
    br.set_cookie('name2', 'value2', domain='.mydomain.com')
    # Make a POST request with some data
    br.open('https://someurl.com', {'username': 'def', 'password': 'pwd'}).read()
    # Do a login via a simple web form (only supported with mechanize browsers)
    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()

返回此问题封面图片的“URL”或“None”。 默认情况下，它返回成员“self.cover_url”的值，通常为“None”。 如果您希望您的新闻源下载电子书的封面，请在子类中重写此方法，或者在调用此方法之前设置成员变量“self.cover_url”。

get_extra_css()

默认情况下返回“self.extra_css”。 如果您想以编程方式生成 extra_css，请覆盖。

get_feeds()

返回要为此配置文件获取的“RSS”提要列表。 列表中的每个元素必须是 (title, url) 形式的 2 元素元组。 如果 title 为 None 或空字符串，则使用提要中的标题。 如果您的新闻源需要进行一些处理来找出要下载的提要列表，则此方法非常有用。 如果是这样，请在您的子类中重写。

get_masthead_title()

在子类中重写以使用新闻源标题以外的内容

get_masthead_url()

返回此问题的标头图片的“URL”或“无”。 默认情况下，它返回成员“self.masthead_url”的值，通常为“None”。 如果您希望您的新闻源下载电子书的标头，请在子类中重写此方法，或者在调用此方法之前设置成员变量 self.masthead_url 。 标头图像用于 Kindle MOBI 文件中。

get_obfuscated_article(url)

如果您设置了“articles_are_obfuscated”，则每个文章 URL 都会调用此方法。 它应该返回文件系统上包含文章 HTML 的文件的路径。 该文件由递归 HTML 获取引擎处理，因此它可以包含指向 Web 上的页面/图像的链接。 或者，您可以返回以下形式的字典：{'data': 1, 'url': 2}。 这避免了需要创建临时文件。 如果文章的有效 URL 与传递到此方法的 URL 不同，例如由于重定向，则字典中的“url”键很有用。 如果 URL 不变，则可以省略。

此方法通常适用于试图阻止自动访问文章内容的网站。

get_url_specific_delay(url)

返回下载此 URL 之前的延迟，以秒为单位。 如果您想以编程方式确定指定 URL 的延迟，请在子类中重写此方法，默认情况下为您不想影响的 URL 返回 self.delay。

返回:

浮点数，以秒为单位的延迟。

classmethod image_url_processor(baseurl, url)

对图像 url 执行一些处理（可能消除动态生成的图像的大小限制等）并返回处理后的 URL。 返回 None 或空字符串以跳过获取图像。

index_to_soup(url_or_raw, raw=False, as_tree=False, save_raw=None)

便捷方法，获取索引页面的 URL 并返回它的 BeautifulSoup。

url_or_raw：URL 或下载的索引页作为字符串

is_link_wanted(url, tag)

如果应遵循链接，则返回 True，否则返回 False。 默认情况下，引发 NotImplementedError ，导致下载器忽略它。

参数:

• url -- 要关注的 URL

• tag -- 派生 URL 的标签

parse_feeds()

从“BasicNewsRecipe.get_feeds”返回的提要列表中创建文章列表。 返回“Feed”对象的列表。

parse_index()

此方法应该在解析网站而不是提要来生成文章列表的新闻源中实现。 典型用途是具有“印刷版”网页的新闻源，其中列出了当前印刷版的所有文章。 如果实现此功能，它将优先于“BasicNewsRecipe.parse_feeds”使用。

它必须返回一个列表。 列表中的每个元素必须是形式为``('提要标题'，文章列表)`` 的 2 元素元组。

每个文章列表必须包含以下形式的字典：

{
'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”的方法。 此外，您可以为文章的作者添加“作者”。

如果您想出于某种原因中止处理并让 calibre 向用户显示一条简单的消息而不是错误，请调用“abort_recipe_processing”。

populate_article_metadata(article, soup, first)

下载属于文章的每个 HTML 页面时调用。 旨在用于获取文章元数据，如作者/摘要/等。 来自解析的 HTML（汤）。

参数:

• article -- calibre.web.feeds.Article 类的对象。 如果更改摘要，请记住同时更改 text_summary

• soup -- 属于本文的已解析 HTML

• first -- 当且仅当解析的 HTML 是文章的第一页时为 true。

postprocess_book(oeb, opts, log)

对已解析的下载电子书运行任何所需的后处理。

参数:

• oeb -- 一个 OEBBook 对象

• opts -- 转换选项

postprocess_html(soup, first_fetch)

在解析链接和图像后，使用每个下载的 HTML 文件的源调用此方法。 它可用于对 HTML 进行任意强大的后处理。 处理后它应该返回`soup`。

参数:

• soup -- 一个 BeautifulSoup 实例，包含下载的 HTML。

• first_fetch -- 如果这是文章的第一页，则为 true。

preprocess_html(soup)

在解析链接和图像之前，使用每个下载的“HTML”文件的源调用此方法。 它在remove_tags等指定的清理之后被调用。它可以用来对“HTML”进行任意强大的预处理。 处理后它应该返回`soup`。

soup：一个 BeautifulSoup 实例，包含下载的 HTML。

preprocess_image(img_data, image_url)

对下载的图像数据进行一些处理。 在完成任何大小调整之前，会对原始数据调用此方法。 必须返回处理后的原始数据。 返回 None 以跳过图像。

preprocess_raw_html(raw_html, url)

在将每个下载的 HTML 文件解析为对象树之前，会调用此方法。 raw_html 是一个 unicode 字符串，表示从网络下载的原始 HTML。 url 是下载 HTML 的 URL。

请注意，此方法在 preprocess_regexps *之前*起作用。

此方法必须将处理后的 raw_html 作为 unicode 对象返回。

classmethod print_version(url)

获取指向包含文章内容的网页的“url”，并返回指向文章打印版本的“URL”。 默认情况下不执行任何操作。 例如：

def print_version(self, url):
    return url + '?&pagewanted=print'

publication_date()

使用此方法设置此问题的发布日期。 默认为下载时刻。 必须返回一个“datetime.datetime”对象。

skip_ad_pages(soup)

在应用任何清理属性（如remove_tags、keep_only_tags）之前，使用每个下载的 HTML 文件的源调用此方法。 请注意，preprocess_regexps 已被应用。 它的目的是允许菜谱跳过广告页面。 如果汤代表广告页面，则返回真实页面的 HTML。 否则返回 None。

soup：一个 BeautifulSoup 实例，包含下载的 HTML。

sort_index_by(index, weights)

根据“权重”对“索引”中的标题进行排序的便捷方法。 index 已就地排序。 返回“索引”。

index: 标题列表。

weights：将权重映射到标题的字典。 如果索引中的任何标题不在权重中，则假定它们的权重为 0。

classmethod tag_to_string(tag, use_alt=True, normalize_whitespace=True)

获取 BeautifulSoup Tag 并从中递归提取文本的便捷方法，包括任何 CDATA 部分和 alt 标签属性。 返回一个可能为空的 Unicode 字符串。

use_alt：如果为`True`，则尝试对没有任何文本内容的标签使用 alt 属性

tag: BeautifulSoup 标签

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"

browser_type = 'mechanize'

从服务器下载时使用的模拟浏览器引擎。默认使用Python机械化浏览器引擎，支持登录。但是，如果您不需要登录，请考虑将其更改为“webengine”（使用实际Chromium浏览器执行网络请求）或“qt”（使用Qt Networks后台）。“webengine”和“qt”都支持HTTP/2，但机制不支持，因此更难为机器人保护服务进行指纹识别。

center_navbar = True

如果 True 则导航栏居中对齐，否则左对齐

compress_news_images = False

Set this to False to ignore all scaling and compression parameters and pass images through unmodified. If True and the other compression parameters are left at their default values, images will be scaled to fit in the screen dimensions set by the output profile and compressed to size at most (w * h)/16 where w x h are the scaled image dimensions.

compress_news_images_auto_size = 16

自动压缩 JPEG 图像时使用的系数。 如果设置为 None，则禁用自动压缩。 否则，如果可能的话，通过降低质量级别，图像的大小将减小到 (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)/factor，其中 w 和 h 现在是*缩放*图像尺寸。 换句话说，这种压缩发生在缩放之后。

compress_news_images_max_size = None

设置 JPEG 质量，使图像不超过给定的大小（以千字节为单位）。 如果设置，此参数将覆盖通过 compress_news_images_auto_size 自动压缩。 最低 JPEG 质量将为 5/100，因此可能无法满足此限制。

conversion_options = {}

用于控制将下载的内容转换为电子书的特定于新闻源的选项。 这些将覆盖任何用户或插件指定的值，因此仅在绝对必要时使用。 例如：

conversion_options = {
  'base_font_size'   : 16,
  'linearize_tables' : True,
}

cover_margins = (0, 0, '#ffffff')

默认情况下， get_cover_url() 返回的封面图像将用作期刊的封面。 在您的配方中覆盖此选项会指示 calibre 将下载的封面渲染到一个框架中，该框架的宽度和高度以下载封面的百分比表示。 cover_margins = (10, 15, '#ffffff') 在封面上填充左侧和右侧 10 像素的白边距，顶部和底部 15 像素的白边距。 颜色名称在“此处 <https://www.imagemagick.org/script/color.php>”定义。 请注意，由于某种原因，白色并不总是在 Windows 中起作用。 使用#ffffff代替

delay = 0

连续下载之间的默认延迟，以秒为单位。 该参数可以是浮点数以指示更精确的时间。 请参阅“get_url_specific_delay”来实现每个 URL 的延迟。

description = ''

几行描述了此新闻源下载的内容。 这将主要用在显示新闻源列表的 GUI 中。

encoding = None

为字符集规范不正确的站点指定覆盖编码。 最常见的是指定“latin1”并使用“cp1252”。 如果没有，请尝试检测编码。 如果它是可调用的，则使用两个参数调用可调用的：新闻源对象和要解码的源。 它必须返回解码后的源。

extra_css = None

指定应添加到下载的“HTML”文件中的任何额外“CSS”。 它将被插入到“<style>”标签中，就在结束“</head>”标签之前，从而覆盖所有“CSS”，除了在各个“HTML”标签上使用 style 属性声明的内容之外。 请注意，如果您想以编程方式生成 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 = True

如果您不想在机械化浏览器中使用gzipped传输，请设置为False。请注意，一些旧服务器因gZip而崩溃。

ignore_duplicate_articles = None

忽略出现在多个部分中的重复文章。 重复文章是指具有相同标题和/或 URL 的文章。 要忽略具有相同标题的文章，请将其设置为：

ignore_duplicate_articles = {'title'}

要改为使用 URL，请将其设置为：

ignore_duplicate_articles = {'url'}

要匹配标题或 URL，请将其设置为：

ignore_duplicate_articles = {'title', 'url'}

keep_only_tags = []

仅保留指定的标签及其子标签。 有关指定标签的格式，请参阅“BasicNewsRecipe.remove_tags”。 如果此列表不为空，则“<body>”标签将被清空并用与此列表中的条目匹配的标签重新填充。 例如：

keep_only_tags = [dict(id=['content', 'heading'])]

将仅保留具有“id”属性为“内容”或“标题”的标签。

language = 'und'

新闻所使用的语言。必须是 ISO-639 代码，长度为两个或三个字符

masthead_url = None

默认情况下，calibre 将使用默认图像作为标头（仅限 Kindle）。 在您的配方中覆盖此设置以提供用作标头的 URL。

match_regexps = []

确定要跟踪哪些链接的正则表达式列表。 如果为空，则被忽略。 仅当未实现 is_link_wanted 时使用。 例如：

match_regexps = [r'page=[0-9]+']

将匹配所有包含“page=some number”的 URL。

仅应定义“BasicNewsRecipe.match_regexps”或“BasicNewsRecipe.filter_regexps”之一。

max_articles_per_feed = 100

从每个提要下载的最大文章数。 这主要对于没有文章日期的提要有用。 对于大多数提要，您应该使用“BasicNewsRecipe.oldest_article”

needs_subscription = False

如果为 True，GUI 将要求用户提供下载时使用的用户名和密码。 如果设置为“可选”，则用户名和密码的使用将变为可选

no_stylesheets = False

方便的标志，用于禁用样式表加载的网站，这些网站的样式表过于复杂，不适合转换为电子书格式。 如果未下载和处理 True 样式表

oldest_article = 7.0

从此新闻源下载最旧的文章。 几天之内。

preprocess_regexps = []

要在下载的“HTML”上运行的“regexp”替换规则列表。 列表的每个元素应该是一个二元素元组。 元组的第一个元素应该是已编译的正则表达式，第二个元素应该是可调用的，它接受单个匹配对象并返回一个字符串来替换匹配项。 例如：

preprocess_regexps = [
   (re.compile(r'<!--Article ends here-->.*</body>', re.DOTALL|re.IGNORECASE),
    lambda match: '</body>'),
]

将删除从 <!--Articleendshere--> 到 </body> 的所有内容。

publication_type = 'unknown'

出版物类型 设置为报纸、杂志或博客。 如果设置为 None，则不会将任何发布类型元数据写入 opf 文件。

recipe_disabled = None

设置为非空字符串以禁用此新闻源。 该字符串将用作禁用消息

recipe_specific_options = None

指定此新闻源特定的选项。这些可供用户在“获取新闻”对话框的“高级”选项卡或电子书转换命令行中自定义。这些选项被指定为将选项名称映射到有关该选项的元数据的字典。例如：

recipe_specific_options = {
    'edition_date': {
        'short': 'The issue date to download',
        'long':  'Specify a date in the format YYYY-mm-dd to download the issue corresponding to that date',
        'default': 'current',
    }
}

运行配方时，self.recipe_specific_ensions将是将选项名称映射到用户指定的选项值的dict。当用户未指定该选项时，它将具有由“默认”指定的值。如果未指定默认值，则当用户未指定时，该选项根本不会出现在dict中。

recursions = 0

文章网页上可跟踪的链接级别数

remove_attributes = []

要从所有标签中删除的属性列表。 例如：

remove_attributes = ['style', 'font']

remove_empty_feeds = False

如果为 True，则从输出中删除空提要。 如果在子类中重写了 parse_index，则此选项无效。 它仅适用于使用“feeds”或“get_feeds”返回提要列表的配方。 如果您使用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', 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)

使用此新闻源所需的calibre的最低版本

resolve_internal_links = False

如果设置为 True，则下载文章中指向其他下载文章的链接将更改为指向该文章的下载副本，而不是其原始 Web URL。 如果将此设置为 True，您可能还需要实现“canonicalize_internal_url”以使用特定网站的 URL 方案。

reverse_article_order = False

颠倒每个提要中文章的顺序

scale_news_images = None

图像缩放到的最大尺寸（宽，高）。 如果scale_news_images_to_device为True，则设置为由输出配置文件设置的设备屏幕尺寸，除非没有配置文件集，在这种情况下，它将保留为已分配的任何值（默认为“无”）。

scale_news_images_to_device = True

重新缩放图像以适合输出配置文件设置的设备屏幕尺寸。 如果未设置输出配置文件，则忽略。

simultaneous_downloads = 5

同时下载的数量。 如果服务器挑剔，则设置为 1。 如果 BasicNewsRecipe.delay > 0，则自动减少到 1

summary_length = 500

简短描述中的最大字符数

template_css = '\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 = '未知新闻来源'

用于电子书的标题

use_embedded_content = None

通常，我们会尝试根据嵌入内容的长度来猜测提要是否嵌入了完整的文章。 如果“无”，则使用默认猜测。 如果为“True”，则我们始终假设提要具有嵌入内容，如果为“False”，我们始终假设提要没有嵌入内容。

© 版权 Kovid Goyal。 最后一次更新于 12月 20, 2024。