djraphdb 0.1.0__py3-none-any.whl

djraphdb/__init__.py

@@ -0,0 +1,138 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from contextlib import AbstractContextManager
+
+    import neo4j
+
+__version__ = "0.1.0"
+
+from djraphdb.conf import ConnectionConfig, DjraphdbSettings, get_settings
+from djraphdb.decorators import graph_read, graph_transaction, graph_write
+from djraphdb.exceptions import (
+    ConfigurationError,
+    DjraphdbError,
+    QueryError,
+    RetryExhaustedError,
+    TransactionError,
+)
+from djraphdb.exceptions import (
+    ConnectionError as GraphConnectionError,
+)
+from djraphdb.health import (
+    Neo4jHealthView,
+    check_neo4j_connection,
+    get_all_health,
+    get_neo4j_health,
+)
+from djraphdb.middleware import (
+    GraphSessionMiddleware,
+    GraphTransactionMiddleware,
+    get_graph_session,
+    get_graph_tx,
+)
+from djraphdb.nodes import DoesNotExist, GraphNode, MultipleObjectsReturned
+from djraphdb.query import CypherQuery
+from djraphdb.retry import RetryConfig
+from djraphdb.service import GraphService
+from djraphdb.signals import (
+    neo4j_connected,
+    neo4j_disconnected,
+    neo4j_query_executed,
+    neo4j_slow_query,
+)
+from djraphdb.types import NodeResult, RelationshipResult, ResultMapper
+
+__all__ = [
+    "__version__",
+    # Settings
+    "DjraphdbSettings",
+    "ConnectionConfig",
+    "get_settings",
+    # Exceptions
+    "DjraphdbError",
+    "GraphConnectionError",
+    "QueryError",
+    "TransactionError",
+    "ConfigurationError",
+    "RetryExhaustedError",
+    # Retry
+    "RetryConfig",
+    # Types
+    "NodeResult",
+    "RelationshipResult",
+    "ResultMapper",
+    # Nodes
+    "GraphNode",
+    "DoesNotExist",
+    "MultipleObjectsReturned",
+    # Service
+    "GraphService",
+    # Query builder
+    "CypherQuery",
+    # Connection helpers
+    "get_driver",
+    "get_session",
+    # Decorators
+    "graph_read",
+    "graph_write",
+    "graph_transaction",
+    # Middleware
+    "GraphSessionMiddleware",
+    "GraphTransactionMiddleware",
+    "get_graph_session",
+    "get_graph_tx",
+    # Health
+    "check_neo4j_connection",
+    "get_neo4j_health",
+    "get_all_health",
+    "Neo4jHealthView",
+    # Signals
+    "neo4j_connected",
+    "neo4j_disconnected",
+    "neo4j_query_executed",
+    "neo4j_slow_query",
+]
+
+
+def get_driver(using: str = "default") -> "neo4j.Driver":  # type: ignore[name-defined]
+    """Return the ``neo4j.Driver`` for the named connection.
+
+    Convenience wrapper around
+    :meth:`~djraphdb.connection.ConnectionManager.get_driver`.
+
+    Args:
+        using: Connection name.  Defaults to ``"default"``.
+
+    Returns:
+        The ``neo4j.Driver`` for the named connection.
+
+    Raises:
+        :exc:`GraphConnectionError`: If the manager is not initialised or
+            ``using`` is not a known connection name.
+    """
+    from djraphdb.connection import connection_manager
+
+    return connection_manager.get_driver(using)
+
+
+def get_session(
+    using: str = "default", **kwargs: Any
+) -> "AbstractContextManager[neo4j.Session]":
+    """Return a session context manager for the named connection.
+
+    Convenience wrapper around
+    :meth:`~djraphdb.connection.ConnectionManager.session`.
+
+    Args:
+        using: Connection name.  Defaults to ``"default"``.
+        **kwargs: Forwarded to ``neo4j.Driver.session()``.
+
+    Returns:
+        A context manager that yields a ``neo4j.Session``.
+    """
+    from djraphdb.connection import connection_manager
+
+    return connection_manager.session(using, **kwargs)

djraphdb/apps.py

@@ -0,0 +1,58 @@
+"""AppConfig for the djraphdb Django application."""
+
+from __future__ import annotations
+
+import atexit
+import logging
+
+from django.apps import AppConfig
+
+logger = logging.getLogger("djraphdb")
+
+
+class DjraphdbConfig(AppConfig):
+    """AppConfig for djraphdb.
+
+    Registers the djraphdb application and initialises the Neo4j connection
+    manager when Django starts up.
+    """
+
+    name = "djraphdb"
+    verbose_name = "djraphdb"
+    default_auto_field = "django.db.models.BigAutoField"
+
+    def ready(self) -> None:
+        """Initialise the Neo4j connection manager when Django starts.
+
+        Reads settings from ``DJRAPHDB``, creates drivers for each configured
+        connection, then verifies connectivity.  Connectivity failures are
+        logged as warnings rather than raised, so a temporarily-unreachable
+        Neo4j server will not prevent Django from starting.
+
+        An ``atexit`` handler is registered to close all drivers cleanly
+        when the process exits.
+        """
+        from djraphdb.conf import DjraphdbSettings
+        from djraphdb.connection import connection_manager
+
+        try:
+            settings = DjraphdbSettings.from_django_settings()
+        except Exception as exc:
+            logger.warning(
+                "djraphdb: could not load settings, skipping initialisation: %s",
+                exc,
+            )
+            return
+
+        connection_manager.initialize(settings)
+        atexit.register(connection_manager.close)
+
+        # Verify all connections; log warnings but do not crash.
+        results = connection_manager.verify_all()
+        for name, reachable in results.items():
+            if not reachable:
+                logger.warning(
+                    "djraphdb: connection %r is not reachable at startup", name
+                )
+
+        from djraphdb import health as _health_module  # noqa: F401 — registers system checks

djraphdb/conf.py

@@ -0,0 +1,420 @@
+"""
+Settings and configuration module for djraphdb.
+
+Reads configuration from ``django.conf.settings.DJRAPHDB`` and exposes it
+through ``DjraphdbSettings`` and ``ConnectionConfig``.
+
+Two configuration formats are supported:
+
+**Flat / single-connection format** — ``"URI"`` appears as a top-level key.
+The entire dict is automatically wrapped as the ``"default"`` connection::
+
+    DJRAPHDB = {
+        "URI": "bolt://localhost:7687",
+        "AUTH": ("neo4j", "password"),
+        "DATABASE": "neo4j",
+    }
+
+**Multi-database format** — every top-level value is itself a dict (and
+``"URI"`` is *not* a top-level key).  Each key names a connection::
+
+    DJRAPHDB = {
+        "default": {
+            "URI": "bolt://localhost:7687",
+            "AUTH": ("neo4j", "password"),
+        },
+        "analytics": {
+            "URI": "bolt://analytics:7687",
+            "AUTH": ("neo4j", "password"),
+            "DATABASE": "analytics",
+        },
+        "LOG_QUERIES": True,
+    }
+
+Global settings (``LOG_QUERIES``, ``LOG_QUERY_PARAMETERS``,
+``SLOW_QUERY_THRESHOLD_MS``) are extracted from the top-level dict in both
+formats.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+__all__ = [
+    "ConnectionConfig",
+    "DjraphdbSettings",
+    "get_settings",
+]
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+#: Keys that are treated as global settings rather than per-connection config.
+_GLOBAL_SETTING_KEYS: frozenset[str] = frozenset(
+    {"LOG_QUERIES", "LOG_QUERY_PARAMETERS", "SLOW_QUERY_THRESHOLD_MS"}
+)
+
+#: Default retry configuration shared by every new ``ConnectionConfig``.
+_DEFAULT_RETRY: dict = {
+    "enabled": True,
+    "max_attempts": 3,
+    "initial_delay": 1.0,
+    "multiplier": 2.0,
+    "max_delay": 30.0,
+}
+
+
+@dataclass
+class ConnectionConfig:
+    """Per-connection configuration for a single Neo4j driver instance.
+
+    All fields except ``uri`` have sensible defaults so most deployments only
+    need to supply ``URI`` and optionally ``AUTH``.
+
+    Attributes:
+        uri: The Bolt/Neo4j URI, e.g. ``"bolt://localhost:7687"``.
+        auth: A ``(username, password)`` tuple or ``None`` for unauthenticated
+            connections.
+        database: The Neo4j database name.  ``None`` lets Neo4j use its
+            configured default database.
+        max_connection_pool_size: Maximum number of connections kept open by
+            the driver's internal pool.
+        connection_timeout: Seconds to wait when establishing a new
+            connection.
+        max_transaction_retry_time: Maximum seconds spent retrying a failed
+            transaction.
+        connection_acquisition_timeout: Seconds to wait to acquire a
+            connection from the pool before raising an error.
+        encrypted: Whether to use TLS.  Defaults to ``False``.
+        trusted_certificates: A ``neo4j.TrustAll``, ``neo4j.TrustCustomCAs``
+            or similar object.  ``None`` uses the driver default.
+        retry: Retry/backoff configuration dict with keys ``enabled``,
+            ``max_attempts``, ``initial_delay``, ``multiplier``, ``max_delay``.
+        options: Additional keyword arguments forwarded verbatim to
+            ``neo4j.GraphDatabase.driver()``.
+    """
+
+    uri: str
+    auth: tuple[str, str] | None = field(default=None, repr=False)
+    database: str | None = None
+    max_connection_pool_size: int = 50
+    connection_timeout: float = 30.0
+    max_transaction_retry_time: float = 30.0
+    connection_acquisition_timeout: float = 60.0
+    encrypted: bool = False
+    trusted_certificates: object | None = None
+    retry: dict = field(default_factory=lambda: dict(_DEFAULT_RETRY))
+    options: dict = field(default_factory=dict)
+
+    def __repr__(self) -> str:
+        """Return a repr that redacts the password from the auth tuple.
+
+        The username is preserved to aid debugging (e.g. confirming which
+        Neo4j user is being used), but the password is replaced with ``***``
+        so that credentials are never exposed in logs, Sentry reports, or
+        Django debug pages.
+        """
+        auth_display = (self.auth[0], "***") if self.auth else None
+        return (
+            f"ConnectionConfig(uri={self.uri!r}, auth={auth_display!r}, "
+            f"database={self.database!r})"
+        )
+
+
+@dataclass
+class DjraphdbSettings:
+    """Top-level djraphdb configuration, loaded from ``settings.DJRAPHDB``.
+
+    Attributes:
+        connections: Mapping from connection name to ``ConnectionConfig``.
+            There must be at least one entry named ``"default"``.
+        log_queries: When ``True``, every Cypher query is logged at DEBUG
+            level.
+        log_query_parameters: When ``True``, query parameters are included in
+            DEBUG logs.  Only meaningful when ``log_queries`` is also
+            ``True``.
+
+            Warning: enabling this will write all query parameter values (which
+            may include passwords, PII, or sensitive data) to the DEBUG log.
+        slow_query_threshold_ms: Queries that take longer than this many
+            milliseconds are logged at WARNING level.
+    """
+
+    connections: dict[str, ConnectionConfig] = field(default_factory=dict)
+    log_queries: bool = False
+    log_query_parameters: bool = False
+    slow_query_threshold_ms: int = 1000
+
+    # ------------------------------------------------------------------
+    # Public factory methods
+    # ------------------------------------------------------------------
+
+    @classmethod
+    def from_django_settings(cls) -> "DjraphdbSettings":
+        """Load configuration from ``django.conf.settings.DJRAPHDB``.
+
+        Returns:
+            A fully populated ``DjraphdbSettings`` instance.
+
+        Raises:
+            django.core.exceptions.ImproperlyConfigured: If ``DJRAPHDB`` is
+                not present in Django settings, if any connection is missing
+                a ``URI``, or if ``AUTH`` is not a 2-element sequence of
+                strings.
+        """
+        from django.conf import settings
+        from django.core.exceptions import ImproperlyConfigured
+
+        if not hasattr(settings, "DJRAPHDB"):
+            raise ImproperlyConfigured(
+                "djraphdb requires a DJRAPHDB dict in your Django settings. "
+                "See the djraphdb documentation for configuration examples."
+            )
+
+        raw: dict = settings.DJRAPHDB
+        if not isinstance(raw, dict):
+            raise ImproperlyConfigured(
+                "DJRAPHDB must be a dict, got %s." % type(raw).__name__
+            )
+
+        return cls.from_dict(raw)
+
+    @classmethod
+    def from_dict(cls, config: dict) -> "DjraphdbSettings":
+        """Build a ``DjraphdbSettings`` instance from a plain dict.
+
+        This method implements the same parsing logic as
+        ``from_django_settings`` and is useful for testing without a live
+        Django project.
+
+        The dict may use either the flat single-connection format (where
+        ``"URI"`` is a top-level key) or the multi-database format (where
+        every top-level value is itself a dict).
+
+        Args:
+            config: A plain Python dict following the ``DJRAPHDB`` structure
+                documented in this module.
+
+        Returns:
+            A fully populated ``DjraphdbSettings`` instance.
+
+        Raises:
+            django.core.exceptions.ImproperlyConfigured: If any connection is
+                missing a ``URI``, or if ``AUTH`` is malformed.
+        """
+        from django.core.exceptions import ImproperlyConfigured
+
+        if not isinstance(config, dict):
+            raise ImproperlyConfigured(
+                "DJRAPHDB configuration must be a dict, got %s." % type(config).__name__
+            )
+
+        # ----------------------------------------------------------------
+        # Determine format: flat vs. multi-database
+        # ----------------------------------------------------------------
+        is_flat = "URI" in config
+
+        if is_flat:
+            # Treat the whole dict as the "default" connection.  Global
+            # settings are pulled from the same top-level namespace.
+            connection_dicts: dict[str, dict] = {"default": config}
+        else:
+            # Multi-database format.  Separate connection sub-dicts from
+            # global-setting keys.
+            connection_dicts = {}
+            for key, value in config.items():
+                if key in _GLOBAL_SETTING_KEYS:
+                    continue
+                if not isinstance(value, dict):
+                    raise ImproperlyConfigured(
+                        "DJRAPHDB: expected a connection dict for key %r, got %s. "
+                        "If you meant to configure a single connection, include "
+                        "a top-level 'URI' key." % (key, type(value).__name__)
+                    )
+                connection_dicts[key] = value
+
+        # ----------------------------------------------------------------
+        # Extract global settings
+        # ----------------------------------------------------------------
+        log_queries: bool = bool(config.get("LOG_QUERIES", False))
+        log_query_parameters: bool = bool(config.get("LOG_QUERY_PARAMETERS", False))
+        _raw_threshold = config.get("SLOW_QUERY_THRESHOLD_MS", 1000)
+        try:
+            slow_query_threshold_ms: int = int(_raw_threshold)
+        except (TypeError, ValueError) as exc:
+            raise ImproperlyConfigured(
+                "DJRAPHDB: 'SLOW_QUERY_THRESHOLD_MS' must be an integer, got %r."
+                % (_raw_threshold,)
+            ) from exc
+
+        # ----------------------------------------------------------------
+        # Parse each named connection
+        # ----------------------------------------------------------------
+        connections: dict[str, ConnectionConfig] = {}
+        for name, conn_dict in connection_dicts.items():
+            connections[name] = _parse_connection_config(
+                name=name,
+                raw=conn_dict,
+                ImproperlyConfigured=ImproperlyConfigured,
+            )
+
+        if not connections:
+            raise ImproperlyConfigured(
+                "DJRAPHDB must define at least one connection. "
+                "Provide a 'URI' key (flat format) or a dict of named connections."
+            )
+
+        return cls(
+            connections=connections,
+            log_queries=log_queries,
+            log_query_parameters=log_query_parameters,
+            slow_query_threshold_ms=slow_query_threshold_ms,
+        )
+
+
+# ---------------------------------------------------------------------------
+# Module-level convenience
+# ---------------------------------------------------------------------------
+
+
+def get_settings() -> DjraphdbSettings:
+    """Return the current djraphdb settings, loaded from Django settings.
+
+    This is a thin convenience wrapper around
+    ``DjraphdbSettings.from_django_settings()``.
+
+    Returns:
+        A ``DjraphdbSettings`` instance populated from
+        ``django.conf.settings.DJRAPHDB``.
+
+    Raises:
+        django.core.exceptions.ImproperlyConfigured: If ``DJRAPHDB`` is
+            absent or invalid.
+    """
+    return DjraphdbSettings.from_django_settings()
+
+
+# ---------------------------------------------------------------------------
+# Private parsing helpers
+# ---------------------------------------------------------------------------
+
+
+def _parse_connection_config(
+    *,
+    name: str,
+    raw: dict,
+    ImproperlyConfigured: type[Exception],
+) -> ConnectionConfig:
+    """Parse a single connection configuration dict into a ``ConnectionConfig``.
+
+    Args:
+        name: The connection name (used in error messages).
+        raw: The raw dict for this connection (uppercase keys).
+        ImproperlyConfigured: The exception class to raise on validation
+            failures (passed in to avoid a circular import with Django).
+
+    Returns:
+        A ``ConnectionConfig`` instance.
+
+    Raises:
+        ImproperlyConfigured: If ``URI`` is missing or ``AUTH`` is malformed.
+    """
+    # --- URI (required) ---------------------------------------------------
+    uri: str | None = raw.get("URI")
+    if not uri:
+        raise ImproperlyConfigured(
+            "DJRAPHDB connection %r is missing the required 'URI' key." % name
+        )
+
+    # --- AUTH (optional) --------------------------------------------------
+    auth_raw = raw.get("AUTH", None)
+    auth: tuple[str, str] | None = None
+    if auth_raw is not None:
+        if (
+            not isinstance(auth_raw, (list, tuple))
+            or len(auth_raw) != 2
+            or not all(isinstance(part, str) for part in auth_raw)
+        ):
+            raise ImproperlyConfigured(
+                "DJRAPHDB connection %r: 'AUTH' must be a 2-element tuple of "
+                "strings (username, password), got %s with length %d."
+                % (
+                    name,
+                    type(auth_raw).__name__,
+                    len(auth_raw) if hasattr(auth_raw, "__len__") else 0,
+                )
+            )
+        auth = (auth_raw[0], auth_raw[1])
+
+    # --- Retry config (merge user values over defaults) -------------------
+    retry_raw: dict = raw.get("RETRY", {})
+    if not isinstance(retry_raw, dict):
+        raise ImproperlyConfigured(
+            "DJRAPHDB connection %r: 'RETRY' must be a dict, got %s."
+            % (name, type(retry_raw).__name__)
+        )
+    retry: dict = {**_DEFAULT_RETRY, **retry_raw}
+
+    # --- MAX_CONNECTION_POOL_SIZE (optional, integer) ----------------------
+    _raw_pool_size = raw.get("MAX_CONNECTION_POOL_SIZE", 50)
+    try:
+        max_connection_pool_size: int = int(_raw_pool_size)
+    except (TypeError, ValueError) as exc:
+        raise ImproperlyConfigured(
+            "DJRAPHDB connection %r: 'MAX_CONNECTION_POOL_SIZE' must be an "
+            "integer, got %r." % (name, _raw_pool_size)
+        ) from exc
+
+    # --- CONNECTION_TIMEOUT (optional, float) ------------------------------
+    _raw_conn_timeout = raw.get("CONNECTION_TIMEOUT", 30.0)
+    try:
+        connection_timeout: float = float(_raw_conn_timeout)
+    except (TypeError, ValueError) as exc:
+        raise ImproperlyConfigured(
+            "DJRAPHDB connection %r: 'CONNECTION_TIMEOUT' must be a number, "
+            "got %r." % (name, _raw_conn_timeout)
+        ) from exc
+
+    # --- MAX_TRANSACTION_RETRY_TIME (optional, float) ----------------------
+    _raw_retry_time = raw.get("MAX_TRANSACTION_RETRY_TIME", 30.0)
+    try:
+        max_transaction_retry_time: float = float(_raw_retry_time)
+    except (TypeError, ValueError) as exc:
+        raise ImproperlyConfigured(
+            "DJRAPHDB connection %r: 'MAX_TRANSACTION_RETRY_TIME' must be a "
+            "number, got %r." % (name, _raw_retry_time)
+        ) from exc
+
+    # --- CONNECTION_ACQUISITION_TIMEOUT (optional, float) ------------------
+    _raw_acq_timeout = raw.get("CONNECTION_ACQUISITION_TIMEOUT", 60.0)
+    try:
+        connection_acquisition_timeout: float = float(_raw_acq_timeout)
+    except (TypeError, ValueError) as exc:
+        raise ImproperlyConfigured(
+            "DJRAPHDB connection %r: 'CONNECTION_ACQUISITION_TIMEOUT' must be "
+            "a number, got %r." % (name, _raw_acq_timeout)
+        ) from exc
+
+    # --- OPTIONS (optional, dict) ------------------------------------------
+    options_raw = raw.get("OPTIONS", {})
+    if not isinstance(options_raw, dict):
+        raise ImproperlyConfigured(
+            "DJRAPHDB connection %r: 'OPTIONS' must be a dict, got %s."
+            % (name, type(options_raw).__name__)
+        )
+    options: dict = dict(options_raw)
+
+    return ConnectionConfig(
+        uri=uri,
+        auth=auth,
+        database=raw.get("DATABASE"),
+        max_connection_pool_size=max_connection_pool_size,
+        connection_timeout=connection_timeout,
+        max_transaction_retry_time=max_transaction_retry_time,
+        connection_acquisition_timeout=connection_acquisition_timeout,
+        encrypted=bool(raw.get("ENCRYPTED", False)),
+        trusted_certificates=raw.get("TRUSTED_CERTIFICATES", None),
+        retry=retry,
+        options=options,
+    )