cypher-graphdb 0.2.7__tar.gz → 0.2.8__tar.gz

{cypher_graphdb-0.2.7/src/cypher_graphdb.egg-info → cypher_graphdb-0.2.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cypher_graphdb
-Version: 0.2.7
+Version: 0.2.8
 Summary: ORM like library and CLI for cypher query language supporting graph databases.
 Author-email: Wolfgang Miller <wolfgang.miller@petrarca-labs.com>
 License-Expression: Apache-2.0

{cypher_graphdb-0.2.7 → cypher_graphdb-0.2.8}/src/cypher_graphdb/backendprovider.py

@@ -79,13 +79,18 @@ class BackendProvider(collections.abc.Collection):
         return self._backends.get(name.casefold(), None)
 
     def resolve(self, name: str) -> CypherBackend:
-        """Load and instantiate the backend for the given name.
+        """Load and return a fresh backend instance for the given name.
+
+        Each call returns a **new instance** so that multiple pools using the
+        same backend type (e.g. two AGE pools with different graph names) get
+        independent backend objects. The registry always stores the class, never
+        a cached instance.
 
         Args:
             name: Identifier of the backend to resolve (case-insensitive).
 
         Returns:
-            An instantiated CypherBackend, or None if resolution fails.
+            A new CypherBackend instance, or None if resolution fails.
 
         """
         with self._lock:
@@ -100,13 +105,17 @@ class BackendProvider(collections.abc.Collection):
                 if not phase and not self._try_to_load_backend(name):
                     break
 
-            # Instantiate only if result is a backend class (not an instance already)
-            if result and isinstance(result, type) and issubclass(result, CypherBackend):
-                result = result()
-                # replace class with singleton instance
-                self._backends[normalized_name] = result
+            if result is None:
+                return None
+
+            # Always instantiate from the class. If the registry already holds
+            # an instance (legacy / pre-existing code path), use its class.
+            if isinstance(result, type) and issubclass(result, CypherBackend):
+                return result()
+            if isinstance(result, CypherBackend):
+                return type(result)()
 
-            return result
+            return None
 
     def items(self) -> dict[str, CypherBackend | type[CypherBackend]]:
         """Return a snapshot of the registry mapping names to backends.

cypher_graphdb-0.2.8/src/cypher_graphdb/settings.py

@@ -0,0 +1,240 @@
+"""CypherGraphDB library configuration using Pydantic Settings.
+
+This module centralizes runtime configuration for the CypherGraphDB library.
+Values can be provided via environment variables (preferred) or fall back to
+the defaults below. A ``Settings`` instance is intended to be retrieved via
+``get_settings`` which caches the object for reuse across the process.
+
+Environment variables (default prefix ``CGDB_``): ``CGDB_BACKEND``,
+``CGDB_CINFO``, ``CGDB_GRAPH``, ``CGDB_READ_ONLY``,
+``CGDB_CREATE_GRAPH_IF_NOT_EXISTS``, ``CGDB_QUERY_TIMEOUT_S``.
+
+For applications that need multiple independent graph databases in the same
+process, ``Settings.with_prefix("CGDB_TS_")`` produces a Settings object
+bound to a different env-var prefix (``CGDB_TS_BACKEND``, etc.). The default
+prefix is ``CGDB_`` for backward compatibility.
+"""
+
+import os
+from functools import lru_cache
+from typing import Any
+
+from pydantic import Field, computed_field, field_serializer
+from pydantic.fields import FieldInfo
+from pydantic_settings import BaseSettings, EnvSettingsSource, SettingsConfigDict
+
+# Suffixes mapped to Settings fields. The full env var name is the
+# extension's ``env_prefix`` concatenated with one of these suffixes.
+# This is the single source of truth: field definitions below and
+# _PrefixedEnvSource both derive from it.
+_ENV_SUFFIXES: dict[str, str] = {
+    "backend": "BACKEND",
+    "cinfo": "CINFO",
+    "graph": "GRAPH",
+    "read_only": "READ_ONLY",
+    "create_graph": "CREATE_GRAPH_IF_NOT_EXISTS",
+    "query_timeout_s": "QUERY_TIMEOUT_S",
+}
+
+DEFAULT_ENV_PREFIX = "CGDB_"
+
+
+class _PrefixedEnvSource(EnvSettingsSource):
+    """Env settings source that ignores ``validation_alias`` and reads a custom prefix.
+
+    Used by :meth:`Settings.with_prefix` to populate a Settings instance from
+    environment variables under a custom prefix without falling back to the
+    default ``CGDB_*`` aliases declared on each Field.
+
+    The source disables ``.env`` file loading -- multi-instance setups are
+    expected to provide explicit environment variables per backend.
+    """
+
+    def __init__(self, settings_cls: type[BaseSettings], runtime_prefix: str) -> None:
+        super().__init__(settings_cls)
+        self._runtime_prefix = runtime_prefix.upper()
+
+    def get_field_value(self, field: FieldInfo, field_name: str) -> tuple[Any, str, bool]:
+        """Look up the env var as ``<prefix><SUFFIX>`` for the given field.
+
+        Ignores ``validation_alias`` entirely. Returns the raw string value
+        if present, or ``(None, field_name, False)`` if absent.
+
+        Fields not in ``_ENV_SUFFIXES`` (e.g. computed fields) are skipped.
+        """
+        suffix = _ENV_SUFFIXES.get(field_name)
+        if suffix is None:
+            # Computed fields and any future non-env fields are skipped.
+            return None, field_name, False
+        env_name = f"{self._runtime_prefix}{suffix}"
+        # Read env at call time (not construction time) -- consistent with
+        # how EnvSettingsSource works and safe for test monkeypatching.
+        env_upper = {k.upper(): v for k, v in os.environ.items()}
+        value = env_upper.get(env_name)
+        if value is not None:
+            return value, field_name, False
+        return None, field_name, False
+
+
+class Settings(BaseSettings):
+    """Runtime CypherGraphDB library settings.
+
+    Attributes map to environment variables. The default prefix is ``CGDB_``
+    so ``backend`` <- ``CGDB_BACKEND``. To use a different prefix (for
+    multi-instance setups), construct via ``Settings.with_prefix("CGDB_TS_")``.
+
+    These settings control the default behavior for CypherGraphDB connections
+    and can be overridden at runtime when creating CypherGraphDB instances.
+    """
+
+    backend: str | None = Field(
+        default=None,
+        description="Default backend type (memgraph, age, etc.)",
+        validation_alias=f"{DEFAULT_ENV_PREFIX}{_ENV_SUFFIXES['backend']}",
+    )
+    cinfo: str | None = Field(
+        default=None,
+        description="Default connection information/DSN",
+        validation_alias=f"{DEFAULT_ENV_PREFIX}{_ENV_SUFFIXES['cinfo']}",
+    )
+    graph: str | None = Field(
+        default=None,
+        description="Default graph name",
+        validation_alias=f"{DEFAULT_ENV_PREFIX}{_ENV_SUFFIXES['graph']}",
+    )
+    read_only: bool = Field(
+        default=False,
+        description="Enable read-only mode (prevents write operations)",
+        validation_alias=f"{DEFAULT_ENV_PREFIX}{_ENV_SUFFIXES['read_only']}",
+    )
+    create_graph: bool = Field(
+        default=False,
+        description="Auto-create graph if it does not exist (AGE only)",
+        validation_alias=f"{DEFAULT_ENV_PREFIX}{_ENV_SUFFIXES['create_graph']}",
+    )
+    query_timeout_s: int | None = Field(
+        default=30,
+        description=(
+            "Maximum seconds a single query may run before the backend cancels it. "
+            "Default is 30s -- enough for any legitimate graph query while preventing "
+            "runaway queries from exhausting the connection pool. "
+            "Set to 0 or None to disable. "
+            "AGE: sets PostgreSQL statement_timeout at connection time. "
+            "Memgraph: sets database setting query.timeout after connecting."
+        ),
+        validation_alias=f"{DEFAULT_ENV_PREFIX}{_ENV_SUFFIXES['query_timeout_s']}",
+    )
+
+    @computed_field  # type: ignore[misc]
+    @property
+    def cinfo_sanitized(self) -> str | None:
+        """Get sanitized connection info safe for logging."""
+        return self._sanitize_cinfo(self.cinfo)
+
+    def _sanitize_cinfo(self, cinfo: str | None) -> str | None:
+        """Sanitize connection info for safe logging."""
+        if not cinfo:
+            return None
+
+        from .utils.connection_utils import sanitize_connection_string_for_logging
+
+        return sanitize_connection_string_for_logging(cinfo)
+
+    @field_serializer("cinfo")
+    def serialize_cinfo(self, _value: str | None) -> str | None:
+        """Serialize cinfo as sanitized version for safe output."""
+        return self.cinfo_sanitized
+
+    def __repr__(self) -> str:
+        """String representation with sanitized cinfo."""
+        from .utils.settings_repr import safe_settings_repr
+
+        return safe_settings_repr(self, field_sanitizers={"cinfo": lambda _: self.cinfo_sanitized})
+
+    def __str__(self) -> str:
+        """String representation with sanitized cinfo."""
+        from .utils.settings_repr import safe_settings_str
+
+        return safe_settings_str(self, field_sanitizers={"cinfo": lambda _: self.cinfo_sanitized})
+
+    model_config = SettingsConfigDict(
+        case_sensitive=False,
+        extra="ignore",  # Ignore unexpected env vars
+        env_file=".env",  # Optional .env loading (if present)
+        env_file_encoding="utf-8",
+        populate_by_name=True,  # Allow construction by field name (used by with_prefix)
+    )
+
+    @classmethod
+    def with_prefix(cls, env_prefix: str) -> Settings:
+        """Build a Settings instance from environment variables with a custom prefix.
+
+        This enables multi-instance setups where independent CypherGraphDB pools
+        each read their own set of env vars. For example, with
+        ``env_prefix="CGDB_TS_"`` the instance reads ``CGDB_TS_BACKEND``,
+        ``CGDB_TS_CINFO``, ``CGDB_TS_GRAPH``, etc.
+
+        Unlike the default ``Settings()`` constructor, this method does NOT
+        fall back to the default ``CGDB_*`` env vars or the ``.env`` file -- it
+        reads exclusively from env vars matching the given prefix. Pass
+        ``Settings.with_prefix("CGDB_")`` to read the default prefix without
+        consulting ``.env``.
+
+        Args:
+            env_prefix: Prefix to apply to env var names. Must end with ``_``
+                by convention (not enforced). Pass ``""`` to read unprefixed
+                env vars (``BACKEND``, ``CINFO``, ...).
+
+        Returns:
+            A Settings instance populated from env vars with the given prefix.
+            Fields whose env var is not set use the field default.
+
+        Examples:
+            ```python
+            # Default (reads CGDB_BACKEND, CGDB_GRAPH, ...; also .env)
+            settings = Settings()
+
+            # Scoped, env only -- no .env fallback, no default-prefix fallback
+            ts_settings = Settings.with_prefix("CGDB_TS_")
+            cg_settings = Settings.with_prefix("CGDB_CG_")
+            ```
+        """
+        from pydantic_core import PydanticUndefinedType
+
+        source = _PrefixedEnvSource(cls, env_prefix)
+        env_data = source()
+        # Build kwargs for only the regular (non-computed) fields that are in
+        # _ENV_SUFFIXES. For each field:
+        #   - use the env value if the source found one
+        #   - use the declared default if it is defined (not PydanticUndefined)
+        #   - leave absent fields out so pydantic uses its own default mechanism
+        # Because we pass a value for every regular field as an init kwarg,
+        # pydantic-settings' init_settings source (highest priority) wins over
+        # the env/dotenv sources -- masking the default CGDB_* env vars and .env.
+        full_kwargs: dict[str, Any] = {}
+        for field_name in _ENV_SUFFIXES:
+            if field_name in env_data:
+                full_kwargs[field_name] = env_data[field_name]
+            else:
+                field_info = cls.model_fields.get(field_name)
+                if field_info is not None and not isinstance(field_info.default, PydanticUndefinedType):
+                    full_kwargs[field_name] = field_info.default
+                else:
+                    full_kwargs[field_name] = None
+        return cls(_env_file=None, **full_kwargs)
+
+
+@lru_cache
+def get_settings() -> Settings:
+    """Return the cached ``Settings`` instance.
+
+    The first invocation reads environment variables / .env file; subsequent
+    calls reuse the same object to ensure consistent config.
+
+    Returns:
+        Settings: The cached settings instance.
+    """
+    return Settings()
+
+
+__all__ = ["DEFAULT_ENV_PREFIX", "Settings", "get_settings"]

{cypher_graphdb-0.2.7 → cypher_graphdb-0.2.8/src/cypher_graphdb.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cypher_graphdb
-Version: 0.2.7
+Version: 0.2.8
 Summary: ORM like library and CLI for cypher query language supporting graph databases.
 Author-email: Wolfgang Miller <wolfgang.miller@petrarca-labs.com>
 License-Expression: Apache-2.0

{cypher_graphdb-0.2.7 → cypher_graphdb-0.2.8}/src/cypher_graphdb.egg-info/SOURCES.txt

@@ -262,6 +262,7 @@ tests/unit/test_models.py
 tests/unit/test_prepared_statement_recovery.py
 tests/unit/test_query_timeout.py
 tests/unit/test_schema_converter.py
+tests/unit/test_settings.py
 tests/unit/cli/__init__.py
 tests/unit/cli/test_cmd_map.py
 tests/unit/cli/test_command_registry.py

cypher_graphdb-0.2.8/tests/unit/test_settings.py

@@ -0,0 +1,164 @@
+"""Unit tests for cypher_graphdb.settings.Settings.
+
+Covers:
+- Default prefix behaviour (CGDB_*)
+- Custom env_prefix via Settings.with_prefix()
+- Multi-instance isolation (two settings reading two prefixes)
+- Case-insensitive env var matching
+- Type coercion (bool, int) from prefixed env vars
+"""
+
+import os
+
+import pytest
+
+from cypher_graphdb.settings import DEFAULT_ENV_PREFIX, Settings, get_settings
+
+
+@pytest.fixture(autouse=True)
+def _isolated_env(monkeypatch, tmp_path):
+    """Clear CGDB-related env vars and prevent .env from being read.
+
+    The local ``.env`` file in the repo root would otherwise pollute these
+    tests with real connection strings. We point pydantic-settings at a
+    nonexistent file to disable .env loading for the duration of each test.
+    """
+    for key in list(os.environ.keys()):
+        if "CGDB" in key.upper() or key in {
+            "BACKEND",
+            "CINFO",
+            "GRAPH",
+            "READ_ONLY",
+            "CREATE_GRAPH_IF_NOT_EXISTS",
+            "QUERY_TIMEOUT_S",
+        }:
+            monkeypatch.delenv(key, raising=False)
+    # Patch Settings.model_config to not read any .env during tests.
+    monkeypatch.setitem(Settings.model_config, "env_file", str(tmp_path / "nonexistent.env"))
+    # Reset the lru_cache.
+    get_settings.cache_clear()
+    yield
+    get_settings.cache_clear()
+
+
+class TestDefaultPrefix:
+    """Default CGDB_ prefix behaviour (unchanged)."""
+
+    def test_reads_default_cgdb_env_vars(self, monkeypatch):
+        monkeypatch.setenv("CGDB_BACKEND", "age")
+        monkeypatch.setenv("CGDB_CINFO", "postgresql://localhost/x")
+        monkeypatch.setenv("CGDB_GRAPH", "techgraph")
+        s = Settings()
+        assert s.backend == "age"
+        assert s.cinfo == "postgresql://localhost/x"
+        assert s.graph == "techgraph"
+
+    def test_defaults_when_no_env_vars(self):
+        s = Settings()
+        assert s.backend is None
+        assert s.cinfo is None
+        assert s.graph is None
+        assert s.read_only is False
+        assert s.create_graph is False
+        assert s.query_timeout_s == 30
+
+    def test_get_settings_returns_cached_instance(self, monkeypatch):
+        monkeypatch.setenv("CGDB_BACKEND", "memgraph")
+        s1 = get_settings()
+        s2 = get_settings()
+        assert s1 is s2
+        assert s1.backend == "memgraph"
+
+    def test_default_env_prefix_constant(self):
+        assert DEFAULT_ENV_PREFIX == "CGDB_"
+
+
+class TestWithPrefix:
+    """Settings.with_prefix() for multi-instance setups."""
+
+    def test_reads_prefixed_env_vars(self, monkeypatch):
+        monkeypatch.setenv("CGDB_TS_BACKEND", "age")
+        monkeypatch.setenv("CGDB_TS_CINFO", "postgresql://localhost/techstack")
+        monkeypatch.setenv("CGDB_TS_GRAPH", "techgraph")
+        s = Settings.with_prefix("CGDB_TS_")
+        assert s.backend == "age"
+        assert s.cinfo == "postgresql://localhost/techstack"
+        assert s.graph == "techgraph"
+
+    def test_ignores_default_env_vars_when_prefixed(self, monkeypatch):
+        # Default vars set, but with_prefix should ignore them.
+        monkeypatch.setenv("CGDB_BACKEND", "default-backend")
+        monkeypatch.setenv("CGDB_GRAPH", "default-graph")
+        # Only the prefixed graph is set.
+        monkeypatch.setenv("CGDB_CG_GRAPH", "codegraph")
+        s = Settings.with_prefix("CGDB_CG_")
+        assert s.backend is None  # CGDB_CG_BACKEND not set
+        assert s.graph == "codegraph"
+
+    def test_two_instances_isolated(self, monkeypatch):
+        monkeypatch.setenv("CGDB_TS_BACKEND", "age")
+        monkeypatch.setenv("CGDB_TS_GRAPH", "techgraph")
+        monkeypatch.setenv("CGDB_CG_BACKEND", "memgraph")
+        monkeypatch.setenv("CGDB_CG_GRAPH", "codegraph")
+        ts = Settings.with_prefix("CGDB_TS_")
+        cg = Settings.with_prefix("CGDB_CG_")
+        assert ts.backend == "age"
+        assert ts.graph == "techgraph"
+        assert cg.backend == "memgraph"
+        assert cg.graph == "codegraph"
+
+    def test_with_default_prefix_matches_settings(self, monkeypatch):
+        monkeypatch.setenv("CGDB_BACKEND", "age")
+        monkeypatch.setenv("CGDB_GRAPH", "g")
+        plain = Settings()
+        prefixed = Settings.with_prefix(DEFAULT_ENV_PREFIX)
+        assert plain.backend == prefixed.backend
+        assert plain.graph == prefixed.graph
+
+    def test_case_insensitive_env_lookup(self, monkeypatch):
+        # Lowercase env var should still match (case_sensitive=False).
+        monkeypatch.setenv("cgdb_ts_backend", "age")
+        s = Settings.with_prefix("CGDB_TS_")
+        assert s.backend == "age"
+
+    def test_bool_coercion(self, monkeypatch):
+        monkeypatch.setenv("CGDB_TS_READ_ONLY", "true")
+        monkeypatch.setenv("CGDB_TS_CREATE_GRAPH_IF_NOT_EXISTS", "1")
+        s = Settings.with_prefix("CGDB_TS_")
+        assert s.read_only is True
+        assert s.create_graph is True
+
+    def test_int_coercion(self, monkeypatch):
+        monkeypatch.setenv("CGDB_TS_QUERY_TIMEOUT_S", "120")
+        s = Settings.with_prefix("CGDB_TS_")
+        assert s.query_timeout_s == 120
+
+    def test_defaults_when_prefixed_env_not_set(self):
+        s = Settings.with_prefix("CGDB_UNSET_")
+        assert s.backend is None
+        assert s.cinfo is None
+        assert s.graph is None
+        assert s.read_only is False
+        assert s.create_graph is False
+        assert s.query_timeout_s == 30
+
+    def test_empty_prefix_reads_all_unprefixed(self, monkeypatch):
+        # Empty prefix means read BACKEND/CINFO/GRAPH directly.
+        monkeypatch.setenv("BACKEND", "age")
+        monkeypatch.setenv("GRAPH", "g")
+        s = Settings.with_prefix("")
+        assert s.backend == "age"
+        assert s.graph == "g"
+
+
+class TestPrefixSanitization:
+    """cinfo sanitization works regardless of prefix source."""
+
+    def test_sanitized_cinfo_with_prefix(self, monkeypatch):
+        monkeypatch.setenv("CGDB_TS_CINFO", "postgresql://user:secret@host/db")
+        s = Settings.with_prefix("CGDB_TS_")
+        # Sanitized variant must redact the secret.
+        assert s.cinfo == "postgresql://user:secret@host/db"
+        sanitized = s.cinfo_sanitized
+        assert sanitized is not None
+        assert "secret" not in sanitized