Python如何正确导入asciidoc3包实现脚本内AsciiDoc转HTML

报错原因 #

抛出AttributeError: module 'asciidoc3' has no attribute 'execute'和导入语句写法无关，是API使用方式不符合要求导致的：

• 实例化AsciiDoc3API类时必须传入第一个位置参数，作用和命令行调用时的argv[0]一致，作为程序运行标识，传任意非空字符串即可。省略该参数时内部初始化逻辑异常，会错误尝试调用顶层asciidoc3模块不存在的execute方法。
• execute方法内部会读取输入输出对象的name属性做逻辑判断，原生io.StringIO对象默认没有该属性，会触发逻辑回退到错误的调用分支。
• options()方法要求传入选项组成的列表，不能直接传入拼接好的选项字符串。

可运行代码示例 #

首先确保虚拟环境中已正确安装依赖：

pip install asciidoc3

内存中直接转换字符串（不生成中间文件） #

适合在业务逻辑中直接处理AsciiDoc格式文本，输出HTML片段：

import io
from asciidoc3.asciidoc3api import AsciiDoc3API

# 适配asciidoc3的参数校验，给内存流增加name属性
class MemoryBuffer(io.StringIO):
    def __init__(self, content: str = "", name: str = "<memory>"):
        super().__init__(content)
        self.name = name

if __name__ == "__main__":
    # 初始化实例，必须传入第一个运行标识参数
    ad3_converter = AsciiDoc3API("asciidoc3")
    # 配置转换选项：不输出完整HTML的头尾部，仅输出正文内容
    ad3_converter.options(["--no-header-footer"])

    # 待转换的AsciiDoc内容
    adoc_text = """
= 示例文档标题
Hello AsciiDoc3

这是一段普通文本，支持常用的AsciiDoc语法：
* 无序列表项1
* 无序列表项2
. 有序列表项1
. 有序列表项2
`行内代码` *加粗文本* _斜体文本_
"""
    in_buf = MemoryBuffer(adoc_text)
    out_buf = MemoryBuffer()

    # 执行转换，指定HTML后端
    ad3_converter.execute(in_buf, out_buf, backend="html5")

    # 获取转换后的HTML结果
    html_result = out_buf.getvalue()
    print(html_result)

转换本地文件 #

如果是处理本地磁盘上的.adoc文件，直接传文件路径即可，不需要自定义流对象：

from asciidoc3.asciidoc3api import AsciiDoc3API

ad3_converter = AsciiDoc3API("asciidoc3")
# 输出完整HTML文档，不带--no-header-footer选项
ad3_converter.options([])
# 直接传入输入、输出文件路径
ad3_converter.execute("input.adoc", "output.html", backend="html5")

补充说明 #

• 常用配置选项可以通过options()方法传入列表，比如要开启安全模式、禁用目录生成，可传["--safe-mode=safe", "--no-toc"]
• 支持的输出后端包括html、html4、html5、docbook，可根据输出需求选择
• 如果需要自定义样式、模板，可以通过options传入--conf-file参数指定自定义配置文件路径，用法和命令行版本完全一致

内容的提问来源于stack exchange，提问作者Lindsey