Документация 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)[исходный код]

If you set articles_are_obfuscated this method is called with every article URL. It should return the path to a file on the filesystem that contains the article HTML. That file is processed by the recursive HTML fetching engine, so it can contain links to pages/images on the web. Alternately, you can return a dictionary of the form: {„data“: <HTML data>, „url“: <the resolved URL of the article>}. This avoids needing to create temporary files. The url key in the dictionary is useful if the effective URL of the article is different from the URL passed into this method, for example, because of redirects. It can be omitted if the URL is unchanged.

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

get_url_specific_delay(url)[исходный код]

Возвращает задержку в секундах перед загрузкой этого URL. Если вы хотите программно определить задержку для указанного URL-адреса, переопределите этот метод в своём подклассе, возвращая self.delay по умолчанию для URL-адресов, на которые вы не хотите влиять.

Результат:

Число с плавающей запятой, задержка в секундах.

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, либо загруженная страница индекса в виде строки

Вернуть 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

The default delay between consecutive downloads in seconds. The argument may be a floating point number to indicate a more precise time. See get_url_specific_delay() to implement per URL delays.

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, необходимая для использования этого рецепта

Если установлено значение 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 - всегда предполагается, что у каналов нет встроенного контента.