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.
Files changed (237) hide show
  1. prograph/__init__.py +36 -0
  2. prograph/__main__.py +5 -0
  3. prograph/_version.py +375 -0
  4. prograph/cli/__init__.py +1 -0
  5. prograph/cli/_iri_utils.py +124 -0
  6. prograph/cli/emit_genie_space.py +107 -0
  7. prograph/cli/generate_views.py +140 -0
  8. prograph/cli/main.py +420 -0
  9. prograph/cli/schema_inferrer.py +746 -0
  10. prograph/cli/ttl_loader.py +289 -0
  11. prograph/cli/upload_genie_space.py +84 -0
  12. prograph/config/__init__.py +27 -0
  13. prograph/config/yaml_config.py +848 -0
  14. prograph/demos/__init__.py +14 -0
  15. prograph/demos/turbofan/README.md +74 -0
  16. prograph/demos/turbofan/SCENARIO.md +209 -0
  17. prograph/demos/turbofan/__init__.py +75 -0
  18. prograph/demos/turbofan/create_tables.sql +206 -0
  19. prograph/demos/turbofan/data/engine-instances.ttl +1123 -0
  20. prograph/demos/turbofan/data/sensor-timeseries.csv +90 -0
  21. prograph/demos/turbofan/demo.py +162 -0
  22. prograph/demos/turbofan/genie_qa_notebook.py +434 -0
  23. prograph/demos/turbofan/graph.yaml +1098 -0
  24. prograph/demos/turbofan/instance_graph_demo.py +32 -0
  25. prograph/demos/turbofan/load.py +223 -0
  26. prograph/demos/turbofan/mapping.r2rml.ttl +991 -0
  27. prograph/demos/turbofan/ontology/engine-maintenance.ttl +606 -0
  28. prograph/demos/turbofan/payload-shapes.ttl +33 -0
  29. prograph/demos/turbofan/queries/example-queries.sparql +215 -0
  30. prograph/demos/turbofan/shapes.ttl +75 -0
  31. prograph/demos/turbofan/tables.py +106 -0
  32. prograph/demos/turbofan/turbofan_schema.py +393 -0
  33. prograph/demos/turbofan/validation_demo.py +153 -0
  34. prograph/describe.py +231 -0
  35. prograph/endpoint/__init__.py +12 -0
  36. prograph/endpoint/app.py +722 -0
  37. prograph/endpoint/cli.py +280 -0
  38. prograph/endpoint/credentials.py +240 -0
  39. prograph/endpoint/engines.py +418 -0
  40. prograph/endpoint/negotiate.py +101 -0
  41. prograph/endpoint/results.py +181 -0
  42. prograph/endpoint/service.py +31 -0
  43. prograph/engine.py +2718 -0
  44. prograph/execution.py +455 -0
  45. prograph/executors/__init__.py +6 -0
  46. prograph/executors/base.py +11 -0
  47. prograph/executors/databricks_sql_executor.py +51 -0
  48. prograph/executors/duckdb_executor.py +24 -0
  49. prograph/executors/mysql_executor.py +20 -0
  50. prograph/executors/oracle_executor.py +24 -0
  51. prograph/executors/pandas_executor.py +72 -0
  52. prograph/executors/postgresql_executor.py +35 -0
  53. prograph/executors/spark_executor.py +88 -0
  54. prograph/executors/sqlserver_executor.py +35 -0
  55. prograph/extras/__init__.py +1 -0
  56. prograph/extras/graphql/__init__.py +33 -0
  57. prograph/extras/graphql/execute.py +25 -0
  58. prograph/extras/graphql/schema.py +314 -0
  59. prograph/extras/instance_graph.py +559 -0
  60. prograph/genie/__init__.py +83 -0
  61. prograph/genie/databricks_uploader.py +306 -0
  62. prograph/genie/deploy.py +393 -0
  63. prograph/genie/formats.py +414 -0
  64. prograph/genie/instruction_generator.py +375 -0
  65. prograph/genie/sample_query_generator.py +256 -0
  66. prograph/genie/shacl_views.py +318 -0
  67. prograph/genie/space_emitter.py +329 -0
  68. prograph/genie/view_generator.py +628 -0
  69. prograph/genie/view_writer.py +172 -0
  70. prograph/graph/__init__.py +1 -0
  71. prograph/graph/ansi_session.py +348 -0
  72. prograph/graph/databricks_sql_graph.py +300 -0
  73. prograph/graph/drivers.py +143 -0
  74. prograph/graph/duckdb_graph.py +68 -0
  75. prograph/graph/mysql_graph.py +38 -0
  76. prograph/graph/oracle_graph.py +285 -0
  77. prograph/graph/pandas_graph.py +343 -0
  78. prograph/graph/postgresql_graph.py +644 -0
  79. prograph/graph/spark_graph.py +556 -0
  80. prograph/graph/sql_graph.py +83 -0
  81. prograph/graph/sqlserver_graph.py +72 -0
  82. prograph/hints.py +95 -0
  83. prograph/logging.py +550 -0
  84. prograph/mcp/__init__.py +29 -0
  85. prograph/mcp/__main__.py +180 -0
  86. prograph/mcp/bootstrap.py +98 -0
  87. prograph/mcp/server.py +601 -0
  88. prograph/mcp/sparql.py +397 -0
  89. prograph/mcp/tools.py +504 -0
  90. prograph/nlp/__init__.py +79 -0
  91. prograph/nlp/client.py +305 -0
  92. prograph/nlp/databricks_tools.py +369 -0
  93. prograph/nlp/graph_context.py +313 -0
  94. prograph/nlp/interface.py +652 -0
  95. prograph/nlp/prompts/__init__.py +19 -0
  96. prograph/nlp/prompts/examples.py +258 -0
  97. prograph/nlp/prompts/system.py +239 -0
  98. prograph/nlp/providers/__init__.py +14 -0
  99. prograph/nlp/providers/anthropic.py +274 -0
  100. prograph/nlp/providers/databricks.py +312 -0
  101. prograph/nlp/providers/openai.py +203 -0
  102. prograph/nlp/schema_context.py +78 -0
  103. prograph/ontology/__init__.py +53 -0
  104. prograph/ontology/alignment.py +542 -0
  105. prograph/ontology/hierarchy.py +310 -0
  106. prograph/ontology/imports.py +587 -0
  107. prograph/ontology/layer.py +991 -0
  108. prograph/ontology/skos.py +61 -0
  109. prograph/owl/__init__.py +27 -0
  110. prograph/owl/defined_classes.py +323 -0
  111. prograph/parameters.py +242 -0
  112. prograph/parser/__init__.py +1 -0
  113. prograph/parser/cypher/CypherLexer.py +836 -0
  114. prograph/parser/cypher/CypherListener.py +966 -0
  115. prograph/parser/cypher/CypherParser.py +10854 -0
  116. prograph/parser/cypher/CypherVisitor.py +543 -0
  117. prograph/parser/cypher/__init__.py +1 -0
  118. prograph/parser/sparql/SparqlLexer.py +801 -0
  119. prograph/parser/sparql/SparqlParser.py +10146 -0
  120. prograph/parser/sparql/SparqlParserListener.py +1056 -0
  121. prograph/parser/sparql/SparqlParserVisitor.py +593 -0
  122. prograph/parser/sparql/__init__.py +8 -0
  123. prograph/plan/__init__.py +3 -0
  124. prograph/plan/ir/__init__.py +1 -0
  125. prograph/plan/ir/casts.py +338 -0
  126. prograph/plan/ir/consistency.py +397 -0
  127. prograph/plan/ir/construct.py +90 -0
  128. prograph/plan/ir/cost.py +234 -0
  129. prograph/plan/ir/cypher_answer.py +1081 -0
  130. prograph/plan/ir/cypher_apoc.py +717 -0
  131. prograph/plan/ir/cypher_apoc_convert.py +505 -0
  132. prograph/plan/ir/cypher_apoc_date.py +845 -0
  133. prograph/plan/ir/cypher_apoc_map.py +496 -0
  134. prograph/plan/ir/cypher_apoc_meta.py +384 -0
  135. prograph/plan/ir/cypher_apoc_path.py +597 -0
  136. prograph/plan/ir/cypher_apoc_procedures.py +163 -0
  137. prograph/plan/ir/cypher_apoc_text.py +785 -0
  138. prograph/plan/ir/cypher_front.py +5474 -0
  139. prograph/plan/ir/cypher_functions.py +565 -0
  140. prograph/plan/ir/cypher_lists.py +935 -0
  141. prograph/plan/ir/cypher_maps.py +370 -0
  142. prograph/plan/ir/cypher_mixed.py +604 -0
  143. prograph/plan/ir/cypher_ontology.py +226 -0
  144. prograph/plan/ir/cypher_procedures.py +191 -0
  145. prograph/plan/ir/cypher_runtime_errors.py +107 -0
  146. prograph/plan/ir/cypher_temporal.py +1357 -0
  147. prograph/plan/ir/cypher_temporal_arith.py +339 -0
  148. prograph/plan/ir/cypher_values.py +546 -0
  149. prograph/plan/ir/cypher_write.py +612 -0
  150. prograph/plan/ir/dataset.py +643 -0
  151. prograph/plan/ir/dates.py +102 -0
  152. prograph/plan/ir/entry.py +992 -0
  153. prograph/plan/ir/expr.py +260 -0
  154. prograph/plan/ir/facts.py +1171 -0
  155. prograph/plan/ir/fresh.py +291 -0
  156. prograph/plan/ir/freshness.py +625 -0
  157. prograph/plan/ir/identity.py +797 -0
  158. prograph/plan/ir/java_datetime.py +265 -0
  159. prograph/plan/ir/java_regex.py +391 -0
  160. prograph/plan/ir/join_order.py +39 -0
  161. prograph/plan/ir/key_checks.py +433 -0
  162. prograph/plan/ir/keys.py +454 -0
  163. prograph/plan/ir/lower.py +5323 -0
  164. prograph/plan/ir/ops.py +619 -0
  165. prograph/plan/ir/owl_rl.py +1119 -0
  166. prograph/plan/ir/owl_rl_rules.py +725 -0
  167. prograph/plan/ir/profiles.py +694 -0
  168. prograph/plan/ir/ql.py +987 -0
  169. prograph/plan/ir/rdfs.py +342 -0
  170. prograph/plan/ir/rewrite.py +1782 -0
  171. prograph/plan/ir/saturate.py +339 -0
  172. prograph/plan/ir/semantics.py +103 -0
  173. prograph/plan/ir/slot.py +509 -0
  174. prograph/plan/ir/sparql_front.py +3418 -0
  175. prograph/plan/ir/strings.py +534 -0
  176. prograph/plan/ir/term_functions.py +274 -0
  177. prograph/plan/ir/terms.py +84 -0
  178. prograph/plan/ir/xpath_regex.py +264 -0
  179. prograph/plan/run_record.py +65 -0
  180. prograph/plan/sql/__init__.py +21 -0
  181. prograph/plan/sql/dialect.py +3726 -0
  182. prograph/plan/sql/mysql_serializer.py +103 -0
  183. prograph/plan/sql/names.py +65 -0
  184. prograph/plan/sql/oracle_serializer.py +306 -0
  185. prograph/plan/sql/pg_serializer.py +501 -0
  186. prograph/plan/sql/rel_algebra.py +781 -0
  187. prograph/plan/sql/sql_serializer.py +1419 -0
  188. prograph/plan/sql/sqlserver_serializer.py +603 -0
  189. prograph/provenance.py +222 -0
  190. prograph/r2rml/__init__.py +48 -0
  191. prograph/r2rml/catalog.py +259 -0
  192. prograph/r2rml/compile.py +372 -0
  193. prograph/r2rml/direct.py +140 -0
  194. prograph/r2rml/export.py +495 -0
  195. prograph/r2rml/model.py +180 -0
  196. prograph/r2rml/parser.py +546 -0
  197. prograph/r2rml/schema.py +120 -0
  198. prograph/read_only.py +122 -0
  199. prograph/results.py +157 -0
  200. prograph/rules/__init__.py +168 -0
  201. prograph/rules/__main__.py +32 -0
  202. prograph/schema/__init__.py +60 -0
  203. prograph/schema/change_set.py +50 -0
  204. prograph/schema/collations.py +198 -0
  205. prograph/schema/compile_schema.py +388 -0
  206. prograph/schema/context.py +845 -0
  207. prograph/schema/examples.py +234 -0
  208. prograph/schema/iri.py +817 -0
  209. prograph/schema/literals.py +94 -0
  210. prograph/schema/lpg_view.py +617 -0
  211. prograph/schema/mapping.py +1803 -0
  212. prograph/schema/maps_schema.py +40 -0
  213. prograph/schema/naming.py +77 -0
  214. prograph/schema/query_sources.py +59 -0
  215. prograph/schema/rows.py +215 -0
  216. prograph/schema/source_map.py +1103 -0
  217. prograph/schema/store_view.py +459 -0
  218. prograph/schema/types.py +569 -0
  219. prograph/schema/xsd.py +569 -0
  220. prograph/shacl/__init__.py +30 -0
  221. prograph/shacl/dqv.py +58 -0
  222. prograph/shacl/generate.py +255 -0
  223. prograph/shacl/report.py +138 -0
  224. prograph/shacl/validator.py +164 -0
  225. prograph/store.py +1737 -0
  226. prograph/utils/__init__.py +6 -0
  227. prograph/utils/exceptions.py +308 -0
  228. prograph/utils/helpers.py +126 -0
  229. prograph/warnings.py +46 -0
  230. prograph/writes.py +369 -0
  231. prograph-1.3.3.dist-info/METADATA +281 -0
  232. prograph-1.3.3.dist-info/RECORD +237 -0
  233. prograph-1.3.3.dist-info/WHEEL +5 -0
  234. prograph-1.3.3.dist-info/entry_points.txt +3 -0
  235. prograph-1.3.3.dist-info/licenses/LICENSE +201 -0
  236. prograph-1.3.3.dist-info/licenses/NOTICE +10 -0
  237. prograph-1.3.3.dist-info/top_level.txt +1 -0
@@ -0,0 +1,587 @@
1
+ """Ontology import resolution: an owl:imports is read from a local file, never fetched from the network.
2
+
3
+ An import resolves, in this order, from: the caller's `imports={iri: path}`; a `catalog-v001.xml` beside the
4
+ importing ontology (the OASIS XML Catalog Protege writes: `<uri name=IRI uri=path/>` entries, also inside `<group>`,
5
+ and `<rewriteURI>`, paths relative to the catalog file or its `xml:base`; the root ontology's catalog applies to every
6
+ import, and a catalog beside an imported file adds its entries after); an `owl:Ontology` of that IRI already in the
7
+ graph; a `file:` IRI of an existing file; a file named as the IRI's last path segment beside the importing file, then
8
+ beside the root ontology; or the cache directory (a file the user put there). An explicit mapping (`imports=`, a
9
+ catalog) is used even where the graph holds an `owl:Ontology` header of that IRI: a header alone is not the
10
+ ontology's document. Anything else is unresolved: `OntologyLayer` raises `ImportResolutionError` for it unless
11
+ `on_unsupported="ignore"`. A catalog or `imports=` entry whose file is missing or does not parse is an error naming
12
+ the entry, whatever `on_unsupported` says. A file read as JSON-LD with a remote `@context` is refused
13
+ (`ImportResolutionError`): reading it would fetch the context.
14
+
15
+ The registry of well-known ontologies only names where each is published (`get_well_known_ontology_info`); nothing
16
+ is downloaded from it."""
17
+
18
+ import hashlib
19
+ import json
20
+ import logging
21
+ from pathlib import Path
22
+ from typing import Dict, List, Optional, Set, Tuple
23
+ from urllib.parse import unquote, urljoin, urlparse
24
+
25
+ try:
26
+ import rdflib
27
+ from rdflib import OWL, URIRef
28
+ RDFLIB_AVAILABLE = True
29
+ except ImportError:
30
+ RDFLIB_AVAILABLE = False
31
+ rdflib = None
32
+
33
+ logger = logging.getLogger(__name__)
34
+
35
+
36
+ # Well-known ontology registry
37
+ # Maps ontology URIs to where each is published (information only: nothing is fetched) and its cache format
38
+ WELL_KNOWN_ONTOLOGIES: Dict[str, Dict[str, str]] = {
39
+ # GIST Core Ontology
40
+ 'https://w3id.org/semanticarts/ontology/gistCore': {
41
+ 'remote_url': 'https://raw.githubusercontent.com/semanticarts/gist/master/gistCore.ttl',
42
+ 'format': 'turtle',
43
+ 'description': 'GIST Core - Minimalist upper ontology for the enterprise'
44
+ },
45
+ # Alternative GIST URIs (versioned)
46
+ 'https://w3id.org/semanticarts/ns/ontology/gist/': {
47
+ 'remote_url': 'https://raw.githubusercontent.com/semanticarts/gist/master/gistCore.ttl',
48
+ 'format': 'turtle',
49
+ 'description': 'GIST Core (versioned namespace)'
50
+ },
51
+ # gistCyber - Cybersecurity extension
52
+ 'https://w3id.org/semanticarts/ontology/gistCyber': {
53
+ 'remote_url': 'https://raw.githubusercontent.com/semanticarts/gistCyber/main/gistCyber.ttl',
54
+ 'format': 'turtle',
55
+ 'description': 'gistCyber - Cybersecurity concepts aligned with STIX'
56
+ },
57
+ # FIBO - Financial Industry Business Ontology (foundation)
58
+ 'https://spec.edmcouncil.org/fibo/ontology/FND/': {
59
+ 'remote_url': 'https://spec.edmcouncil.org/fibo/ontology/master/latest/FND/MetadataFND/FNDDomain.rdf',
60
+ 'format': 'xml',
61
+ 'description': 'FIBO Foundation - Core financial concepts'
62
+ },
63
+ # Dublin Core Terms
64
+ 'http://purl.org/dc/terms/': {
65
+ 'remote_url': 'https://www.dublincore.org/specifications/dublin-core/dcmi-terms/dublin_core_terms.ttl',
66
+ 'format': 'turtle',
67
+ 'description': 'Dublin Core Metadata Terms'
68
+ },
69
+ # SKOS - Simple Knowledge Organization System
70
+ 'http://www.w3.org/2004/02/skos/core': {
71
+ 'remote_url': 'https://www.w3.org/2009/08/skos-reference/skos.rdf',
72
+ 'format': 'xml',
73
+ 'description': 'SKOS Core Vocabulary'
74
+ },
75
+ }
76
+
77
+
78
+ class ImportResolutionError(Exception):
79
+ """An owl:imports could not be resolved from a local file (`imports`: the IRIs, `OntologyLayer`'s
80
+ ``on_unsupported="error"``, the default). The message names each IRI and what to do: pass the imported
81
+ ontology's file, or load with ``on_unsupported="ignore"``. An import is never fetched from the network."""
82
+
83
+ def __init__(self, message: str, imports: Tuple[str, ...] = ()):
84
+ self.imports = tuple(imports)
85
+ super().__init__(message)
86
+
87
+
88
+ CATALOG_NAME = 'catalog-v001.xml'
89
+ _CATALOG_NS = 'urn:oasis:names:tc:entity:xmlns:xml:catalog'
90
+ _NETWORK = ('http://', 'https://', 'ftp://')
91
+
92
+
93
+ def _format_of(path: Path) -> Optional[str]:
94
+ return {'.owl': 'xml', '.rdf': 'xml', '.xml': 'xml', '.ttl': 'turtle', '.n3': 'n3', '.nt': 'nt',
95
+ '.jsonld': 'json-ld'}.get(path.suffix.lower())
96
+
97
+
98
+ def _remote_context(node, found: List[str]) -> None:
99
+ """Every string `@context` or `@import` value of a JSON-LD document that is a network address."""
100
+ if isinstance(node, dict):
101
+ for key, value in node.items():
102
+ if key in ('@context', '@import'):
103
+ for item in (value if isinstance(value, list) else [value]):
104
+ if isinstance(item, str) and item.lower().startswith(_NETWORK):
105
+ found.append(item)
106
+ _remote_context(value, found)
107
+ elif isinstance(node, list):
108
+ for item in node:
109
+ _remote_context(item, found)
110
+
111
+
112
+ def parse_file(graph: 'rdflib.Graph', path: Path) -> 'rdflib.Graph':
113
+ """Parse the ontology file `path` into `graph`, never touching the network: a file rdflib reads as JSON-LD
114
+ (by extension: .jsonld, .json) whose `@context` (or `@import`) is a network address raises
115
+ `ImportResolutionError` (rdflib would fetch it)."""
116
+ path = Path(path)
117
+ fmt = _format_of(path)
118
+ if fmt is None:
119
+ from rdflib.util import guess_format
120
+ fmt = guess_format(str(path))
121
+ if fmt == 'json-ld':
122
+ found: List[str] = []
123
+ _remote_context(json.loads(path.read_text(encoding='utf-8')), found)
124
+ if found:
125
+ raise ImportResolutionError(
126
+ f"{path}: the JSON-LD @context {found[0]} is a network address, and nothing is fetched from the "
127
+ "network. Save the context as a local file and refer to it by a relative path, or write the "
128
+ "ontology in Turtle or RDF/XML.", imports=())
129
+ graph.parse(str(path), format=fmt) if fmt else graph.parse(str(path))
130
+ return graph
131
+
132
+
133
+ def _load_mapped(path: Path, iri: str, where: str) -> 'rdflib.Graph':
134
+ """The file a mapping (`imports=` or a catalog entry) names for `iri`: a file that does not parse is an
135
+ error naming the file, the IRI and the parser's message (never "not resolved")."""
136
+ try:
137
+ return parse_file(rdflib.Graph(), path)
138
+ except ImportResolutionError:
139
+ raise
140
+ except Exception as e:
141
+ raise ImportResolutionError(
142
+ f"{where}: the file {path}, mapped for the import {iri}, could not be read as RDF: {e}. Fix the file "
143
+ "or the mapping.", imports=(iri,)) from e
144
+
145
+
146
+ def _doctype_ok(raw: bytes) -> bool:
147
+ """False for an ENTITY declaration or a DOCTYPE with an internal subset (`[`); an external DOCTYPE
148
+ (`<!DOCTYPE catalog PUBLIC "..." "...dtd">`) is fine: the parser never fetches it."""
149
+ low = raw.lower()
150
+ if b'<!entity' in low:
151
+ return False
152
+ i = low.find(b'<!doctype')
153
+ if i < 0:
154
+ return True
155
+ quote = None
156
+ for byte in raw[i + 9:]:
157
+ ch = chr(byte)
158
+ if quote:
159
+ quote = None if ch == quote else quote
160
+ elif ch in '"\'':
161
+ quote = ch
162
+ elif ch == '[':
163
+ return False
164
+ elif ch == '>':
165
+ return True
166
+ return False
167
+
168
+
169
+ _XML_BASE = '{http://www.w3.org/XML/1998/namespace}base'
170
+
171
+
172
+ class Catalog:
173
+ """An OASIS XML Catalog (`catalog-v001.xml`): IRI -> file mappings, resolved relative to the catalog file
174
+ (and to `xml:base` on the `<catalog>` or a `<group>`).
175
+
176
+ An owl:imports is a URI reference, so a URI is resolved as OASIS XML Catalogs 1.1 section 7.2.2 resolves one:
177
+ a `<uri name= uri=/>` entry of exactly that URI; else the `<rewriteURI uriStartString= rewritePrefix=/>` of the
178
+ longest matching prefix; else the `<uriSuffix uriSuffix= uri=/>` of the longest matching suffix; else, where
179
+ `<delegateURI uriStartString= catalog=/>` entries match, only their catalogs (longest prefix first) and
180
+ nothing after them; else each `<nextCatalog catalog=/>` in document order. Entries may sit in `<group>`. A
181
+ catalog a `delegateURI` or `nextCatalog` names is a local file like the rest (a network address or a missing
182
+ file is an error naming the entry); a catalog met twice is read once. The system-identifier entries
183
+ (`system`, `rewriteSystem`, `systemSuffix`, `delegateSystem`) resolve DTDs and entities, not URIs, and are not
184
+ read. An external DOCTYPE (the standard `PUBLIC "-//OASIS//DTD XML Catalogs V1.1//EN" "...dtd"`) is accepted
185
+ and never fetched; an ENTITY or a DOCTYPE with an internal subset is refused."""
186
+
187
+ def __init__(self, path: Path):
188
+ import xml.etree.ElementTree as ET
189
+ self.path = Path(path)
190
+ raw = self.path.read_bytes()
191
+ if not _doctype_ok(raw):
192
+ raise ImportResolutionError(
193
+ f"{self.path}: the catalog has an ENTITY declaration or a DOCTYPE with an internal subset, which "
194
+ "is refused (an entity could read a file or fetch a URL). Remove it.", imports=())
195
+ try:
196
+ root = ET.fromstring(raw)
197
+ except ET.ParseError as e:
198
+ raise ImportResolutionError(f"{self.path}: the catalog is not well-formed XML: {e}", imports=())
199
+ self.exact: Dict[str, Tuple[str, str]] = {}
200
+ self.rewrites: List[Tuple[str, str, str]] = []
201
+ self.suffixes: List[Tuple[str, str, str]] = []
202
+ self.delegates: List[Tuple[str, str, str]] = [] # (prefix, catalog, base)
203
+ self.nexts: List[Tuple[str, str]] = [] # (catalog, base), in document order
204
+ self._read(root, self.path.resolve().as_uri())
205
+
206
+ def _read(self, el, base: str) -> None:
207
+ if el.get(_XML_BASE) is not None:
208
+ base = urljoin(base, el.get(_XML_BASE))
209
+ tag = el.tag.split('}')[-1] if isinstance(el.tag, str) else ''
210
+ if tag == 'uri' and el.get('name') and el.get('uri') is not None:
211
+ self.exact.setdefault(el.get('name'), (el.get('uri'), base))
212
+ elif tag == 'rewriteURI' and el.get('uriStartString') and el.get('rewritePrefix') is not None:
213
+ self.rewrites.append((el.get('uriStartString'), el.get('rewritePrefix'), base))
214
+ elif tag == 'uriSuffix' and el.get('uriSuffix') and el.get('uri') is not None:
215
+ self.suffixes.append((el.get('uriSuffix'), el.get('uri'), base))
216
+ elif tag == 'delegateURI' and el.get('uriStartString') and el.get('catalog'):
217
+ self.delegates.append((el.get('uriStartString'), el.get('catalog'), base))
218
+ elif tag == 'nextCatalog' and el.get('catalog'):
219
+ self.nexts.append((el.get('catalog'), base))
220
+ for child in el:
221
+ self._read(child, base)
222
+
223
+ def lookup(self, iri: str, _seen: Optional[Set[Path]] = None) -> Optional[Tuple[Path, str]]:
224
+ """(file, the entry in words) for `iri`, or None where the catalog (with the catalogs it delegates to or
225
+ names next) does not name it."""
226
+ seen = _seen if _seen is not None else set()
227
+ seen.add(self.path.resolve())
228
+ target, base, entry = None, '', ''
229
+ if iri in self.exact:
230
+ target, base = self.exact[iri]
231
+ entry = f'<uri name="{iri}" uri="{target}"/>'
232
+ else:
233
+ best = max((r for r in self.rewrites if iri.startswith(r[0])), key=lambda r: len(r[0]), default=None)
234
+ if best:
235
+ target, base = best[1] + iri[len(best[0]):], best[2]
236
+ entry = f'<rewriteURI uriStartString="{best[0]}" rewritePrefix="{best[1]}"/>'
237
+ else:
238
+ tail = max((r for r in self.suffixes if iri.endswith(r[0])), key=lambda r: len(r[0]), default=None)
239
+ if tail:
240
+ target, base = tail[1], tail[2]
241
+ entry = f'<uriSuffix uriSuffix="{tail[0]}" uri="{tail[1]}"/>'
242
+ if target is None:
243
+ delegated = sorted((d for d in self.delegates if iri.startswith(d[0])), key=lambda d: -len(d[0]))
244
+ if delegated:
245
+ # Section 7.2.2: the matching delegates' catalogs alone are consulted, longest prefix first.
246
+ for prefix, catalog, cbase in delegated:
247
+ found = self._other(catalog, cbase, f'<delegateURI uriStartString="{prefix}" '
248
+ f'catalog="{catalog}"/>', seen)
249
+ hit = found.lookup(iri, seen) if found is not None else None
250
+ if hit:
251
+ return hit
252
+ return None
253
+ for catalog, cbase in self.nexts:
254
+ found = self._other(catalog, cbase, f'<nextCatalog catalog="{catalog}"/>', seen)
255
+ hit = found.lookup(iri, seen) if found is not None else None
256
+ if hit:
257
+ return hit
258
+ return None
259
+ where = f"{self.path.name} entry {entry}"
260
+ if not target.lower().startswith(_NETWORK):
261
+ target = urljoin(base, target) # relative to the catalog (or its xml:base); percent-decoded below
262
+ return _local_path(target, Path('.'), where), where
263
+
264
+ def _other(self, catalog: str, base: str, entry: str, seen: Set[Path]) -> Optional['Catalog']:
265
+ """The catalog a `delegateURI` or `nextCatalog` entry names (a local file, relative to the entry's base), or
266
+ None where it was read already in this lookup (a catalog met twice is read once)."""
267
+ where = f"{self.path.name} entry {entry}"
268
+ if not catalog.lower().startswith(_NETWORK):
269
+ catalog = urljoin(base, catalog)
270
+ path = _local_path(catalog, Path('.'), where).resolve()
271
+ if path in seen:
272
+ return None
273
+ return Catalog(path)
274
+
275
+
276
+ def _local_path(target: str, base: Path, where: str) -> Path:
277
+ """The file a mapping entry names (relative to `base`; a `file:` IRI is percent-decoded); a network address or
278
+ a missing file is an error that names the entry."""
279
+ if target.lower().startswith(_NETWORK):
280
+ raise ImportResolutionError(
281
+ f"{where}: {target} is a network address, and nothing is fetched from the network. Map the IRI to a "
282
+ "local file.", imports=())
283
+ if target.startswith('file:'):
284
+ target = unquote(urlparse(target).path)
285
+ path = Path(target)
286
+ path = path if path.is_absolute() else base / path
287
+ if not path.is_file():
288
+ raise ImportResolutionError(f"{where}: the file {path} does not exist. Correct the path.", imports=())
289
+ return path
290
+
291
+
292
+ class OntologyCache:
293
+ """Manages local cache of downloaded ontologies.
294
+
295
+ Ontologies are cached by their URI hash to avoid re-downloading.
296
+ Cache can be in a user-specified directory or the default location.
297
+ """
298
+
299
+ DEFAULT_CACHE_DIR = Path.home() / '.prograph' / 'ontology_cache'
300
+
301
+ def __init__(self, cache_dir: Optional[Path] = None):
302
+ """Initialize the ontology cache.
303
+
304
+ Args:
305
+ cache_dir: Directory for caching ontologies. If None, uses default.
306
+ """
307
+ self.cache_dir = Path(cache_dir) if cache_dir else self.DEFAULT_CACHE_DIR # made when something is put
308
+
309
+ def _uri_to_filename(self, uri: str) -> str:
310
+ """Convert URI to a safe filename using hash."""
311
+ # Use MD5 hash of URI for filename (not security-sensitive)
312
+ uri_hash = hashlib.md5(uri.encode()).hexdigest()[:16]
313
+ # Extract a readable suffix from the URI
314
+ parsed = urlparse(uri)
315
+ path_parts = parsed.path.rstrip('/').split('/')
316
+ suffix = path_parts[-1] if path_parts else 'ontology'
317
+ # Clean suffix for filename
318
+ suffix = ''.join(c if c.isalnum() or c in '-_.' else '_' for c in suffix)
319
+ return f"{suffix}_{uri_hash}"
320
+
321
+ def get_cached_path(self, uri: str, format: str = 'turtle') -> Path:
322
+ """Get the cache path for an ontology URI.
323
+
324
+ Args:
325
+ uri: Ontology URI
326
+ format: Expected format (for extension)
327
+
328
+ Returns:
329
+ Path where the ontology would be cached
330
+ """
331
+ ext_map = {
332
+ 'turtle': '.ttl',
333
+ 'xml': '.rdf',
334
+ 'n3': '.n3',
335
+ 'nt': '.nt',
336
+ 'json-ld': '.jsonld'
337
+ }
338
+ ext = ext_map.get(format, '.ttl')
339
+ filename = self._uri_to_filename(uri) + ext
340
+ return self.cache_dir / filename
341
+
342
+ def is_cached(self, uri: str, format: str = 'turtle') -> bool:
343
+ """Check if an ontology is cached.
344
+
345
+ Args:
346
+ uri: Ontology URI
347
+ format: Expected format
348
+
349
+ Returns:
350
+ True if ontology is in cache
351
+ """
352
+ return self.get_cached_path(uri, format).exists()
353
+
354
+ def get(self, uri: str, format: str = 'turtle') -> Optional[Path]:
355
+ """Get cached ontology path if it exists.
356
+
357
+ Args:
358
+ uri: Ontology URI
359
+ format: Expected format
360
+
361
+ Returns:
362
+ Path to cached file, or None if not cached
363
+ """
364
+ path = self.get_cached_path(uri, format)
365
+ return path if path.exists() else None
366
+
367
+ def put(self, uri: str, content: str, format: str = 'turtle') -> Path:
368
+ """Store ontology content in cache.
369
+
370
+ Args:
371
+ uri: Ontology URI
372
+ content: Ontology content (serialized RDF)
373
+ format: Content format
374
+
375
+ Returns:
376
+ Path to cached file
377
+ """
378
+ path = self.get_cached_path(uri, format)
379
+ self.cache_dir.mkdir(parents=True, exist_ok=True)
380
+ path.write_text(content, encoding='utf-8')
381
+ logger.debug(f"Cached ontology {uri} at {path}")
382
+ return path
383
+
384
+ def clear(self) -> int:
385
+ """Clear all cached ontologies.
386
+
387
+ Returns:
388
+ Number of files removed
389
+ """
390
+ count = 0
391
+ if not self.cache_dir.is_dir():
392
+ return 0
393
+ for f in self.cache_dir.iterdir():
394
+ if f.is_file():
395
+ f.unlink()
396
+ count += 1
397
+ return count
398
+
399
+
400
+ class ImportResolver:
401
+ """Resolves owl:imports statements in ontologies from local files (never from the network).
402
+
403
+ In order: the caller's `imports` ({iri: path}; a relative path is relative to the importing ontology's
404
+ folder), the catalog files (`catalog-v001.xml` beside the importing ontology, then one beside each imported
405
+ file), an owl:Ontology of that IRI already in the graph, a file: IRI, a file named as the IRI's last path segment beside
406
+ the importing file and then beside the root ontology, a well-known ontology's file in the cache directory (put
407
+ there by the user). Imports of imports are followed until none is new (a cycle ends: each IRI is
408
+ read once); there is no depth cap.
409
+ """
410
+
411
+ def __init__(
412
+ self,
413
+ cache: Optional[OntologyCache] = None,
414
+ imports: Optional[Dict[str, object]] = None,
415
+ ):
416
+ """Initialize the import resolver.
417
+
418
+ Args:
419
+ cache: OntologyCache instance. If None, creates default (nothing is made on disk until used).
420
+ imports: {IRI: file path}, first in the order above.
421
+ """
422
+ if not RDFLIB_AVAILABLE:
423
+ raise ImportError("rdflib is required for ImportResolver")
424
+
425
+ self.cache = cache or OntologyCache()
426
+ self.imports = {str(k): Path(v) for k, v in (imports or {}).items()}
427
+ self.catalogs: List[Catalog] = []
428
+ self._catalog_dirs: Set[Path] = set()
429
+ self._resolved: Set[str] = set() # Track resolved URIs to detect cycles
430
+ self._origin: Dict[str, Path] = {} # an import's IRI -> the folder of the file that imports it
431
+
432
+ def add_catalog_beside(self, directory: Optional[Path]) -> None:
433
+ """Read `catalog-v001.xml` of `directory` (once), if there is one."""
434
+ if directory is None or Path(directory) in self._catalog_dirs:
435
+ return
436
+ self._catalog_dirs.add(Path(directory))
437
+ path = Path(directory) / CATALOG_NAME
438
+ if path.is_file():
439
+ self.catalogs.append(Catalog(path))
440
+
441
+ def resolve_imports(
442
+ self,
443
+ graph: 'rdflib.Graph',
444
+ base_path: Optional[Path] = None,
445
+ ) -> Tuple[List[str], List[str]]:
446
+ """Resolve all owl:imports in a graph, and those of what they import.
447
+
448
+ Args:
449
+ graph: RDF graph to resolve imports for
450
+ base_path: Directory of the importing ontology file (its catalog, and files named as an IRI's last
451
+ path segment)
452
+
453
+ Returns:
454
+ Tuple of (successfully_imported, failed_imports)
455
+ """
456
+ self.add_catalog_beside(base_path)
457
+ imported: List[str] = []
458
+ failed: List[str] = []
459
+ while True:
460
+ todo = [str(o) for o in graph.objects(predicate=OWL.imports)
461
+ if isinstance(o, URIRef) and str(o) not in self._resolved]
462
+ if not todo:
463
+ return imported, failed
464
+ for uri in dict.fromkeys(todo):
465
+ self._resolved.add(uri)
466
+ try:
467
+ found = self._resolve_single_import(uri, base_path, self._origin.get(uri), graph)
468
+ except ImportResolutionError:
469
+ raise
470
+ except Exception as e:
471
+ logger.warning(f"Failed to resolve import {uri}: {e}")
472
+ found = None
473
+ if found is None:
474
+ failed.append(uri)
475
+ continue
476
+ imported_graph, where = found
477
+ for triple in imported_graph:
478
+ graph.add(triple)
479
+ imported.append(uri)
480
+ if where is not None:
481
+ self.add_catalog_beside(where.parent)
482
+ for o in imported_graph.objects(predicate=OWL.imports):
483
+ self._origin.setdefault(str(o), where.parent)
484
+
485
+ def _resolve_single_import(
486
+ self,
487
+ uri: str,
488
+ base_path: Optional[Path] = None,
489
+ importer_dir: Optional[Path] = None,
490
+ graph: Optional['rdflib.Graph'] = None,
491
+ ) -> Optional[Tuple['rdflib.Graph', Optional[Path]]]:
492
+ """Resolve a single import URI from a local file: (its graph, its file or None), or None. With `graph`,
493
+ an owl:Ontology of that IRI already in it (after `imports=` and the catalog) is the import: (an empty
494
+ graph, None), nothing to merge."""
495
+ logger.debug(f"Resolving import: {uri}")
496
+
497
+ if uri in self.imports:
498
+ where = f"imports={{{uri!r}: ...}}"
499
+ path = _local_path(str(self.imports[uri]), Path(base_path) if base_path else Path('.'), where)
500
+ return _load_mapped(path, uri, where), path
501
+ for catalog in self.catalogs:
502
+ hit = catalog.lookup(uri)
503
+ if hit:
504
+ return _load_mapped(hit[0], uri, hit[1]), hit[0]
505
+
506
+ if graph is not None and (URIRef(uri), rdflib.RDF.type, OWL.Ontology) in graph:
507
+ return rdflib.Graph(), None # its triples are in the graph already
508
+
509
+ got = self._try_local_resolution(uri, base_path, importer_dir)
510
+ if got:
511
+ return got
512
+
513
+ graph = self._resolve_well_known(uri)
514
+ return (graph, None) if graph else None
515
+
516
+ def _resolve_well_known(self, uri: str) -> Optional['rdflib.Graph']:
517
+ """A well-known ontology (the registry's IRI, or one beneath it) from the cache directory, if the user
518
+ put its file there; None otherwise. Nothing is downloaded."""
519
+ for known_uri, info in WELL_KNOWN_ONTOLOGIES.items():
520
+ if uri == known_uri or uri.startswith(known_uri) or known_uri.startswith(uri):
521
+ fmt = info.get('format', 'turtle')
522
+ cached_path = self.cache.get(known_uri, fmt)
523
+ if cached_path:
524
+ logger.debug(f"Loading {uri} from cache: {cached_path}")
525
+ return parse_file(rdflib.Graph(), cached_path)
526
+ return None
527
+
528
+ def _try_local_resolution(
529
+ self,
530
+ uri: str,
531
+ base_path: Optional[Path] = None,
532
+ importer_dir: Optional[Path] = None,
533
+ ) -> Optional[Tuple['rdflib.Graph', Path]]:
534
+ """Try to resolve import as a local file.
535
+
536
+ Args:
537
+ uri: Import URI (may be file:// or relative path)
538
+ base_path: The root ontology's folder
539
+ importer_dir: The folder of the file that imports it (looked in first)
540
+
541
+ Returns:
542
+ (Parsed RDF graph, its file), or None if not found locally
543
+ """
544
+ # Handle file: IRIs (file:///p, file:/p; percent-decoded)
545
+ if uri.startswith('file:'):
546
+ file_path = Path(unquote(urlparse(uri).path))
547
+ if file_path.is_file():
548
+ return parse_file(rdflib.Graph(), file_path), file_path
549
+
550
+ # A file named as the IRI's last path segment: beside the importing file, then beside the root
551
+ filename = Path(urlparse(uri).path).name
552
+ for folder in (importer_dir, base_path):
553
+ if folder and filename:
554
+ local_path = Path(folder) / filename
555
+ if local_path.is_file():
556
+ logger.debug(f"Found local import: {local_path}")
557
+ return parse_file(rdflib.Graph(), local_path), local_path
558
+
559
+ return None
560
+
561
+ def reset(self) -> None:
562
+ """Reset the resolver state for a new resolution pass."""
563
+ self._resolved.clear()
564
+
565
+
566
+ def get_well_known_ontology_info(uri: str) -> Optional[Dict[str, str]]:
567
+ """Get information about a well-known ontology.
568
+
569
+ Args:
570
+ uri: Ontology URI
571
+
572
+ Returns:
573
+ Dictionary with remote_url, format, description, or None
574
+ """
575
+ return WELL_KNOWN_ONTOLOGIES.get(uri)
576
+
577
+
578
+ def list_well_known_ontologies() -> Dict[str, str]:
579
+ """List all registered well-known ontologies.
580
+
581
+ Returns:
582
+ Dictionary mapping URI to description
583
+ """
584
+ return {
585
+ uri: info.get('description', 'No description')
586
+ for uri, info in WELL_KNOWN_ONTOLOGIES.items()
587
+ }