Convert Lake documents (Yuque) into the specified format.
Project description
将语雀（Yuque）Lake 文档转换为多种格式的 Python 库
快速开始 · 使用示例 · 高级用法 · API 文档 · 架构说明
简介
LakeDoc 是一个用于将语雀（Yuque）Lake 文档转换为多种格式的 Python 库。它支持将包含 <!doctype lake> 标记的 HTML 文档转换为 Markdown、HTML 等格式，并提供灵活的扩展机制，允许开发者自定义转换器。
声明
本模块仅用于对语雀官方 LakeDoc 的学习研究目的，本人未将其作为任何盈利渠道，禁止用于任何违背本国法律的行为。我更加支持语雀官方的内置导出功能，请优先使用官方提供的导出方式。
特性
- 多格式支持：支持转换为 Markdown、HTML 等格式
- 语雀特性适配：支持语雀特有的卡片组件（如代码块、图表、数学公式等）
- 灵活扩展：支持自定义转换器并自动注册
- 简单易用：提供统一的
convert()接口，通过参数配置转换行为 - 调试支持：内置调试工具，便于问题排查
安装
pip install lakedoc
快速开始
import lakedoc
# 从文件转换并返回结果
result = lakedoc.convert('./input.html')
# 从文件转换并保存
lakedoc.convert('./input.html', saveto='./output.md')
# 从 HTML 内容转换（自动识别包含 <!doctype lake> 的内容）
result = lakedoc.convert('<!doctype lake><html>...</html>')
# 转换内容并保存
lakedoc.convert('<!doctype lake><html>...</html>', saveto='./output.md')
使用示例
基本转换
import lakedoc
# 添加标题
lakedoc.convert('./input.html', saveto='./output.md', title='# 我的文档')
# 保存到目录（使用时间戳命名）
lakedoc.convert('./input.html', saveto='./output/')
启用调试模式
import lakedoc
# 启用全局调试模式
lakedoc.enable_debug()
# 转换时显示详细过程
lakedoc.convert('./input.html', debug=True)
高级用法
自定义转换器
from lakedoc.converters import LakeBaseConverter
class MyConverter(LakeBaseConverter):
name = "custom"
suffix = ".custom"
def __init__(self, raw_html: str, **options):
self.raw_html = raw_html
def convert(self) -> str:
# 实现你的转换逻辑
return "converted content"
# 使用自定义转换器
lakedoc.convert('./input.html', converter='custom')
配置转换选项
import lakedoc
# 自定义 HTML 解析器
lakedoc.convert('./input.html', bs4_builder='lxml')
# 自定义需要删除的标签
lakedoc.convert('./input.html', remove_tags={'meta', 'link', 'script'})
# 配置 Markdown 输出选项
lakedoc.convert('./input.html',
heading_style='atx',
bullets='*+-',
code_language='python')
调试 API
import lakedoc
# 启用全局调试模式
lakedoc.enable_debug()
# 禁用全局调试模式
lakedoc.disable_debug()
# 输出调试信息
lakedoc.debug("这是一条调试信息")
# 输出带缩进和颜色的调试信息
lakedoc.debug("这是一条调试信息", level=2, color='red')
API 文档
convert(source, **options)
将 Lake 文档转换为指定格式。
参数：
| 参数 | 类型 | 说明 |
|---|---|---|
source |
str |
输入源，自动识别类型（包含 <!doctype lake> 则为 HTML 内容，否则为文件路径） |
saveto |
str |
PathLike |
converter |
str |
转换器类型，默认 'markdown' |
encoding |
str |
文件编码，默认 'utf-8' |
bs4_builder |
str |
BeautifulSoup HTML 解析器，默认 'html.parser' |
title |
str |
转换后文档标题（可选） |
remove_tags |
Set[str] |
需要从源文件中删除的标签集合 |
debug |
bool |
是否启用调试模式 |
返回：
- 如果未提供
saveto参数，返回转换后的字符串内容 - 如果提供了
saveto参数，返回None（结果已保存到文件）
LakeContext
上下文管理类，用于管理转换器注册和转换选项。
方法：
register(converter, converter_class, is_cover=True)- 注册转换器set_options(**options)- 设置转换选项pick(converter)- 选择指定的转换器
LakeBaseConverter
转换器基类，自定义转换器需要继承此类并实现 convert 方法。
类属性：
name- 转换器名称（强制字段）suffix- 输出文件后缀（强制字段）
方法：
convert()- 执行转换，返回转换后的内容（抽象方法，子类必须实现）
架构说明
LakeDoc 采用分层架构设计，包含以下核心模块：
- Context 层：上下文管理，负责转换器的注册、选择和转换流程的协调
- Converters 层：转换器实现，负责实际的格式转换
- Utils 层：工具模块，提供文件操作、字符串处理、异常定义和调试工具
详细的架构说明请参阅 架构文档。
依赖
beautifulsoup4- HTML 解析colorama- 终端颜色输出markdown- Markdown 到 HTML 转换pymdown-extensions- Markdown 扩展
开发
安装开发依赖
poetry lock
poetry install
运行测试
poetry run pytest
许可证
MIT License - 详见 LICENSE 文件
致谢
感谢以下开源项目：
- Beautiful Soup 4 - HTML/XML 解析库
- Markdownify - HTML 转 Markdown 库
- Colorama - 终端颜色输出库
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file lakedoc-1.1.0.tar.gz.
File metadata
- Download URL: lakedoc-1.1.0.tar.gz
- Upload date:
- Size: 33.3 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: poetry/2.2.1 CPython/3.9.10 Windows/10
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
a65f4a4f23c0427e6c265280ce9387e32cc6650dac78db772d217f58383fae9e
|
|
| MD5 |
9134a9a2293df3584ce10f0079983b85
|
|
| BLAKE2b-256 |
c7df4ef8f97b619b2a88f34ffa7121cdbf1919fede997ece72f61205fce86773
|
File details
Details for the file lakedoc-1.1.0-py3-none-any.whl.
File metadata
- Download URL: lakedoc-1.1.0-py3-none-any.whl
- Upload date:
- Size: 41.6 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: poetry/2.2.1 CPython/3.9.10 Windows/10
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
df6c7d14061e79f083b3d531464655f934ebad064e18b89f85c8756b914964ee
|
|
| MD5 |
9d7ecdbc5be20fe557fa4be4a6ae984c
|
|
| BLAKE2b-256 |
147ef1b2b2075b0aaba7648ab9d34a92397c7e0c22af31d16dc869711819c70f
|
