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,35 @@
1
+ """PostgreSQL executor for graph queries.
2
+
3
+ Executes graph queries by generating PostgreSQL SQL and running it
4
+ against a PostgreSQL database through its ADBC driver.
5
+ """
6
+
7
+ from typing import Any, Dict, Optional
8
+
9
+ from prograph.executors.base import BaseExecutor
10
+ from prograph.graph.postgresql_graph import PostgreSQLGraph
11
+ from prograph.read_only import ExecutorRefusesWrites
12
+
13
+
14
+ class PostgreSQLExecutor(ExecutorRefusesWrites, BaseExecutor):
15
+ """Execute graph queries against a PostgreSQL database.
16
+
17
+ Generates PostgreSQL SQL from graph queries and executes them
18
+ against the provided database connection.
19
+ """
20
+
21
+ def __init__(
22
+ self,
23
+ schema: Any,
24
+ connection: Any,
25
+ table_stats: Optional[Dict[str, int]] = None,
26
+ ):
27
+ """Initialize the PostgreSQL executor.
28
+
29
+ Args:
30
+ schema: GraphSchema with node/relationship mappings
31
+ connection: a PostgreSQL URI, or an ADBC connection
32
+ table_stats: Optional table row counts for optimization
33
+ """
34
+ self.schema = schema
35
+ self.graph = PostgreSQLGraph(schema, connection, table_stats=table_stats)
@@ -0,0 +1,88 @@
1
+ """Spark executor for graph queries over Spark DataFrames.
2
+
3
+ This executor enables graph queries against Spark DataFrames
4
+ using a schema mapping to define the virtual graph structure.
5
+ """
6
+
7
+ from typing import Dict
8
+
9
+ try:
10
+ from pyspark.sql import DataFrame as SparkDataFrame
11
+ SPARK_AVAILABLE = True
12
+ except ImportError:
13
+ SPARK_AVAILABLE = False
14
+ SparkDataFrame = None
15
+
16
+ from prograph.executors.base import BaseExecutor
17
+ from prograph.graph.spark_graph import SparkGraph
18
+ from prograph.schema.mapping import GraphSchema
19
+ from prograph.read_only import ExecutorRefusesWrites
20
+
21
+
22
+ class SparkExecutor(ExecutorRefusesWrites, BaseExecutor):
23
+ """Execute graph queries against Spark DataFrames.
24
+
25
+ This executor provides a read-only virtual graph over Spark DataFrames.
26
+ CREATE, DELETE, and other mutating operations are not supported.
27
+
28
+ Example:
29
+ >>> schema = GraphSchema()
30
+ >>> schema.add_node_mapping(NodeMapping(
31
+ ... source_table='movies',
32
+ ... label='Movie',
33
+ ... id_column='movie_id',
34
+ ... property_columns={'title': 'title'}
35
+ ... ))
36
+ >>> executor = SparkExecutor(schema, {'movies': movies_df})
37
+ >>> # Use with ProGraph
38
+ """
39
+
40
+ def __init__(
41
+ self,
42
+ schema: GraphSchema,
43
+ dataframes: Dict[str, 'SparkDataFrame'],
44
+ sql_warehouse_id: str = None,
45
+ warehouse_timeout: float = None,
46
+ ansi_session: bool = True,
47
+ ):
48
+ """Initialize the Spark executor.
49
+
50
+ Args:
51
+ schema: GraphSchema defining node and relationship mappings
52
+ dataframes: Dictionary mapping table names to Spark DataFrames
53
+ sql_warehouse_id: Optional Databricks SQL Warehouse ID for optimized
54
+ SQL execution. When provided, generated SQL queries are routed to
55
+ the warehouse instead of Spark compute.
56
+ warehouse_timeout: Optional timeout in seconds for SQL Warehouse
57
+ queries. When set, queries that exceed this time are cancelled
58
+ on the warehouse and raise TimeoutError. None (default) means
59
+ poll indefinitely until completion.
60
+ ansi_session: Run each SQL statement with ANSI mode on.
61
+
62
+ Raises:
63
+ ImportError: If pyspark is not installed
64
+ ValueError: If schema or dataframes is invalid
65
+ """
66
+ if not SPARK_AVAILABLE:
67
+ raise ImportError(
68
+ "pyspark is required for the Spark backend. "
69
+ "Install it with: pip install pyspark"
70
+ )
71
+
72
+ if schema is None:
73
+ raise ValueError("schema is required for Spark backend")
74
+ if dataframes is None:
75
+ raise ValueError("dataframes dict is required for Spark backend")
76
+
77
+ self.schema = schema
78
+ self.dataframes = dataframes
79
+ self.graph = SparkGraph(
80
+ schema, dataframes,
81
+ sql_warehouse_id=sql_warehouse_id,
82
+ warehouse_timeout=warehouse_timeout,
83
+ ansi_session=ansi_session,
84
+ )
85
+
86
+
87
+ def __repr__(self) -> str:
88
+ return f"SparkExecutor({self.graph})"
@@ -0,0 +1,35 @@
1
+ """SQL Server executor for graph queries.
2
+
3
+ Executes graph queries by generating SQL Server SQL and running it
4
+ against a SQL Server database via SQLAlchemy or pyodbc.
5
+ """
6
+
7
+ from typing import Any, Dict, Optional
8
+
9
+ from prograph.executors.base import BaseExecutor
10
+ from prograph.graph.sqlserver_graph import SQLServerGraph
11
+ from prograph.read_only import ExecutorRefusesWrites
12
+
13
+
14
+ class SQLServerExecutor(ExecutorRefusesWrites, BaseExecutor):
15
+ """Execute graph queries against a SQL Server database.
16
+
17
+ Generates SQL Server SQL from graph queries and executes them
18
+ against the provided database connection.
19
+ """
20
+
21
+ def __init__(
22
+ self,
23
+ schema: Any,
24
+ connection: Any,
25
+ table_stats: Optional[Dict[str, int]] = None,
26
+ ):
27
+ """Initialize the SQL Server executor.
28
+
29
+ Args:
30
+ schema: GraphSchema with node/relationship mappings
31
+ connection: SQLAlchemy engine or pyodbc connection
32
+ table_stats: Optional table row counts for optimization
33
+ """
34
+ self.schema = schema
35
+ self.graph = SQLServerGraph(schema, connection, table_stats=table_stats)
@@ -0,0 +1 @@
1
+ """Helpers built on ProGraph's public API, outside the engine."""
@@ -0,0 +1,33 @@
1
+ """GraphQL over a ProGraph engine: a schema generated from the engine's schema. Queries
2
+ are not supported in 1.x: `execute_graphql` raises `GraphQLNotInReleaseError`.
3
+
4
+ Experimental: an extra outside ProGraph's engine API, and an exploration. Its schema, arguments and output may
5
+ change between releases. Needs graphql-core (`pip install "prograph[graphql]"`).
6
+
7
+ from prograph.extras.graphql import execute_graphql, graphql_schema
8
+ print(graphql_schema(engine)) # the schema, in SDL
9
+ execute_graphql(engine, "{ person(where: {age_gt: 26}) { name knows { name } } }")
10
+
11
+ The generated schema (`schema.py`) and how an operation is read (`execute.py`) are described in those modules;
12
+ docs/guides/graphql.md is the guide.
13
+ """
14
+ try:
15
+ import graphql # noqa: F401
16
+ except ImportError as e: # pragma: no cover - the message is the point
17
+ raise ImportError('prograph.extras.graphql needs graphql-core: pip install "prograph[graphql]"') from e
18
+ if not graphql.__version__.startswith("3.2."): # pragma: no cover
19
+ # 3.3 changes the execution helpers' return types (get_variable_values gives a VariableValues)
20
+ raise ImportError(f"prograph.extras.graphql needs graphql-core 3.2, not {graphql.__version__}: "
21
+ f'pip install "graphql-core>=3.2,<3.3"')
22
+
23
+ from .execute import execute_graphql, node_id # noqa: E402
24
+ from .schema import GraphQLSchemaError, build_model, graphql_name # noqa: E402
25
+
26
+
27
+ def graphql_schema(engine, required=None) -> str:
28
+ """The engine's generated GraphQL schema, in the schema definition language."""
29
+ from graphql import print_schema
30
+ return print_schema(build_model(engine, required).schema)
31
+
32
+
33
+ __all__ = ["execute_graphql", "graphql_schema", "build_model", "node_id", "graphql_name", "GraphQLSchemaError"]
@@ -0,0 +1,25 @@
1
+ """GraphQL queries over a ProGraph engine: not supported in 1.x.
2
+
3
+ The extra answered a GraphQL operation by reading the data one level at a time in Cypher, which is not built
4
+ for it. `execute_graphql` refuses with `GraphQLNotInReleaseError`; the
5
+ reader is in git at the `pre-1.0.0` tag. The generated schema
6
+ (`schema.py`, `graphql_schema`) reads the mapping only and works.
7
+ """
8
+ from __future__ import annotations
9
+
10
+ from typing import Any, Dict, List, Optional, Tuple
11
+ from urllib.parse import quote
12
+
13
+
14
+ def node_id(label: str, key: Any) -> str:
15
+ """The opaque identity of a node: its label and key, each percent-encoded, so that `node(id:)` reads it back.
16
+ Not elementId's text (whose format is not a contract)."""
17
+ return f"{quote(label, safe='')}:{quote(str(key), safe='')}"
18
+
19
+
20
+ def execute_graphql(engine: Any, query: str, variables: Optional[Dict[str, Any]] = None,
21
+ operation_name: Optional[str] = None, *, model: Any = None,
22
+ trace: Optional[List[Tuple[str, float]]] = None) -> Dict[str, Any]:
23
+ """Not supported in 1.x: raises `GraphQLNotInReleaseError` before anything runs (the extra answers in Cypher)."""
24
+ from prograph.utils.exceptions import GraphQLNotInReleaseError
25
+ raise GraphQLNotInReleaseError()
@@ -0,0 +1,314 @@
1
+ """A GraphQL schema for a ProGraph schema, generated from `engine.schema.describe()` and the recorded column types.
2
+
3
+ - Each node label is an object type implementing `Node`, with `id: ID!` (an opaque identity: the label and the
4
+ node's key, read back by `node(id:)`) and a field for each property.
5
+ - Each relationship type is a list field on its start type (`knows`, from KNOWS) and, read backwards, on its end
6
+ type (`inverseKnows`); `knowsEdges` and `inverseKnowsEdges` give the relationship's own properties beside the
7
+ node at its other end. One field per relationship: two parallel KNOWS from one person to another are two items.
8
+ - `Query` has one list field per label (`person`), with `where`, `orderBy`, `first` and `offset`, and `node(id:)`.
9
+ - No `Mutation` and no `Subscription`: ProGraph does not write.
10
+
11
+ GraphQL names are made from the schema's names by one rule (`graphql_name`); two that come out the same are
12
+ refused by name, never renamed a second time.
13
+ """
14
+ from __future__ import annotations
15
+
16
+ import datetime
17
+ import re
18
+ from dataclasses import dataclass, field
19
+ from decimal import Decimal
20
+ from typing import Any, Callable, Dict, List, Optional, Tuple
21
+
22
+ from graphql import (
23
+ GraphQLArgument, GraphQLBoolean, GraphQLEnumType, GraphQLEnumValue, GraphQLField, GraphQLFloat, GraphQLID,
24
+ GraphQLInputField, GraphQLInputObjectType, GraphQLInt, GraphQLInterfaceType, GraphQLList, GraphQLNonNull,
25
+ GraphQLObjectType, GraphQLScalarType, GraphQLSchema, GraphQLString,
26
+ )
27
+
28
+
29
+ class GraphQLSchemaError(ValueError):
30
+ """The ProGraph schema cannot be given a GraphQL schema as it stands (a name collision, a composite key)."""
31
+
32
+
33
+ # ------------------------------------------------------------------------------------------------ scalars
34
+
35
+ def _text(value: Any) -> str:
36
+ return value.isoformat() if hasattr(value, "isoformat") else str(value)
37
+
38
+
39
+ def _long(value: Any) -> int:
40
+ if isinstance(value, bool) or not isinstance(value, int):
41
+ raise TypeError(f"Long cannot represent {value!r}")
42
+ return value
43
+
44
+
45
+ def _checked(kind: str, read: Callable[[str], Any]) -> Callable[[Any], str]:
46
+ """An input coercion that accepts only text `read` can read, and gives back the text: a bad value is a
47
+ GraphQL error at coercion (GraphQL spec, 5.6.1 for literals, 6.1.2 for variables), never later."""
48
+ def parse(value: Any) -> str:
49
+ if not isinstance(value, str):
50
+ raise TypeError(f"{kind} cannot represent a non-string value: {value!r}")
51
+ try:
52
+ read(value)
53
+ except (ValueError, ArithmeticError) as e:
54
+ raise ValueError(f"{kind} cannot represent {value!r}") from e
55
+ return value
56
+ return parse
57
+
58
+
59
+ def _finite_decimal(text: str) -> Decimal:
60
+ d = Decimal(text)
61
+ if not d.is_finite():
62
+ raise ValueError(text)
63
+ return d
64
+
65
+
66
+ # GraphQL's Int is 32-bit (GraphQL spec, 3.5.1); a ProGraph integer is 64-bit, so an integer column is a Long.
67
+ LONG = GraphQLScalarType("Long", description="A 64-bit integer, as a JSON number.",
68
+ serialize=_long, parse_value=_long)
69
+ DECIMAL = GraphQLScalarType("Decimal", description="An exact decimal, as its text (\"12.50\"), so no digit is lost.",
70
+ serialize=_text, parse_value=_checked("Decimal", _finite_decimal))
71
+ DATE = GraphQLScalarType("Date", description="A date, as ISO 8601 text (\"2026-11-05\").",
72
+ serialize=_text, parse_value=_checked("Date", datetime.date.fromisoformat))
73
+ DATETIME = GraphQLScalarType("DateTime", description="A date and time, as ISO 8601 text.",
74
+ serialize=_text, parse_value=_checked("DateTime", datetime.datetime.fromisoformat))
75
+ _SCALARS = {"INTEGER": LONG, "FLOAT": GraphQLFloat, "STRING": GraphQLString, "BOOLEAN": GraphQLBoolean,
76
+ "DECIMAL": DECIMAL, "DATE": DATE, "DATETIME": DATETIME, "LOCALDATETIME": DATETIME}
77
+
78
+
79
+ def _scalar_of(cypher_type: Any):
80
+ """The GraphQL scalar for a recorded column type; String where the source recorded none, or a kind this
81
+ module does not map (a list, a map, a time), whose value is given as its text."""
82
+ if cypher_type is None:
83
+ return GraphQLString
84
+ if getattr(cypher_type, "exact", False): # a DECIMAL is the float kind, exact (prograph.schema.types)
85
+ return DECIMAL
86
+ kind = str(getattr(cypher_type, "kind", cypher_type)).upper()
87
+ return _SCALARS.get(kind, GraphQLString)
88
+
89
+
90
+ # ------------------------------------------------------------------------------------------------ names
91
+
92
+ _NAME = re.compile(r"^[_A-Za-z][_0-9A-Za-z]*$")
93
+
94
+
95
+ def graphql_name(name: str) -> str:
96
+ """A legal GraphQL name (GraphQL spec, 2.1.9) from a schema name: every other character becomes "_", a
97
+ leading digit gets a "_" before it, and a leading "__" (reserved for introspection) keeps one "_"."""
98
+ out = re.sub(r"[^_0-9A-Za-z]", "_", name)
99
+ if not out or out[0].isdigit():
100
+ out = "_" + out
101
+ while out.startswith("__"):
102
+ out = out[1:]
103
+ return out
104
+
105
+
106
+ def _camel(rel_type: str) -> str:
107
+ """KNOWS -> knows, LIVES_IN -> livesIn, worksFor -> worksFor."""
108
+ if rel_type.upper() == rel_type:
109
+ words = [w for w in rel_type.lower().split("_") if w]
110
+ return graphql_name(words[0] + "".join(w.capitalize() for w in words[1:])) if words else graphql_name(rel_type)
111
+ return graphql_name(rel_type[0].lower() + rel_type[1:])
112
+
113
+
114
+ # ------------------------------------------------------------------------------------------------ the model
115
+
116
+ @dataclass
117
+ class Prop:
118
+ field: str # GraphQL field name
119
+ name: str # ProGraph property name (what Cypher reads)
120
+ scalar: Any
121
+ required: bool = False
122
+
123
+
124
+ @dataclass
125
+ class Rel:
126
+ field: str # the node list field (knows, inverseKnows)
127
+ edges_field: str # the edge list field (knowsEdges)
128
+ rel_type: str
129
+ inverse: bool # read from the end node back to the start
130
+ target: str # the label at the other end
131
+ props: List[Prop] = field(default_factory=list)
132
+
133
+
134
+ @dataclass
135
+ class Label:
136
+ label: str
137
+ type_name: str
138
+ root_field: str
139
+ key: str # the key column, readable in Cypher as a property
140
+ key_kind: str = "STRING" # the key column's recorded kind: an id's key text is read back as it
141
+ props: Dict[str, Prop] = field(default_factory=dict) # by GraphQL field
142
+ rels: Dict[str, Rel] = field(default_factory=dict) # by node list field or edge list field
143
+
144
+
145
+ @dataclass
146
+ class Model:
147
+ labels: Dict[str, Label] # by label
148
+ by_type: Dict[str, Label] # by GraphQL type name
149
+ schema: GraphQLSchema = None
150
+
151
+
152
+ def _claim(names: Dict[str, str], name: str, what: str) -> None:
153
+ if name in names:
154
+ raise GraphQLSchemaError(f"{what} and {names[name]} are both named {name!r} in GraphQL; rename one in the "
155
+ f"ProGraph schema (no name is changed a second time)")
156
+ names[name] = what
157
+
158
+
159
+ def build_model(engine: Any, required: Optional[Dict[str, List[str]]] = None) -> Model:
160
+ """The model of the GraphQL schema: which label, property and relationship each type and field reads.
161
+ `required` names properties to type non-null (`{"Person": ["name"]}`): the schema does not say a column has
162
+ no nulls, so a property is nullable unless the caller says so; a node whose required property is null is
163
+ then an error, which GraphQL propagates to the nearest nullable field (GraphQL spec, 6.4.4)."""
164
+ from prograph.r2rml.schema import require_property_graph
165
+ require_property_graph(engine.schema, "GraphQL")
166
+ required = required or {}
167
+ described = engine.schema.describe()
168
+ mappings = {m.label: m for m in engine.schema.node_mappings if m.label is not None}
169
+ rel_mappings = {(m.rel_type, m.start_node_label, m.end_node_label): m for m in engine.schema.relationship_mappings}
170
+ labels: Dict[str, Label] = {}
171
+ type_names: Dict[str, str] = {"Query": "the query type", "Node": "the Node interface", "Long": "a scalar",
172
+ "Decimal": "a scalar", "Date": "a scalar", "DateTime": "a scalar",
173
+ "SortDirection": "an enum"}
174
+ root_fields: Dict[str, str] = {"node": "the node(id:) lookup"}
175
+ for node in described.nodes:
176
+ if node.label is None:
177
+ continue # an unlabelled node mapping: GraphQL types are labels
178
+ if len(node.id_columns) != 1:
179
+ raise GraphQLSchemaError(f"label {node.label!r} has a composite key {node.id_columns}; this exploration "
180
+ f"reads labels with a one-column key only")
181
+ type_name = graphql_name(node.label)
182
+ _claim(type_names, type_name, f"label {node.label!r}")
183
+ for suffix in ("Where", "OrderBy", "Edge"):
184
+ _claim(type_names, type_name + suffix, f"label {node.label!r}'s {suffix} type")
185
+ root = graphql_name(node.label[0].lower() + node.label[1:])
186
+ _claim(root_fields, root, f"label {node.label!r}")
187
+ mapping = mappings[node.label]
188
+ key_type = engine.schema.column_type(mapping, node.id_columns[0])
189
+ entry = Label(node.label, type_name, root, node.id_columns[0],
190
+ "DECIMAL" if getattr(key_type, "exact", False)
191
+ else str(getattr(key_type, "kind", key_type or "STRING")).upper())
192
+ fields: Dict[str, str] = {"id": "the identity"}
193
+ filters: Dict[str, str] = {"id": "the id filter", "id_in": "the id filter", "AND": "AND", "OR": "OR",
194
+ "NOT": "NOT"}
195
+ for p in node.properties:
196
+ name = graphql_name(p.name)
197
+ _claim(fields, name, f"property {p.name!r} of {node.label!r}")
198
+ for suffix in ("", "_not", "_in", "_lt", "_lte", "_gt", "_gte"):
199
+ _claim(filters, name + suffix, f"{node.label!r}'s filter on property {p.name!r}")
200
+ entry.props[name] = Prop(name, p.name, _scalar_of(engine.schema.column_type(mapping, p.column)),
201
+ required=p.name in required.get(node.label, []))
202
+ unknown = set(required.get(node.label, [])) - {p.name for p in node.properties}
203
+ if unknown:
204
+ raise GraphQLSchemaError(f"required names properties {sorted(unknown)} that {node.label!r} does not have")
205
+ labels[node.label] = entry
206
+ # A relationship type may join one label to several (IS_PART_OF from Component to Engine and to Module): then
207
+ # each field names its far label (isPartOfEngine, isPartOfModule); a type with one far label keeps the short
208
+ # name. One rule, fixed before any name is given, so no name is changed a second time.
209
+ targets: Dict[Tuple[str, str, bool], set] = {}
210
+ # A relationship whose end is no one label (an end given by an identity) has no GraphQL field.
211
+ described_rels = [r for r in described.relationships if r.start_label in labels and r.end_label in labels]
212
+ for rel in described_rels:
213
+ targets.setdefault((rel.start_label, rel.rel_type, False), set()).add(rel.end_label)
214
+ targets.setdefault((rel.end_label, rel.rel_type, True), set()).add(rel.start_label)
215
+ for rel in described_rels:
216
+ mapping = rel_mappings.get((rel.rel_type, rel.start_label, rel.end_label))
217
+ props = []
218
+ names: Dict[str, str] = {"node": "the edge's node"}
219
+ for p in rel.properties:
220
+ name = graphql_name(p.name)
221
+ _claim(names, name, f"property {p.name!r} of {rel.rel_type!r}")
222
+ props.append(Prop(name, p.name, _scalar_of(engine.schema.column_type(mapping, p.column) if mapping else None)))
223
+ out_field = _camel(rel.rel_type)
224
+ in_field = "inverse" + out_field[0].upper() + out_field[1:]
225
+ for owner, other, fname, inverse in ((rel.start_label, rel.end_label, out_field, False),
226
+ (rel.end_label, rel.start_label, in_field, True)):
227
+ if owner not in labels or other not in labels:
228
+ continue
229
+ entry = labels[owner]
230
+ if len(targets[(owner, rel.rel_type, inverse)]) > 1:
231
+ fname = fname + labels[other].type_name
232
+ taken = {"id": "the identity", **{f: f"property {p.name!r}" for f, p in entry.props.items()},
233
+ **{f: f"relationship {r.rel_type!r}" for f, r in entry.rels.items()}}
234
+ what = f"relationship {rel.rel_type!r} ({'into' if inverse else 'out of'} {owner!r})"
235
+ _claim(taken, fname, what)
236
+ _claim(taken, fname + "Edges", what + "'s edges")
237
+ r = Rel(fname, fname + "Edges", rel.rel_type, inverse, other, props)
238
+ entry.rels[fname] = r
239
+ entry.rels[fname + "Edges"] = r
240
+ model = Model(labels, {l.type_name: l for l in labels.values()})
241
+ model.schema = _graphql_schema(model)
242
+ return model
243
+
244
+
245
+ # ------------------------------------------------------------------------------------------------ GraphQL types
246
+
247
+ SORT = GraphQLEnumType("SortDirection", {"ASC": GraphQLEnumValue("ASC"), "DESC": GraphQLEnumValue("DESC")})
248
+
249
+
250
+ def _where_type(entry: Label) -> GraphQLInputObjectType:
251
+ def fields():
252
+ out = {"id": GraphQLInputField(GraphQLID), "id_in": GraphQLInputField(GraphQLList(GraphQLNonNull(GraphQLID)))}
253
+ for name, p in entry.props.items():
254
+ out[name] = GraphQLInputField(p.scalar, description="equal to; null means the property has no value")
255
+ out[name + "_not"] = GraphQLInputField(p.scalar, description="not equal to; null means it has a value")
256
+ out[name + "_in"] = GraphQLInputField(GraphQLList(GraphQLNonNull(p.scalar)))
257
+ if p.scalar is not GraphQLBoolean:
258
+ for op in ("lt", "lte", "gt", "gte"):
259
+ out[f"{name}_{op}"] = GraphQLInputField(p.scalar)
260
+ out["AND"] = GraphQLInputField(GraphQLList(GraphQLNonNull(where)))
261
+ out["OR"] = GraphQLInputField(GraphQLList(GraphQLNonNull(where)))
262
+ out["NOT"] = GraphQLInputField(where)
263
+ return out
264
+ where = GraphQLInputObjectType(entry.type_name + "Where", fields)
265
+ return where
266
+
267
+
268
+ def _order_type(entry: Label) -> GraphQLInputObjectType:
269
+ return GraphQLInputObjectType(entry.type_name + "OrderBy", {name: GraphQLInputField(SORT) for name in entry.props}
270
+ or {"id": GraphQLInputField(SORT)})
271
+
272
+
273
+ def _graphql_schema(model: Model) -> GraphQLSchema:
274
+ node_interface = GraphQLInterfaceType("Node", {"id": GraphQLField(GraphQLNonNull(GraphQLID))},
275
+ resolve_type=lambda obj, *_: obj["#typename"])
276
+ objects: Dict[str, GraphQLObjectType] = {}
277
+ wheres = {label: _where_type(e) for label, e in model.labels.items()}
278
+ orders = {label: _order_type(e) for label, e in model.labels.items()}
279
+
280
+ def list_args(label: str) -> Dict[str, GraphQLArgument]:
281
+ return {"where": GraphQLArgument(wheres[label]),
282
+ "orderBy": GraphQLArgument(GraphQLList(GraphQLNonNull(orders[label]))),
283
+ "first": GraphQLArgument(GraphQLInt), "offset": GraphQLArgument(GraphQLInt)}
284
+
285
+ edge_types: Dict[Tuple[str, str], GraphQLObjectType] = {}
286
+
287
+ def edge_type(rel: Rel) -> GraphQLObjectType:
288
+ """One edge type per relationship type and the label at the edge's far end: KnowsEdgeToPerson."""
289
+ key = (rel.rel_type, rel.target)
290
+ if key not in edge_types:
291
+ camel = _camel(rel.rel_type)
292
+ name = f"{camel[0].upper()}{camel[1:]}EdgeTo{model.labels[rel.target].type_name}"
293
+ fields = {p.field: GraphQLField(p.scalar) for p in rel.props}
294
+ fields["node"] = GraphQLField(GraphQLNonNull(objects[model.labels[rel.target].type_name]))
295
+ edge_types[key] = GraphQLObjectType(name, fields)
296
+ return edge_types[key]
297
+
298
+ for label, entry in model.labels.items():
299
+ def fields(entry=entry):
300
+ out = {"id": GraphQLField(GraphQLNonNull(GraphQLID))}
301
+ for name, p in entry.props.items():
302
+ out[name] = GraphQLField(GraphQLNonNull(p.scalar) if p.required else p.scalar)
303
+ for fname, rel in entry.rels.items():
304
+ target = objects[model.labels[rel.target].type_name]
305
+ item = edge_type(rel) if fname == rel.edges_field else target
306
+ out[fname] = GraphQLField(GraphQLNonNull(GraphQLList(GraphQLNonNull(item))), args=list_args(rel.target))
307
+ return out
308
+ objects[entry.type_name] = GraphQLObjectType(entry.type_name, fields, interfaces=[node_interface],
309
+ is_type_of=lambda obj, _info, n=entry.type_name: obj["#typename"] == n)
310
+ query_fields = {e.root_field: GraphQLField(GraphQLNonNull(GraphQLList(GraphQLNonNull(objects[e.type_name]))),
311
+ args=list_args(label))
312
+ for label, e in model.labels.items()}
313
+ query_fields["node"] = GraphQLField(node_interface, args={"id": GraphQLArgument(GraphQLNonNull(GraphQLID))})
314
+ return GraphQLSchema(query=GraphQLObjectType("Query", query_fields), types=list(objects.values()))