Convert Lake documents (Yuque) into the specified format.

Navigation

Verified details

These details have been verified by PyPI
Maintainers
Avatar for 332920287 from gravatar.com 332920287

Unverified details

These details have not been verified by PyPI
Project links
Meta
  • Author: gupingan
  • Requires: Python >=3.7
Classifiers
Report project as malware

Project description

LakeDoc Logo

将语雀（Yuque）Lake 文档转换为多种格式的 Python 库

Language Contributors Forks Stargazers Issues MIT License

快速开始 · 使用示例 · 高级用法 · 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')

高级用法

自定义转换器

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
from lakedoc import HeadingStyle 

# 自定义 HTML 解析器
lakedoc.convert('./input.html', bs4_builder='lxml')

# 自定义需要删除的标签
lakedoc.convert('./input.html', remove_tags={'meta', 'link', 'script'})

# 配置 Markdown 输出选项
lakedoc.convert('./input.html', 
                heading_style=HeadingStyle.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、str类型，保存路径，支持目录、文件等
converter str 转换器类型，默认 'markdown'
encoding str 文件编码，默认 'utf-8'
title str 转换后文档标题（可选）
bs4_builder str BeautifulSoup HTML 解析器，默认 'html.parser'
remove_tags Set[str] 需要从源文件中删除的标签集合
diagram_as_code bool 是否将 diagram 转换为代码块格式，默认 False
diagram_as_code_cond Optional[Callable[[str, str, str],bool]] 指定需要转换为代码块的回调条件函数： (src, lang, code) => bool
autolinks bool 是否自动将 URL 转换为自动链接格式
bullets str 无序列表的标记字符序列
code_language str 代码块的语言标识符
code_language_callback Optional[Callable[[Tag], Optional[str]]] 代码块语言回调函数
convert Optional[List[str]] 要转换的标签列表（与 strip 互斥）
default_title bool 是否为没有标题的链接使用 URL 作为默认标题
escape_asterisks bool 是否转义星号
escape_underscores bool 是否转义下划线
escape_misc bool 是否转义其他特殊字符
heading_style HeadingStyle 标题样式（HeadingStyle枚举）：ATX / ATX_CLOSED / UNDERLINED / SETEXT
keep_inline_images_in Optional[List[str]] 保持内联图片的父标签列表
newline_style NewlineStyle 换行样式（NewLineStyle枚举）：SPACES / BACKSLASH
strip Optional[List[str]] 要移除的标签列表（与 convert 互斥）
strip_document Optional[StripMode] 文档空白处理方式（StripMode枚举）：LSTRIP / RSTRIP / STRIP / STRIP_ONE
strip_pre Optional[StripMode] pre 标签空白处理方式（StripMode枚举）：LSTRIP / RSTRIP / STRIP / STRIP_ONE
strong_em_symbol StrongEmSymbol 粗体和斜体符号（StrongEmSymbol枚举）：ASTERISK / UNDERSCORE
sub_symbol str 下标符号，默认为 '~'
sup_symbol str 上标符号，默认为 '^'
table_infer_header bool 是否推断表格标题行
wrap bool 是否自动换行
wrap_width int 换行宽度

返回：

  • 如果未提供 saveto 参数，返回转换后的字符串内容
  • 如果提供了 saveto 参数，结果保存到文件并返回转换后的字符串内容

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 文件

致谢

感谢以下开源项目：

Project details

Verified details

These details have been verified by PyPI
Maintainers
Avatar for 332920287 from gravatar.com 332920287

Unverified details

These details have not been verified by PyPI
Project links
Meta
  • Author: gupingan
  • Requires: Python >=3.7
Classifiers

Release history Release notifications | RSS feed

This version

1.1.2

1.1.1

1.1.0

1.0.5

1.0.4

1.0.3

1.0.2

1.0.1

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

lakedoc-1.1.2.tar.gz (34.8 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

lakedoc-1.1.2-py3-none-any.whl (42.8 kB view details)

Uploaded Python 3

File details

Details for the file lakedoc-1.1.2.tar.gz.

File metadata

  • Download URL: lakedoc-1.1.2.tar.gz
  • Upload date:
  • Size: 34.8 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/2.2.1 CPython/3.9.10 Windows/10

File hashes

Hashes for lakedoc-1.1.2.tar.gz
Algorithm Hash digest
SHA256 592260bf299376486b68a8cc48a125c22d008d1b554b2a6d884fd18ad33ca1dc
MD5 7ade300250dd3036f2cb27dea1ea1513
BLAKE2b-256 bf508504e4d963504f418228e64db38d0d5560da7fd1069e03d0d37027221603

See more details on using hashes here.

File details

Details for the file lakedoc-1.1.2-py3-none-any.whl.

File metadata

  • Download URL: lakedoc-1.1.2-py3-none-any.whl
  • Upload date:
  • Size: 42.8 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/2.2.1 CPython/3.9.10 Windows/10

File hashes

Hashes for lakedoc-1.1.2-py3-none-any.whl
Algorithm Hash digest
SHA256 7cd15966d416d237b4f09f6724e56fe548e44dc779f6ed1386d282a5b15d20c5
MD5 363f4d45a6ae1dcefc6989b6a99a551c
BLAKE2b-256 d636e33e51e9aef78c5a0f420c19be51eb7b03b27157590742dd2ca138ae2546

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page