Документация 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-адрес. Вернуть None или пустую строку, чтобы пропустить загрузку изображения.

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'

publication_date()[исходный код]¶: Используйте этот метод, чтобы установить дату публикации этого выпуска. По умолчанию на момент загрузки. Должен вернуть datetime.datetime объект.

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 = True¶: Установите значение False, если вы не хотите использовать gzip-сжатие передач. Внимание! Некоторые старые серверы могут захлебнуться при включенном 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 «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 - всегда предполагается, что у каналов нет встроенного контента.