drivine 0.1.0__py3-none-any.whl

drivine/__init__.py

@@ -0,0 +1,244 @@
+"""
+Drivine: a graph database client for Python. https://drivine.org
+"""
+
+from drivine.annotation.aggregate import Aggregate, Count
+from drivine.annotation.aggregate_function import AggregateFunction
+from drivine.annotation.direction import Direction
+from drivine.annotation.empty_when_absent import EmptyWhenAbsent
+from drivine.annotation.full_text_index import FullTextIndex
+from drivine.annotation.graph_path import GraphPath
+from drivine.annotation.graph_property import GraphProperty
+from drivine.annotation.hop import Hop, hop
+from drivine.annotation.json_packed import JsonPacked
+from drivine.annotation.node_id import NodeId
+from drivine.annotation.node_labels import NodeLabels
+from drivine.annotation.node_stamp import NodeStamp
+from drivine.annotation.null_as_default import NullAsDefault
+from drivine.annotation.property_bag import PropertyBag
+from drivine.annotation.range_index import RangeIndex
+from drivine.annotation.read_only import ReadOnly
+from drivine.annotation.relationship import Relationship
+from drivine.annotation.root import Root
+from drivine.annotation.sorted_by import SortedBy
+from drivine.annotation.target_node import TargetNode
+from drivine.annotation.transient import Transient
+from drivine.annotation.unique import Unique
+from drivine.annotation.vector_index import VectorIndex
+from drivine.connection.connection import Connection
+from drivine.connection.connection_properties import ConnectionProperties
+from drivine.connection.connection_provider import ConnectionProvider
+from drivine.connection.connection_provider_builder import ConnectionProviderBuilder
+from drivine.connection.database_registry import DatabaseRegistry
+from drivine.connection.database_type import DatabaseType
+from drivine.connection.transaction_mode import TransactionMode
+from drivine.cursor.cursor import Cursor
+from drivine.cursor.cursor_specification import CursorSpecification
+from drivine.drivine_error import DrivineError
+from drivine.dsl.bag_refs import BagRefs
+from drivine.dsl.comparable_ref import ComparableRef
+from drivine.dsl.condition import Condition, Where, all_of, any_of, not_
+from drivine.dsl.index_advice_policy import IndexAdvicePolicy
+from drivine.dsl.list_ref import ListRef
+from drivine.dsl.node_tests import NodeTests
+from drivine.dsl.order_expressions import (
+    above,
+    at_least,
+    at_most,
+    below,
+    case_of,
+    coalesce,
+    div,
+    epoch_seconds,
+    equal_to,
+    exp,
+    floor,
+    has_no_value,
+    has_value,
+    minus,
+    negate,
+    not_equal_to,
+    param,
+    plus,
+    times,
+)
+from drivine.dsl.order_term import OrderTerm
+from drivine.dsl.query_index_advisor import QueryIndexAdvisor
+from drivine.dsl.ref import Ref, refs
+from drivine.dsl.seek_value import SeekValue
+from drivine.dsl.string_ref import StringRef
+from drivine.dsl.value_ref import ValueRef
+from drivine.manager.cascade_type import CascadeType
+from drivine.manager.delegating_persistence_manager import DelegatingPersistenceManager
+from drivine.manager.edge_operations import EdgeOperations
+from drivine.manager.graph_object_manager_factory import GraphObjectManagerFactory
+from drivine.manager.group_aggregate import GroupAggregate
+from drivine.manager.group_operations import GroupOperations
+from drivine.manager.groups import avg, count, key, max_, min_, path_key, sum_
+from drivine.manager.node_ref import NodeRef, node_ref
+from drivine.manager.non_transactional_persistence_manager import NonTransactionalPersistenceManager
+from drivine.manager.null_policy import NullPolicy
+from drivine.manager.patch_result import PatchResult
+from drivine.manager.path_key import PathKey
+from drivine.manager.persistence_manager import PersistenceManager
+from drivine.manager.persistence_manager_factory import PersistenceManagerFactory
+from drivine.manager.property_key import PropertyKey
+from drivine.manager.relate_mode import RelateMode
+from drivine.manager.removed_targets import RemovedTargets
+from drivine.manager.save_options import SaveOptions
+from drivine.manager.scored import Scored
+from drivine.manager.stale_object_error import StaleObjectError
+from drivine.manager.stateless_graph_object_manager import StatelessGraphObjectManager
+from drivine.manager.transactional_persistence_manager import TransactionalPersistenceManager
+from drivine.model import stamps
+from drivine.model.graph_view import GraphView
+from drivine.model.model_registry import ModelRegistry
+from drivine.model.node_fragment import NodeFragment
+from drivine.model.property_names import PropertyNames
+from drivine.model.relationship_fragment import RelationshipFragment
+from drivine.query.query_specification import QuerySpecification
+from drivine.query.statement import Statement, cypher_file, cypher_statement, sql_file, sql_statement
+from drivine.schema.constraint_manager import ConstraintManager
+from drivine.schema.engine_vector_options import EngineVectorOptions
+from drivine.schema.ensure_result import EnsureResult
+from drivine.schema.index_manager import IndexManager
+from drivine.schema.schema_catalog import SchemaCatalog
+from drivine.schema.schema_manager import SchemaManager
+from drivine.schema.schema_options import SchemaOptions
+from drivine.schema.schema_specs import full_text_index, range_index, uniqueness_constraint, vector_index
+from drivine.store.store_identity import StoreIdentity
+from drivine.transaction.transaction import Transaction, current_transaction
+from drivine.transaction.transaction_rolled_back_error import TransactionRolledBackError
+from drivine.transaction.transactional import transaction, transactional
+
+__all__ = [
+    "above",
+    "Aggregate",
+    "AggregateFunction",
+    "all_of",
+    "any_of",
+    "at_least",
+    "at_most",
+    "avg",
+    "BagRefs",
+    "below",
+    "CascadeType",
+    "case_of",
+    "coalesce",
+    "ComparableRef",
+    "Condition",
+    "Connection",
+    "ConnectionProperties",
+    "ConnectionProvider",
+    "ConnectionProviderBuilder",
+    "ConstraintManager",
+    "Count",
+    "count",
+    "current_transaction",
+    "Cursor",
+    "CursorSpecification",
+    "cypher_file",
+    "cypher_statement",
+    "DatabaseRegistry",
+    "DatabaseType",
+    "DelegatingPersistenceManager",
+    "Direction",
+    "div",
+    "DrivineError",
+    "EdgeOperations",
+    "EmptyWhenAbsent",
+    "EngineVectorOptions",
+    "EnsureResult",
+    "epoch_seconds",
+    "equal_to",
+    "exp",
+    "floor",
+    "full_text_index",
+    "FullTextIndex",
+    "GraphObjectManagerFactory",
+    "GraphPath",
+    "GraphProperty",
+    "GraphView",
+    "GroupAggregate",
+    "GroupOperations",
+    "has_no_value",
+    "has_value",
+    "Hop",
+    "hop",
+    "IndexAdvicePolicy",
+    "IndexManager",
+    "JsonPacked",
+    "key",
+    "ListRef",
+    "max_",
+    "min_",
+    "minus",
+    "ModelRegistry",
+    "negate",
+    "node_ref",
+    "NodeFragment",
+    "NodeId",
+    "NodeLabels",
+    "NodeRef",
+    "NodeStamp",
+    "NodeTests",
+    "NonTransactionalPersistenceManager",
+    "not_",
+    "not_equal_to",
+    "NullAsDefault",
+    "NullPolicy",
+    "OrderTerm",
+    "param",
+    "PatchResult",
+    "path_key",
+    "PathKey",
+    "PersistenceManager",
+    "PersistenceManagerFactory",
+    "plus",
+    "PropertyBag",
+    "PropertyKey",
+    "PropertyNames",
+    "QueryIndexAdvisor",
+    "QuerySpecification",
+    "range_index",
+    "RangeIndex",
+    "ReadOnly",
+    "Ref",
+    "refs",
+    "RelateMode",
+    "Relationship",
+    "RelationshipFragment",
+    "RemovedTargets",
+    "Root",
+    "SaveOptions",
+    "SchemaCatalog",
+    "SchemaManager",
+    "SchemaOptions",
+    "Scored",
+    "SeekValue",
+    "SortedBy",
+    "sql_file",
+    "sql_statement",
+    "StaleObjectError",
+    "stamps",
+    "StatelessGraphObjectManager",
+    "Statement",
+    "StoreIdentity",
+    "StringRef",
+    "sum_",
+    "TargetNode",
+    "times",
+    "Transaction",
+    "transaction",
+    "transactional",
+    "TransactionalPersistenceManager",
+    "TransactionMode",
+    "TransactionRolledBackError",
+    "Transient",
+    "Unique",
+    "uniqueness_constraint",
+    "ValueRef",
+    "vector_index",
+    "VectorIndex",
+    "Where",
+]

drivine/annotation/aggregate.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from drivine.annotation.aggregate_function import AggregateFunction
+from drivine.annotation.direction import Direction
+
+
+@dataclass(frozen=True)
+class Aggregate:
+    """
+    A field of a view computed in the query from the nodes one relationship type leads to from the root: their
+    number, or the SUM, AVG, MIN or MAX of one of their properties, named as stored. SUM and COUNT of none are 0; AVG,
+    MIN and MAX of none are None. Read-only.
+    """
+
+    function: AggregateFunction
+    type: str
+    property: str | None = None
+    direction: Direction = Direction.OUTGOING
+
+
+def Count(type: str, direction: Direction = Direction.OUTGOING) -> Aggregate:  # noqa: N802 - reads as a marker
+    """The number of nodes a relationship type leads to from the view's root. Read-only."""
+    return Aggregate(AggregateFunction.COUNT, type, None, direction)

drivine/annotation/aggregate_function.py

@@ -0,0 +1,9 @@
+from enum import StrEnum
+
+
+class AggregateFunction(StrEnum):
+    COUNT = "COUNT"
+    SUM = "SUM"
+    AVG = "AVG"
+    MIN = "MIN"
+    MAX = "MAX"

drivine/annotation/direction.py

@@ -0,0 +1,7 @@
+from enum import StrEnum
+
+
+class Direction(StrEnum):
+    OUTGOING = "OUTGOING"
+    INCOMING = "INCOMING"
+    UNDIRECTED = "UNDIRECTED"

drivine/annotation/empty_when_absent.py

@@ -0,0 +1,8 @@
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class EmptyWhenAbsent:
+    """
+    Loads an absent or null collection as an empty one: a list, set or tuple as one with no items, a dict as `{}`.
+    """

drivine/annotation/full_text_index.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class FullTextIndex:
+    """A full-text index over the field, or, as a class argument, over the fields named. Drives `load_matching`."""
+
+    properties: Sequence[str] = ()

drivine/annotation/graph_path.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+
+from drivine.annotation.hop import Hop
+
+
+@dataclass(frozen=True)
+class GraphPath:
+    """
+    A field of a view holding the nodes at the far end of a fixed list of hops from the root, each once, skipping the
+    nodes between: `directors: Annotated[list[Director], GraphPath([hop("ACTED_IN"), hop("DIRECTED_BY")])] = []`.
+    Read-only. A single path typed without `None` is required, and a list is with `required=True`.
+    """
+
+    hops: Sequence[Hop]
+    required: bool = False
+
+    def __hash__(self) -> int:
+        return hash((tuple(self.hops), self.required))

drivine/annotation/graph_property.py

@@ -0,0 +1,11 @@
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class GraphProperty:
+    """
+    Stores a field under the given property name, rather than the one the fragment's naming gives it:
+    `url_v2: Annotated[str, GraphProperty("urlV2")]`.
+    """
+
+    name: str

drivine/annotation/hop.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from drivine.annotation.direction import Direction
+
+
+@dataclass(frozen=True)
+class Hop:
+    """
+    One hop of a path: a relationship type, its direction, and optionally a label the node it reaches must carry,
+    and a property of that node to read the path in the order of. See TypeScript's `Hop` for how an order is read.
+    """
+
+    type: str
+    direction: Direction = Direction.OUTGOING
+    label: str | None = None
+    order_by: str | None = None
+    ascending: bool = True
+
+
+def hop(
+    type: str,
+    direction: Direction = Direction.OUTGOING,
+    label: str | None = None,
+    order_by: str | None = None,
+    ascending: bool = True,
+) -> Hop:
+    return Hop(type, direction, label, order_by, ascending)

drivine/annotation/json_packed.py

@@ -0,0 +1,9 @@
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class JsonPacked:
+    """
+    Stores a field as a JSON string, for a value an engine can't store as a property: a list of maps, or a map.
+    Unpacked on load.
+    """

drivine/annotation/node_id.py

@@ -0,0 +1,9 @@
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class NodeId:
+    """
+    Marks the field that identifies a node: `uuid: Annotated[str, NodeId()]`. A fragment has at most one, and needs
+    one to be loaded or saved by id.
+    """

drivine/annotation/node_labels.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+from dataclasses import dataclass
+from enum import Enum
+
+
+@dataclass(frozen=True)
+class NodeLabels:
+    """
+    Maps a field holding strings, a list or a set, to the node's labels beyond its fragment's own. With `members` (a
+    list of names, or a string Enum) the set is closed: the field reads only those labels. Without, it is open: it
+    reads every label besides the fragment's own. One to a fragment.
+    """
+
+    members: tuple[str, ...] | None = None
+
+    def __init__(self, members: Iterable[str] | type[Enum] | None = None) -> None:
+        if members is None:
+            names = None
+        elif isinstance(members, type):
+            names = tuple(str(it.value) for it in members)
+        else:
+            names = tuple(members)
+        object.__setattr__(self, "members", names)

drivine/annotation/node_stamp.py

@@ -0,0 +1,10 @@
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class NodeStamp:
+    """
+    Marks the field that holds the node's stamp, which a save checks to refuse overwriting a newer write:
+    `stamp: Annotated[str | None, NodeStamp()] = None`. Stored as `__drivine.stamp`, as TypeScript and drivine4j
+    store it.
+    """

drivine/annotation/null_as_default.py

@@ -0,0 +1,9 @@
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class NullAsDefault:
+    """
+    Loads a stored null as the field's default: `status: Annotated[str, NullAsDefault()] = "active"`. A property the
+    node doesn't have gets the default anyway. TypeScript's `@Default`.
+    """

drivine/annotation/property_bag.py

@@ -0,0 +1,16 @@
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class PropertyBag:
+    """
+    Maps a dict field of a node fragment to node properties, one for each entry, stored as `<prefix><delimiter><key>`:
+    real properties, visible and indexable. `prefix` defaults to the field's stored name and `delimiter` to `.`.
+
+    A flat bag has no prefix: each entry is stored under its bare key, and the bag reads back every property no field
+    or other bag accounts for. One to a fragment.
+    """
+
+    prefix: str | None = None
+    delimiter: str = "."
+    flat: bool = False

drivine/annotation/range_index.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class RangeIndex:
+    """
+    A range index over the field, `Annotated[str, RangeIndex()]`, or, as a class argument, over the fields named:
+    `class Session(NodeFragment, labels=[...], schema=[RangeIndex(["last_activity_at", "session_id"])])`.
+    """
+
+    properties: Sequence[str] = ()

drivine/annotation/read_only.py

@@ -0,0 +1,9 @@
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class ReadOnly:
+    """
+    Marks a relationship field of a view that is loaded and never written. A list of fragments read over several hops
+    (`max_depth` above 1) is read-only whether or not it is marked so.
+    """

drivine/annotation/relationship.py

@@ -0,0 +1,21 @@
+from dataclasses import dataclass
+
+from drivine.annotation.direction import Direction
+
+
+@dataclass(frozen=True)
+class Relationship:
+    """
+    Marks a view's field as a relationship from its root: `employment_history: Annotated[list[WorkHistory],
+    Relationship("WORKS_FOR")] = []`. What it holds, a node fragment, a relationship fragment or a view, is read from
+    the annotation, so is whether it is a list.
+
+    A single relationship typed without `None` is required: only roots that have it are loaded. A list is required
+    when `required=True`. `max_depth` is how deep a relationship to the view's own class, or one that leads back to
+    it, is expanded.
+    """
+
+    type: str
+    direction: Direction = Direction.OUTGOING
+    max_depth: int = 1
+    required: bool = False

drivine/annotation/root.py

@@ -0,0 +1,8 @@
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Root:
+    """
+    Marks a view's root, the node fragment the query starts from: `person: Annotated[Person, Root()]`. A view has one.
+    """

drivine/annotation/sorted_by.py

@@ -0,0 +1,12 @@
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class SortedBy:
+    """
+    Sorts a list relationship of a view after it is loaded, by a field path: `"name"`, or `"person.name"` into a
+    related view or relationship fragment. Nulls go last.
+    """
+
+    path: str
+    ascending: bool = True

drivine/annotation/target_node.py

@@ -0,0 +1,9 @@
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class TargetNode:
+    """
+    Marks the field of a relationship fragment that holds the node the relationship leads to: a node fragment or a
+    view.
+    """

drivine/annotation/transient.py

@@ -0,0 +1,8 @@
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Transient:
+    """
+    Marks a field that is neither loaded nor saved. It needs a default.
+    """

drivine/annotation/unique.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Unique:
+    """A uniqueness constraint over the field, or, as a class argument, over the fields named."""
+
+    properties: Sequence[str] = ()

drivine/annotation/vector_index.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+
+@dataclass(frozen=True)
+class VectorIndex:
+    """
+    A vector index over the field. Its dimensions come from the catalog's dimension provider when the catalog is built
+    (they belong to the embedding model, known at run time), unless given here. Drives `load_nearest`.
+    """
+
+    similarity: Literal["COSINE", "EUCLIDEAN"] = "COSINE"
+    dimensions: int | None = None
+    hnsw_m: int | None = None
+    hnsw_ef_construction: int | None = None

drivine/backend/backends.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from drivine.backend.cypher_backend import CypherBackend
+from drivine.backend.cypher_grammar import cypher_grammar_for
+from drivine.backend.graph_backend import GraphBackend
+from drivine.connection.database_type import DatabaseType
+
+
+def backend_for(type: DatabaseType, graph_name: str | None = None) -> GraphBackend:
+    """The backend that writes an engine's statements: on Oracle, over the tables of the graph named."""
+    if type is DatabaseType.ORACLE:
+        from drivine.backend.oracle.oracle_backend import OracleBackend
+        from drivine.backend.oracle.oracle_graph import DEFAULT_GRAPH, OracleGraph
+
+        return OracleBackend(OracleGraph(graph_name or DEFAULT_GRAPH))
+    return CypherBackend(cypher_grammar_for(type))

drivine/backend/cascade_targets.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+from drivine.annotation.direction import Direction
+from drivine.backend.cypher import label_expression, quote_name
+from drivine.backend.cypher_grammar import CypherGrammar
+from drivine.backend.view_projector import ViewProjector, label_test, target
+from drivine.model.fragment_model import FragmentModel
+from drivine.model.graph_view_model import GraphViewModel
+from drivine.model.relationship_model import RelationshipModel
+
+
+class CascadeTargets:
+    """
+    The nodes a view reaches from its root, as one list expression: a pattern comprehension for each position in the
+    view, each a flat path from the root, joined with `+`. Paths are flat, with no comprehension nested in another,
+    because FalkorDB evaluates nested ones wrongly when they are combined (FalkorDB/FalkorDB#2006, #3386).
+
+    The view's max_depth and the requirements of its nested views apply, so the list holds what loading the view would
+    load. A node reached by two paths is listed twice.
+    """
+
+    def __init__(self, grammar: CypherGrammar) -> None:
+        self.grammar = grammar
+        self._alias_count = 0
+
+    def of(self, model: GraphViewModel, root: str) -> str:
+        lists = self._view(model, f"({root})", [], [])
+        return " + ".join(lists) if lists else "[]"
+
+    def _view(
+        self, model: GraphViewModel, chain: str, conditions: list[str], path: list[RelationshipModel]
+    ) -> list[str]:
+        lists: list[str] = []
+        for rel in model.relationships:
+            if sum(1 for it in path if it is rel) >= rel.max_depth:
+                continue
+            self._alias_count += 1
+            alias = f"c{self._alias_count}"
+            into = target(rel)
+            hops = f"*1..{rel.max_depth}" if isinstance(into, FragmentModel) and rel.max_depth > 1 else ""
+            labels = into.root.labels if isinstance(into, GraphViewModel) else into.labels
+            step = f"{chain}{_hop(rel, hops)}({alias}"
+            extended = f"{step}{label_expression(labels)})"
+            own = ViewProjector(self.grammar).requirements(into, alias) if isinstance(into, GraphViewModel) else []
+            every = [*conditions, *own]
+            where = f" WHERE {' AND '.join(every)}" if every else ""
+            # Where the grammar says so, the far node's labels are tested after the match, the next level's chain
+            # keeping them.
+            if self.grammar.far_labels_after_match:
+                lists.append(f"[{alias} IN [{step}){where} | {alias}] WHERE {label_test(alias, labels)}]")
+            else:
+                lists.append(f"[{extended}{where} | {alias}]")
+            if isinstance(into, GraphViewModel):
+                lists.extend(self._view(into, extended, every, [*path, rel]))
+        return lists
+
+
+def _hop(rel: RelationshipModel, hops: str) -> str:
+    edge = f"[:{quote_name(rel.type)}{hops}]"
+    if rel.direction is Direction.INCOMING:
+        return f"<-{edge}-"
+    if rel.direction is Direction.UNDIRECTED:
+        return f"-{edge}-"
+    return f"-{edge}->"