prograph 1.3.3__py3-none-any.whl
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.
- prograph/__init__.py +36 -0
- prograph/__main__.py +5 -0
- prograph/_version.py +375 -0
- prograph/cli/__init__.py +1 -0
- prograph/cli/_iri_utils.py +124 -0
- prograph/cli/emit_genie_space.py +107 -0
- prograph/cli/generate_views.py +140 -0
- prograph/cli/main.py +420 -0
- prograph/cli/schema_inferrer.py +746 -0
- prograph/cli/ttl_loader.py +289 -0
- prograph/cli/upload_genie_space.py +84 -0
- prograph/config/__init__.py +27 -0
- prograph/config/yaml_config.py +848 -0
- prograph/demos/__init__.py +14 -0
- prograph/demos/turbofan/README.md +74 -0
- prograph/demos/turbofan/SCENARIO.md +209 -0
- prograph/demos/turbofan/__init__.py +75 -0
- prograph/demos/turbofan/create_tables.sql +206 -0
- prograph/demos/turbofan/data/engine-instances.ttl +1123 -0
- prograph/demos/turbofan/data/sensor-timeseries.csv +90 -0
- prograph/demos/turbofan/demo.py +162 -0
- prograph/demos/turbofan/genie_qa_notebook.py +434 -0
- prograph/demos/turbofan/graph.yaml +1098 -0
- prograph/demos/turbofan/instance_graph_demo.py +32 -0
- prograph/demos/turbofan/load.py +223 -0
- prograph/demos/turbofan/mapping.r2rml.ttl +991 -0
- prograph/demos/turbofan/ontology/engine-maintenance.ttl +606 -0
- prograph/demos/turbofan/payload-shapes.ttl +33 -0
- prograph/demos/turbofan/queries/example-queries.sparql +215 -0
- prograph/demos/turbofan/shapes.ttl +75 -0
- prograph/demos/turbofan/tables.py +106 -0
- prograph/demos/turbofan/turbofan_schema.py +393 -0
- prograph/demos/turbofan/validation_demo.py +153 -0
- prograph/describe.py +231 -0
- prograph/endpoint/__init__.py +12 -0
- prograph/endpoint/app.py +722 -0
- prograph/endpoint/cli.py +280 -0
- prograph/endpoint/credentials.py +240 -0
- prograph/endpoint/engines.py +418 -0
- prograph/endpoint/negotiate.py +101 -0
- prograph/endpoint/results.py +181 -0
- prograph/endpoint/service.py +31 -0
- prograph/engine.py +2718 -0
- prograph/execution.py +455 -0
- prograph/executors/__init__.py +6 -0
- prograph/executors/base.py +11 -0
- prograph/executors/databricks_sql_executor.py +51 -0
- prograph/executors/duckdb_executor.py +24 -0
- prograph/executors/mysql_executor.py +20 -0
- prograph/executors/oracle_executor.py +24 -0
- prograph/executors/pandas_executor.py +72 -0
- prograph/executors/postgresql_executor.py +35 -0
- prograph/executors/spark_executor.py +88 -0
- prograph/executors/sqlserver_executor.py +35 -0
- prograph/extras/__init__.py +1 -0
- prograph/extras/graphql/__init__.py +33 -0
- prograph/extras/graphql/execute.py +25 -0
- prograph/extras/graphql/schema.py +314 -0
- prograph/extras/instance_graph.py +559 -0
- prograph/genie/__init__.py +83 -0
- prograph/genie/databricks_uploader.py +306 -0
- prograph/genie/deploy.py +393 -0
- prograph/genie/formats.py +414 -0
- prograph/genie/instruction_generator.py +375 -0
- prograph/genie/sample_query_generator.py +256 -0
- prograph/genie/shacl_views.py +318 -0
- prograph/genie/space_emitter.py +329 -0
- prograph/genie/view_generator.py +628 -0
- prograph/genie/view_writer.py +172 -0
- prograph/graph/__init__.py +1 -0
- prograph/graph/ansi_session.py +348 -0
- prograph/graph/databricks_sql_graph.py +300 -0
- prograph/graph/drivers.py +143 -0
- prograph/graph/duckdb_graph.py +68 -0
- prograph/graph/mysql_graph.py +38 -0
- prograph/graph/oracle_graph.py +285 -0
- prograph/graph/pandas_graph.py +343 -0
- prograph/graph/postgresql_graph.py +644 -0
- prograph/graph/spark_graph.py +556 -0
- prograph/graph/sql_graph.py +83 -0
- prograph/graph/sqlserver_graph.py +72 -0
- prograph/hints.py +95 -0
- prograph/logging.py +550 -0
- prograph/mcp/__init__.py +29 -0
- prograph/mcp/__main__.py +180 -0
- prograph/mcp/bootstrap.py +98 -0
- prograph/mcp/server.py +601 -0
- prograph/mcp/sparql.py +397 -0
- prograph/mcp/tools.py +504 -0
- prograph/nlp/__init__.py +79 -0
- prograph/nlp/client.py +305 -0
- prograph/nlp/databricks_tools.py +369 -0
- prograph/nlp/graph_context.py +313 -0
- prograph/nlp/interface.py +652 -0
- prograph/nlp/prompts/__init__.py +19 -0
- prograph/nlp/prompts/examples.py +258 -0
- prograph/nlp/prompts/system.py +239 -0
- prograph/nlp/providers/__init__.py +14 -0
- prograph/nlp/providers/anthropic.py +274 -0
- prograph/nlp/providers/databricks.py +312 -0
- prograph/nlp/providers/openai.py +203 -0
- prograph/nlp/schema_context.py +78 -0
- prograph/ontology/__init__.py +53 -0
- prograph/ontology/alignment.py +542 -0
- prograph/ontology/hierarchy.py +310 -0
- prograph/ontology/imports.py +587 -0
- prograph/ontology/layer.py +991 -0
- prograph/ontology/skos.py +61 -0
- prograph/owl/__init__.py +27 -0
- prograph/owl/defined_classes.py +323 -0
- prograph/parameters.py +242 -0
- prograph/parser/__init__.py +1 -0
- prograph/parser/cypher/CypherLexer.py +836 -0
- prograph/parser/cypher/CypherListener.py +966 -0
- prograph/parser/cypher/CypherParser.py +10854 -0
- prograph/parser/cypher/CypherVisitor.py +543 -0
- prograph/parser/cypher/__init__.py +1 -0
- prograph/parser/sparql/SparqlLexer.py +801 -0
- prograph/parser/sparql/SparqlParser.py +10146 -0
- prograph/parser/sparql/SparqlParserListener.py +1056 -0
- prograph/parser/sparql/SparqlParserVisitor.py +593 -0
- prograph/parser/sparql/__init__.py +8 -0
- prograph/plan/__init__.py +3 -0
- prograph/plan/ir/__init__.py +1 -0
- prograph/plan/ir/casts.py +338 -0
- prograph/plan/ir/consistency.py +397 -0
- prograph/plan/ir/construct.py +90 -0
- prograph/plan/ir/cost.py +234 -0
- prograph/plan/ir/cypher_answer.py +1081 -0
- prograph/plan/ir/cypher_apoc.py +717 -0
- prograph/plan/ir/cypher_apoc_convert.py +505 -0
- prograph/plan/ir/cypher_apoc_date.py +845 -0
- prograph/plan/ir/cypher_apoc_map.py +496 -0
- prograph/plan/ir/cypher_apoc_meta.py +384 -0
- prograph/plan/ir/cypher_apoc_path.py +597 -0
- prograph/plan/ir/cypher_apoc_procedures.py +163 -0
- prograph/plan/ir/cypher_apoc_text.py +785 -0
- prograph/plan/ir/cypher_front.py +5474 -0
- prograph/plan/ir/cypher_functions.py +565 -0
- prograph/plan/ir/cypher_lists.py +935 -0
- prograph/plan/ir/cypher_maps.py +370 -0
- prograph/plan/ir/cypher_mixed.py +604 -0
- prograph/plan/ir/cypher_ontology.py +226 -0
- prograph/plan/ir/cypher_procedures.py +191 -0
- prograph/plan/ir/cypher_runtime_errors.py +107 -0
- prograph/plan/ir/cypher_temporal.py +1357 -0
- prograph/plan/ir/cypher_temporal_arith.py +339 -0
- prograph/plan/ir/cypher_values.py +546 -0
- prograph/plan/ir/cypher_write.py +612 -0
- prograph/plan/ir/dataset.py +643 -0
- prograph/plan/ir/dates.py +102 -0
- prograph/plan/ir/entry.py +992 -0
- prograph/plan/ir/expr.py +260 -0
- prograph/plan/ir/facts.py +1171 -0
- prograph/plan/ir/fresh.py +291 -0
- prograph/plan/ir/freshness.py +625 -0
- prograph/plan/ir/identity.py +797 -0
- prograph/plan/ir/java_datetime.py +265 -0
- prograph/plan/ir/java_regex.py +391 -0
- prograph/plan/ir/join_order.py +39 -0
- prograph/plan/ir/key_checks.py +433 -0
- prograph/plan/ir/keys.py +454 -0
- prograph/plan/ir/lower.py +5323 -0
- prograph/plan/ir/ops.py +619 -0
- prograph/plan/ir/owl_rl.py +1119 -0
- prograph/plan/ir/owl_rl_rules.py +725 -0
- prograph/plan/ir/profiles.py +694 -0
- prograph/plan/ir/ql.py +987 -0
- prograph/plan/ir/rdfs.py +342 -0
- prograph/plan/ir/rewrite.py +1782 -0
- prograph/plan/ir/saturate.py +339 -0
- prograph/plan/ir/semantics.py +103 -0
- prograph/plan/ir/slot.py +509 -0
- prograph/plan/ir/sparql_front.py +3418 -0
- prograph/plan/ir/strings.py +534 -0
- prograph/plan/ir/term_functions.py +274 -0
- prograph/plan/ir/terms.py +84 -0
- prograph/plan/ir/xpath_regex.py +264 -0
- prograph/plan/run_record.py +65 -0
- prograph/plan/sql/__init__.py +21 -0
- prograph/plan/sql/dialect.py +3726 -0
- prograph/plan/sql/mysql_serializer.py +103 -0
- prograph/plan/sql/names.py +65 -0
- prograph/plan/sql/oracle_serializer.py +306 -0
- prograph/plan/sql/pg_serializer.py +501 -0
- prograph/plan/sql/rel_algebra.py +781 -0
- prograph/plan/sql/sql_serializer.py +1419 -0
- prograph/plan/sql/sqlserver_serializer.py +603 -0
- prograph/provenance.py +222 -0
- prograph/r2rml/__init__.py +48 -0
- prograph/r2rml/catalog.py +259 -0
- prograph/r2rml/compile.py +372 -0
- prograph/r2rml/direct.py +140 -0
- prograph/r2rml/export.py +495 -0
- prograph/r2rml/model.py +180 -0
- prograph/r2rml/parser.py +546 -0
- prograph/r2rml/schema.py +120 -0
- prograph/read_only.py +122 -0
- prograph/results.py +157 -0
- prograph/rules/__init__.py +168 -0
- prograph/rules/__main__.py +32 -0
- prograph/schema/__init__.py +60 -0
- prograph/schema/change_set.py +50 -0
- prograph/schema/collations.py +198 -0
- prograph/schema/compile_schema.py +388 -0
- prograph/schema/context.py +845 -0
- prograph/schema/examples.py +234 -0
- prograph/schema/iri.py +817 -0
- prograph/schema/literals.py +94 -0
- prograph/schema/lpg_view.py +617 -0
- prograph/schema/mapping.py +1803 -0
- prograph/schema/maps_schema.py +40 -0
- prograph/schema/naming.py +77 -0
- prograph/schema/query_sources.py +59 -0
- prograph/schema/rows.py +215 -0
- prograph/schema/source_map.py +1103 -0
- prograph/schema/store_view.py +459 -0
- prograph/schema/types.py +569 -0
- prograph/schema/xsd.py +569 -0
- prograph/shacl/__init__.py +30 -0
- prograph/shacl/dqv.py +58 -0
- prograph/shacl/generate.py +255 -0
- prograph/shacl/report.py +138 -0
- prograph/shacl/validator.py +164 -0
- prograph/store.py +1737 -0
- prograph/utils/__init__.py +6 -0
- prograph/utils/exceptions.py +308 -0
- prograph/utils/helpers.py +126 -0
- prograph/warnings.py +46 -0
- prograph/writes.py +369 -0
- prograph-1.3.3.dist-info/METADATA +281 -0
- prograph-1.3.3.dist-info/RECORD +237 -0
- prograph-1.3.3.dist-info/WHEEL +5 -0
- prograph-1.3.3.dist-info/entry_points.txt +3 -0
- prograph-1.3.3.dist-info/licenses/LICENSE +201 -0
- prograph-1.3.3.dist-info/licenses/NOTICE +10 -0
- prograph-1.3.3.dist-info/top_level.txt +1 -0
prograph/schema/iri.py
ADDED
|
@@ -0,0 +1,817 @@
|
|
|
1
|
+
"""IRI resolution, the single place a mapping's RDF identity is decided.
|
|
2
|
+
|
|
3
|
+
Mapped data has an identity in two worlds: rows and columns in a table, and
|
|
4
|
+
IRIs in RDF. Several subsystems need the second one, R2RML (which imports and exports mappings), the SPARQL
|
|
5
|
+
front-end (whose results are RDF terms, not backend row objects), and the PROV-O
|
|
6
|
+
provenance export (whose entities must be the same nodes the SPARQL graph holds),
|
|
7
|
+
and they must agree, or the same thing acquires a different IRI depending on
|
|
8
|
+
which one you ask.
|
|
9
|
+
|
|
10
|
+
Two kinds of identity live here.
|
|
11
|
+
|
|
12
|
+
**Entity IRIs**, which node a row is:
|
|
13
|
+
|
|
14
|
+
1. If the ``NodeMapping`` declares an ``iri_template``, that wins. Templates are
|
|
15
|
+
R2RML-style, with ``{column}`` placeholders resolved against the row:
|
|
16
|
+
``http://example.org/person/{person_id}``.
|
|
17
|
+
2. Otherwise the IRI is synthesized as ``{base_iri}{source_table}/{id}``, with
|
|
18
|
+
composite keys joined by ``/`` in ``id_columns`` order.
|
|
19
|
+
|
|
20
|
+
A template referencing a column that is missing or null yields no IRI (``None``)
|
|
21
|
+
rather than an IRI containing the string ``None``, the node simply has no
|
|
22
|
+
identity in RDF, which is what an unresolvable subject map means in R2RML.
|
|
23
|
+
|
|
24
|
+
A value placed in an IRI is made **IRI-safe** first (R2RML 7.3): every
|
|
25
|
+
character outside ``iunreserved`` is percent-encoded, so a key holding ``/``,
|
|
26
|
+
a space, ``#``, ``?`` or a quote cannot be read as IRI structure and the IRI
|
|
27
|
+
parses back to the key it was built from. The characters are one list,
|
|
28
|
+
:data:`IRI_SAFE_ENCODING`, which every builder reads (this module, the Spark
|
|
29
|
+
column form, the SPARQL term expression), because they must agree string for
|
|
30
|
+
string. A template that is one placeholder and no literal text is
|
|
31
|
+
column-valued (R2RML's ``rr:column``): the column holds the whole IRI, used
|
|
32
|
+
as it is.
|
|
33
|
+
|
|
34
|
+
**Vocabulary IRIs**, which class or predicate a label, property or relationship
|
|
35
|
+
type is. Same rule in the same shape: a declaration wins, otherwise the
|
|
36
|
+
convention applies.
|
|
37
|
+
|
|
38
|
+
1. A ``NodeMapping.class_iri``, or a ``PredicateMapping`` naming the predicate,
|
|
39
|
+
is authoritative. That is how an externally-authored ontology binds to the
|
|
40
|
+
data, and the whole point of declaring one.
|
|
41
|
+
2. Otherwise ``{vocab_iri}{Label}`` for a class, ``{vocab_iri}{property}`` for a
|
|
42
|
+
datatype predicate, and ``{vocab_iri}{camelCasedRelType}`` for an object
|
|
43
|
+
predicate.
|
|
44
|
+
|
|
45
|
+
The other direction, which element a query's IRI names, is the same IRIs
|
|
46
|
+
read back (:func:`labels_of_class`): an IRI names an element only when it
|
|
47
|
+
is the very IRI above, never by its local name in another namespace.
|
|
48
|
+
|
|
49
|
+
Relationship types are UPPER_SNAKE_CASE in ProGraph and camelCase in ontologies
|
|
50
|
+
(``WORKS_AT`` ↔ ``worksAt``), so the convention converts between them rather
|
|
51
|
+
than emitting a spelling no ontology would use. :func:`predicate_local_name` is
|
|
52
|
+
the inverse of ``prograph.schema.naming.rel_type_from_local_name``.
|
|
53
|
+
"""
|
|
54
|
+
|
|
55
|
+
import re
|
|
56
|
+
from typing import Any, Callable, Dict, List, Optional, Sequence, Tuple
|
|
57
|
+
from prograph.schema.types import is_missing
|
|
58
|
+
from prograph.rules import home, module_home
|
|
59
|
+
|
|
60
|
+
module_home("node-iri-parsing", "Node and class IRIs",
|
|
61
|
+
terms=("IRI", "iri_template", "node IRI", "class IRI", "parse_node_iri", "template_values", "base IRI"))
|
|
62
|
+
|
|
63
|
+
# The default namespaces for synthesized IRIs.
|
|
64
|
+
DEFAULT_BASE_IRI = "http://example.org/data/"
|
|
65
|
+
DEFAULT_VOCAB_IRI = "http://example.org/ontology/"
|
|
66
|
+
|
|
67
|
+
_PLACEHOLDER = re.compile(r"\{([^{}]+)\}")
|
|
68
|
+
|
|
69
|
+
# R2RML 7.3, "IRI-safe": percent-encode every character that is not in
|
|
70
|
+
# iunreserved (ALPHA, DIGIT, "-", ".", "_", "~", and non-ASCII). Among
|
|
71
|
+
# printable ASCII that is the list below. '%' is first, so that a builder
|
|
72
|
+
# applying the pairs as replacements in order does not encode its own
|
|
73
|
+
# output. (character, its encoding), in the order to apply them.
|
|
74
|
+
IRI_SAFE_ENCODING: List[Tuple[str, str]] = [
|
|
75
|
+
(character, f"%{ord(character):02X}")
|
|
76
|
+
for character in "%" + " !\"#$&'()*+,/:;<=>?@[\\]^`{|}"
|
|
77
|
+
]
|
|
78
|
+
|
|
79
|
+
|
|
80
|
+
# What else R2RML 7.3 percent-encodes (RFC 3987: iunreserved holds only ucschar of the non-ASCII
|
|
81
|
+
# characters), as code-point ranges: the ASCII controls and DEL, the C1 controls, private use
|
|
82
|
+
# (iprivate is no ucschar) and the noncharacters (U+FDD0 to U+FDEF, the last two of every plane).
|
|
83
|
+
IRI_UNSAFE_RANGES: List[Tuple[int, int]] = (
|
|
84
|
+
[(0x00, 0x1F), (0x7F, 0x9F), (0xE000, 0xF8FF), (0xFDD0, 0xFDEF), (0xFFFE, 0xFFFF)]
|
|
85
|
+
+ [(p * 0x10000 + 0xFFFE, p * 0x10000 + 0xFFFF) for p in range(1, 15)]
|
|
86
|
+
+ [(0xF0000, 0x10FFFF)])
|
|
87
|
+
# The same as an XPath character class of the characters themselves (NUL left out: no SQL text
|
|
88
|
+
# holds one), for the SQL guard (`plan.ir.lower.iri_safe`).
|
|
89
|
+
IRI_UNSAFE_CLASS = "[" + "".join(f"{chr(max(lo, 1))}-{chr(hi)}" for lo, hi in IRI_UNSAFE_RANGES) + "]"
|
|
90
|
+
# The same class written with escapes, per regex engine (`plan.ir.lower.iri_safe`), so the printed SQL holds
|
|
91
|
+
# no control or private-use character: Java's (Spark, Databricks) and RE2's (DuckDB) `\x{h..h}`, PostgreSQL's
|
|
92
|
+
# `\Uhhhhhhhh`. The database's string literal escapes the backslash where it needs to (`Dialect.literal`).
|
|
93
|
+
IRI_UNSAFE_ESCAPED = {
|
|
94
|
+
"java": "[" + "".join(f"\\x{{{max(lo, 1):X}}}-\\x{{{hi:X}}}" for lo, hi in IRI_UNSAFE_RANGES) + "]",
|
|
95
|
+
"re2": "[" + "".join(f"\\x{{{max(lo, 1):X}}}-\\x{{{hi:X}}}" for lo, hi in IRI_UNSAFE_RANGES) + "]",
|
|
96
|
+
"pg": "[" + "".join(f"\\U{max(lo, 1):08X}-\\U{hi:08X}" for lo, hi in IRI_UNSAFE_RANGES) + "]",
|
|
97
|
+
}
|
|
98
|
+
_UNSAFE = re.compile("[" + "".join(f"\\U{lo:08x}-\\U{hi:08x}" for lo, hi in IRI_UNSAFE_RANGES) + "]")
|
|
99
|
+
|
|
100
|
+
|
|
101
|
+
# The characters a template's own text alone can write into an IRI: `iri_safe` encodes them in every
|
|
102
|
+
# value (an integer's text is digits and '-'), so they cut a template's terms into runs
|
|
103
|
+
# (`source_map.one_term_per_values`, `source_map._iri_runs`). '%' starts a value's escape.
|
|
104
|
+
IRI_TEMPLATE_CUT = frozenset(c for c, _ in IRI_SAFE_ENCODING) - {"%"}
|
|
105
|
+
|
|
106
|
+
|
|
107
|
+
@home("iri-safe", "A value made IRI-safe for a template (R2RML 7.3)",
|
|
108
|
+
terms=("IRI-safe", "percent-encode", "iunreserved", "RFC 3987", "ucschar", "control character",
|
|
109
|
+
"private use", "noncharacter"))
|
|
110
|
+
def iri_safe(value: Any) -> str:
|
|
111
|
+
"""`value` as text, IRI-safe (R2RML 7.3): fit to stand between two '/' of an IRI. Every
|
|
112
|
+
character outside RFC 3987's iunreserved is percent-encoded, its UTF-8 bytes as %XX: the
|
|
113
|
+
printable ASCII ones (`IRI_SAFE_ENCODING`), and the controls, private-use characters and
|
|
114
|
+
noncharacters (`IRI_UNSAFE_CLASS`), so an IRI template never errors (one-plan.md 8.2). The SQL form encodes the first and refuses the second (`plan.ir.lower.iri_safe`).
|
|
115
|
+
"""
|
|
116
|
+
text = str(value)
|
|
117
|
+
for character, encoded in IRI_SAFE_ENCODING:
|
|
118
|
+
text = text.replace(character, encoded)
|
|
119
|
+
return _UNSAFE.sub(lambda m: "".join(f"%{b:02X}" for b in m.group(0).encode("utf-8")), text)
|
|
120
|
+
|
|
121
|
+
|
|
122
|
+
def iri_value(text: str) -> str:
|
|
123
|
+
"""The value an IRI-safe piece of an IRI stands for: `iri_safe` undone."""
|
|
124
|
+
from urllib.parse import unquote
|
|
125
|
+
return unquote(text)
|
|
126
|
+
|
|
127
|
+
|
|
128
|
+
def template_values(parts: Sequence[Tuple[str, bool]], iri: str, *,
|
|
129
|
+
decode: Callable[[str], str] = iri_value, safe: bool = False,
|
|
130
|
+
every: bool = True) -> List[Tuple[str, ...]]:
|
|
131
|
+
"""Every way the template `parts` (`template_parts` form) makes `iri`:
|
|
132
|
+
for each, the text of each placeholder in order, `decode`d (IRI-safe
|
|
133
|
+
undone, `iri_value`), a placeholder never empty and one column the
|
|
134
|
+
template reads twice the same text at both. The one parse of an IRI
|
|
135
|
+
back to a template's values (`parse_node_iri` reads it).
|
|
136
|
+
|
|
137
|
+
Several where a separator is a character a value may hold too
|
|
138
|
+
(`{a}-{b}` and `q-r-s`), the shortest first piece first; `every`
|
|
139
|
+
False stops at the first. With `safe`, each piece must be the form
|
|
140
|
+
`iri_safe` writes of its value (R2RML 7.3), so only IRIs a row's
|
|
141
|
+
values render are parsed."""
|
|
142
|
+
found: List[Tuple[str, ...]] = []
|
|
143
|
+
names = [text for text, is_column in parts if is_column]
|
|
144
|
+
|
|
145
|
+
def ends(at: int, i: int):
|
|
146
|
+
following = parts[i + 1] if i + 1 < len(parts) else None
|
|
147
|
+
if following is None:
|
|
148
|
+
return [len(iri)] if len(iri) > at else []
|
|
149
|
+
if following[1]:
|
|
150
|
+
return range(at + 1, len(iri) + 1)
|
|
151
|
+
out, end = [], iri.find(following[0], at + 1)
|
|
152
|
+
while end != -1:
|
|
153
|
+
out.append(end)
|
|
154
|
+
end = iri.find(following[0], end + 1)
|
|
155
|
+
return out
|
|
156
|
+
|
|
157
|
+
def match(at: int, i: int, pieces: Tuple[str, ...]) -> None:
|
|
158
|
+
if found and not every:
|
|
159
|
+
return
|
|
160
|
+
if i == len(parts):
|
|
161
|
+
if at == len(iri):
|
|
162
|
+
found.append(pieces)
|
|
163
|
+
return
|
|
164
|
+
text, is_column = parts[i]
|
|
165
|
+
if not is_column:
|
|
166
|
+
if iri.startswith(text, at):
|
|
167
|
+
match(at + len(text), i + 1, pieces)
|
|
168
|
+
return
|
|
169
|
+
earlier = names.index(text)
|
|
170
|
+
for end in ends(at, i):
|
|
171
|
+
piece = iri[at:end]
|
|
172
|
+
if earlier < len(pieces) and pieces[earlier] != piece:
|
|
173
|
+
continue
|
|
174
|
+
if safe and iri_safe(decode(piece)) != piece:
|
|
175
|
+
continue
|
|
176
|
+
match(end, i + 1, pieces + (piece,))
|
|
177
|
+
|
|
178
|
+
match(0, 0, ())
|
|
179
|
+
return [tuple(decode(piece) for piece in pieces) for pieces in found]
|
|
180
|
+
|
|
181
|
+
|
|
182
|
+
# An IRI's scheme (RFC 3987): an IRI that starts with one is absolute.
|
|
183
|
+
IRI_SCHEME = re.compile(r"[A-Za-z][A-Za-z0-9+.-]*:")
|
|
184
|
+
|
|
185
|
+
|
|
186
|
+
def prepended_iri(text: str, base: Optional[str]) -> str:
|
|
187
|
+
"""An R2RML IRI term map's IRI from its text (R2RML 7.3): the text where
|
|
188
|
+
it is an absolute IRI, else the base IRI prepended; ValueError where
|
|
189
|
+
it is relative and there is no base. The plan's lowering writes the
|
|
190
|
+
same rule in SQL, per row (`plan.ir.lower.absolute`)."""
|
|
191
|
+
if IRI_SCHEME.match(text):
|
|
192
|
+
return text
|
|
193
|
+
if not base:
|
|
194
|
+
raise ValueError(f"the relative IRI {text!r} and no base IRI")
|
|
195
|
+
return base + text
|
|
196
|
+
|
|
197
|
+
|
|
198
|
+
def is_column_valued(template: str) -> bool:
|
|
199
|
+
"""Whether a template is one placeholder and nothing else, `{uri}`: the
|
|
200
|
+
column holds the whole IRI (R2RML's rr:column), so it is used as it is."""
|
|
201
|
+
parts = template_parts(template)
|
|
202
|
+
return len(parts) == 1 and parts[0][1]
|
|
203
|
+
|
|
204
|
+
|
|
205
|
+
def template_columns(template: str) -> List[str]:
|
|
206
|
+
"""Return the column names a template references, in order of appearance."""
|
|
207
|
+
return _PLACEHOLDER.findall(template)
|
|
208
|
+
|
|
209
|
+
|
|
210
|
+
def template_parts(template: str, escapes: bool = False) -> List[Tuple[str, bool]]:
|
|
211
|
+
"""Split a template into ``(text, is_column)`` pieces, in order.
|
|
212
|
+
|
|
213
|
+
``"http://x/{a}/{b}"`` → ``[("http://x/", False), ("a", True), ("/", False),
|
|
214
|
+
("b", True)]``. Empty literal runs are dropped.
|
|
215
|
+
|
|
216
|
+
Exists so that a renderer which cannot substitute values directly, the
|
|
217
|
+
Spark quad materializer builds a column *expression*, not a string, can
|
|
218
|
+
still be driven by this module's parse rather than its own.
|
|
219
|
+
|
|
220
|
+
With `escapes`, the template is an R2RML string template (R2RML 7.3):
|
|
221
|
+
a backslash escapes the character after it, so ``\\{``, ``\\}`` and
|
|
222
|
+
``\\\\`` are literal text, and a ``{`` not escaped opens a placeholder
|
|
223
|
+
that the next ``}`` not escaped closes; a template not so formed raises
|
|
224
|
+
:class:`TemplateSyntaxError`. A ProGraph template has no escapes (a
|
|
225
|
+
backslash is text), so the default reads it as it always has.
|
|
226
|
+
"""
|
|
227
|
+
if escapes:
|
|
228
|
+
return _escaped_template_parts(template)
|
|
229
|
+
parts: List[Tuple[str, bool]] = []
|
|
230
|
+
position = 0
|
|
231
|
+
for match in _PLACEHOLDER.finditer(template):
|
|
232
|
+
if match.start() > position:
|
|
233
|
+
parts.append((template[position:match.start()], False))
|
|
234
|
+
parts.append((match.group(1), True))
|
|
235
|
+
position = match.end()
|
|
236
|
+
if position < len(template):
|
|
237
|
+
parts.append((template[position:], False))
|
|
238
|
+
return parts
|
|
239
|
+
|
|
240
|
+
|
|
241
|
+
class TemplateSyntaxError(ValueError):
|
|
242
|
+
"""An R2RML string template that is not well formed (R2RML 7.3): an
|
|
243
|
+
unclosed or empty placeholder, a brace not escaped where it opens or
|
|
244
|
+
closes nothing, or a backslash at its end."""
|
|
245
|
+
|
|
246
|
+
|
|
247
|
+
def _escaped_template_parts(template: str) -> List[Tuple[str, bool]]:
|
|
248
|
+
"""`template_parts` of an R2RML string template (R2RML 7.3)."""
|
|
249
|
+
parts: List[Tuple[str, bool]] = []
|
|
250
|
+
text: List[str] = []
|
|
251
|
+
column: Optional[List[str]] = None
|
|
252
|
+
i, n = 0, len(template)
|
|
253
|
+
while i < n:
|
|
254
|
+
c = template[i]
|
|
255
|
+
if c == "\\":
|
|
256
|
+
if i + 1 >= n:
|
|
257
|
+
raise TemplateSyntaxError(f"template {template!r} ends in a backslash")
|
|
258
|
+
(column if column is not None else text).append(template[i + 1])
|
|
259
|
+
i += 2
|
|
260
|
+
continue
|
|
261
|
+
if c == "{":
|
|
262
|
+
if column is not None:
|
|
263
|
+
raise TemplateSyntaxError(f"template {template!r}: '{{' inside a placeholder")
|
|
264
|
+
if text:
|
|
265
|
+
parts.append(("".join(text), False))
|
|
266
|
+
text = []
|
|
267
|
+
column = []
|
|
268
|
+
elif c == "}":
|
|
269
|
+
if column is None:
|
|
270
|
+
raise TemplateSyntaxError(f"template {template!r}: '}}' that closes nothing")
|
|
271
|
+
if not column:
|
|
272
|
+
raise TemplateSyntaxError(f"template {template!r}: an empty placeholder")
|
|
273
|
+
parts.append(("".join(column), True))
|
|
274
|
+
column = None
|
|
275
|
+
else:
|
|
276
|
+
(column if column is not None else text).append(c)
|
|
277
|
+
i += 1
|
|
278
|
+
if column is not None:
|
|
279
|
+
raise TemplateSyntaxError(f"template {template!r}: a placeholder not closed")
|
|
280
|
+
if text:
|
|
281
|
+
parts.append(("".join(text), False))
|
|
282
|
+
return parts
|
|
283
|
+
|
|
284
|
+
|
|
285
|
+
def _is_missing(value: Any) -> bool:
|
|
286
|
+
"""True for values that cannot form part of an IRI.
|
|
287
|
+
|
|
288
|
+
Pandas turns ``None`` in a numeric column into ``NaN``; a NaN is a missing
|
|
289
|
+
value here, not the float it claims to be (pyshacl's Decimal comparator
|
|
290
|
+
raises on one).
|
|
291
|
+
"""
|
|
292
|
+
return is_missing(value)
|
|
293
|
+
|
|
294
|
+
|
|
295
|
+
def render_iri_template(template: str, values: Dict[str, Any]) -> Optional[str]:
|
|
296
|
+
"""Substitute ``{column}`` placeholders in a template from a row's values.
|
|
297
|
+
|
|
298
|
+
Returns None if any referenced column is absent or null, so callers never
|
|
299
|
+
produce an IRI with a hole in it. Values are made IRI-safe, except in a
|
|
300
|
+
column-valued template, whose one value is the IRI.
|
|
301
|
+
"""
|
|
302
|
+
missing = False
|
|
303
|
+
encode = (lambda value: str(value)) if is_column_valued(template) else iri_safe
|
|
304
|
+
|
|
305
|
+
def _substitute(match: "re.Match[str]") -> str:
|
|
306
|
+
nonlocal missing
|
|
307
|
+
column = match.group(1)
|
|
308
|
+
if column not in values or _is_missing(values[column]):
|
|
309
|
+
missing = True
|
|
310
|
+
return ""
|
|
311
|
+
return encode(values[column])
|
|
312
|
+
|
|
313
|
+
rendered = _PLACEHOLDER.sub(_substitute, template)
|
|
314
|
+
return None if missing else rendered
|
|
315
|
+
|
|
316
|
+
|
|
317
|
+
class IRITemplateError(ValueError):
|
|
318
|
+
"""An `iri_template` whose IRIs cannot be read back: two placeholders
|
|
319
|
+
with nothing between them."""
|
|
320
|
+
|
|
321
|
+
|
|
322
|
+
class IdentityConflictError(ValueError):
|
|
323
|
+
"""Two node mappings on one table whose keys differ, with nothing that
|
|
324
|
+
keeps their IRIs apart."""
|
|
325
|
+
|
|
326
|
+
|
|
327
|
+
from prograph.rules import home # noqa: E402
|
|
328
|
+
|
|
329
|
+
|
|
330
|
+
class UnstableIdentityError(ValueError):
|
|
331
|
+
"""A node mapping whose `iri_template` reads columns other than its
|
|
332
|
+
key, where a call needs the IRI a key stands for."""
|
|
333
|
+
|
|
334
|
+
|
|
335
|
+
def _literal_prefix(template: str) -> str:
|
|
336
|
+
"""A template's text before its first placeholder."""
|
|
337
|
+
parts = template_parts(template)
|
|
338
|
+
return parts[0][0] if parts and not parts[0][1] else ""
|
|
339
|
+
|
|
340
|
+
|
|
341
|
+
def _prefixes_overlap(first: str, second: str) -> bool:
|
|
342
|
+
return first.startswith(second) or second.startswith(first)
|
|
343
|
+
|
|
344
|
+
|
|
345
|
+
def check_identities(schema: Any) -> None:
|
|
346
|
+
"""Refuse a schema whose node IRIs cannot name one node each.
|
|
347
|
+
|
|
348
|
+
- `{a}{b}`: with nothing between two placeholders, a=1, b=23 and a=12,
|
|
349
|
+
b=3 are the same IRI, and it parses back as one of them.
|
|
350
|
+
- Two mappings on one table with different keys give one row two
|
|
351
|
+
identities under the synthesized form. It is allowed when both
|
|
352
|
+
declare an `iri_template` and neither template's leading text starts
|
|
353
|
+
the other's, so no IRI can be both; a wide table holding two kinds
|
|
354
|
+
of entity is mapped so. Two labels on one table with the same key
|
|
355
|
+
are one entity and are not this.
|
|
356
|
+
"""
|
|
357
|
+
mappings = list(getattr(schema, "node_mappings", []))
|
|
358
|
+
for mapping in mappings:
|
|
359
|
+
template = getattr(mapping, "iri_template", None)
|
|
360
|
+
if not template:
|
|
361
|
+
continue
|
|
362
|
+
parts = template_parts(template)
|
|
363
|
+
for (_, first), (_, second) in zip(parts, parts[1:]):
|
|
364
|
+
if first and second:
|
|
365
|
+
raise IRITemplateError(
|
|
366
|
+
f"iri_template {template!r} of {mapping.label} has two placeholders "
|
|
367
|
+
f"with nothing between them, so its IRIs cannot be read back; "
|
|
368
|
+
f"put a separator between them")
|
|
369
|
+
for index, mapping in enumerate(mappings):
|
|
370
|
+
for other in mappings[:index]:
|
|
371
|
+
if (other.qualified_source_table != mapping.qualified_source_table
|
|
372
|
+
or list(other.id_columns) == list(mapping.id_columns)):
|
|
373
|
+
continue
|
|
374
|
+
templates = [getattr(m, "iri_template", None) for m in (other, mapping)]
|
|
375
|
+
pair = (f"{other.label} (key {', '.join(other.id_columns)}) and "
|
|
376
|
+
f"{mapping.label} (key {', '.join(mapping.id_columns)}) "
|
|
377
|
+
f"on table {mapping.source_table}")
|
|
378
|
+
if not all(templates):
|
|
379
|
+
raise IdentityConflictError(
|
|
380
|
+
f"{pair} have different keys, so one row would have two node ids; "
|
|
381
|
+
f"give both an iri_template, or the same key")
|
|
382
|
+
if _prefixes_overlap(*(_literal_prefix(t) for t in templates)):
|
|
383
|
+
raise IdentityConflictError(
|
|
384
|
+
f"{pair} have different keys and iri_templates that can give "
|
|
385
|
+
f"the same node id ({templates[0]!r}, {templates[1]!r}); start them "
|
|
386
|
+
f"with different text")
|
|
387
|
+
|
|
388
|
+
|
|
389
|
+
def require_key_template(mapping: Any) -> None:
|
|
390
|
+
"""Refuse a mapping whose IRI cannot be computed from its key: its
|
|
391
|
+
template reads another column. A call that turns a key
|
|
392
|
+
into an IRI, or an IRI into the row to write, needs that."""
|
|
393
|
+
template = getattr(mapping, "iri_template", None)
|
|
394
|
+
if not template:
|
|
395
|
+
return
|
|
396
|
+
other = [c for c in template_columns(template) if c not in mapping.id_columns]
|
|
397
|
+
if other:
|
|
398
|
+
raise UnstableIdentityError(
|
|
399
|
+
f"the iri_template of {mapping.label} reads {', '.join(other)}, which "
|
|
400
|
+
f"is not its key ({', '.join(mapping.id_columns)}): its IRI cannot be "
|
|
401
|
+
f"computed from a key")
|
|
402
|
+
|
|
403
|
+
|
|
404
|
+
def base_iri_of(schema_or_mapping: Any) -> str:
|
|
405
|
+
"""The namespace synthesized instance IRIs start with: the schema's
|
|
406
|
+
`base_iri`, its one home. Given a mapping, its schema's; a mapping in
|
|
407
|
+
no schema has the default."""
|
|
408
|
+
schema = getattr(schema_or_mapping, "_schema", schema_or_mapping)
|
|
409
|
+
return getattr(schema, "base_iri", None) or DEFAULT_BASE_IRI
|
|
410
|
+
|
|
411
|
+
|
|
412
|
+
def default_node_iri(source_table: str, entity_id: Any, base_iri: str = DEFAULT_BASE_IRI) -> str:
|
|
413
|
+
"""The synthesized IRI for a node with no declared template.
|
|
414
|
+
|
|
415
|
+
``entity_id`` may be a tuple for a composite key, matching how composite node
|
|
416
|
+
ids are carried internally.
|
|
417
|
+
"""
|
|
418
|
+
parts = entity_id if isinstance(entity_id, tuple) else (entity_id,)
|
|
419
|
+
key = "/".join(iri_safe(part) for part in parts)
|
|
420
|
+
return f"{base_iri}{source_table}/{key}"
|
|
421
|
+
|
|
422
|
+
|
|
423
|
+
def iri_segment(mapping: Any) -> str:
|
|
424
|
+
"""The segment a mapping's synthesized IRIs carry after the base: its `iri_segment` where one is set
|
|
425
|
+
(a YAML source's name, kept whether `to_schema(by_table=True)` reads the source's qualified table or
|
|
426
|
+
not, so one source mints one IRI either way), else its `source_table`."""
|
|
427
|
+
return getattr(mapping, "iri_segment", None) or mapping.source_table
|
|
428
|
+
|
|
429
|
+
|
|
430
|
+
def node_iri_template(mapping: Any) -> str:
|
|
431
|
+
"""The template a node mapping's IRIs are written by, with `{column}`
|
|
432
|
+
placeholders: its declared ``iri_template``, else the synthesized form
|
|
433
|
+
(`default_node_iri`), ``{base_iri}{source_table}/{key}``. What an agent
|
|
434
|
+
writes an individual's IRI from."""
|
|
435
|
+
template = getattr(mapping, "iri_template", None)
|
|
436
|
+
if template:
|
|
437
|
+
return template
|
|
438
|
+
key = "/".join("{" + column + "}" for column in mapping.id_columns)
|
|
439
|
+
shared = getattr(mapping, "identity", None)
|
|
440
|
+
if shared and shared not in ("global", "distinct"): # keywords, not a shared name
|
|
441
|
+
# A shared identity: maps of one name, over any tables, give one subject per key.
|
|
442
|
+
return f"{base_iri_of(mapping)}{shared}/{key}"
|
|
443
|
+
return f"{base_iri_of(mapping)}{iri_segment(mapping)}/{key}"
|
|
444
|
+
|
|
445
|
+
|
|
446
|
+
def node_iri(
|
|
447
|
+
mapping: Any,
|
|
448
|
+
values: Dict[str, Any],
|
|
449
|
+
) -> Optional[str]:
|
|
450
|
+
"""Resolve a node's IRI from its mapping and a row's column values.
|
|
451
|
+
|
|
452
|
+
Args:
|
|
453
|
+
mapping: The ``NodeMapping`` the node came from.
|
|
454
|
+
values: Column name -> value for the row. Must cover the mapping's id
|
|
455
|
+
columns, and any column the ``iri_template`` references.
|
|
456
|
+
Returns:
|
|
457
|
+
The IRI, or None when a referenced column is missing or null.
|
|
458
|
+
"""
|
|
459
|
+
template = getattr(mapping, "iri_template", None)
|
|
460
|
+
if template:
|
|
461
|
+
return render_iri_template(template, values)
|
|
462
|
+
|
|
463
|
+
id_values = []
|
|
464
|
+
for column in mapping.id_columns:
|
|
465
|
+
value = values.get(column)
|
|
466
|
+
if _is_missing(value):
|
|
467
|
+
return None
|
|
468
|
+
id_values.append(value)
|
|
469
|
+
|
|
470
|
+
if not id_values:
|
|
471
|
+
return None
|
|
472
|
+
|
|
473
|
+
key = id_values[0] if len(id_values) == 1 else tuple(id_values)
|
|
474
|
+
return default_node_iri(iri_segment(mapping), key, base_iri_of(mapping))
|
|
475
|
+
|
|
476
|
+
|
|
477
|
+
def node_iri_from_id(
|
|
478
|
+
mapping: Any,
|
|
479
|
+
entity_id: Any,
|
|
480
|
+
) -> Optional[str]:
|
|
481
|
+
"""Resolve a node's IRI when only its id is in hand.
|
|
482
|
+
|
|
483
|
+
A declared ``iri_template`` that references non-id columns cannot be rendered
|
|
484
|
+
from an id alone; such a mapping returns None here and needs the row form
|
|
485
|
+
(:func:`node_iri`) instead.
|
|
486
|
+
"""
|
|
487
|
+
template = getattr(mapping, "iri_template", None)
|
|
488
|
+
if template:
|
|
489
|
+
id_columns = mapping.id_columns
|
|
490
|
+
ids = entity_id if isinstance(entity_id, tuple) else (entity_id,)
|
|
491
|
+
if len(ids) != len(id_columns):
|
|
492
|
+
return None
|
|
493
|
+
values = dict(zip(id_columns, ids))
|
|
494
|
+
if any(column not in values for column in template_columns(template)):
|
|
495
|
+
return None
|
|
496
|
+
return render_iri_template(template, values)
|
|
497
|
+
|
|
498
|
+
if _is_missing(entity_id):
|
|
499
|
+
return None
|
|
500
|
+
return default_node_iri(iri_segment(mapping), entity_id, base_iri_of(mapping))
|
|
501
|
+
|
|
502
|
+
|
|
503
|
+
# ── Vocabulary IRIs ──────────────────────────────────────────────────────
|
|
504
|
+
#
|
|
505
|
+
# Classes and predicates, as opposed to the entity IRIs above. Same rule: a
|
|
506
|
+
# declaration wins, the convention is the fallback.
|
|
507
|
+
|
|
508
|
+
|
|
509
|
+
def parse_node_iri(schema: Any, iri: str) -> List[Tuple[Any, Dict[str, str]]]:
|
|
510
|
+
"""The node mappings whose IRIs could be `iri`, each with the values (as
|
|
511
|
+
text) the IRI gives the columns that build it.
|
|
512
|
+
|
|
513
|
+
The inverse of :func:`node_iri`: a declared template matches with each
|
|
514
|
+
placeholder standing for text, and its columns are the template's,
|
|
515
|
+
which need not be the key (`{_uri}`); the synthesized form
|
|
516
|
+
matches ``{base_iri}{source_table}/{key}`` and gives the key columns.
|
|
517
|
+
Several mappings may match (labels on one table), and a match says only
|
|
518
|
+
what the IRI could name, not that the node exists;
|
|
519
|
+
:meth:`ProGraph.resolve_iri` checks that. A relationship's instance IRI
|
|
520
|
+
names no node: its segment after the table starts with ``@``.
|
|
521
|
+
"""
|
|
522
|
+
matches: List[Tuple[Any, Dict[str, str]]] = []
|
|
523
|
+
for mapping in getattr(schema, "node_mappings", []):
|
|
524
|
+
id_columns = list(mapping.id_columns)
|
|
525
|
+
template = getattr(mapping, "iri_template", None)
|
|
526
|
+
if template:
|
|
527
|
+
parts = template_parts(template)
|
|
528
|
+
columns = list(dict.fromkeys(text for text, is_column in parts if is_column))
|
|
529
|
+
if not columns:
|
|
530
|
+
continue
|
|
531
|
+
decode = (lambda text: text) if is_column_valued(template) else iri_value
|
|
532
|
+
found = template_values(parts, iri, decode=decode, every=False)
|
|
533
|
+
if found:
|
|
534
|
+
placeholders = [text for text, is_column in parts if is_column]
|
|
535
|
+
matches.append((mapping, dict(zip(placeholders, found[0]))))
|
|
536
|
+
continue
|
|
537
|
+
prefix = f"{base_iri_of(schema)}{iri_segment(mapping)}/"
|
|
538
|
+
if not iri.startswith(prefix):
|
|
539
|
+
continue
|
|
540
|
+
key = iri[len(prefix):].split("/")
|
|
541
|
+
if key[0].startswith(RELATIONSHIP_MARK):
|
|
542
|
+
continue # a relationship's IRI; parse_relationship_iri reads those
|
|
543
|
+
if len(key) == len(id_columns) and all(key):
|
|
544
|
+
matches.append((mapping, dict(zip(id_columns, map(iri_value, key)))))
|
|
545
|
+
return matches
|
|
546
|
+
|
|
547
|
+
|
|
548
|
+
def predicate_local_name(rel_type: str) -> str:
|
|
549
|
+
"""The predicate local name for a relationship type.
|
|
550
|
+
|
|
551
|
+
ProGraph stores relationship types UPPER_SNAKE_CASE (``IS_PART_OF``);
|
|
552
|
+
ontologies name the same predicate camelCase (``isPartOf``). The convention
|
|
553
|
+
converts, so a synthesized predicate looks like one an ontology would
|
|
554
|
+
declare. Inverse of ``prograph.schema.naming.rel_type_from_local_name``.
|
|
555
|
+
"""
|
|
556
|
+
if "_" not in rel_type:
|
|
557
|
+
return rel_type.lower()
|
|
558
|
+
parts = rel_type.split("_")
|
|
559
|
+
return parts[0].lower() + "".join(part.capitalize() for part in parts[1:])
|
|
560
|
+
|
|
561
|
+
|
|
562
|
+
def default_class_iri(label: str, vocab_iri: str = DEFAULT_VOCAB_IRI) -> str:
|
|
563
|
+
"""The synthesized class IRI for a label with no declared one."""
|
|
564
|
+
return f"{vocab_iri}{label}"
|
|
565
|
+
|
|
566
|
+
|
|
567
|
+
def default_property_iri(property_name: str, vocab_iri: str = DEFAULT_VOCAB_IRI) -> str:
|
|
568
|
+
"""The synthesized predicate IRI for a datatype property."""
|
|
569
|
+
return f"{vocab_iri}{property_name}"
|
|
570
|
+
|
|
571
|
+
|
|
572
|
+
def default_relationship_iri(rel_type: str, vocab_iri: str = DEFAULT_VOCAB_IRI) -> str:
|
|
573
|
+
"""The synthesized predicate IRI for a relationship type."""
|
|
574
|
+
return f"{vocab_iri}{predicate_local_name(rel_type)}"
|
|
575
|
+
|
|
576
|
+
|
|
577
|
+
def default_relation_class_iri(rel_type: str, vocab_iri: str = DEFAULT_VOCAB_IRI) -> str:
|
|
578
|
+
"""The synthesized class IRI for a reified relationship.
|
|
579
|
+
|
|
580
|
+
An edge with properties needs a node to hang them on, and that node needs a
|
|
581
|
+
class for a shape to target. ``WORKS_AT`` becomes ``WorksAt``, the class
|
|
582
|
+
spelling, beside ``worksAt`` the predicate spelling, which is how an
|
|
583
|
+
ontology names the relation and the property it reifies.
|
|
584
|
+
"""
|
|
585
|
+
return f"{vocab_iri}{''.join(part.capitalize() for part in rel_type.split('_'))}"
|
|
586
|
+
|
|
587
|
+
|
|
588
|
+
def relation_class_iri(mapping: Any, vocab_iri: str = DEFAULT_VOCAB_IRI) -> str:
|
|
589
|
+
"""The class a reified relationship's statement node is typed with."""
|
|
590
|
+
declared = getattr(mapping, "relation_class_iri", None)
|
|
591
|
+
if declared:
|
|
592
|
+
return declared
|
|
593
|
+
return default_relation_class_iri(mapping.rel_type, vocab_iri)
|
|
594
|
+
|
|
595
|
+
|
|
596
|
+
def relationship_instance_iri(
|
|
597
|
+
mapping: Any,
|
|
598
|
+
source_id: Any,
|
|
599
|
+
target_id: Any,
|
|
600
|
+
) -> Optional[str]:
|
|
601
|
+
"""The IRI naming one relationship row, so something can be said *about* it.
|
|
602
|
+
|
|
603
|
+
An edge is a triple, and a triple is not a resource, to attach properties
|
|
604
|
+
(reification) or lineage (PROV-O) you first have to name it. Both do, and
|
|
605
|
+
they must produce the same name or a shape's violation cannot be joined to
|
|
606
|
+
the provenance of the very edge it flagged.
|
|
607
|
+
|
|
608
|
+
The form is ``{base}{table}/@{REL_TYPE}/{start key}/{end key}``, every
|
|
609
|
+
part of a composite key its own segment. It is derived only from the
|
|
610
|
+
mapping and the two ids, with no declarable template: every caller must
|
|
611
|
+
be able to compute it, and the provenance path holds a bare pair of ids,
|
|
612
|
+
not a row.
|
|
613
|
+
|
|
614
|
+
The ``@`` segment keeps it apart from every node IRI. A key part is
|
|
615
|
+
IRI-safe, so it never holds a bare ``@``; without the segment, a node
|
|
616
|
+
keyed ``(order, line)`` and an edge ``order -> part`` on the same table
|
|
617
|
+
were both ``{base}lineitem/1/5``. The type in it keeps two relationship
|
|
618
|
+
types mapped on one table apart.
|
|
619
|
+
|
|
620
|
+
The cost is that **parallel edges collide**, two rows of one type joining
|
|
621
|
+
the same pair in the same table are one statement in RDF, and their
|
|
622
|
+
properties merge onto it. Model a multigraph edge as a node if that
|
|
623
|
+
matters.
|
|
624
|
+
"""
|
|
625
|
+
parts: List[Any] = []
|
|
626
|
+
for entity_id in (source_id, target_id):
|
|
627
|
+
# A composite key is a tuple; its parts join on '/', as a node's do.
|
|
628
|
+
for part in (entity_id if isinstance(entity_id, tuple) else (entity_id,)):
|
|
629
|
+
if _is_missing(part):
|
|
630
|
+
return None
|
|
631
|
+
parts.append(part)
|
|
632
|
+
return (relationship_iri_prefix(mapping)
|
|
633
|
+
+ "/".join(iri_safe(part) for part in parts))
|
|
634
|
+
|
|
635
|
+
|
|
636
|
+
RELATIONSHIP_MARK = "@"
|
|
637
|
+
|
|
638
|
+
|
|
639
|
+
def relationship_iri_prefix(mapping: Any) -> str:
|
|
640
|
+
"""What every instance IRI of a relationship mapping starts with, up to
|
|
641
|
+
and including the '/' before the start key."""
|
|
642
|
+
return (f"{base_iri_of(mapping)}{iri_segment(mapping)}/"
|
|
643
|
+
f"{RELATIONSHIP_MARK}{iri_safe(mapping.rel_type)}/")
|
|
644
|
+
|
|
645
|
+
|
|
646
|
+
def is_rdf_class(mapping: Any) -> bool:
|
|
647
|
+
"""Whether a node mapping's rows are typed with a class (`rdf_class`): a mapping with no label gives none
|
|
648
|
+
unless it declares a `class_iri` (an unlabelled node has no rdf:type of its own)."""
|
|
649
|
+
if getattr(mapping, "label", None) is None and not getattr(mapping, "class_iri", None):
|
|
650
|
+
return False
|
|
651
|
+
return getattr(mapping, "rdf_class", True)
|
|
652
|
+
|
|
653
|
+
|
|
654
|
+
# A label as a constraint inside a query, for a label that is no class:
|
|
655
|
+
# never a term of the data, so never a result.
|
|
656
|
+
LABEL_IRI_PREFIX = "urn:prograph:label:"
|
|
657
|
+
|
|
658
|
+
|
|
659
|
+
def class_iri(mapping: Any, vocab_iri: str = DEFAULT_VOCAB_IRI) -> str:
|
|
660
|
+
"""The class IRI a node mapping's rows are typed with.
|
|
661
|
+
|
|
662
|
+
A declared ``class_iri`` wins. That is how a mapping binds to an
|
|
663
|
+
externally-authored ontology's class rather than to an invented one.
|
|
664
|
+
"""
|
|
665
|
+
declared = getattr(mapping, "class_iri", None)
|
|
666
|
+
if declared:
|
|
667
|
+
return declared
|
|
668
|
+
return default_class_iri(mapping.label, vocab_iri)
|
|
669
|
+
|
|
670
|
+
|
|
671
|
+
def property_iri(
|
|
672
|
+
schema: Any,
|
|
673
|
+
label: Optional[str],
|
|
674
|
+
property_name: str,
|
|
675
|
+
vocab_iri: str = DEFAULT_VOCAB_IRI,
|
|
676
|
+
) -> str:
|
|
677
|
+
"""The predicate IRI for a datatype property on a label.
|
|
678
|
+
|
|
679
|
+
Prefers a ``PredicateMapping`` declared for this (label, property), the
|
|
680
|
+
user's own vocabulary, and otherwise synthesizes one. Without this the
|
|
681
|
+
bridge would emit an invented predicate for a property the user had already
|
|
682
|
+
bound to ``foaf:name``, and a shape or axiom written against ``foaf:name``
|
|
683
|
+
would silently match nothing.
|
|
684
|
+
"""
|
|
685
|
+
if schema is not None:
|
|
686
|
+
declared = schema.find_predicate_iri_for_property(label, property_name)
|
|
687
|
+
if declared:
|
|
688
|
+
return declared
|
|
689
|
+
return default_property_iri(property_name, vocab_iri)
|
|
690
|
+
|
|
691
|
+
|
|
692
|
+
def relationship_iri(
|
|
693
|
+
schema: Any,
|
|
694
|
+
rel_type: str,
|
|
695
|
+
vocab_iri: str = DEFAULT_VOCAB_IRI,
|
|
696
|
+
) -> str:
|
|
697
|
+
"""The predicate IRI for a relationship type, declaration first."""
|
|
698
|
+
if schema is not None:
|
|
699
|
+
declared = schema.find_predicate_iri_for_relationship(rel_type)
|
|
700
|
+
if declared:
|
|
701
|
+
return declared
|
|
702
|
+
return default_relationship_iri(rel_type, vocab_iri)
|
|
703
|
+
|
|
704
|
+
|
|
705
|
+
# The inverse direction: which class or predicate of the schema a query's IRI
|
|
706
|
+
# names. Two IRIs are equal only when they are the same string (RDF 1.1
|
|
707
|
+
# Concepts 3.2), and SPARQL matches a term by equality (SPARQL 1.1 18.3), so a
|
|
708
|
+
# query's IRI names a label, property or relationship type only when it is the
|
|
709
|
+
# IRI that element is published under: the declared one, else the default
|
|
710
|
+
# vocabulary's. A local name in another namespace names nothing.
|
|
711
|
+
|
|
712
|
+
def labels_of_class(schema: Any, iri: str) -> List[str]:
|
|
713
|
+
"""The labels whose rows are typed with class `iri` (``class_iri``), in
|
|
714
|
+
mapping order; a label that is no RDF class is none."""
|
|
715
|
+
if schema is None:
|
|
716
|
+
return []
|
|
717
|
+
return list(dict.fromkeys(m.label for m in schema.node_mappings
|
|
718
|
+
if is_rdf_class(m) and class_iri(m) == iri))
|
|
719
|
+
|
|
720
|
+
|
|
721
|
+
class IdentityMeetWarning(UserWarning):
|
|
722
|
+
"""Two YAML or Python maps over different rows whose authored IRI templates may give one IRI:
|
|
723
|
+
their subjects are one node where they meet (RDF: one IRI is one node), which a template copied
|
|
724
|
+
across tables does silently. One `identity:` on both says it is meant. Worded in mapping terms
|
|
725
|
+
(property-graph users need not know what an IRI is); the templates are in `detail`."""
|
|
726
|
+
|
|
727
|
+
def __init__(self, message: str, detail: str = ""):
|
|
728
|
+
super().__init__(message)
|
|
729
|
+
self.detail = detail
|
|
730
|
+
|
|
731
|
+
|
|
732
|
+
@home("identity-meetings", "Which maps' subjects may meet, and the refusal",
|
|
733
|
+
terms=("identity", "identity: global", "shared identity", "IdentityMeetWarning", "may meet",
|
|
734
|
+
"per-table IRI", "minted IRI"))
|
|
735
|
+
def check_meetings(schema: Any) -> None:
|
|
736
|
+
"""keys-and-identity.md 4, one-plan 2.3 for 1.0, over the schema's source maps (a YAML file's
|
|
737
|
+
included R2RML among them). For two node maps over different rows (not of one subject
|
|
738
|
+
identity) whose subject templates may give one IRI (`TermMap.may_equal`):
|
|
739
|
+
- one minted by ProGraph (no iri_template: `{base_iri}{table}/{key}`, or a shared identity's
|
|
740
|
+
`{base_iri}{name}/{key}`) and the other not of that same minted identity: refused
|
|
741
|
+
(`IdentityConflictError`, naming both), since it would merge another's rows into
|
|
742
|
+
ProGraph's subjects;
|
|
743
|
+
- both authored YAML or Python templates: a warning (`IdentityMeetWarning`), unless both
|
|
744
|
+
declare one `identity:` name, or both `identity: global`;
|
|
745
|
+
- an R2RML template: global (R2RML 6), no warning."""
|
|
746
|
+
try:
|
|
747
|
+
maps = schema.source_maps()
|
|
748
|
+
except Exception: # noqa: BLE001 - a schema the one plan does not read is checked elsewhere
|
|
749
|
+
return
|
|
750
|
+
from prograph.schema.source_map import IRI, LEXICAL_R2RML, kept_apart
|
|
751
|
+
def declared(m):
|
|
752
|
+
# The map's own declaration (`NodeMap.identity`): no authoring object is read.
|
|
753
|
+
return m.identity if m.subject.lexical != LEXICAL_R2RML else None
|
|
754
|
+
|
|
755
|
+
nodes = [m for m in maps.nodes if m.subject.term_type == IRI and m.subject.constant is None]
|
|
756
|
+
import warnings
|
|
757
|
+
warned: set = set()
|
|
758
|
+
for i, a in enumerate(nodes):
|
|
759
|
+
for b in nodes[:i]:
|
|
760
|
+
if maps.subject_identity(a) == maps.subject_identity(b) or not a.subject.may_equal(b.subject) \
|
|
761
|
+
or kept_apart(a, b):
|
|
762
|
+
continue
|
|
763
|
+
ia, ib = declared(a), declared(b)
|
|
764
|
+
pair = f"{b.label or b.id} ({b.source.table}) and {a.label or a.id} ({a.source.table})"
|
|
765
|
+
minted = [m for m in (a, b) if m.subject.synthesized]
|
|
766
|
+
if minted:
|
|
767
|
+
if ia is not None and ia == ib and ia != "global":
|
|
768
|
+
continue # one shared identity, minted alike
|
|
769
|
+
whole = [m for m in (a, b) if not m.subject.synthesized and m.subject.column is not None]
|
|
770
|
+
if whole:
|
|
771
|
+
# A column holding whole IRIs (`{uri}`) may hold any IRI, ProGraph's minted ones
|
|
772
|
+
# too; its rows meet a minted subject only where the column holds that very IRI,
|
|
773
|
+
# the mapping's own choice: a warning, once per mapping (decided 2026-11-10).
|
|
774
|
+
w = whole[0]
|
|
775
|
+
if w.id not in warned:
|
|
776
|
+
warned.add(w.id)
|
|
777
|
+
other = a if w is b else b
|
|
778
|
+
warnings.warn(IdentityMeetWarning(
|
|
779
|
+
f"{pair} may describe the same nodes: a {w.source.table} row whose "
|
|
780
|
+
f"{w.subject.column} column holds one of {other.label or other.id}'s node ids is "
|
|
781
|
+
f"that node. If {w.label or w.id}'s nodes are never another mapping's, add "
|
|
782
|
+
f"identity: distinct to it",
|
|
783
|
+
detail=f"{w.subject.column} holds whole IRIs; {other.label or other.id}'s are "
|
|
784
|
+
f"{other.subject.text()}"), stacklevel=3)
|
|
785
|
+
continue
|
|
786
|
+
raise IdentityConflictError(
|
|
787
|
+
f"{pair} could give their rows the same node ids ({a.subject.text()} and "
|
|
788
|
+
f"{b.subject.text()}), which would merge their rows into one node. Give them one "
|
|
789
|
+
f"identity: <name> to make them one, or an iri_template that keeps them apart")
|
|
790
|
+
if LEXICAL_R2RML in (a.subject.lexical, b.subject.lexical):
|
|
791
|
+
continue # an R2RML template is global (R2RML 6)
|
|
792
|
+
if ia is not None and ia == ib:
|
|
793
|
+
continue # one identity declared: meant
|
|
794
|
+
warnings.warn(IdentityMeetWarning(
|
|
795
|
+
f"{pair} may describe the same nodes: where their iri_templates give one node id, their rows "
|
|
796
|
+
f"are one node. If that is meant, give both the same identity: <name> (or identity: global); "
|
|
797
|
+
f"if not, add identity: distinct to one, or keep the templates apart",
|
|
798
|
+
detail=f"{b.subject.text()} and {a.subject.text()}"), stacklevel=3)
|
|
799
|
+
# A relationship end whose label has node maps of different subjects ends at the node of its key in each
|
|
800
|
+
# (compile_schema: one edge map per pair of ends); a key two of them hold is two nodes, both its ends.
|
|
801
|
+
seen = set()
|
|
802
|
+
by_id = {n.id: n for n in maps.nodes}
|
|
803
|
+
for e in maps.edges:
|
|
804
|
+
if e.rel_type is None:
|
|
805
|
+
continue
|
|
806
|
+
for side, ref in (("start", e.start), ("end", e.end)):
|
|
807
|
+
branches = [x for x in maps.edges if (x.id == e.id or x.branch_of == e.id)]
|
|
808
|
+
refs = {getattr(x, side).map_id for x in branches}
|
|
809
|
+
if e.branch_of is not None or len(refs) < 2 or (e.rel_type, side) in seen:
|
|
810
|
+
continue
|
|
811
|
+
seen.add((e.rel_type, side))
|
|
812
|
+
tables = ", ".join(dict.fromkeys(by_id[r].source.table for r in refs if r in by_id))
|
|
813
|
+
warnings.warn(IdentityMeetWarning(
|
|
814
|
+
f"{e.rel_type}'s {side} label {ref.label} is given by node mappings over {tables} that are not "
|
|
815
|
+
f"one identity: a {side} key one of them holds is that node, and a key two of them hold may be "
|
|
816
|
+
f"two {ref.label} nodes, each an {side} of the relationship. If they describe the same entities, "
|
|
817
|
+
f"give them one identity: <name>"), stacklevel=3)
|