pySHACL

SHACL的Python验证器。

这是一个纯Python模块，允许对RDF图进行验证，以符合SHACL图。该模块使用rdflib Python库来处理RDF，并依赖于OWL-RL Python模块来扩展数据图，基于OWL2 RL配置文件。

本模块的开发是为了遵守SHACL建议

Holger Knublauch；Dimitris Kontokostas. 形状约束语言（SHACL）。2017年7月20日。W3C建议。URL：https://www.w3.org/TR/shacl/ ED：https://w3c.github.io/data-shapes/shacl/

帮助与支持社区

SHACL社区有一个用于讨论SHACL及其规范相关主题的Discord服务器。

使用此邀请链接加入服务器：https://discord.gg/RTbGfJqdKB

有一个用于讨论此Python库的#pyshacl频道，您也可以请求一般性的SHACL帮助。

安装

使用PIP安装（使用Python3 pip安装程序 pip3）

$ pip3 install pyshacl

或在python虚拟env中安装（以下示例命令行指令适用于基于Linux/Unix的操作系统）

$ python3 -m virtualenv --python=python3 --no-site-packages .venv
$ source ./.venv/bin/activate
$ pip3 install pyshacl

退出虚拟环境

$ deactivate

命令行使用

对于命令行使用：（以下示例命令行指令适用于基于Linux/Unix的操作系统）

$ pyshacl -s /path/to/shapesGraph.ttl -m -i rdfs -a -j -f human /path/to/dataGraph.ttl

其中

• -s是（可选）要使用的形状图的路径
• -e是（可选）导入额外本体图的路径
• -i是预推理选项
• -f是验证报告的输出格式（《human》=可读的验证报告）
• -m启用meta-shacl功能
• -a启用SHACL高级功能
• -j启用SHACL-JS功能（如果安装了pyhsacl[js]）

系统退出代码是：0 = 数据图符合规范 1 = 数据图不符合规范 2 = 验证器遇到了RuntimeError（详细信息请检查stderr输出） 3 = 未实现；验证器遇到了尚未实现的SHACL功能。

完整的CLI使用选项

$ pyshacl -h
$ python3 -m pyshacl -h
usage: pyshacl [-h] [-s [SHACL]] [-e [ONT]] [-i {none,rdfs,owlrl,both}] [-m]
               [-im] [-a] [-j] [-it] [--abort] [--allow-info] [-w]
               [--max-depth [MAX_DEPTH]] [-d]
               [-f {human,table,turtle,xml,json-ld,nt,n3}]
               [-df {auto,turtle,xml,json-ld,nt,n3}]
               [-sf {auto,turtle,xml,json-ld,nt,n3}]
               [-ef {auto,turtle,xml,json-ld,nt,n3}] [-V] [-o [OUTPUT]]
               [--server]
               DataGraph

PySHACL 0.26.0 command line tool.

positional arguments:
  DataGraph             The file containing the Target Data Graph.

optional arguments:
  --server              Ignore all the rest of the options, start the HTTP Server.
  -h, --help            show this help message and exit
  -s [SHACL], --shacl [SHACL]
                        A file containing the SHACL Shapes Graph.
  -e [ONT], --ont-graph [ONT]
                        A file path or URL to a document containing extra
                        ontological information. RDFS and OWL definitions from this 
                        are used to inoculate the DataGraph.
  -i {none,rdfs,owlrl,both}, --inference {none,rdfs,owlrl,both}
                        Choose a type of inferencing to run against the Data
                        Graph before validating.
  -m, --metashacl       Validate the SHACL Shapes graph against the shacl-
                        shacl Shapes Graph before validating the Data Graph.
  -im, --imports        Allow import of sub-graphs defined in statements with
                        owl:imports.
  -a, --advanced        Enable features from the SHACL Advanced Features
                        specification.
  -j, --js              Enable features from the SHACL-JS Specification.
  -it, --iterate-rules  Run Shape's SHACL Rules iteratively until the
                        data_graph reaches a steady state.
  --abort               Abort on first invalid data.
  --allow-info, --allow-infos
                        Shapes marked with severity of Info will not cause
                        result to be invalid.
  -w, --allow-warning, --allow-warnings
                        Shapes marked with severity of Warning or Info will
                        not cause result to be invalid.
  --max-depth [MAX_DEPTH]
                        The maximum number of SHACL shapes "deep" that the
                        validator can go before reaching an "endpoint"
                        constraint.
  -d, --debug           Output additional runtime messages.
  -f {human,table,turtle,xml,json-ld,nt,n3}, --format {human,table,turtle,xml,json-ld,nt,n3}
                        Choose an output format. Default is "human".
  -df {auto,turtle,xml,json-ld,nt,n3}, --data-file-format {auto,turtle,xml,json-ld,nt,n3}
                        Explicitly state the RDF File format of the input
                        DataGraph file. Default="auto".
  -sf {auto,turtle,xml,json-ld,nt,n3}, --shacl-file-format {auto,turtle,xml,json-ld,nt,n3}
                        Explicitly state the RDF File format of the input
                        SHACL file. Default="auto".
  -ef {auto,turtle,xml,json-ld,nt,n3}, --ont-file-format {auto,turtle,xml,json-ld,nt,n3}
                        Explicitly state the RDF File format of the extra
                        ontology file. Default="auto".
  -V, --version         Show PySHACL version and exit.
  -o [OUTPUT], --output [OUTPUT]
                        Send output to a file (defaults to stdout).
  --server              Ignore all the rest of the options, start the HTTP
                        Server. Same as `pyshacl_server`.

Python模块使用

对于本模块的基本使用，您可以像这样调用pyshacl模块的validate函数

from pyshacl import validate
r = validate(data_graph,
      shacl_graph=sg,
      ont_graph=og,
      inference='rdfs',
      abort_on_first=False,
      allow_infos=False,
      allow_warnings=False,
      meta_shacl=False,
      advanced=False,
      js=False,
      debug=False)
conforms, results_graph, results_text = r

其中

• data_graph是rdflib的Graph对象或要验证的图的文件路径
• shacl_graph是rdflib的Graph对象或包含要验证的SHACL形状的图的文件路径或Web URL，或者为None，如果SHACL形状包含在数据图中。
• ont_graph是rdflib的Graph对象或包含额外本体信息的图的文件路径或Web URL，或者为None，如果不需要。此处的RDFS和OWL定义用于感染数据图。
• inference是一个Python字符串值，表示是否在验证之前执行OWL推理扩展data_graph。选项是'rdfs'、'owlrl'、'both'或'none'。默认是'none'。
• abort_on_first（可选）bool值，表示程序在遇到第一个验证失败后是否应该终止，或者继续。默认是继续。
• allow_infos（可选）bool值，标记为Info严重性的形状不会导致结果无效。
• allow_warnings（可选）bool值，标记为Warning或Info严重性的形状不会导致结果无效。
• meta_shacl（可选）bool值，表示程序是否应该启用Meta-SHACL功能。默认是False。
• advanced： （可选）bool值，用于启用SHACL高级功能
• js： （可选）bool值，用于启用SHACL-JS功能（如果安装了pyshacl[js]）
• debug（可选）bool值，用于指示程序是否应输出调试文本，包括未导致总体不符的违规。因此，当debug为True时，不要通过违规消息的缺失来判断合规性。默认值为False。

在validate函数上可用的其他一些可选关键字变量

• data_graph_format：覆盖给定数据图源文件的格式检测。
• shacl_graph_format：覆盖给定shacl图源文件的格式检测。
• ont_graph_format：覆盖给定额外本体图源文件的格式检测。
• iterate_rules：迭代SHACL规则，直到找到稳态（仅在高级模式下有效）。
• do_owl_imports：启用功能，允许使用owl:imports导入形状图和本体图中的子图。注意，您明确不能在目标数据图上使用此功能。
• serialize_report_graph：将报告结果图转换为序列化表示形式（例如，'turtle'）。
• check_dash_result：将验证结果与给定的预期DASH测试套件结果进行比较。
• check_sht_result：将验证结果与给定的预期SHT测试套件结果进行比较。

返回值

• 一个包含三个组件的tuple
  • conforms：一个bool，指示data_graph是否与shacl_graph相符
  • results_graph：一个根据SHACL规范验证报告结构构建的Graph对象
  • results_text：表示验证报告的详细文本的Python字符串

Python模块调用

您可以通过使用Python3可执行文件来获取命令行工具的等效功能

$ python3 -m pyshacl

集成OpenAPI-3.0兼容的HTTP REST服务

PySHACL现在具有一个内置的验证服务，通过OpenAPI3.0兼容的REST API公开。

由于需要额外的依赖项来运行，此功能是一个可选的额外功能。

您必须首先通过启用http额外选项来安装PySHACL

$ pip3 install -U pyshacl[http]

安装后，您可以通过执行CLI入口点来启动服务

$ pyshacl --server
# or
$ pyshacl_server
# or
$ python3 -m pyshacl server
# or
$ docker run --rm -e PYSHACL_SERVER=TRUE -i -t docker.io/ashleysommer/pyshacl:latest

默认情况下，此服务将在本地地址127.0.0.1上的端口8099运行。

要查看服务的SwaggerUI文档，请导航到http://127.0.0.1:8099/docs/swagger，对于ReDoc版本，请访问http://127.0.0.1:8099/docs/redoc。

要查看OpenAPI3模式，请参阅http://127.0.0.1:8099/docs/openapi.json

配置HTTP REST服务

• 您可以通过传递环境变量PYSHACL_SERVER=TRUE强制PySHACL CLI以HTTP服务器模式启动。这在容器化服务中很有用，其中您将仅以此模式运行PySHACL。
• PYSHACL_SERVER_LISTEN=1.2.3.4监听不同的IP地址或主机名
• PYSHACL_SERVER_PORT=8080监听给定的不同TCP端口
• PYSHACL_SERVER_HOSTNAME=example.org当您在反向代理或容器化环境中托管服务器时，使用此选项，以便PySHACL服务器知道您的对外主机名是什么

错误

在某些情况下，pySHACL可以产生一个Validation Failure。这是一个由SHACL规范定义的正式错误，并要求在SHACL图中的特定条件下生成。如果验证器产生一个Validation Failure，则由validate()函数返回的results_graph变量将是ValidationFailure的实例。查看该实例的message属性以获取有关验证失败的更多信息。

验证器可以生成的其他错误

• ShapeLoadError：当SHACL图中的SHACL Shape处于无效状态且无法加载到验证引擎中时，将抛出此错误。
• ConstraintLoadError：当SHACL约束组件处于无效状态且无法加载到验证引擎时抛出此错误。
• ReportableRuntimeError：由于不同原因发生错误，应将原因反馈给验证器用户。
• RuntimeError：验证器遇到了导致其抛出错误的情况，但原因并不影响用户。

与ValidationFailure不同，这些错误不是通过validate()函数作为结果返回的，而是由验证引擎抛出异常，必须在try ... except块中捕获。在ShapeLoadError和ConstraintLoadError的情况下，请查看异常实例的str()字符串表示形式，其中包含错误消息以及SHACL规范文档中相关部分的链接。

Windows CLI

Pyinstaller可以使用来创建具有与Linux/Mac CLI程序相同特性的Windows可执行文件。必要的.spec文件已包含在pyshacl/pyshacl-cli.spec中。pyshacl-cli.spec PyInstaller规范文件为pySHACL命令行实用程序创建一个.exe文件。请参阅上面的pySHACL命令行实用程序使用说明。

有关如何在Windows上安装PyInstaller的信息，请参阅PyInstaller安装指南。

一旦安装了pyinstaller，就可以使用pyinstaller生成pyshacl.exe CLI文件，如下所示

$ cd src/pyshacl
$ pyinstaller pyshacl-cli.spec

这将在src/pyshacl目录中的dist目录中输出pyshacl.exe。

现在，您可以通过pyshacl.exe运行pySHACL命令行实用程序。请参阅上面的pySHACL命令行实用程序使用说明。

Docker

从Dockerhub拉取官方docker镜像：docker pull docker.io/ashleysommer/pyshacl:latest

或者使用docker build . -t pyshacl从PySHACL存储库自行构建镜像。

现在您可以在容器中运行PySHACL；但您需要挂载数据以进行验证。例如，为了验证graph.ttl与shacl.ttl，运行

docker run --rm -i -t --mount type=bind,src=`pwd`,dst=/data pyshacl -s /data/shacl.ttl /data/graph.ttl

兼容性

PySHACL是Python3库。为获得最佳兼容性，请使用Python v3.7或更高版本。Python3 v3.6或更低版本不支持，并且此库在Python v2.7.x或更低版本上不工作。

PySHACL现在是一个PEP518 & PEP517项目，它使用pyproject.toml和poetry来管理依赖项、构建和安装。

要从PyPI使用pip安装时获得最佳兼容性，请升级到pip v18.1.0或更高版本。

• 如果您使用的是Ubuntu 16.04或18.04，则需要运行sudo pip3 install --upgrade pip以获取较新版本。

功能

功能矩阵保存在FEATURES文件中。

变更日志

综合变更日志保存在CHANGELOG文件中。

基准测试

此项目包含一个脚本来测量使用每种不同的推理选项对已推理的相同源图进行验证的性能差异。在您的计算机上运行它，以查看验证器为您操作的速度。

许可证

此存储库根据Apache License，版本2.0授权。有关详细信息，请参阅LICENSE契约。

贡献者

请参阅CONTRIBUTORS文件。

引用

DOI：10.5281/zenodo.4750840（适用于所有版本/最新版本）

联系方式

项目负责人：Nicholas Car 高级实验科学家 澳大利亚CSIRO陆地与水，环境信息组 布里斯班，昆士兰州，澳大利亚 nicholas.car@csiro.au http://orcid.org/0000-0002-8742-7730

首席开发者： Ashley Sommer 信息学软件工程师 澳大利亚联邦科学和工业研究组织（CSIRO）土地与水资源，环境信息学小组 布里斯班，昆士兰州，澳大利亚 Ashley.Sommer@csiro.au https://orcid.org/0000-0003-0590-0131