tripper 0.2.16__tar.gz → 0.3.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (90) hide show
  1. {tripper-0.2.16 → tripper-0.3.0}/.github/workflows/ci_tests.yml +5 -2
  2. {tripper-0.2.16 → tripper-0.3.0}/.pre-commit-config.yaml +1 -1
  3. {tripper-0.2.16 → tripper-0.3.0}/CHANGELOG.md +19 -4
  4. {tripper-0.2.16 → tripper-0.3.0}/PKG-INFO +7 -6
  5. tripper-0.3.0/docs/tutorial.md +411 -0
  6. {tripper-0.2.16 → tripper-0.3.0}/pyproject.toml +7 -6
  7. {tripper-0.2.16 → tripper-0.3.0}/tests/convert/test_convert.py +48 -0
  8. {tripper-0.2.16 → tripper-0.3.0}/tests/test_literals.py +28 -5
  9. tripper-0.3.0/tests/test_sparql.py +261 -0
  10. {tripper-0.2.16 → tripper-0.3.0}/tests/test_triplestore.py +80 -24
  11. {tripper-0.2.16 → tripper-0.3.0}/tripper/__init__.py +1 -1
  12. {tripper-0.2.16 → tripper-0.3.0}/tripper/backends/rdflib.py +63 -27
  13. {tripper-0.2.16 → tripper-0.3.0}/tripper/convert/__init__.py +2 -0
  14. {tripper-0.2.16 → tripper-0.3.0}/tripper/convert/convert.py +20 -9
  15. {tripper-0.2.16 → tripper-0.3.0}/tripper/interface.py +4 -1
  16. {tripper-0.2.16 → tripper-0.3.0}/tripper/literal.py +29 -17
  17. {tripper-0.2.16 → tripper-0.3.0}/tripper/mappings/mappings.py +1 -5
  18. {tripper-0.2.16 → tripper-0.3.0}/tripper/namespace.py +6 -2
  19. {tripper-0.2.16 → tripper-0.3.0}/tripper/triplestore.py +82 -38
  20. {tripper-0.2.16 → tripper-0.3.0}/tripper/utils.py +18 -4
  21. tripper-0.2.16/docs/tutorial.md +0 -219
  22. tripper-0.2.16/tests/test_sparql.py +0 -88
  23. {tripper-0.2.16 → tripper-0.3.0}/.github/dependabot.yml +0 -0
  24. {tripper-0.2.16 → tripper-0.3.0}/.github/pull_request_template.md +0 -0
  25. {tripper-0.2.16 → tripper-0.3.0}/.github/workflows/cd_release.yml +0 -0
  26. {tripper-0.2.16 → tripper-0.3.0}/.github/workflows/ci_automerge_dependency_prs.yml +0 -0
  27. {tripper-0.2.16 → tripper-0.3.0}/.github/workflows/ci_cd_updated_main.yml +0 -0
  28. {tripper-0.2.16 → tripper-0.3.0}/.github/workflows/ci_check_dependencies.yml +0 -0
  29. {tripper-0.2.16 → tripper-0.3.0}/.github/workflows/ci_update_dependencies.yml +0 -0
  30. {tripper-0.2.16 → tripper-0.3.0}/.gitignore +0 -0
  31. {tripper-0.2.16 → tripper-0.3.0}/LICENSE +0 -0
  32. {tripper-0.2.16 → tripper-0.3.0}/README.md +0 -0
  33. {tripper-0.2.16 → tripper-0.3.0}/docs/CHANGELOG.md +0 -0
  34. {tripper-0.2.16 → tripper-0.3.0}/docs/LICENSE.md +0 -0
  35. {tripper-0.2.16 → tripper-0.3.0}/docs/api_reference/.pages +0 -0
  36. {tripper-0.2.16 → tripper-0.3.0}/docs/api_reference/backends/.pages +0 -0
  37. {tripper-0.2.16 → tripper-0.3.0}/docs/api_reference/backends/collection.md +0 -0
  38. {tripper-0.2.16 → tripper-0.3.0}/docs/api_reference/backends/ontopy.md +0 -0
  39. {tripper-0.2.16 → tripper-0.3.0}/docs/api_reference/backends/rdflib.md +0 -0
  40. {tripper-0.2.16 → tripper-0.3.0}/docs/api_reference/backends/sparqlwrapper.md +0 -0
  41. {tripper-0.2.16 → tripper-0.3.0}/docs/api_reference/convert/.pages +0 -0
  42. {tripper-0.2.16 → tripper-0.3.0}/docs/api_reference/convert/convert.md +0 -0
  43. {tripper-0.2.16 → tripper-0.3.0}/docs/api_reference/errors.md +0 -0
  44. {tripper-0.2.16 → tripper-0.3.0}/docs/api_reference/interface.md +0 -0
  45. {tripper-0.2.16 → tripper-0.3.0}/docs/api_reference/literal.md +0 -0
  46. {tripper-0.2.16 → tripper-0.3.0}/docs/api_reference/mappings/.pages +0 -0
  47. {tripper-0.2.16 → tripper-0.3.0}/docs/api_reference/mappings/mappings.md +0 -0
  48. {tripper-0.2.16 → tripper-0.3.0}/docs/api_reference/namespace.md +0 -0
  49. {tripper-0.2.16 → tripper-0.3.0}/docs/api_reference/testutils.md +0 -0
  50. {tripper-0.2.16 → tripper-0.3.0}/docs/api_reference/triplestore.md +0 -0
  51. {tripper-0.2.16 → tripper-0.3.0}/docs/api_reference/tripper.md +0 -0
  52. {tripper-0.2.16 → tripper-0.3.0}/docs/api_reference/utils.md +0 -0
  53. {tripper-0.2.16 → tripper-0.3.0}/docs/backend_discovery.md +0 -0
  54. {tripper-0.2.16 → tripper-0.3.0}/docs/css/reference.css +0 -0
  55. {tripper-0.2.16 → tripper-0.3.0}/docs/index.md +0 -0
  56. {tripper-0.2.16 → tripper-0.3.0}/docs/mappings/figs/function_emmo.svg +0 -0
  57. {tripper-0.2.16 → tripper-0.3.0}/docs/planned-backends.md +0 -0
  58. {tripper-0.2.16 → tripper-0.3.0}/examples/workflow-mappings/README.md +0 -0
  59. {tripper-0.2.16 → tripper-0.3.0}/examples/workflow-mappings/knowledge-base.svg +0 -0
  60. {tripper-0.2.16 → tripper-0.3.0}/examples/workflow-mappings/route.svg +0 -0
  61. {tripper-0.2.16 → tripper-0.3.0}/examples/workflow-mappings/workflow.svg +0 -0
  62. {tripper-0.2.16 → tripper-0.3.0}/examples/workflow-mappings/workflow_mappings.py +0 -0
  63. {tripper-0.2.16 → tripper-0.3.0}/examples/workflow-mappings/workflow_w_pipes.svg +0 -0
  64. {tripper-0.2.16 → tripper-0.3.0}/mkdocs.yml +0 -0
  65. {tripper-0.2.16 → tripper-0.3.0}/tests/backends/__init__.py +0 -0
  66. {tripper-0.2.16 → tripper-0.3.0}/tests/backends/dummy.py +0 -0
  67. {tripper-0.2.16 → tripper-0.3.0}/tests/backends/test_collection.py +0 -0
  68. {tripper-0.2.16 → tripper-0.3.0}/tests/backends/test_rdflib.py +0 -0
  69. {tripper-0.2.16 → tripper-0.3.0}/tests/conftest.py +0 -0
  70. {tripper-0.2.16 → tripper-0.3.0}/tests/mappings/test_cost.py +0 -0
  71. {tripper-0.2.16 → tripper-0.3.0}/tests/mappings/test_function.py +0 -0
  72. {tripper-0.2.16 → tripper-0.3.0}/tests/mappings/test_mappings.py +0 -0
  73. {tripper-0.2.16 → tripper-0.3.0}/tests/ontologies/family.ttl +0 -0
  74. {tripper-0.2.16 → tripper-0.3.0}/tests/ontologies/food-more.ttl +0 -0
  75. {tripper-0.2.16 → tripper-0.3.0}/tests/ontologies/food.ttl +0 -0
  76. {tripper-0.2.16 → tripper-0.3.0}/tests/output/.gitignore +0 -0
  77. {tripper-0.2.16 → tripper-0.3.0}/tests/test_add_function.py +0 -0
  78. {tripper-0.2.16 → tripper-0.3.0}/tests/test_custom_backend.py +0 -0
  79. {tripper-0.2.16 → tripper-0.3.0}/tests/test_eval_function.py +0 -0
  80. {tripper-0.2.16 → tripper-0.3.0}/tests/test_get_data.py +0 -0
  81. {tripper-0.2.16 → tripper-0.3.0}/tests/test_namespace.py +0 -0
  82. {tripper-0.2.16 → tripper-0.3.0}/tests/test_utils.py +0 -0
  83. {tripper-0.2.16 → tripper-0.3.0}/tripper/backends/__init__.py +0 -0
  84. {tripper-0.2.16 → tripper-0.3.0}/tripper/backends/collection.py +0 -0
  85. {tripper-0.2.16 → tripper-0.3.0}/tripper/backends/ontopy.py +0 -0
  86. {tripper-0.2.16 → tripper-0.3.0}/tripper/backends/sparqlwrapper.py +0 -0
  87. {tripper-0.2.16 → tripper-0.3.0}/tripper/errors.py +0 -0
  88. {tripper-0.2.16 → tripper-0.3.0}/tripper/mappings/__init__.py +0 -0
  89. {tripper-0.2.16 → tripper-0.3.0}/tripper/testutils.py +0 -0
  90. {tripper-0.2.16 → tripper-0.3.0}/tripper/tripper.py +0 -0
@@ -34,11 +34,14 @@ jobs:
34
34
  # https://pyup.io/vulnerabilities/CVE-2021-41495/44715/
35
35
  # https://pyup.io/vulnerabilities/CVE-2021-41496/44716/
36
36
  # https://pyup.io/vulnerabilities/CVE-2021-34141/44717/
37
+ # 70612: Jinja2 vulnerability. Only used as subdependency for mkdocs++ in tripper.
38
+ # https://data.safetycli.com/v/70612/97c/
37
39
  safety_options: |
38
40
  --ignore=48547
39
41
  --ignore=44715
40
42
  --ignore=44716
41
43
  --ignore=44717
44
+ --ignore=70612
42
45
 
43
46
  ## Build package
44
47
  run_build_package: true
@@ -63,7 +66,7 @@ jobs:
63
66
  strategy:
64
67
  fail-fast: false
65
68
  matrix:
66
- python-version: ["3.7", "3.8", "3.9", "3.10", "3.11"]
69
+ python-version: ["3.7", "3.8", "3.9", "3.10", "3.11", "3.12"]
67
70
 
68
71
  steps:
69
72
  - name: Checkout tripper
@@ -99,7 +102,7 @@ jobs:
99
102
  strategy:
100
103
  fail-fast: false
101
104
  matrix:
102
- python-version: ["3.7", "3.8", "3.9", "3.10", "3.11"]
105
+ python-version: ["3.7", "3.8", "3.9", "3.10", "3.11", "3.12"]
103
106
 
104
107
  steps:
105
108
  - name: Checkout tripper
@@ -46,7 +46,7 @@ repos:
46
46
  - id: black
47
47
 
48
48
  - repo: https://github.com/PyCQA/bandit
49
- rev: 1.7.8
49
+ rev: 1.7.9
50
50
  hooks:
51
51
  - id: bandit
52
52
  args: ["-r"]
@@ -1,17 +1,32 @@
1
1
  # Changelog
2
2
 
3
- ## [Unreleased](https://github.com/EMMC-ASBL/tripper/tree/HEAD)
3
+ ## [v0.3.0](https://github.com/EMMC-ASBL/tripper/tree/v0.3.0) (2024-06-24)
4
4
 
5
- [Full Changelog](https://github.com/EMMC-ASBL/tripper/compare/v0.2.16...HEAD)
5
+ [Full Changelog](https://github.com/EMMC-ASBL/tripper/compare/v0.2.16...v0.3.0)
6
6
 
7
- **Fixed bugs:**
7
+ **Merged pull requests:**
8
8
 
9
- - cannot release [\#211](https://github.com/EMMC-ASBL/tripper/issues/211)
9
+ - Tutorial update [\#227](https://github.com/EMMC-ASBL/tripper/pull/227) ([jesper-friis](https://github.com/jesper-friis))
10
+ - Get rid of the last warning in the tests [\#226](https://github.com/EMMC-ASBL/tripper/pull/226) ([jesper-friis](https://github.com/jesper-friis))
11
+ - Get restrictions as dicts [\#225](https://github.com/EMMC-ASBL/tripper/pull/225) ([jesper-friis](https://github.com/jesper-friis))
12
+ - \[pre-commit.ci\] pre-commit autoupdate [\#224](https://github.com/EMMC-ASBL/tripper/pull/224) ([pre-commit-ci[bot]](https://github.com/apps/pre-commit-ci))
13
+ - Added an additional test for convert [\#223](https://github.com/EMMC-ASBL/tripper/pull/223) ([jesper-friis](https://github.com/jesper-friis))
14
+ - Minor fix in tutorial [\#221](https://github.com/EMMC-ASBL/tripper/pull/221) ([jesper-friis](https://github.com/jesper-friis))
15
+ - Updated the tutorial [\#220](https://github.com/EMMC-ASBL/tripper/pull/220) ([jesper-friis](https://github.com/jesper-friis))
16
+ - Improved the handling of different return types from the query\(\) method [\#219](https://github.com/EMMC-ASBL/tripper/pull/219) ([jesper-friis](https://github.com/jesper-friis))
17
+ - Correct parsing literals from the rdflib backend. [\#217](https://github.com/EMMC-ASBL/tripper/pull/217) ([jesper-friis](https://github.com/jesper-friis))
18
+ - Do not save cache while interpreter shotdown. [\#216](https://github.com/EMMC-ASBL/tripper/pull/216) ([jesper-friis](https://github.com/jesper-friis))
19
+ - Allow string literal to compare equal to strings. [\#215](https://github.com/EMMC-ASBL/tripper/pull/215) ([jesper-friis](https://github.com/jesper-friis))
20
+ - Also test for Python 3.12 [\#213](https://github.com/EMMC-ASBL/tripper/pull/213) ([jesper-friis](https://github.com/jesper-friis))
10
21
 
11
22
  ## [v0.2.16](https://github.com/EMMC-ASBL/tripper/tree/v0.2.16) (2024-05-16)
12
23
 
13
24
  [Full Changelog](https://github.com/EMMC-ASBL/tripper/compare/v0.2.15...v0.2.16)
14
25
 
26
+ **Fixed bugs:**
27
+
28
+ - cannot release [\#211](https://github.com/EMMC-ASBL/tripper/issues/211)
29
+
15
30
  **Closed issues:**
16
31
 
17
32
  - Add caching and extension to tripper.Namespace [\#194](https://github.com/EMMC-ASBL/tripper/issues/194)
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.1
2
2
  Name: tripper
3
- Version: 0.2.16
3
+ Version: 0.3.0
4
4
  Summary: A triplestore wrapper for Python.
5
5
  Keywords: triplestore,ontology,RDF
6
6
  Author-email: SINTEF <TEAM4.0@sintef.no>
@@ -14,12 +14,13 @@ Classifier: Programming Language :: Python :: 3.8
14
14
  Classifier: Programming Language :: Python :: 3.9
15
15
  Classifier: Programming Language :: Python :: 3.10
16
16
  Classifier: Programming Language :: Python :: 3.11
17
+ Classifier: Programming Language :: Python :: 3.12
17
18
  Classifier: Environment :: Plugins
18
19
  Classifier: Natural Language :: English
19
20
  Classifier: Operating System :: OS Independent
20
21
  Requires-Dist: typing-extensions ~=4.7; python_version<'3.8'
21
22
  Requires-Dist: pint>=0.16.1,<0.24
22
- Requires-Dist: mike ~=2.0 ; extra == "dev"
23
+ Requires-Dist: mike ~=2.1 ; extra == "dev"
23
24
  Requires-Dist: mkdocs ~=1.5 ; extra == "dev"
24
25
  Requires-Dist: mkdocs-awesome-pages-plugin ~=2.9 ; extra == "dev"
25
26
  Requires-Dist: mkdocs-material >=9.2.8 ; extra == "dev"
@@ -31,8 +32,8 @@ Requires-Dist: pytest-cov ~=4.1 ; extra == "dev"
31
32
  Requires-Dist: EMMOntoPy ~=0.7 ; extra == "dev"
32
33
  Requires-Dist: rdflib ~=6.3 ; extra == "dev"
33
34
  Requires-Dist: SPARQLWrapper ~=2.0 ; extra == "dev"
34
- Requires-Dist: DLite-Python >=0.5.1,<1 ; extra == "dev"
35
- Requires-Dist: mike ~=2.0 ; extra == "docs"
35
+ Requires-Dist: DLite-Python >=0.5.1,<0.5.17 ; extra == "dev"
36
+ Requires-Dist: mike ~=2.1 ; extra == "docs"
36
37
  Requires-Dist: mkdocs ~=1.5 ; extra == "docs"
37
38
  Requires-Dist: mkdocs-awesome-pages-plugin ~=2.9 ; extra == "docs"
38
39
  Requires-Dist: mkdocs-material >=9.2.8 ; extra == "docs"
@@ -40,7 +41,7 @@ Requires-Dist: mkdocstrings[python-legacy] ~=0.22.0 ; extra == "docs"
40
41
  Requires-Dist: EMMOntoPy ~=0.7 ; extra == "docs"
41
42
  Requires-Dist: rdflib ~=6.3 ; extra == "docs"
42
43
  Requires-Dist: SPARQLWrapper ~=2.0 ; extra == "docs"
43
- Requires-Dist: DLite-Python >=0.5.1,<1 ; extra == "docs"
44
+ Requires-Dist: DLite-Python >=0.5.1,<0.5.17 ; extra == "docs"
44
45
  Requires-Dist: pre-commit ~=2.21 ; extra == "pre-commit"
45
46
  Requires-Dist: pylint ~=2.13 ; extra == "pre-commit"
46
47
  Requires-Dist: pytest ~=7.4 ; extra == "testing"
@@ -48,7 +49,7 @@ Requires-Dist: pytest-cov ~=4.1 ; extra == "testing"
48
49
  Requires-Dist: EMMOntoPy ~=0.7 ; extra == "testing"
49
50
  Requires-Dist: rdflib ~=6.3 ; extra == "testing"
50
51
  Requires-Dist: SPARQLWrapper ~=2.0 ; extra == "testing"
51
- Requires-Dist: DLite-Python >=0.5.1,<1 ; extra == "testing"
52
+ Requires-Dist: DLite-Python >=0.5.1,<0.5.17 ; extra == "testing"
52
53
  Requires-Dist: graphviz ~= 0.20 ; extra == "testing"
53
54
  Requires-Dist: pint>=0.16.1,<0.23 ; extra == "testing"
54
55
  Requires-Dist: pytest ~=7.4 ; extra == "testing-core"
@@ -0,0 +1,411 @@
1
+ Basic tutorial
2
+ ==============
3
+ <!-- markdownlint-disable MD007 -->
4
+
5
+
6
+ Introduction
7
+ ------------
8
+ Tripper is a Python library providing a common interface to a range of pre-defined triplestores.
9
+ This is done via a plugin system for different triplestore `backends`.
10
+ See the README file for a [list of currently supported backends].
11
+
12
+ The API provided by Tripper is modelled after [rdflib], so if you know that library, you will find Tripper rather familiar.
13
+ But there are some differences to be aware of.
14
+ Most important are:
15
+
16
+ * All IRIs are represented by Python strings.
17
+ Example: `"https://w3id.org/emmo#Metre"`
18
+ * Blank nodes are strings starting with "_:".
19
+ Example: `"_:bnode1"`
20
+ * Literals are constructed with [`tripper.Literal`][Literal].
21
+ Example: `tripper.Literal(3.14, datatype=XSD.float)`
22
+ * Namespace object works similar to namespace objects in rdflib, but its
23
+ attribution access expands to plain Python strings.
24
+ Example: `XSD.float`
25
+
26
+ Tripper namespaces has also additional features that make them very
27
+ convinient when working with ontologies, like [EMMO] that uses
28
+ numerical IRIs.
29
+
30
+
31
+ Getting started
32
+ ---------------
33
+ To interface a triplestore, you create an instance of [Triplestore] providing the name of the triplestore as the `backend` argument.
34
+
35
+ For example, to create an interface to an in-memory [rdflib] triplestore, you can use the `rdflib` backend:
36
+
37
+ ```python
38
+ >>> from tripper import Triplestore
39
+ >>> ts = Triplestore(backend="rdflib")
40
+
41
+ ```
42
+
43
+ ### Namespace objects
44
+ Namespace objects are a very convenient feature that simplifies writing IRIs.
45
+ Tripper provides a set of standard pre-defined namespaces that can simply be imported.
46
+ For example:
47
+
48
+ ```python
49
+ >>> from tripper import OWL, RDFS
50
+ >>> RDFS.subClassOf
51
+ 'http://www.w3.org/2000/01/rdf-schema#subClassOf'
52
+
53
+ ```
54
+
55
+ New namespaces can be created using the [Namespace] class, but are usually added with the [`bind()`] method:
56
+
57
+ ```python
58
+ >>> ONTO = ts.bind("onto", "http://example.com/onto#")
59
+ >>> ONTO.MyConcept
60
+ 'http://example.com/onto#MyConcept'
61
+
62
+ ```
63
+
64
+ ### Adding triples to the triplestore
65
+ Triples can now be added to the triplestore, using the [`add()`] and [`add_triples()`] methods:
66
+
67
+ ```python
68
+ >>> from tripper.utils import en
69
+ >>> ts.add_triples([
70
+ ... (ONTO.MyConcept, RDFS.subClassOf, OWL.Thing),
71
+ ... (ONTO.MyConcept, RDFS.label, en("My briliant ontological concept.")),
72
+ ... ])
73
+
74
+ ```
75
+
76
+ The function [`en()`] is just a convenient function for adding English literals.
77
+ It is equivalent to `tripper.Literal(msg, lang="en")`.
78
+
79
+ Triples can also be added from a source using the [`parse()`] method.
80
+ For example will
81
+
82
+ ```python
83
+ ts.parse("onto.ttl", format="turtle")
84
+ ```
85
+
86
+ load all triples in turtle file `onto.ttl` into the triplestore.
87
+
88
+ Similarly, the triplestore can be serialised to a string or a file using the [`serialize()`] method:
89
+
90
+ ```python
91
+ ts.serialize("onto2.ttl") # serialise to file `onto2.ttl`
92
+ s = ts.serialize(format="ntriples") # serialise to string s in ntriples format
93
+ ```
94
+
95
+ ### Retrieving triples from and querying a triplestore
96
+ A set of convenient functions exist for simple queries, including [`triples()`], [`subjects()`], [`predicates()`], [`objects()`], [`subject_predicates()`], [`subject_objects()`], [`predicate_objects()`] and [`value()`].
97
+ Except for [`value()`], they return iterators.
98
+ For example:
99
+
100
+ ```python
101
+ >>> ts.objects(subject=ONTO.MyConcept, predicate=RDFS.subClassOf) # doctest: +ELLIPSIS
102
+ <generator object Triplestore.objects at 0x...>
103
+
104
+ >>> list(ts.objects(subject=ONTO.MyConcept, predicate=RDFS.subClassOf))
105
+ ['http://www.w3.org/2002/07/owl#Thing']
106
+
107
+ ```
108
+
109
+ The [`query()`] and [`update()`] methods can be used to query and update the triplestore using SPARQL.
110
+ See the next section.
111
+
112
+
113
+ Slightly more advanced features
114
+ -------------------------------
115
+
116
+ ### More advanced use of namespaces
117
+ Namespace also supports access by label and IRI checking.
118
+ Both of these features requires loading an ontology.
119
+ The following example shows how to create an EMMO namespace with IRI checking.
120
+ The keyword argument `label_annotations=True` enables access by `skos:prefLabel`, `rdfs:label` or `skos:altLabel`.
121
+ What labels to use can also be specified explicitly.
122
+ The `check=True` enables checking for existing IRIs.
123
+
124
+ ```python
125
+ >>> EMMO = ts.bind(
126
+ ... prefix="emmo",
127
+ ... namespace="https://w3id.org/emmo#",
128
+ ... label_annotations=True,
129
+ ... check=True,
130
+ ... )
131
+
132
+ # Access by label
133
+ >>> EMMO.Atom
134
+ 'https://w3id.org/emmo#EMMO_eb77076b_a104_42ac_a065_798b2d2809ad'
135
+
136
+ # This fails because we set `check=True`
137
+ >>> EMMO.invalid_name # doctest: +ELLIPSIS
138
+ Traceback (most recent call last):
139
+ ...
140
+ tripper.errors.NoSuchIRIError: https://w3id.org/emmo#invalid_name
141
+ Maybe you have to remove the cache file: ...
142
+
143
+ ```
144
+
145
+ The above example works, since the `namespace="https://w3id.org/emmo#"` is resolvable.
146
+ When the IRI in the `namespace` argument is not resolvable, it is possible to supply a resolvable IRI or a reference to a populated [Triplestore] instance via the `triplestore` keyword argument.
147
+
148
+ Access by label makes it much easier to work with ontologies, like EMMO, that uses non-human readable IDs for the IRIs.
149
+ More about this below.
150
+
151
+ The utility function [`extend_namespace()`] can be used to add additional known labels to a namespace.
152
+ For example:
153
+
154
+ ```python
155
+ >>> from tripper import Namespace
156
+ >>> from tripper.utils import extend_namespace
157
+ >>> FOOD = Namespace(
158
+ ... "http://onto-ns.com/ontologies/examples/food#",
159
+ ... label_annotations=True,
160
+ ... check=True,
161
+ ... reload=True,
162
+ ... triplestore="https://raw.githubusercontent.com/EMMC-ASBL/tripper/master/tests/ontologies/food.ttl",
163
+ ... format="turtle",
164
+ ... )
165
+
166
+ # Hamburger is not a known label
167
+ >>> FOOD.Hamburger # doctest: +ELLIPSIS
168
+ Traceback (most recent call last):
169
+ ...
170
+ tripper.errors.NoSuchIRIError: http://onto-ns.com/ontologies/examples/food#Hamburger
171
+ ...
172
+
173
+ # Add Hamburger to known labels
174
+ >>> extend_namespace(FOOD, {"Hamburger": FOOD + "Hamburger"})
175
+ >>> FOOD.Hamburger == FOOD + "Hamburger"
176
+ True
177
+
178
+ # Fish is not a known label
179
+ >>> FOOD.Fish # doctest: +ELLIPSIS
180
+ Traceback (most recent call last):
181
+ ...
182
+ tripper.errors.NoSuchIRIError: http://onto-ns.com/ontologies/examples/food#Fish
183
+ ...
184
+
185
+ # Extend FOOD from an online turtle file
186
+ >>> extend_namespace(
187
+ ... FOOD,
188
+ ... "https://raw.githubusercontent.com/EMMC-ASBL/tripper/master/tests/ontologies/food-more.ttl",
189
+ ... format="turtle",
190
+ ... )
191
+
192
+ # Now Fish is in the namespace
193
+ >>> FOOD.Fish
194
+ 'http://onto-ns.com/ontologies/examples/food#FOOD_90f5dd54_9e5c_46c9_824f_e10625a90c26'
195
+
196
+ ```
197
+
198
+
199
+ ### Writing SPARQL queries using Tripper
200
+ A challenge with ontologies using numerical IRIs is that SPARQL queries become difficult to read and understand.
201
+ This challenge is greatly mitigated by using the `label_annotations` feature of Tripper namespaces.
202
+ The example below shows how to write and execute a SPARQL query with Tripper that finds the IRI and unit symbol of all length units.
203
+ Note:
204
+ 1. EMMO classes and properties are written as `{EMMO.LengthUnit}`, which would expand to `https://w3id.org/emmo#EMMO_b3600e73_3e05_479d_9714_c041c3acf5cc`.
205
+ 2. The curly brackets after the `WHERE` clause have to be written `{{`, `}}` because the query is an f-string.
206
+
207
+ ```python
208
+ # Load pre-inferred EMMO
209
+ >>> ts = Triplestore("rdflib", base_iri="https://w3id.org/emmo#")
210
+ >>> ts.parse("https://w3id.org/emmo#inferred")
211
+
212
+ # Bind "emmo" prefix to base_iri
213
+ >>> EMMO = ts.bind("emmo", label_annotations=True, check=True)
214
+
215
+ # Get IRI and symbol of all length units
216
+ >>> query = f"""
217
+ ... PREFIX owl: <http://www.w3.org/2002/07/owl#>
218
+ ... PREFIX rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>
219
+ ... PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>
220
+ ...
221
+ ... SELECT ?unit ?symbol
222
+ ... WHERE {{
223
+ ... ?unit rdfs:subClassOf <{EMMO.LengthUnit}> .
224
+ ... ?unit rdfs:subClassOf ?r .
225
+ ... ?r rdf:type owl:Restriction .
226
+ ... ?r owl:onProperty <{EMMO.hasSymbolValue}> .
227
+ ... ?r owl:hasValue ?symbol .
228
+ ... }}
229
+ ... """
230
+ >>> r = ts.query(query)
231
+ >>> (EMMO.Metre, "m") in r
232
+ True
233
+
234
+ ```
235
+
236
+ ### Class restrictions
237
+ When working with OWL ontologies, it is often required to inspect or add class [restriction]s.
238
+ The Triplestore class has two convenient methods for this, that do not require knowledge about how restrictions are represented in RDF.
239
+ Only support basic restrictions, without any nested logical constructs, are supoprted.
240
+ For more advanced restrictions, we recommend to use [EMMOntoPy] or [Owlready2].
241
+
242
+ A [restriction] restricts a class to only those individuals that satisfy the restriction.
243
+ It is described by the following set of parameters.
244
+
245
+ * **cls**: IRI of class to which the restriction applies.
246
+ * **property**: IRI of restriction property.
247
+ * **type**: The type of the restriction. Should be one of:
248
+ - *some*: existential restriction (target is a class IRI)
249
+ - *only*: universal restriction (target is a class IRI)
250
+ - *exactly*: cardinality restriction (target is a class IRI)
251
+ - *min*: minimum cardinality restriction (target is a class IRI)
252
+ - *max*: maximum cardinality restriction (target is a class IRI)
253
+ - *value*: Value restriction (target is an IRI of an individual or a literal)
254
+
255
+ * **cardinality**: the cardinality value for cardinality restrictions.
256
+ * **value**: The IRI or literal value of the restriction target.
257
+
258
+ As an example, the class `onto:Bacteria` can be logically restricted to be unicellular.
259
+ In Manchester syntax, this can be stated as `onto:Bacteria emmo:hasPart exactly 1 onto:Cell`.
260
+ With Tripper this can be stated as:
261
+
262
+ ```python
263
+ >>> iri = ts.add_restriction(
264
+ ... cls=ONTO.Bacteria,
265
+ ... property=EMMO.hasPart,
266
+ ... type="exactly",
267
+ ... cardinality=1,
268
+ ... value=ONTO.Cell,
269
+ ... )
270
+
271
+ ```
272
+ The returned `iri` is the blank node IRI of the new restriction.
273
+
274
+ To find the above restriction, the [`restrictions()`] method can be used.
275
+ It returns an iterator over all restrictions that matches the provided criteria.
276
+ For example:
277
+
278
+ ```python
279
+ >>> g = ts.restrictions(cls=ONTO.Bacteria, property=EMMO.hasPart, asdict=True)
280
+ >>> list(g) # doctest: +ELLIPSIS
281
+ [{'iri': '_:...', 'cls': 'http://example.com/onto#Bacteria', 'property': 'https://w3id.org/emmo#EMMO_17e27c22_37e1_468c_9dd7_95e137f73e7f', 'type': 'exactly', 'cardinality': 1, 'value': 'http://example.com/onto#Cell'}]
282
+
283
+ ```
284
+
285
+ With the `asdict` argument set to false, an iterator over the IRIs of all matching restrictions is returned:
286
+
287
+ ```python
288
+ >>> g = ts.restrictions(cls=ONTO.Bacteria, property=EMMO.hasPart, asdict=False)
289
+ >>> next(g) == iri
290
+ True
291
+
292
+ ```
293
+
294
+
295
+ ### Utilities
296
+ *Todo: Describe the `tripper.utils` module*
297
+
298
+
299
+
300
+ Specialised features
301
+ ====================
302
+
303
+
304
+ Working with mappings
305
+ ---------------------
306
+ With a *data model*, we here mean an abstract model that describes the structure of a dataset.
307
+ To provide a shared semantic meaning of a data model and its *properties* (structural elements), one can create *mappings* between these elements and ontological concepts (typically a class in an OWL ontology).
308
+
309
+ Mappings can also be used to semantically document the arguments and return values of a function.
310
+
311
+ The [Triplestore] class has two specialised methods for adding mappings, [`map()`] and [`add_function()`].
312
+ The purpose of the [`map()`] method, is to map a data models and its properties to ontological concepts, while [`add_function()`] maps the arguments and return value of a function to ontological concepts.
313
+
314
+ **Note**, the name of the [`map()`] and [`add_function()`] methods are not very intuitive and may be changed in the future.
315
+
316
+
317
+ ### Adding mappings
318
+ Lets assume that you have a data model identified by the IRI `http://onto-ns.com/meta/ex/0.1/MyDataModel`, which has a property (structural element) called *velocity*.
319
+ A namespace object for this data model can be created with
320
+
321
+ ```python
322
+ from tripper import Namespace
323
+ DM = Namespace("http://onto-ns.com/meta/ex/0.1/MyDataModel#")
324
+ ```
325
+
326
+ and use to map the data model property `velocity` to the concept `ONTO.Velocity` in the ontology
327
+
328
+
329
+ ```python
330
+ ts.map(DM.velocity, ONTO.Velocity)
331
+ ```
332
+
333
+ One can also work directly with DLite and SOFT7 data models.
334
+ Here we repeat the above with DLite:
335
+
336
+ ```python
337
+ import dlite
338
+ mymodel = dlite.get_instance("http://onto-ns.com/meta/ex/0.1/MyDataModel")
339
+ ts.map(mymodel.velocity, ONTO.Velocity)
340
+ ```
341
+
342
+ The `add_function()` method documents a Python function semantically and adds mappings for its arguments and return value(s).
343
+ Currently, it supports both [EMMO] and the [Function Ontology (FnO)] for the semantic documentation.
344
+
345
+ For example, to semantically document the general function `mean()` applied to the special context of arm lengths, one can do
346
+
347
+ ```python
348
+ def mean(x, y):
349
+ """Returns the mean value of `x` and `y`."""
350
+ return (x + y)/2
351
+
352
+ ts.add_function(
353
+ mean,
354
+ expects=(ONTO.RightArmLength, ONTO.LeftArmLength),
355
+ returns=ONTO.AverageArmLength,
356
+ )
357
+ ```
358
+
359
+
360
+ ### Using mappings
361
+ *Todo: Describe the `tripper.mappings` subpackage...*
362
+
363
+
364
+
365
+
366
+
367
+ [rdflib]: https://rdflib.readthedocs.io/
368
+ [EMMO]: https://emmc.eu/emmo/
369
+ [OTEIO]: https://github.com/emmo-repo/domain-oteio/
370
+ [Function Ontology (FnO)]: https://fno.io/
371
+ [EMMOntoPy]: https://emmo-repo.github.io/EMMOntoPy/
372
+ [Owlready2]: https://pypi.org/project/owlready2/
373
+ [restriction]: https://www.w3.org/TR/owl-ref/#Restriction
374
+ [JSON-LD]: https://json-ld.org/
375
+
376
+ [Creating a triplestore interface]: #creating-a-triplestore-interface
377
+ [list of currently supported backends]: https://github.com/EMMC-ASBL/tripper?tab=readme-ov-file#available-backends
378
+
379
+ [tripper.convert]: https://emmc-asbl.github.io/tripper/latest/api_reference/convert/convert/
380
+
381
+ [Triplestore]: https://emmc-asbl.github.io/tripper/latest/api_reference/triplestore/#tripper.triplestore.Triplestore
382
+ [Namespace]:
383
+ https://emmc-asbl.github.io/tripper/latest/api_reference/namespace/#tripper.namespace.Namespace
384
+ [Literal]:
385
+ https://emmc-asbl.github.io/tripper/latest/api_reference/literal/#tripper.literal.Literal
386
+
387
+ [`en()`]: https://emmc-asbl.github.io/tripper/latest/api_reference/triplestore/#tripper.utils.en
388
+ [`extend_namespace()`]: https://emmc-asbl.github.io/tripper/latest/api_reference/triplestore/#tripper.utils.extend_namespace
389
+
390
+ [`load_container()`]: https://emmc-asbl.github.io/tripper/latest/api_reference/convert/convert/#tripper.convert.convert.load_container
391
+ [`save_container()`]: https://emmc-asbl.github.io/tripper/latest/api_reference/convert/convert/#tripper.convert.convert.save_container
392
+
393
+ [`add()`]: https://emmc-asbl.github.io/tripper/latest/api_reference/triplestore/#tripper.triplestore.Triplestore.add
394
+ [`add_function()`]: https://emmc-asbl.github.io/tripper/latest/api_reference/triplestore/#tripper.triplestore.Triplestore.add_function
395
+ [`add_restriction()`]: https://emmc-asbl.github.io/tripper/latest/api_reference/triplestore/#tripper.triplestore.Triplestore.add_restriction
396
+ [`add_triples()`]: https://emmc-asbl.github.io/tripper/latest/api_reference/triplestore/#tripper.triplestore.Triplestore.add_triples
397
+ [`bind()`]: https://emmc-asbl.github.io/tripper/latest/api_reference/triplestore/#tripper.triplestore.Triplestore.bind
398
+ [`map()`]: https://emmc-asbl.github.io/tripper/latest/api_reference/triplestore/#tripper.triplestore.Triplestore.map
399
+ [`objects()`]: https://emmc-asbl.github.io/tripper/latest/api_reference/triplestore/#tripper.triplestore.Triplestore.objects
400
+ [`parse()`]: https://emmc-asbl.github.io/tripper/latest/api_reference/triplestore/#tripper.triplestore.Triplestore.parse
401
+ [`predicates()`]: https://emmc-asbl.github.io/tripper/latest/api_reference/triplestore/#tripper.triplestore.Triplestore.predicates
402
+ [`predicate_objects()`]: https://emmc-asbl.github.io/tripper/latest/api_reference/triplestore/#tripper.triplestore.Triplestore.predicate_objects
403
+ [`query()`]: https://emmc-asbl.github.io/tripper/latest/api_reference/triplestore/#tripper.triplestore.Triplestore.query
404
+ [`restrictions()`]: https://emmc-asbl.github.io/tripper/latest/api_reference/triplestore/#tripper.triplestore.Triplestore.restrictions
405
+ [`serialize()`]: https://emmc-asbl.github.io/tripper/latest/api_reference/triplestore/#tripper.triplestore.Triplestore.serialize
406
+ [`subject_objects()`]: https://emmc-asbl.github.io/tripper/latest/api_reference/triplestore/#tripper.triplestore.Triplestore.subject_objects
407
+ [`subject_predicates()`]: https://emmc-asbl.github.io/tripper/latest/api_reference/triplestore/#tripper.triplestore.Triplestore.subject_predicates
408
+ [`subjects()`]: https://emmc-asbl.github.io/tripper/latest/api_reference/triplestore/#tripper.triplestore.Triplestore.subjects
409
+ [`triples()`]: https://emmc-asbl.github.io/tripper/latest/api_reference/triplestore/#tripper.triplestore.Triplestore.triples
410
+ [`update()`]: https://emmc-asbl.github.io/tripper/latest/api_reference/triplestore/#tripper.triplestore.Triplestore.update
411
+ [`value()`]: https://emmc-asbl.github.io/tripper/latest/api_reference/triplestore/#tripper.triplestore.Triplestore.value
@@ -19,6 +19,7 @@ classifiers = [
19
19
  "Programming Language :: Python :: 3.9",
20
20
  "Programming Language :: Python :: 3.10",
21
21
  "Programming Language :: Python :: 3.11",
22
+ "Programming Language :: Python :: 3.12",
22
23
  "Environment :: Plugins",
23
24
  "Natural Language :: English",
24
25
  "Operating System :: OS Independent",
@@ -34,7 +35,7 @@ dependencies = [
34
35
 
35
36
  [project.optional-dependencies]
36
37
  docs = [
37
- "mike ~=2.0",
38
+ "mike ~=2.1",
38
39
  "mkdocs ~=1.5",
39
40
  "mkdocs-awesome-pages-plugin ~=2.9",
40
41
  "mkdocs-material >=9.2.8",
@@ -42,7 +43,7 @@ docs = [
42
43
  "EMMOntoPy ~=0.7",
43
44
  "rdflib ~=6.3",
44
45
  "SPARQLWrapper ~=2.0",
45
- "DLite-Python >=0.5.1,<1",
46
+ "DLite-Python >=0.5.1,<0.5.17",
46
47
  ]
47
48
  pre-commit = [
48
49
  "pre-commit ~=2.21",
@@ -54,7 +55,7 @@ testing = [
54
55
  "EMMOntoPy ~=0.7",
55
56
  "rdflib ~=6.3",
56
57
  "SPARQLWrapper ~=2.0",
57
- "DLite-Python >=0.5.1,<1",
58
+ "DLite-Python >=0.5.1,<0.5.17",
58
59
  "graphviz ~= 0.20",
59
60
  "pint>=0.16.1,<0.23",
60
61
  ]
@@ -63,7 +64,7 @@ testing-core = [
63
64
  "pytest-cov ~=4.1",
64
65
  ]
65
66
  dev = [
66
- "mike ~=2.0",
67
+ "mike ~=2.1",
67
68
  "mkdocs ~=1.5",
68
69
  "mkdocs-awesome-pages-plugin ~=2.9",
69
70
  "mkdocs-material >=9.2.8",
@@ -75,7 +76,7 @@ dev = [
75
76
  "EMMOntoPy ~=0.7",
76
77
  "rdflib ~=6.3",
77
78
  "SPARQLWrapper ~=2.0",
78
- "DLite-Python >=0.5.1,<1",
79
+ "DLite-Python >=0.5.1,<0.5.17",
79
80
  ]
80
81
 
81
82
  [project.urls]
@@ -93,7 +94,7 @@ line_length = 79 # PEP8
93
94
  line-length = 79
94
95
 
95
96
  [tool.mypy]
96
- python_version = "3.7"
97
+ python_version = "3.11"
97
98
  ignore_missing_imports = true
98
99
  scripts_are_modules = true
99
100
  warn_unused_configs = true