PyLD文档加载器完全指南：Requests同步与aiohttp异步加载一次讲透-平芜编程栈

PyLD文档加载器完全指南：Requests同步与aiohttp异步加载一次讲透

【免费下载链接】pyldJSON-LD processor written in Python项目地址: https://gitcode.com/gh_mirrors/py/pyld

想用 Python 处理 JSON-LD 数据，却总被"文档加载器（Document Loader）"这个概念卡住？PyLD 文档加载器是 PyLD（Python 版 JSON-LD 处理器）中负责远程获取上下文（Context）与外部文档的关键组件，不理解它，你就无法真正玩转扩展（expand）、压缩（compact）等核心操作。这篇 PyLD 文档加载器完全指南，将把同步的 Requests 加载器与异步的 aiohttp 加载器一次讲透，帮你快速上手、少踩坑。

PyLD 文档加载器是什么？为什么必须了解它

JSON-LD 的魅力在于"远程上下文"：一个@context链接就能引入整套词汇表。而 PyLD 处理这类远程资源时，必须通过文档加载器去 HTTP 拉取。它本质上是一个"URL → RemoteDocument"的调用约定，返回内容包含contentType、contextUrl、documentUrl和document四部分。

PyLD 内置了两种开箱即用的加载器：

加载器	模式	底层库	适用场景
`RequestsDocumentLoader`	同步	requests	绝大多数常规项目、脚本
`AioHttpDocumentLoader`	异步内部实现	aiohttp	高并发、需要复用一个事件循环的场景

它们的核心逻辑都继承自pyld.documentloader.base中的DocumentLoader抽象基类，接口完全统一，随时可以替换。

快速安装 PyLD 文档加载器依赖

默认安装 PyLD 只包含核心，文档加载器属于可选依赖。按需安装即可：

# 使用同步 Requests 加载器 pip install "PyLD[requests]" # 使用异步 aiohttp 加载器 pip install "PyLD[aiohttp]" # 两者都要 pip install "PyLD[requests,aiohttp]"

同步加载首选：Requests 文档加载器配置方法

对于大部分业务代码，同步的RequestsDocumentLoader最简单可靠。它内部使用requests.Session()复用连接，性能也足够好。最基础的用法只需要在jsonld.expand()的 options 里传入documentLoader：

import json from pyld import RequestsDocumentLoader, jsonld doc = { "@context": {"name": "http://schema.org/name"}, "name": "Earth", } loader = RequestsDocumentLoader(timeout=10) result = jsonld.expand(doc, options={"documentLoader": loader}) print(json.dumps(result, indent=2))

⚠️ 官方文档反复强调：生产环境务必设置timeout，否则一旦远程服务无响应，你的程序可能长时间挂起。参考官方示例 requests_timeout.py。

传递 requests 高级参数：证书、验证与超时

RequestsDocumentLoader的额外关键字参数会原样透传给requests.get()，所以verify、cert、proxies等都能直接用：

loader = RequestsDocumentLoader( timeout=10, verify=True, cert=("client.crt", "client.key"), )

这在调用私有 CA 或需要双向 TLS 认证的 JSON-LD 服务时非常实用，完整写法见 requests_extra_kwargs.py。

使用工厂函数快速创建加载器

如果你习惯函数式风格，可以用requests_document_loader()工厂函数，效果完全一样：

from pyld import jsonld, requests_document_loader loader = requests_document_loader(timeout=10) result = jsonld.expand(doc, options={"documentLoader": loader})

它的实现源码非常简短，就在 requests.py 的末尾。

异步加载教程：aiohttp 文档加载器使用技巧

如果你身处 asyncio 生态，AioHttpDocumentLoader是绝佳选择。它的神奇之处在于：内部用异步方式拉取文档，但对外仍是同步接口，因此可以直接无缝接入 PyLD 同步的 JSON-LD 处理流程，无需改写任何业务代码：

import json from pyld import AioHttpDocumentLoader, jsonld doc = { "@context": {"name": "http://schema.org/name"}, "name": "Earth", } loader = AioHttpDocumentLoader(timeout=10) result = jsonld.expand(doc, options={"documentLoader": loader}) print(json.dumps(result, indent=2))

对应官方示例见 aiohttp_class.py。

aiohttp 加载器的双环境适配原理

细看源码会发现它做了很聪明的环境检测（aiohttp.py）：

🖥️ 同步环境中：直接调用asyncio.run()驱动内部协程；
⚡ 异步环境中：自动启动一个后台守护事件循环，通过run_coroutine_threadsafe()把任务投递过去再取回结果。

这意味着在 FastAPI、aiogram 等异步框架里调用它也不会阻塞事件循环，开发者完全无感。aiohttp_document_loader()工厂函数同样提供，loop参数已废弃保留仅为兼容旧代码。

安全模式：开启 secure 强制 HTTPS

两个加载器都支持secure=True，开启后任何非 HTTPS 的 URL 都会被直接拒绝并抛出InvalidUrl错误。这对处理敏感数据的应用是重要的安全防线：

loader = RequestsDocumentLoader(secure=True, timeout=10) # loader = AioHttpDocumentLoader(secure=True, timeout=10) # 异步版本同理

官方示例 requests_secure.py 和 aiohttp_secure.py 可以直接对照学习。

进阶：自定义 PyLD 文档加载器

当内置加载器无法满足需求（比如本地缓存、mock 数据、私有协议），你可以继承DocumentLoader实现自己的加载器。只需实现__call__(url, options)并返回 RemoteDocument 结构：

from pyld import DocumentLoader, jsonld DOCUMENT_CACHE = { "context://my-app/vocab": { "contentType": "application/ld+json", "contextUrl": None, "documentUrl": "context://my-app/vocab", "document": {"@context": {"name": "https://schema.org/name"}}, } } class ExampleDocumentLoader(DocumentLoader): def __call__(self, url, options): return DOCUMENT_CACHE[url] result = jsonld.expand( {"@context": "context://my-app/vocab", "name": "Earth"}, options={"documentLoader": ExampleDocumentLoader()}, )

更完整的参考实现见 custom_document_loader.py 与基类定义 base.py。另外，PyLD 还提供了预置了常用公共上下文的frozen加载器（frozen/），以及带 SQLite 磁盘缓存的 requests_sqlite_cache.py，实测能大幅减少重复网络请求。