入门：Python

Python 包封装的是同一个原生 Rust 引擎，而非重新实现，因此解析、序列化、SPARQL 与验证的行为与 Rust、JavaScript 和 C 接口完全一致。

译注：中国大陆镜像。 如需使用 PyPI 镜像，可参考 TUNA、USTC 与阿里云的说明。例如，pip install -i https://pypi.tuna.tsinghua.edu.cn/simple purrdf 使用 TUNA 镜像。具体配置以各镜像站的说明为准。

pip install purrdf

解析

import purrdf

quads = purrdf.parse(
    '<https://example.org/alice> <http://xmlns.com/foaf/0.1/name> "Alice" .',
    purrdf.RdfFormat.TURTLE,
)

验证：SHACL 与 ShEx

原生验证引擎以顶层子模块的形式公开，与 Rust 的 purrdf 门面 crate（umbrella crate）保持同构——绝不直接经由内部的 purrdf_native 扩展模块：

from purrdf import shapes, shex

report = shapes.validate(shapes_ttl=my_shapes, data_nt=my_data)
print(report["conforms"])

results = shex.validate(my_schema_shexc, my_data_ttl,
                        [("https://example.org/alice", "https://example.org/PersonShape")])
print(results[0]["conformant"])

SHACL 结果字典保留稳定的键 focus、path、value、severity、component、source_shape 与 messages（每条 sh:resultMessage，连同其语言标签与方向）。两个引擎各自覆盖的范围见 SHACL 与 ShEx。

蕴涵

purrdf.entail 在某一 SPARQL 蕴涵机制（entailment regime）下对数据集求闭包。它不是 purrdf.shapes.entail——后者应用的是_形状_图所声明的 SHACL-AF sh:rule；这里不接受任何形状，只使用该蕴涵机制自身规范中的规则表。

import purrdf
from purrdf import entail

dataset = purrdf.RdfDataset(my_turtle, purrdf.RdfFormat.TURTLE)
closure, report = entail.materialize(dataset, "rdfs", "", [], [])
print(closure.to_nquads())
print(report)          # 已触发的、未触发的、边界、预算、契约哈希

推理报告是第二个返回值，且永远不可省略——这与 Rust、WebAssembly 和 C 接口所执行的纪律一致。两个 [] 参数分别是该数据集的 owl:imports 表——由 (ontology_iri, nquads) 对组成——以及读取该数据集所用的 IRI：导入了某份文档的数据集会在合并结果上求推理闭包，而该表无法解析的导入会抛出点名它的 ValueError。entail.materialize_nt(text, regime, program, imports, premise_iris) 是其对应的文本进、文本出版本，供持有 N-Triples/N-Quads 文档的调用方使用。

覆盖率是可测量的，而非口头断言：entail.rules(regime) 是规范用以定义该蕴涵机制的规则表，entail.implemented_rules(regime) 则是其中实际会触发的子集。"owl-direct" 与 "rif" 在此返回 []——二者都没有自己的规范规则表，一个通过 tableau 判定，另一个在调用方自己的规则下蕴涵——而不是抛出错误。完整说明见蕴涵，逐条规则的表格见规则清单。

rdflib 兼容

本包附带一个 rdflib 兼容层：

from purrdf.compat.rdflib import Graph

若需要逐字不改的 import rdflib，可选装一个 extra：

pip install "purrdf[rdflib]"

这会拉入独立的 purrdf-rdflib 分发包，其顶层 rdflib 包重新导出兼容层的接口，于是现有第三方代码中的 import rdflib / from rdflib.namespace import RDF 便透明地运行在 PurRDF 之上。注意：该影子包占用了 rdflib 这一导入名，绝不可与真正的 rdflib 同时安装——二者无法共存于同一环境。它是一个独立的分发包（从不打进主 purrdf wheel），正是为了让需要真实 rdflib 的环境直接不装它即可。

兼容层在 CI 中以 rdflib 7.6 自带的、随库固化（vendored）的测试套件加上第一方的差分对等性测试套件把关——细节以及已知的、已入台账的分歧见 rdflib 兼容。

GTS 关系型行

Python 包把一个 GTS 容器读回为内存中的关系型行：

from purrdf import gts_relational_rows_from_bytes

rows = gts_relational_rows_from_bytes(gts_bytes)  # 项、四元组、具体化节点、注解、二进制块

gts_to_sqlite(data, path)、gts_to_duckdb(data, path) 与 gts_to_parquet(data, out_dir) 按投影自身的行顺序写出同样的五张表——因此把一个容器导出两次会产生相同的内容。SQLite 只需标准库；另外两者会抛出 ModuleNotFoundError，并指明需要安装的 extra（purrdf[duckdb]、purrdf[parquet]）。

图、表格与 Research Object（RO）归档

purrdf.project(data, format=..., profile=..., config=...) 返回规范的 USTAR 字节与结构化的损失记录。purrdf.lift(archive, profile=..., config=...) 则为十个双向 profile 重建 RDF。每个宿主都使用同一套严格配置与同样确定性的 Rust 代码路径；各 profile 及完整示例见图、表格与 Research Object 投影。

后续步骤

rdflib 兼容——直接替换方案的深入说明。
验证——在 Python 中使用 SHACL 与 ShEx。
蕴涵——各蕴涵机制、推理报告，以及各自触发的规则。
GTS 图传输——导出功能所读取的容器格式。
图、表格与 Research Object 投影——LPG、CSVW、OBO、SKOS 与五种 Research Object 载体。

Keyboard shortcuts

The PurRDF Book