PyLD文档加载器完全指南Requests同步与aiohttp异步加载一次讲透【免费下载链接】pyldJSON-LD processor written in Python项目地址: https://gitcode.com/gh_mirrors/py/pyld想用 Python 处理 JSON-LD 数据却总被文档加载器Document Loader这个概念卡住PyLD 文档加载器是 PyLDPython 版 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 里传入documentLoaderimport json from pyld import RequestsDocumentLoader, jsonld doc { context: {name: http://schema.org/name}, name: Earth, } loader RequestsDocumentLoader(timeout10) result jsonld.expand(doc, options{documentLoader: loader}) print(json.dumps(result, indent2))⚠️ 官方文档反复强调生产环境务必设置timeout否则一旦远程服务无响应你的程序可能长时间挂起。参考官方示例 requests_timeout.py。传递 requests 高级参数证书、验证与超时RequestsDocumentLoader的额外关键字参数会原样透传给requests.get()所以verify、cert、proxies等都能直接用loader RequestsDocumentLoader( timeout10, verifyTrue, 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(timeout10) 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(timeout10) result jsonld.expand(doc, options{documentLoader: loader}) print(json.dumps(result, indent2))对应官方示例见 aiohttp_class.py。aiohttp 加载器的双环境适配原理细看源码会发现它做了很聪明的环境检测aiohttp.py️ 同步环境中直接调用asyncio.run()驱动内部协程⚡ 异步环境中自动启动一个后台守护事件循环通过run_coroutine_threadsafe()把任务投递过去再取回结果。这意味着在 FastAPI、aiogram 等异步框架里调用它也不会阻塞事件循环开发者完全无感。aiohttp_document_loader()工厂函数同样提供loop参数已废弃保留仅为兼容旧代码。安全模式开启 secure 强制 HTTPS两个加载器都支持secureTrue开启后任何非 HTTPS 的 URL 都会被直接拒绝并抛出InvalidUrl错误。这对处理敏感数据的应用是重要的安全防线loader RequestsDocumentLoader(secureTrue, timeout10) # loader AioHttpDocumentLoader(secureTrue, timeout10) # 异步版本同理官方示例 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/ldjson, 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实测能大幅减少重复网络请求。同步还是异步PyLD 加载器选型建议最后给你一张速查表照着选就行常规后端服务 / 脚本→RequestsDocumentLoader简单直接生态成熟高并发抓取、已重度使用 asyncio→AioHttpDocumentLoader无缝融入事件循环涉及隐私数据→ 无论选哪个记得secureTrue测试、离线、mock→ 自定义加载器或 frozen 内置上下文。记住一个关键结论PyLD 的 JSON-LD 处理过程本身始终是同步的aiohttp 加载器只是把网络拉取这一步异步化。理解了这一点你就真正掌握了 PyLD 文档加载器的精髓。更多细节可查阅官方文档目录 document-loaders动手试试吧【免费下载链接】pyldJSON-LD processor written in Python项目地址: https://gitcode.com/gh_mirrors/py/pyld创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
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 文档加载器是 PyLDPython 版 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 里传入documentLoaderimport json from pyld import RequestsDocumentLoader, jsonld doc { context: {name: http://schema.org/name}, name: Earth, } loader RequestsDocumentLoader(timeout10) result jsonld.expand(doc, options{documentLoader: loader}) print(json.dumps(result, indent2))⚠️ 官方文档反复强调生产环境务必设置timeout否则一旦远程服务无响应你的程序可能长时间挂起。参考官方示例 requests_timeout.py。传递 requests 高级参数证书、验证与超时RequestsDocumentLoader的额外关键字参数会原样透传给requests.get()所以verify、cert、proxies等都能直接用loader RequestsDocumentLoader( timeout10, verifyTrue, 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(timeout10) 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(timeout10) result jsonld.expand(doc, options{documentLoader: loader}) print(json.dumps(result, indent2))对应官方示例见 aiohttp_class.py。aiohttp 加载器的双环境适配原理细看源码会发现它做了很聪明的环境检测aiohttp.py️ 同步环境中直接调用asyncio.run()驱动内部协程⚡ 异步环境中自动启动一个后台守护事件循环通过run_coroutine_threadsafe()把任务投递过去再取回结果。这意味着在 FastAPI、aiogram 等异步框架里调用它也不会阻塞事件循环开发者完全无感。aiohttp_document_loader()工厂函数同样提供loop参数已废弃保留仅为兼容旧代码。安全模式开启 secure 强制 HTTPS两个加载器都支持secureTrue开启后任何非 HTTPS 的 URL 都会被直接拒绝并抛出InvalidUrl错误。这对处理敏感数据的应用是重要的安全防线loader RequestsDocumentLoader(secureTrue, timeout10) # loader AioHttpDocumentLoader(secureTrue, timeout10) # 异步版本同理官方示例 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/ldjson, 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实测能大幅减少重复网络请求。同步还是异步PyLD 加载器选型建议最后给你一张速查表照着选就行常规后端服务 / 脚本→RequestsDocumentLoader简单直接生态成熟高并发抓取、已重度使用 asyncio→AioHttpDocumentLoader无缝融入事件循环涉及隐私数据→ 无论选哪个记得secureTrue测试、离线、mock→ 自定义加载器或 frozen 内置上下文。记住一个关键结论PyLD 的 JSON-LD 处理过程本身始终是同步的aiohttp 加载器只是把网络拉取这一步异步化。理解了这一点你就真正掌握了 PyLD 文档加载器的精髓。更多细节可查阅官方文档目录 document-loaders动手试试吧【免费下载链接】pyldJSON-LD processor written in Python项目地址: https://gitcode.com/gh_mirrors/py/pyld创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考