xml2epub

批量将多个网页、html文件或图片转换为单一电子书。

特性

• 自动生成封面：如果html中的<title>文本是COVER_TITLE_LIST之一，则将自动添加封面，否则将生成默认封面。我们将随机生成与“O'Reilly”风格相似的封面图片。
• 自动获取文章的核心内容：我们过滤获取到的html字符串并保留核心内容。有关在html中保留的标签列表，请参阅SUPPORTED_TAGS。

目录

• xml2epub
  • 目录
  • 如何安装
  • 基本用法
  • API
  • 技巧
  • 常见问题解答

如何安装

xml2epub可在PyPI上找到 https://pypi.ac.cn/project/xml2epub/

$ pip install xml2epub

基本用法

import xml2epub

## create an empty eBook
book = xml2epub.Epub("My New E-book Name")
## create chapters by url
#### custom your own cover image
chapter0 = xml2epub.create_chapter_from_string("https://cdn.jsdelivr.net.cn/gh/dfface/img0@master/2022/02-10-0R7kll.png", title='cover', strict=False)
#### create chapter objects
chapter1 = xml2epub.create_chapter_from_url("https://dev.to/devteam/top-7-featured-dev-posts-from-the-past-week-h6h")
chapter2 = xml2epub.create_chapter_from_url("https://dev.to/ks1912/getting-started-with-docker-34g6")
## add chapters to your eBook
book.add_chapter(chapter0)
book.add_chapter(chapter1)
book.add_chapter(chapter2)
## generate epub file
book.create_epub("Your Output Directory")

等待一段时间后，如果没有错误报告，将在“您的输出目录”中生成以下“我的新电子书名称.epub”文件。

有关更多示例，请参阅： 示例目录。

如果我们无法从html字符串推断封面图片，我们将生成一个。随机生成的封面图片与“O'Reilly”风格相似。

API

• create_chapter_from_file(file_name, url=None, title=None, strict=True, local=False)：从html或xhtml文件创建章节对象。
  • file_name (字符串)：包含创建的章节html或xhtml内容的文件名。
  • url (可选[string])：用于推断章节标题的url。建议提供url参数，这有助于识别网页中的相对链接。
  • 标题（Option[string]）：章节的名称，如果为 None，则使用从网页文件中获取的标题标签内容作为章节名称。
  • 严格（Option[boolean]）：是否执行严格页面清理，这将删除内联样式、不重要的属性等，通常为 True。
  • 本地（Option[boolean]）：是否使用本地资源，这意味着 html 中的所有图像和 css 文件都已保存到本地，资源将直接使用 html 中的文件路径复制，而不是从互联网获取。
• create_chapter_from_url(url, title=None, strict=True, local=False)：通过从给定的 url 提取网页来创建章节对象。
  • url（string）：网站链接。建议携带 url 参数，这有助于识别网页中的相对链接。
  • 标题（Option[string]）：章节的名称，如果为 None，则使用从网页文件中获取的标题标签内容作为章节名称。
  • 严格（Option[boolean]）：是否执行严格页面清理，这将删除内联样式、不重要的属性等，通常为 True。当为 False 时，可以输入图像链接并指定标题，这对自定义封面图像很有帮助。
  • 本地（Option[boolean]）：是否使用本地资源，这意味着 html 中的所有图像和 css 文件都已保存到本地，资源将直接使用 html 中的文件路径复制，而不是从互联网获取。
• create_chapter_from_string(html_string, url=None, title=None, strict=True, local=False)：从字符串创建章节对象。上述两种方法的原理是首先获取 html 或 xml 字符串，然后调用此方法。
  • html_string（string）：html 或 xhtml 字符串、图像 url（strict=False）或 图像 路径（strict=False 和 local=True）。当它是图像时，如果不存在 title 字段或 title 字段是 COVER_TITLE_LIST 中的任何一项，例如 cover，则该图像将被用作封面。
  • url (可选[string])：用于推断章节标题的url。建议提供url参数，这有助于识别网页中的相对链接。
  • 标题（Option[string]）：章节的名称，如果为 None，则使用从网页文件中获取的标题标签内容作为章节名称。
  • 严格（Option[boolean]）：是否执行严格页面清理，这将删除内联样式、不重要的属性等，通常为 True。
  • 本地（Option[boolean]）：是否使用本地资源，这意味着 html 中的所有图像和 css 文件都已保存到本地，资源将直接使用 html 中的文件路径复制，而不是从互联网获取。
• Epub(title, creator='dfface', language='en', rights='', publisher='dfface', epub_dir=None)：创建 Epub 对象的构造函数。主要用于添加书籍信息和所有章节以及生成 epub 文件。
  • 标题（str）：epub 的 标题。
  • 创作者（Option[str]）：epub 的 作者。
  • 语言（Option[str]）：epub 的 语言。
  • 版权（Option[str]）：epub 的 版权。
  • 出版社（Option[str]）：epub 的 出版社。
  • epub_dir（Option[str]）：中间文件的路径，默认使用系统的临时文件路径，或者可以自行指定。
• Epub 对象 add_chapter(chapter_object)：将章节对象添加到 Epub。
  • chapter_object（Chapter 对象）：使用创建章节对象的三种方法获取对象。
• Epub 对象 create_epub(output_directory, epub_name=None)：从 Epub 对象创建 epub 文件。
  • 输出目录（str）：输出 epub 文件的目录。
  • epub_name（Option[str]）：epub 的文件名。文件名中的每个字符都必须是可打印的，并且通过 str.isprintable() 测试。不可打印的字符将被过滤。该文件名不应包含 .epub。如果未提供此参数，则默认为 epub 的标题。
  • 绝对位置（Option[str]）：文件的绝对路径和文件名，不包括文件类型后缀（不包含 .epub）。如果不传递，文件位置为 ${current working path}/${output_directory}/${epub_name}.epub。如果传递此参数，文件将保存到由参数指定的绝对路径。请确保您对该位置具有写权限，并且路径是合法的。
• html_clean(input_string, help_url=None, tag_clean_list=constants.TAG_DELETE_LIST, class_list=constants.CLASS_INCLUDE_LIST, tag_dictionary=constants.SUPPORTED_TAGS)：我们公开的内部默认 clean 方法，便于自定义。
  • input_string (str)：表示HTML / XML的字符串。
  • help_url (可选[str])：当前章节的URL，有助于识别网页中的相对链接。
  • tag_dictionary (可选[dict])：定义所有需要保存的标签及其类，您可以在SUPPORTED_TAGS中查看默认值。
  • tag_clean_list (可选[list])：定义所有需要删除的标签。请注意，这里将直接删除整个标签及其子标签。您可以在TAG_DELETE_LIST中查看默认值。
  • class_list (可选[list])：定义包含需要删除的类内容的所有标签，也就是说，只要任何标签的类属性包含此列表中的内容，则整个标签及其子标签都将被删除。您可以在CLASS_INCLUDE_LIST中查看默认值。

技巧

• 如果您想自己添加封面图片，请使用create_chapter_from_string方法，然后将html_string赋值为图片URL（例如https://www.xxx.com/xxx.png），并保持strict=False参数。或者将html_string赋值为本地图片文件路径（例如./xxx.png），并保持local=True和strict=False参数。最好添加一个title='Cover'参数。
• 如果您想自己清理网页内容，首先使用爬虫获取html字符串，然后使用公开的html_clean方法（建议添加tag_clean_list、class_clean_list和url的值）并将输出赋给create_chapter_from_string方法的html_string参数，同时保持strict=False。
• 无论使用哪种方法，在使用create_chapter_*和strict=False时，建议添加url参数，这有助于识别网页中的相对链接。
• 无论何时使用html_clean方法，建议包括help_url参数，这有助于识别网页中的相对链接。
• 在生成epub后，最好使用calibre将epub转换为更符合标准的epub/mobi/azw3，以解决某些软件中无法读取epub的问题。如果生成的epub有样式问题，您也可以使用calibre编辑电子书并调整样式以适应您的阅读习惯。
• 如果您的html中的图片和CSS文件是本地资源，请在create_chapter_*中将local参数设置为True，然后程序将自动复制本地资源而不是从互联网上获取它们。

常见问题解答

1. 生成的epub没有内容吗？

通过URL生成epub时，您需要确保URL对应的网页是静态网页，并且可以无登录访问所有内容。如果您生成的epub打开时为空，则您可能遇到了需要登录才能访问的网站。在这种情况下，您可以尝试获取URL对应的html字符串，然后使用create_chapter_from_string方法生成epub。也就是说，您需要使用某种爬虫技术。

2. 生成的epub包含我不想要的内容？

虽然我们在清理html字符串时做了一些过滤，但这并不保证在所有情况下都能正常工作。在这种情况下，我建议在使用create_chapter_from_string方法之前自己过滤html字符串。

3. 想要直接从html字符串生成epub而不清理内容？

将create_chapter_from_string的strict参数设置为False，这意味着它将不会内部清理。

4. 如果您选择自己获取html字符串并自行清理，可以按照以下步骤进行
   1. 使用爬虫技术获取html字符串，例如requests.get(url).text。
   2. 使用我们公开的 html_clean 方法来清理字符串，例如 html_clean(html_string, tag_clean_list=['sidebar'])。或者，您也可以编写自己的方法来清理字符串，目的都是为了获取干净的字符串，无论您想要什么。
   3. 使用 create_chapter_from_string(html_string, strict=False) 方法来生成章节对象，请注意将参数 strict 设置为 False，这意味着将跳过我们的内部清理策略。
   4. 之后，您可以根据基本用法生成 epub。参见 vuepress2epub.py 作为示例。