daplug-cypher 1.0.0b1__py3-none-any.whl

daplug_cypher/__init__.py

@@ -0,0 +1,13 @@
+"""Public interface for the daplug_cypher package."""
+
+from typing import Any
+
+from .adapter import CypherAdapter
+
+
+def adapter(**kwargs: Any) -> CypherAdapter:
+    """Factory helper returning a configured CypherAdapter instance."""
+    return CypherAdapter(**kwargs)
+
+
+__all__ = ["adapter", "CypherAdapter"]

daplug_cypher/adapter.py

@@ -0,0 +1,351 @@
+"""Cypher adapter implementing graph CRUD operations with Trellis-style patterns."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+from neo4j import GraphDatabase
+from neo4j import Driver, Session, Transaction
+
+from daplug_cypher.common import BaseAdapter, map_to_schema, merge
+from daplug_cypher.cypher.parameters import convert_placeholders
+from daplug_cypher.cypher.serialization import serialize_records
+
+
+class CypherAdapter(BaseAdapter):
+    """Graph adapter coordinating schema normalization, sessions, and publishing."""
+
+    def __init__(self, **kwargs: Any) -> None:
+        super().__init__(**kwargs)
+        self.auto_connect: bool = kwargs.get("auto_connect", True)
+        self.bolt: Dict[str, Any] = kwargs.get("bolt", {})
+        self.neptune: Optional[Dict[str, Any]] = kwargs.get("neptune")
+        self.schema_file: Optional[str] = kwargs.get("schema_file")
+        self.schema_name: Optional[str] = kwargs.get("schema")
+        self.validate_schema: bool = kwargs.get("validate_schema", True)
+        self.driver_config: Dict[str, Any] = kwargs.get("driver_config", {})
+
+        self._driver: Optional[Driver] = None
+        self._session: Optional[Session] = None
+
+    # ---- Connection lifecycle -------------------------------------------------
+    def open(self) -> None:
+        """Establish a Cypher session using Neo4j driver configuration."""
+        if self._session:
+            return
+
+        bolt_config = self.__resolve_bolt_config()
+        uri = bolt_config.get("url")
+        user = bolt_config.get("user")
+        password = bolt_config.get("password")
+
+        if not uri or not user:
+            raise ValueError("bolt configuration requires 'url' and 'user'")
+
+        auth = (user, password) if password is not None else None
+        driver: Driver = GraphDatabase.driver(uri, auth=auth, **self.driver_config)
+        session: Session = driver.session()
+        self._driver = driver
+        self._session = session
+
+    def close(self) -> None:
+        """Close any active driver/session."""
+        if self._session:
+            self._session.close()
+            self._session = None
+        if self._driver:
+            self._driver.close()
+            self._driver = None
+
+    def __auto_open(self) -> None:
+        """Open a session when auto-connect is enabled."""
+        if self.auto_connect:
+            self.open()
+
+    def __auto_close(self) -> None:
+        """Close a session when auto-connect is enabled."""
+        if self.auto_connect:
+            self.close()
+
+    # ---- CRUD surface ---------------------------------------------------------
+    def create(self, **kwargs: Any) -> Dict[str, Any]:
+        """Insert a node using schema-normalized payloads."""
+        node_label = kwargs.get("node") or kwargs.get("label")
+        if not node_label:
+            raise ValueError("node label must be provided for create operations")
+        payload = self.__map_with_schema(kwargs["data"])
+        query = kwargs.get("query") or self.__default_create_query(node_label)
+
+        def _create(tx: Transaction) -> Any:
+            result = tx.run(query, placeholder=payload)
+            result.consume()
+
+        self.__auto_open()
+        try:
+            self.__execute_write(_create)
+        finally:
+            self.__auto_close()
+
+        self.publish("create", payload, **kwargs)
+        return payload
+
+    def read(self, **kwargs: Any) -> Any:
+        """Dispatch to query/match readers and return serialized content."""
+        params = dict(kwargs)
+        serialize = params.pop("serialize", True)
+        search = params.pop("search", False)
+        node_label = params.get("node") or params.get("label")
+        query = params["query"]
+        placeholder = params.get("placeholder")
+        records = self.__match(query, placeholder, node_label=node_label, serialize=serialize, search=search)
+        return records
+
+    def query(self, **kwargs: Any) -> Any:
+        """Execute arbitrary parameterized queries."""
+        if "query" not in kwargs:
+            raise ValueError("query text is required")
+        query_text = kwargs["query"]
+        if "$" not in query_text:
+            raise ValueError("SECURITY ERROR: parameter placeholders ($) are required")
+
+        parameters = self.__clean_placeholders(kwargs.get("placeholder") or {})
+
+        self.__auto_open()
+        try:
+            result = self.__run_read(query_text, parameters)
+            return list(result)
+        finally:
+            self.__auto_close()
+
+    def update(self, **kwargs: Any) -> Dict[str, Any]:
+        """Perform optimistic updates leveraging merge + schema mapping."""
+        node_label = kwargs.get("node") or kwargs.get("label")
+        if not node_label:
+            raise ValueError("node label must be provided for update operations")
+        identifier = kwargs.get("identifier")
+        idempotence_key = kwargs.get("idempotence_key")
+        if not identifier or not idempotence_key:
+            raise ValueError("identifier and idempotence_key must be provided for updates")
+        original_version = kwargs.get("original_idempotence_value")
+        if original_version is None:
+            raise ValueError("original_idempotence_value is required for optimistic updates")
+
+        query_text = kwargs.get("query")
+        if not query_text:
+            raise ValueError("query text is required for update operations")
+        placeholder = kwargs.get("placeholder")
+
+        original_records: List[Any] = self.__match(
+            query_text,
+            placeholder,
+            node_label=node_label,
+            serialize=False,
+            search=kwargs.get("search", False),
+        )
+        if not original_records:
+            raise ValueError("ATOMIC ERROR: No records found; record may have been deleted")
+
+        original_node = self.__first_node(original_records[0])
+        if original_node is None:
+            raise ValueError("ATOMIC ERROR: Unable to read existing node properties")
+
+        original_properties = dict(original_node)
+        merged = self.__merge_payload(original_properties, kwargs["data"], **kwargs)
+        normalized = self.__map_with_schema(merged)
+
+        update_query = kwargs.get("update_query") or self.__default_update_query(node_label, identifier, idempotence_key)
+        update_params = {
+            "id": normalized[identifier],
+            "version": original_version,
+            "placeholder": normalized,
+        }
+        update_params = self.__clean_placeholders(update_params)
+
+        self.__auto_open()
+        try:
+            result = self.__execute_write(lambda tx: tx.run(update_query, **update_params))
+            records = list(result)
+            if not records:
+                raise ValueError("ATOMIC ERROR: No records updated; version may have changed")
+        finally:
+            self.__auto_close()
+
+        self.publish("update", normalized, **kwargs)
+        return normalized
+
+    def delete(self, **kwargs: Any) -> Dict[str, Any]:
+        """Remove node(s) and publish deletion events."""
+        node_label = kwargs.get("node") or kwargs.get("label")
+        if not node_label:
+            raise ValueError("node label must be provided for delete operations")
+        identifier = kwargs.get("identifier")
+        if not identifier:
+            raise ValueError("identifier must be provided for delete operations")
+        delete_identifier = kwargs.get("delete_identifier")
+        if delete_identifier is None:
+            raise ValueError("delete_identifier is required")
+
+        read_result = self.__get_before_delete(node_label, identifier, delete_identifier, **kwargs)
+        if not read_result:
+            return {}
+
+        delete_query = kwargs.get("delete_query")
+        self.__perform_delete(node_label, identifier, delete_identifier, delete_query)
+        self.publish("delete", read_result, **kwargs)
+        return read_result
+
+    def create_relationship(self, **kwargs: Any) -> Any:
+        """Create relationships with Cypher safeguards."""
+        query_text = kwargs.get("query")
+        if not query_text:
+            raise ValueError("query is required to create relationships")
+        if "-" not in query_text or "[" not in query_text:
+            raise ValueError("INTEGRITY ERROR: relationship queries must include edges")
+
+        parameters = self.__clean_placeholders(kwargs.get("placeholder") or {})
+        self.__auto_open()
+        try:
+            result = self.__run_write(query_text, parameters)
+            result_list = list(result)
+            self.publish("create", result_list, **kwargs)  # type: ignore[arg-type]
+            return result_list
+        finally:
+            self.__auto_close()
+
+    def delete_relationship(self, **kwargs: Any) -> Any:
+        """Delete relationships while enforcing integrity constraints."""
+        query_text = kwargs.get("query")
+        if not query_text:
+            raise ValueError("query is required to delete relationships")
+        upper_query = query_text.upper()
+        if "DELETE" not in upper_query and "DETACH" not in upper_query:
+            raise ValueError("INTEGRITY ERROR: delete relationship queries must delete edges")
+
+        parameters = self.__clean_placeholders(kwargs.get("placeholder") or {})
+        self.__auto_open()
+        try:
+            result = self.__run_write(query_text, parameters)
+            result_list = list(result)
+            self.publish("delete", result_list, **kwargs)  # type: ignore[arg-type]
+            return result_list
+        finally:
+            self.__auto_close()
+
+    # ---- Support utilities ----------------------------------------------------
+    def __map_with_schema(self, data: Dict[str, Any]) -> Dict[str, Any]:
+        """Normalize payloads using shared schema helpers."""
+        if self.schema_file and self.schema_name:
+            return map_to_schema(data, self.schema_file, self.schema_name)
+        return dict(data)
+
+    def __merge_payload(self, original: Dict[str, Any], incoming: Dict[str, Any], **kwargs: Any) -> Dict[str, Any]:
+        """Reuse daplug-ddb merge semantics for optimistic updates."""
+        return merge(original, incoming, **kwargs)
+
+    def __serialize(
+        self,
+        records: Any,
+        *,
+        node_label: Optional[str],
+        serialize: bool = True,
+        search: bool = False,
+    ) -> Any:
+        """Turn Cypher driver records into JSON-ish payloads."""
+        return serialize_records(records, label=node_label, serialize=serialize, search=search)
+
+    def __clean_placeholders(self, placeholder: Optional[Dict[str, Any]]) -> Dict[str, Any]:
+        """Convert user-supplied parameters into cypher-friendly values."""
+        if placeholder is None:
+            return {}
+        return convert_placeholders(placeholder)
+
+    def __resolve_bolt_config(self) -> Dict[str, Any]:
+        """Choose the appropriate bolt configuration (Neptune overrides)."""
+        return self.neptune or self.bolt
+
+    def __execute_write(self, callback) -> Any:
+        if not self._session:
+            raise ValueError("session has not been opened")
+        return self._session.execute_write(callback)
+
+    def __run_read(self, query: str, parameters: Dict[str, Any]) -> Any:
+        if not self._session:
+            raise ValueError("session has not been opened")
+        return self._session.run(query, parameters)
+
+    def __run_write(self, query: str, parameters: Dict[str, Any]) -> Any:
+        if not self._session:
+            raise ValueError("session has not been opened")
+        return self._session.run(query, parameters)
+
+    def __default_create_query(self, node_label: str) -> str:
+        return f"CREATE (n:{node_label}) SET n = $placeholder RETURN n"
+
+    def __default_update_query(self, node_label: str, identifier: str, idempotence_key: str) -> str:
+        return (
+            f"MATCH (n:{node_label}) "
+            f"WHERE n.{identifier} = $id AND n.{idempotence_key} = $version "
+            f"SET n = $placeholder RETURN n"
+        )
+
+    def __match(
+        self,
+        query: str,
+        placeholder: Optional[Dict[str, Any]],
+        *,
+        node_label: Optional[str],
+        serialize: bool,
+        search: bool,
+    ) -> Any:
+        self.__auto_open()
+        try:
+            parameters = self.__clean_placeholders(placeholder)
+            result = self.__run_read(query, parameters)
+            records = list(result)
+            if serialize:
+                return self.__serialize(records, node_label=node_label, serialize=True, search=search)
+            return records
+        finally:
+            self.__auto_close()
+
+    def __get_before_delete(self, node_label: str, identifier: str, delete_identifier: Any, **kwargs: Any) -> Dict[str, Any]:
+        read_query = kwargs.get("read_query") or f"MATCH (n:{node_label}) WHERE n.{identifier} = $id RETURN n LIMIT 1"
+        records = self.__match(
+            read_query,
+            {"id": delete_identifier},
+            node_label=node_label,
+            serialize=True,
+            search=False,
+        )
+        if isinstance(records, dict):
+            nodes = records.get(node_label, [])
+            return nodes[0] if nodes else {}
+        if isinstance(records, list) and records:
+            return records[0]
+        return {}
+
+    def __perform_delete(self, node_label: str, identifier: str, delete_identifier: Any, delete_query: Optional[str]) -> None:
+        delete_query = delete_query or (
+            f"MATCH (n:{node_label}) WHERE n.{identifier} = $id WITH n LIMIT 1 DETACH DELETE n"
+        )
+        parameters = self.__clean_placeholders({"id": delete_identifier})
+        self.__auto_open()
+        try:
+            self.__run_write(delete_query, parameters)
+        finally:
+            self.__auto_close()
+
+    def __first_node(self, record: Any) -> Optional[Any]:
+        if hasattr(record, "values"):
+            for value in record.values():
+                if self.__is_node(value):
+                    return value
+        return None
+
+    @staticmethod
+    def __is_node(value: Any) -> bool:
+        try:
+            from neo4j.graph import Node  # pylint: disable=import-outside-toplevel
+        except ImportError as exc:
+            raise RuntimeError("neo4j package is required for CypherAdapter") from exc
+        return isinstance(value, Node)

daplug_cypher/common/__init__.py

@@ -0,0 +1,11 @@
+"""Shared utilities used by the DynamoDB adapter."""
+
+from .base_adapter import BaseAdapter
+from .dict_merger import merge
+from .schema_mapper import map_to_schema
+
+__all__ = [
+    "BaseAdapter",
+    "map_to_schema",
+    "merge",
+]

daplug_cypher/common/base_adapter.py

@@ -0,0 +1,69 @@
+"""Shared base adapter that wraps SNS publishing."""
+
+from typing import Any, Dict, Optional
+
+from daplug_cypher.types import MessageAttributes
+
+from . import publisher
+
+
+class BaseAdapter:
+    """Provides shared publish helper logic for adapters."""
+
+    def __init__(self, **kwargs: Any) -> None:
+        self.sns_arn: Optional[str] = kwargs.get("sns_arn")
+        self.sns_custom: Dict[str, Any] = kwargs.get("sns_attributes", {})
+        self.sns_defaults: bool = kwargs.get("sns_default_attributes", True)
+        self.sns_endpoint: Optional[str] = kwargs.get("sns_endpoint")
+        self.publisher = publisher
+        self.default_attributes: Dict[str, Any] = {
+            "identifier": kwargs.get("identifier"),
+            "idempotence_key": kwargs.get("idempotence_key"),
+            "author_identifier": kwargs.get("author_identifier"),
+        }
+
+    def publish(self, db_operation: str, db_data: Dict[str, Any], **kwargs: Any) -> None:
+        attributes = self.create_format_attibutes(db_operation, kwargs.get("sns_attributes", {}))
+        self.publisher.publish(
+            endpoint=self.sns_endpoint,
+            arn=self.sns_arn,
+            attributes=attributes,
+            data=db_data,
+            fifo_group_id=kwargs.get("fifo_group_id"),
+            fifo_duplication_id=kwargs.get("fifo_duplication_id"),
+        )
+
+    def create_format_attibutes(self, operation: str, call_attributes: dict) -> MessageAttributes:
+        combined = self.__combined_attributes(operation, call_attributes)
+        formatted_attributes: MessageAttributes = {}
+        for key, value in combined.items():
+            if value is not None:
+                data_type = "String" if isinstance(value, str) else "Number"
+                formatted_attributes[key] = {
+                    "DataType": data_type,
+                    "StringValue": value,
+                }
+        return formatted_attributes
+
+    def __combined_attributes(self, operation: str, call_attributes: dict) -> Dict[str, Any]:
+        pieces = []
+        base: Dict[str, Any] = {}
+        if self.sns_defaults:
+            base.update(self.default_attributes)
+        base["operation"] = operation
+        pieces.append(base)
+
+        if self.sns_custom:
+            pieces.append(self.sns_custom)
+        if call_attributes:
+            pieces.append(call_attributes)
+
+        return self.__merge_attributes(*pieces)
+
+    def __merge_attributes(self, *dicts: Dict[str, Any]) -> Dict[str, Any]:
+        merged: Dict[str, Any] = {}
+        for data in dicts:
+            if not data:
+                continue
+            merged.update(data)
+        return merged

daplug_cypher/common/dict_merger.py

@@ -0,0 +1,66 @@
+"""Utilities to merge dictionaries and lists with optional strategies."""
+
+from __future__ import annotations
+
+import copy
+from typing import Any, List
+
+import simplejson as json
+
+from daplug_cypher.types import DynamoItem
+
+
+def merge(original_data: DynamoItem, new_data: DynamoItem, **kwargs: Any) -> DynamoItem:
+    updated_data = copy.deepcopy(original_data)
+    _walk_dict(updated_data, new_data, **kwargs)
+    return updated_data
+
+
+def _walk_dict(old_data: DynamoItem, new_data: DynamoItem, **kwargs: Any) -> None:
+    for new_key in new_data.keys():
+        if old_data.get(new_key) and isinstance(new_data[new_key], dict):
+            _walk_dict(old_data[new_key], new_data[new_key], **kwargs)
+        elif isinstance(old_data.get(new_key), list) and isinstance(new_data[new_key], list):
+            old_data[new_key] = _merge_lists(
+                old_data[new_key], new_data[new_key], kwargs.get("update_list_operation", "add")
+            )
+        else:
+            _merge_dicts(new_key, old_data, new_data, kwargs.get("update_dict_operation", "upsert"))
+
+
+def _merge_dicts(
+    dict_key: str,
+    old_dict: DynamoItem,
+    new_dict: DynamoItem,
+    update_dict_operation: str = "upsert",
+) -> None:
+    if update_dict_operation == "remove":
+        old_dict.pop(dict_key, None)
+    else:
+        old_dict[dict_key] = new_dict[dict_key]
+
+
+def _merge_lists(
+    old_list: List[Any], new_list: List[Any], update_list_operation: str = "add"
+) -> List[Any]:
+    if update_list_operation == "remove":
+        _remove_item_in_list(old_list, new_list)
+    elif update_list_operation == "add":
+        _add_unique_item_in_list(old_list, new_list)
+    elif update_list_operation == "replace":
+        old_list = new_list
+    return old_list
+
+
+def _remove_item_in_list(old_list: List[Any], new_list: List[Any]) -> None:
+    for old_item in old_list:
+        old = sorted(old_item.items()) if isinstance(old_item, dict) else old_item
+        new = sorted(new_list[0].items()) if isinstance(new_list[0], dict) else new_list[0]
+        if json.dumps(old) == json.dumps(new):
+            old_list.remove(old_item)
+
+
+def _add_unique_item_in_list(old_list: List[Any], new_list: List[Any]) -> None:
+    for item in new_list:
+        if item not in old_list:
+            old_list.append(item)

daplug_cypher/common/json_helper.py

@@ -0,0 +1,19 @@
+"""Safe JSON encoding/decoding helpers."""
+
+from typing import Any
+
+import json
+
+
+def try_decode_json(possible_json: Any) -> Any:
+    try:
+        return json.loads(possible_json)
+    except Exception:  # pylint: disable=broad-except
+        return possible_json
+
+
+def try_encode_json(possible_json: Any) -> Any:
+    try:
+        return json.dumps(possible_json)
+    except Exception:  # pylint: disable=broad-except
+        return possible_json

daplug_cypher/common/logger.py

@@ -0,0 +1,16 @@
+"""Lightweight stdout logger honoring RUN_MODE."""
+
+from typing import Any, Dict
+
+import os
+
+from . import json_helper
+
+
+def log(**kwargs: Any) -> None:
+    if os.getenv("RUN_MODE") != "unittest":
+        payload: Dict[str, Any] = {
+            "level": kwargs.get("level", "INFO"),
+            "log": kwargs.get("log", {}),
+        }
+        print(json_helper.try_encode_json(payload))

daplug_cypher/common/publisher.py

@@ -0,0 +1,29 @@
+"""SNS publisher helper used by adapters for event fan-out."""
+
+from typing import Any, Dict
+
+import boto3
+import simplejson as json
+
+from . import logger
+
+
+def publish(**kwargs: Any) -> None:
+    if not kwargs.get("arn") or not kwargs.get("data"):
+        return
+    try:
+        sns_client = boto3.client(
+            "sns", region_name=kwargs.get("region"), endpoint_url=kwargs.get("endpoint")
+        )
+        publish_kwargs: Dict[str, Any] = {
+            "TopicArn": kwargs["arn"],
+            "Message": json.dumps(kwargs["data"]),
+            "MessageAttributes": kwargs.get("attributes", {}),
+        }
+        if kwargs.get("fifo_group_id"):
+            publish_kwargs["MessageGroupId"] = kwargs["fifo_group_id"]
+        if kwargs.get("fifo_duplication_id"):
+            publish_kwargs["MessageDeduplicationId"] = kwargs["fifo_duplication_id"]
+        sns_client.publish(**publish_kwargs)
+    except Exception as exc:  # pylint: disable=broad-except
+        logger.log(level="WARN", log={"error": f"publish_sns_error: {exc}"})

daplug_cypher/common/schema_loader.py

@@ -0,0 +1,13 @@
+"""Loads schema definitions with JSON reference resolution."""
+
+from typing import Any, Dict
+
+import jsonref
+import simplejson as json
+import yaml
+
+
+def load_schema(schema_file: str, schema_key: str) -> Dict[str, Any]:
+    with open(schema_file, encoding="UTF-8") as openapi:
+        api_doc = yaml.load(openapi, Loader=yaml.FullLoader)
+    return jsonref.loads(json.dumps(api_doc))["components"]["schemas"][schema_key]

daplug_cypher/common/schema_mapper.py

@@ -0,0 +1,51 @@
+"""Helpers that map arbitrary data to JSON schema-defined structures."""
+
+from typing import Any, Dict, List
+
+from daplug_cypher.types import DynamoItem
+
+from . import schema_loader
+
+
+def map_to_schema(data: DynamoItem, schema_file: str, schema_key: str) -> DynamoItem:
+    model_data: DynamoItem = {}
+    model_schema = schema_loader.load_schema(schema_file, schema_key)
+    schemas = model_schema["allOf"] if model_schema.get("allOf") else [model_schema]
+    for model in schemas:
+        if model.get("type") == "object":
+            _populate_model_data(model.get("properties", {}), data, model_data)
+    return model_data
+
+
+def _populate_model_data(
+    properties: Dict[str, Any], data: Any, model_data: DynamoItem
+) -> DynamoItem:
+    if data and isinstance(data, dict):
+        _populate_model_dict(properties, data, model_data)
+    return model_data
+
+
+def _populate_model_dict(properties: Dict[str, Any], data: Dict[str, Any], model_data: DynamoItem) -> None:
+    for property_key, property_value in properties.items():
+        model_data[property_key] = {}
+        if property_value.get("properties"):
+            _populate_model_data(
+                property_value["properties"], data.get(property_key), model_data[property_key]
+            )
+        elif property_value.get("items", {}).get("properties"):
+            _populate_model_list(model_data, property_key, property_value, data)
+        else:
+            model_data[property_key] = data.get(property_key)
+
+
+def _populate_model_list(
+    model_data: DynamoItem, property_key: str, property_value: Dict[str, Any], data: Dict[str, Any]
+) -> None:
+    model_data[property_key] = []
+    items: List[Any] = data.get(property_key, [])
+    for index in range(len(items)):  # pylint: disable=consider-using-enumerate
+        if data.get(property_key) and isinstance(items, list) and index < len(items):
+            pop = _populate_model_data(
+                property_value["items"]["properties"], items[index], {}
+            )
+            model_data[property_key].append(pop)

daplug_cypher/cypher/__init__.py

@@ -0,0 +1,6 @@
+"""Cypher-specific helper stubs used by the Cypher adapter."""
+
+from .parameters import convert_placeholders
+from .serialization import serialize_records
+
+__all__ = ["convert_placeholders", "serialize_records"]