Документация 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 с атрибутом src тега <img> из статьи, который подходит для использования в качестве эскиза, представляющего статью в Оглавлении. Используется ли миниатюра на самом деле, зависит от устройства (сейчас используется только в Kindle). Обратите внимание, что указанное изображение должно быть успешно загружено, иначе оно будет проигнорировано.

classmethod adeify_images(soup)

Если ваш рецепт при преобразовании в EPUB имеет проблемы с изображениями при просмотре в Adobe Digital Editions, вызовите этот метод изнутри postprocess_html().

canonicalize_internal_url(url, is_link=True)

Вернуть набор канонических представлений url. Реализация по умолчанию использует только имя хоста сервера и путь URL-адреса, игнорируя любые параметры запроса, фрагменты и т.д. Канонические представления должны быть уникальными для всех URL-адресов для этого источника новостей. В противном случае внутренние ссылки могут быть разрешены неверно.

Параметры

is_link – Имеет значение True, если URL-адрес поступает по внутренней ссылке в файле HTML. False, если URL-адрес является URL-адресом, используемым для загрузки статьи.

cleanup()

Вызывается после загрузки всех статей. Используйте его для любой очистки, например, для выхода с сайтов подписки и т. д.

clone_browser(br)

Клонировать браузер br. Клонированные браузеры используются для многопоточной загрузки, поскольку механизация не является потокобезопасной. Подпрограммы клонирования по умолчанию должны фиксировать большинство настроек браузера, но если вы делаете что-то экзотическое в своем рецепте, вам следует переопределить этот метод в своем рецепте и клонировать вручную.

Клонированные экземпляры браузера по умолчанию используют тот же потокобезопасный CookieJar, если вы не настроили обработку файлов cookie.

default_cover(cover_file)

Create a generic cover for recipes that don’t have a cover

download()

Загрузить и предварительно обработать все статьи из каналов в этом рецепте. Этот метод следует вызывать только один раз для конкретного экземпляра Recipe. Вызов его более одного раза приведет к неопределенному поведению. :return:Путь к index.html

extract_readable_article(html, url)

Извлечь основное содержание статьи из html, очистить и вернуть в виде кортежа (article_html, extract_title). На основе оригинального алгоритма читаемости от Arc90.

get_article_url(article)

Override in a subclass to customize extraction of the URL that points to the content for each article. Return the article URL. It is called with article, an object representing a parsed article from a feed. See feedparser. By default it looks for the original link (for feeds syndicated via a service like feedburner or pheedo) and if found, returns that or else returns article.link.

get_browser(*args, **kwargs)

Вернуть экземпляр браузера, используемый для получения документов из Интернета. По умолчанию он возвращает экземпляр браузера mechanize, который поддерживает файлы cookie, игнорирует robots.txt, обрабатывает обновления и имеет пользовательский агент mozilla firefox.

If your recipe requires that you login first, override this method in your subclass. For example, the following code is used in the New York Times recipe to login for full access:

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()

Return a URL to the cover image for this issue or None. By default it returns the value of the member self.cover_url which is normally None. If you want your recipe to download a cover for the e-book override this method in your subclass, or set the member variable self.cover_url before this method is called.

get_extra_css()

По умолчанию возвращает self.extra_css. Переопределите, если вы хотите программно сгенерировать файл extra_css.

get_feeds()

Вернуть список RSS каналов для получения в этом профиле. Каждый элемент списка д. б. двухэлементным кортежем формы (заголовок, URL). Если заголовок - None или пустая строка, используется заголовок из фида. Метод полезен, если рецепт требует вычисления списка каналов для загрузки. Если так, переопределите в своем подклассе.

get_masthead_title()

Переопределить в подклассе, чтобы использовать что-то другое, кроме названия рецепта

get_masthead_url()

Вернуть URL к изображению masthead для этой проблемы или None. По умолчанию возвращает значение члена self.masthead_url, которое обычно равно None. Если вы хотите, чтобы ваш рецепт загружал заголовок для электронной книги, переопределите этот метод в своем подклассе или установите переменную члена self.masthead_url перед вызовом этого метода. Изображения masthead используются в файлах Kindle MOBI.

get_obfuscated_article(url)

Если установлен параметр article_are_obfuscated, этот метод вызывается с каждым URL статьи. Он должен вернуть путь к файлу в файловой системе, который содержит HTML статьи. Этот файл обрабатывается механизмом рекурсивной выборки HTML, поэтому он может содержать ссылки на страницы/изображения в Интернете.

Этот метод обычно полезен для сайтов, которые пытаются затруднить автоматический доступ к содержимому статьи.

classmethod image_url_processor(baseurl, url)

Выполнить некоторую обработку URL-адресов изображений (возможно, снять ограничения на размер для динамически создаваемых изображений и т.д.) и вернуть предварительно обработанный URL-адрес.

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

Удобный метод, который принимает URL-адрес на страницу индекса и возвращает его `BeautifulSoup https://www.crummy.com/software/BeautifulSoup/bs4/doc`__.

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().

It must return a list. Each element of the list must be a 2-element tuple of the form ('feed title', list of articles).

Каждый список статей должен содержать словари вида:

{
'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 для автора статьи.

Если вы хотите по какой-то причине прервать обработку, то чтобы calibre показал пользователю простое сообщение вместо ошибки, вызовите abort_recipe_processing().

populate_article_metadata(article, soup, first)

Вызывается при загрузке каждой HTML-страницы, принадлежащей статье. Предназначен для получения метаданных статьи, таких как автор/резюме/и т. д. из разобранного HTML (soup)

Параметры

• article – Объект класса calibre.web.feeds.Article. Если вы измените сводку, не забудьте также изменить text_summary

• soup – Разобранный HTML, принадлежащий этой статье

• first – True, если проанализированный HTML - первая страница статьи.

postprocess_book(oeb, opts, log)

Запустить любую необходимую постобработку для проанализированной загруженной электронной книги.

Параметры

• oeb – OEBBook объект

• opts – Опции конвертации

postprocess_html(soup, first_fetch)

Этот метод вызывается для источника каждого загруженного файла HTML после его анализа на наличие ссылок и изображений. Можно использовать для постобработки HTML. После обработки он должен вернуть soup.

Параметры

• soup – A BeautifulSoup instance containing the downloaded HTML.

• first_fetch – True если это первая страница статьи.

preprocess_html(soup)

Этот метод вызывается для источника каждого загруженного файла: term: HTML перед анализом на предмет ссылок и изображений. Он вызывается после очистки, remove_tags и т. д. Можно использовать для предварительной обработки HTML. После обработки он должен вернуть soup.

soup: экземпляр` BeautifulSoup <https://www.crummy.com/software/BeautifulSoup/bs4/doc/>`__, содержащий загруженный HTML.

preprocess_image(img_data, image_url)

Выполнить обработку загруженных данных изображения. Вызывается для сырых данных перед изменением размера. Должен возвращать обработанные сырые данные. Вернуть None, чтобы пропустить изображение.

preprocess_raw_html(raw_html, url)

Этот метод вызывается для источника каждого загруженного файла HTML перед его синтаксическим анализом в дерево объектов. raw_html - это Юникод-строка, представляющая необработанный HTML-код, загруженный из Интернета. url - это URL-адрес, откуда был загружен HTML-код.

Note that this method acts before preprocess_regexps.

Этот метод должен возвращать обработанный raw_html как Unicode-объект .

classmethod print_version(url)

Взять url, указывающий на веб-страницу с содержанием статьи, и вернуть URL, указывающий на печатную версию статьи. По умолчанию ничего не делает. Например:

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

skip_ad_pages(soup)

Этот метод вызывается для источника каждого загруженного файла HTML перед применением любого из атрибутов очистки, таких как remove_tags, keep_only_tags. Обратите внимание, что preprocess_regexps уже был применен. Это сделано для того, чтобы рецепт пропускал рекламные страницы. Если soup - рекламная страница, вернуть HTML реальной страницы. Иначе вернуть None.

soup: экземпляр` BeautifulSoup <https://www.crummy.com/software/BeautifulSoup/bs4/doc/>`__, содержащий загруженный HTML.

sort_index_by(index, weights)

Удобный метод сортировки заголовков в index по weights. index сортируется на месте. Возвращает index.

index: A list of titles.

weights: словарь, который отображает веса в названия. Если какие-либо названия в индексе не имеют веса, предполагается, что они имеют вес 0.

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

Удобный метод для того, чтобы взять `BeautifulSoup https://www.crummy.com/software/BeautifulSoup/bs4/doc/`_: code:` Tag` и рекурсивно извлечь из него текст, включая любые разделы CDATA и атрибуты тегов alt. Вернуть возможно пустую строку Unicode.

use_alt: If True try to use the alt attribute for tags that don’t have any textual content

tag: BeautifulSoup Tag

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

If True the navigation bar is center aligned, otherwise it is left aligned

compress_news_images = False

Установите значение False, чтобы игнорировать все параметры масштабирования и сжатия и передавать изображения без изменений. Если True и другие параметры сжатия оставлены в значениях по умолчанию, изображения JPEG будут масштабированы, чтобы соответствовать размерам экрана, установленным выходным профилем, и сжиматься до размера не более (w * h) / 16, где w x 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) / 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 пикселей сверху и снизу. Названия цветов определены здесь. Учтите, что белый цвет почему-то не всегда работает в Windows. Вместо этого используйте #ffffff

delay = 0

Delay between consecutive downloads in seconds. The argument may be a floating point number to indicate a more precise time.

description = ''

A couple of lines that describe the content this recipe downloads. This will be used primarily in a GUI that presents a list of recipes.

encoding = None

Указать переопределяемую кодировку для сайтов с неправильным указанием кодировки. Чаще всего указывается latin1 и используется cp1252. Если None, попробует определить кодировку. Объект вызывается с двумя аргументами: объектом рецепта и источником для декодирования. Он должен возвращать декодированный источник.

extra_css = None

Указать любую дополнительную :term: CSS, которая д. б. добавлена к загружаемым HTML файлам. Она будет вставлена в <style>`теги `непосредственно перед закрывающим `</head>`тегом, переопределив все :term:`CSS, за исключением той, которая объявлена с использованием стилевого атрибута в отдельных тегах HTML. Обратите внимание: если вы хотите программно сгенерировать extra_css, вместо этого переопределите метод get_extra_css (). Например:

extra_css = '.heading { font: serif x-large }'

feeds = None

List of feeds to download. Can be either [url1, url2, ...] or [('title1', url1), ('title2', url2),...]

filter_regexps = []

Список регулярных выражений, определяющий, какие ссылки игнорировать. Если пустой - игнорируется. Используется, только если is_link_wanted не реализован. Например:

filter_regexps = [r'ads\.doubleclick\.net']

will remove all URLs that have ads.doubleclick.net in them.

Должен быть определен только один из BasicNewsRecipe.match_regexps или BasicNewsRecipe.filter_regexps.

handle_gzip = False

Установить True, если вы хотите использовать передачу в формате gziped. Обратите внимание, что некоторые старые серверы с этим не работают, поэтому по умолчанию он отключен.

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 «content» или «heading».

language = 'und'

Язык новостей. Должен быть двух- или трёхзначным кодом ISO-639.

masthead_url = None

По умолчанию calibre будет использовать изображение по умолчанию для шапки (только Kindle). Переопределите это в своем рецепте, чтобы указать URL-адрес для использования в качестве шапки.

match_regexps = []

List of regular expressions that determines which links to follow. If empty, it is ignored. Used only if is_link_wanted is not implemented. For example:

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

будет соответствовать всем URL-адресам, в которых есть page = some number.

Должен быть определен только один из BasicNewsRecipe.match_regexps или BasicNewsRecipe.filter_regexps.

max_articles_per_feed = 100

Максимальное количество статей для загрузки из каждого канала. Это в первую очередь полезно для каналов, в которых нет дат статьи. Для большинства каналов вы должны использовать BasicNewsRecipe.oldest_article

needs_subscription = False

Если True, графический интерфейс запросит у пользователя имя пользователя и пароль для использования при загрузке. Если установлено значение „optional“, использование имени пользователя и пароля становится необязательным.

no_stylesheets = False

Convenient flag to disable loading of stylesheets for websites that have overly complex stylesheets unsuitable for conversion to e-book formats. If True stylesheets are not downloaded and processed

oldest_article = 7.0

Самая старая статья для загрузки из этого источника новостей. В днях.

preprocess_regexps = []

Список правил подстановки regexp для запуска в загруженном HTML. Каждый элемент списка должен быть двухэлементным кортежем. Первый элемент кортежа должен быть скомпилированным регулярным выражением, а второй - вызываемым, который принимает единственный соответствующий объект и возвращает строку для замены совпадения. Например:

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

удалит все от <!–Article ends here–>` до </body>.

publication_type = 'unknown'

Тип публикации Газета, журнал или блог. Если установлено значение Нет, метаданные типа публикации не будут записываться в файл opf.

recipe_disabled = None

Установите непустую строку, чтобы отключить этот рецепт. Строка будет использоваться как отключенное сообщение

recursions = 0

Количество уровней ссылок для перехода на веб-страницах статей

remove_attributes = []

Список атрибутов, которые нужно удалить из всех тегов. Например:

remove_attributes = ['style', 'font']

remove_empty_feeds = False

Если True, пустые каналы удаляются из вывода. Эта опция не действует, если parse_index переопределен в подклассе. Он предназначен только для рецептов, которые возвращают список каналов с использованием feeds или get_feeds(). Он также используется, с опцией ignore_duplicate_articles.

remove_javascript = True

Convenient flag to strip all JavaScript tags from the downloaded HTML

remove_tags = []

Список удаляемых тегов. Указанные теги удаляются из загруженного HTML. Тег задается как словарь формы:

{
 name      : 'tag name',   #e.g. 'div'
 attrs     : a dictionary, #e.g. {'class': 'advertisment'}
}

Все ключи необязательны. Полное объяснение критериев поиска см. В `Beautiful Soup https://www.crummy.com/software/BeautifulSoup/bs4/doc/#searching-the-tree`__ A common example:

remove_tags = [dict(name='div', class_='advert')]

Это приведет к удалению всех тегов <div class=»advert»> и всех их дочерних элементов из загруженного HTML.

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, то ссылки в загруженных статьях, которые указывают на другие загруженные статьи, изменяются, чтобы указывать на загруженную копию статьи, а не на ее исходный веб-URL. При установке значения True, вам также может потребоваться реализовать canonicalize_internal_url() для работы со схемой URL-адресов вашего конкретного веб-сайта.

reverse_article_order = False

Измените порядок статей в каждом фиде

scale_news_images = None

Максимальные размеры (ширина, высота) для масштабирования изображений. Если scale_news_images_to_device имеет значение True, для него устанавливаются размеры экрана устройства, заданные выходным профилем, если профиль не задан, и в этом случае он остается в том значении, которое было назначено (по умолчанию None).

scale_news_images_to_device = True

Rescale images to fit in the device screen dimensions set by the output profile. Ignored if no output profile is set.

simultaneous_downloads = 5

Количество одновременных загрузок. Установите 1, если сервер придирчив. Автоматически уменьшается до 1, если BasicNewsRecipe.delay > 0

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    '

The CSS that is used to style the templates, i.e., the navigation bars and the Tables of Contents. Rather than overriding this variable, you should use extra_css in your recipe to customize look and feel.

timefmt = ' [%a, %d %b %Y]'

Строка формата даты, показанной на первой странице. По умолчанию: Day_Name, Day_Number Month_Name Year

timeout = 120.0

Таймаут для загрузки файлов с сервера в секундах

title = 'Неизвестный новостной ресурс'

Название для электронной книги

use_embedded_content = None

Обычно попытка угадать, есть ли в фиде встроенные полные статьи, основывается на длине встроенного контента. Если «Нет», то используется угадывание по умолчанию. Если True - всегда предполагается, что у каналов есть встроенный контент, False - всегда предполагается, что у каналов нет встроенного контента.

© Копирайт Kovid Goyal. Последнее обновление апр. 17, 2021.