syrtis-python-storage 1.0.1__tar.gz → 2.0.0__tar.gz

syrtis_python_storage-1.0.1/README.md → syrtis_python_storage-2.0.0/PKG-INFO

@@ -1,15 +1,47 @@
+Metadata-Version: 2.1
+Name: syrtis-python-storage
+Version: 2.0.0
+Author-Email: weeger <contact@syrtis.ai>
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Requires-Dist: wexample-config
+Requires-Dist: wexample-helpers>=20.8.0
+Requires-Dist: wexample-remote>=1.2.0
+Provides-Extra: mongo
+Requires-Dist: pymongo>=4.6; extra == "mongo"
+Provides-Extra: neo4j
+Requires-Dist: neo4j>=5; extra == "neo4j"
+Provides-Extra: postgres
+Requires-Dist: psycopg2-binary; extra == "postgres"
+Requires-Dist: sqlalchemy>=2; extra == "postgres"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: wexample-wallet; extra == "dev"
+Description-Content-Type: text/markdown
+
 # python_storage
 
-Version: 1.0.1
+Version: 2.0.0
 
 ## Table of Contents
 
+- [Introduction](#introduction)
 - [Install](#install)
 - [Tests](#tests)
 - [Roadmap](#roadmap)
 - [Status Compatibility](#status-compatibility)
 - [Useful Links](#useful-links)
 
+`syrtis-python-storage` gives an application the places it keeps contents in, behind one interface per kind of content: files written and read back by key, vectors searched by similarity, graphs queried in their own language, documents kept in collections and found by their fields. Each storage has a name and the capabilities it accepts (`files`, `vectors`, `graph`), and a registry picks the storage for a capability — so the code needing a place to write never chooses the backend itself.
+
+Every storage is a `wexample-remote` remote, so it can be checked like any other service. Backends: a local directory, PostgreSQL with pgvector (the `postgres` extra), Neo4j (the `neo4j` extra), MongoDB (the `mongo` extra).
+
+Its PHP twin is `syrtis/php-storage`: the same contracts on the same tables and collections, so that what one language wrote the other reads.
+
 ## Installation
 
 ```bash

syrtis_python_storage-1.0.1/PKG-INFO → syrtis_python_storage-2.0.0/README.md

@@ -1,29 +1,22 @@
-Metadata-Version: 2.1
-Name: syrtis-python-storage
-Version: 1.0.1
-Author-Email: weeger <contact@syrtis.ai>
-License: MIT
-Classifier: Programming Language :: Python :: 3
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Operating System :: OS Independent
-Requires-Python: >=3.10
-Provides-Extra: dev
-Requires-Dist: pytest; extra == "dev"
-Requires-Dist: pytest-cov; extra == "dev"
-Description-Content-Type: text/markdown
-
 # python_storage
 
-Version: 1.0.1
+Version: 2.0.0
 
 ## Table of Contents
 
+- [Introduction](#introduction)
 - [Install](#install)
 - [Tests](#tests)
 - [Roadmap](#roadmap)
 - [Status Compatibility](#status-compatibility)
 - [Useful Links](#useful-links)
 
+`syrtis-python-storage` gives an application the places it keeps contents in, behind one interface per kind of content: files written and read back by key, vectors searched by similarity, graphs queried in their own language, documents kept in collections and found by their fields. Each storage has a name and the capabilities it accepts (`files`, `vectors`, `graph`), and a registry picks the storage for a capability — so the code needing a place to write never chooses the backend itself.
+
+Every storage is a `wexample-remote` remote, so it can be checked like any other service. Backends: a local directory, PostgreSQL with pgvector (the `postgres` extra), Neo4j (the `neo4j` extra), MongoDB (the `mongo` extra).
+
+Its PHP twin is `syrtis/php-storage`: the same contracts on the same tables and collections, so that what one language wrote the other reads.
+
 ## Installation
 
 ```bash

{syrtis_python_storage-1.0.1 → syrtis_python_storage-2.0.0}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "pdm.backend"
 
 [project]
 name = "syrtis-python-storage"
-version = "1.0.1"
+version = "2.0.0"
 authors = [
     { name = "weeger", email = "contact@syrtis.ai" },
 ]
@@ -16,7 +16,11 @@ classifiers = [
     "License :: OSI Approved :: MIT License",
     "Operating System :: OS Independent",
 ]
-dependencies = []
+dependencies = [
+    "wexample-config",
+    "wexample-helpers>=20.8.0",
+    "wexample-remote>=1.2.0",
+]
 
 [project.readme]
 file = "README.md"
@@ -26,9 +30,20 @@ content-type = "text/markdown"
 text = "MIT"
 
 [project.optional-dependencies]
+mongo = [
+    "pymongo>=4.6",
+]
+neo4j = [
+    "neo4j>=5",
+]
+postgres = [
+    "psycopg2-binary",
+    "sqlalchemy>=2",
+]
 dev = [
     "pytest",
     "pytest-cov",
+    "wexample-wallet",
 ]
 
 [tool.setuptools.packages.find]

syrtis_python_storage-2.0.0/src/syrtis_python_storage/__init__.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+from syrtis_python_storage.common.abstract_document_storage import AbstractDocumentStorage
+from syrtis_python_storage.common.abstract_file_storage import AbstractFileStorage
+from syrtis_python_storage.common.abstract_graph_storage import AbstractGraphStorage
+from syrtis_python_storage.common.abstract_storage import AbstractStorage
+from syrtis_python_storage.common.abstract_vector_storage import AbstractVectorStorage
+from syrtis_python_storage.common.filesystem_storage import FilesystemStorage
+from syrtis_python_storage.common.mongo_document_storage import MongoDocumentStorage
+from syrtis_python_storage.common.neo4j_graph_storage import Neo4jGraphStorage
+from syrtis_python_storage.common.mongo_file_storage import MongoFileStorage
+from syrtis_python_storage.common.postgres_document_storage import PostgresDocumentStorage
+from syrtis_python_storage.common.postgres_file_storage import PostgresFileStorage
+from syrtis_python_storage.common.postgres_vector_storage import PostgresVectorStorage
+from syrtis_python_storage.common.storage_registry import StorageRegistry
+from syrtis_python_storage.common.vector_match import VectorMatch
+
+__all__ = [
+    "AbstractDocumentStorage",
+    "AbstractFileStorage",
+    "AbstractGraphStorage",
+    "AbstractStorage",
+    "AbstractVectorStorage",
+    "FilesystemStorage",
+    "MongoDocumentStorage",
+    "Neo4jGraphStorage",
+    "MongoFileStorage",
+    "PostgresDocumentStorage",
+    "PostgresFileStorage",
+    "PostgresVectorStorage",
+    "StorageRegistry",
+    "VectorMatch",
+]

syrtis_python_storage-2.0.0/src/syrtis_python_storage/common/abstract_document_storage.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+from typing import Any
+
+from wexample_helpers.classes.abstract_method import abstract_method
+from wexample_helpers.decorator.base_class import base_class
+
+from syrtis_python_storage.common.abstract_storage import AbstractStorage
+
+
+@base_class
+class AbstractDocumentStorage(AbstractStorage):
+    """Documents — dicts — kept by key in named collections, and found by
+    the values of their fields."""
+
+    @classmethod
+    def get_default_capabilities(cls) -> list[str]:
+        from syrtis_python_storage.const.capability import STORAGE_CAPABILITY_DOCUMENTS
+
+        return [STORAGE_CAPABILITY_DOCUMENTS]
+
+    @abstract_method
+    def delete_document(self, collection: str, key: str) -> None:
+        """Removes the document of the key; nothing when there is none."""
+
+    @abstract_method
+    def find_documents(self, collection: str, filters: dict[str, Any] | None = None) -> list[dict[str, Any]]:
+        """The documents whose fields hold the values given; all without filters."""
+
+    @abstract_method
+    def get_document(self, collection: str, key: str) -> dict[str, Any] | None:
+        """The document of the key, None when there is none."""
+
+    @abstract_method
+    def save_document(self, collection: str, key: str, document: dict[str, Any]) -> None:
+        """Writes the document under the key, replacing the one there."""

syrtis_python_storage-2.0.0/src/syrtis_python_storage/common/abstract_file_storage.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+from wexample_helpers.classes.abstract_method import abstract_method
+from wexample_helpers.decorator.base_class import base_class
+
+from syrtis_python_storage.common.abstract_storage import AbstractStorage
+
+
+@base_class
+class AbstractFileStorage(AbstractStorage):
+    """Contents written and read back by key."""
+
+    @classmethod
+    def get_default_capabilities(cls) -> list[str]:
+        from syrtis_python_storage.const.capability import STORAGE_CAPABILITY_FILES
+
+        return [STORAGE_CAPABILITY_FILES]
+
+    @abstract_method
+    def delete(self, key: str) -> None:
+        pass
+
+    @abstract_method
+    def exists(self, key: str) -> bool:
+        pass
+
+    @abstract_method
+    def read(self, key: str) -> bytes:
+        pass
+
+    def read_text(self, key: str, encoding: str = "utf-8") -> str:
+        return self.read(key).decode(encoding)
+
+    @abstract_method
+    def write(self, key: str, content: bytes | str) -> None:
+        pass

syrtis_python_storage-2.0.0/src/syrtis_python_storage/common/abstract_graph_storage.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from typing import Any
+
+from wexample_helpers.classes.abstract_method import abstract_method
+from wexample_helpers.decorator.base_class import base_class
+
+from syrtis_python_storage.common.abstract_storage import AbstractStorage
+
+
+@base_class
+class AbstractGraphStorage(AbstractStorage):
+    """Nodes and relationships, queried in the backend's own language."""
+
+    @classmethod
+    def get_default_capabilities(cls) -> list[str]:
+        from syrtis_python_storage.const.capability import STORAGE_CAPABILITY_GRAPH
+
+        return [STORAGE_CAPABILITY_GRAPH]
+
+    @abstract_method
+    def run_query(self, query: str, parameters: dict[str, Any] | None = None) -> list[dict[str, Any]]:
+        """The records the query returns, as dicts; none for a pure write."""

syrtis_python_storage-2.0.0/src/syrtis_python_storage/common/abstract_storage.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+from wexample_helpers.classes.base_class import BaseClass
+from wexample_helpers.classes.field import public_field
+from wexample_helpers.decorator.base_class import base_class
+from wexample_remote.common.abstract_remote import AbstractRemote
+
+
+@base_class
+class AbstractStorage(AbstractRemote, BaseClass):
+    """A place contents are kept in — a directory, a bucket, a database —
+    whatever the backend. As a remote, it can be checked."""
+
+    capabilities: list[str] = public_field(
+        description="Kinds of content the storage accepts (e.g. `files`, `vectors`); "
+        "empty takes those of its class.",
+        factory=list,
+    )
+    label: str | None = public_field(default=None, description="Human-readable name.")
+    name: str = public_field(description="Name the storage is registered and chosen by.")
+
+    @classmethod
+    def get_default_capabilities(cls) -> list[str]:
+        return []
+
+    def accepts(self, capability: str) -> bool:
+        return capability in self.get_capabilities()
+
+    def get_capabilities(self) -> list[str]:
+        return self.capabilities or self.get_default_capabilities()
+
+    def get_key(self) -> str:
+        return self.name
+
+    def get_label(self) -> str:
+        return self.label or self.name

syrtis_python_storage-2.0.0/src/syrtis_python_storage/common/abstract_vector_storage.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from wexample_helpers.classes.abstract_method import abstract_method
+from wexample_helpers.decorator.base_class import base_class
+
+from syrtis_python_storage.common.abstract_storage import AbstractStorage
+
+if TYPE_CHECKING:
+    from syrtis_python_storage.common.vector_match import VectorMatch
+
+
+@base_class
+class AbstractVectorStorage(AbstractStorage):
+    """Vectors grouped in namespaces (e.g. one per document), each with a key
+    and the text it was made from, searched by cosine distance."""
+
+    @classmethod
+    def get_default_capabilities(cls) -> list[str]:
+        from syrtis_python_storage.const.capability import STORAGE_CAPABILITY_VECTORS
+
+        return [STORAGE_CAPABILITY_VECTORS]
+
+    @abstract_method
+    def delete_vector(self, namespace: str, key: str) -> None:
+        """Removes the vector of the key; nothing when there is none."""
+
+    @abstract_method
+    def delete_vectors(self, namespace: str) -> None:
+        pass
+
+    @abstract_method
+    def get_vector_keys(self, namespace: str) -> set[str]:
+        pass
+
+    @abstract_method
+    def save_vector(self, namespace: str, key: str, vector: list[float], content: str | None) -> None:
+        """Add the vector, or replace the one of the same key."""
+
+    @abstract_method
+    def search_vectors(
+        self,
+        namespace: str,
+        vector: list[float],
+        limit: int | None = None,
+        max_distance: float | None = None,
+    ) -> list[VectorMatch]:
+        """The closest vectors first."""

syrtis_python_storage-2.0.0/src/syrtis_python_storage/common/filesystem_storage.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from wexample_helpers.classes.field import public_field
+from wexample_helpers.decorator.base_class import base_class
+
+from syrtis_python_storage.common.abstract_file_storage import AbstractFileStorage
+
+if TYPE_CHECKING:
+    from wexample_remote.common.remote_status import RemoteStatus
+
+
+@base_class
+class FilesystemStorage(AbstractFileStorage):
+    """Contents as files of a directory, one per key; the directory is created
+    on first write."""
+
+    path: Path = public_field(description="Directory holding the files.")
+
+    def check_status(self) -> RemoteStatus:
+        from wexample_remote.common.remote_status import RemoteStatus
+
+        directory = Path(self.path)
+        # The closest existing parent is the one a first write would create in.
+        existing = next(parent for parent in (directory, *directory.parents) if parent.exists())
+        if not existing.is_dir() or not os.access(existing, os.W_OK):
+            return RemoteStatus.down(f"Not a writable directory: {existing}")
+        return RemoteStatus.up()
+
+    def delete(self, key: str) -> None:
+        self.get_file_path(key).unlink(missing_ok=True)
+
+    def exists(self, key: str) -> bool:
+        return self.get_file_path(key).is_file()
+
+    def get_file_path(self, key: str) -> Path:
+        """The file of a key, which may not leave the directory."""
+        directory = Path(self.path).resolve()
+        file_path = (directory / key).resolve()
+        if not file_path.is_relative_to(directory):
+            from syrtis_python_storage.exception.invalid_storage_key_exception import (
+                InvalidStorageKeyException,
+            )
+
+            raise InvalidStorageKeyException(key=key, storage_name=self.name)
+        return file_path
+
+    def read(self, key: str) -> bytes:
+        return self.get_file_path(key).read_bytes()
+
+    def write(self, key: str, content: bytes | str) -> None:
+        file_path = self.get_file_path(key)
+        file_path.parent.mkdir(parents=True, exist_ok=True)
+        file_path.write_bytes(content.encode() if isinstance(content, str) else content)

syrtis_python_storage-2.0.0/src/syrtis_python_storage/common/mongo_document_storage.py

@@ -0,0 +1,93 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from wexample_helpers.classes.field import public_field
+from wexample_helpers.classes.private_field import private_field
+from wexample_helpers.decorator.base_class import base_class
+
+from syrtis_python_storage.common.abstract_document_storage import AbstractDocumentStorage
+
+if TYPE_CHECKING:
+    from wexample_remote.common.remote_status import RemoteStatus
+
+# The field a document's key is kept in.
+MONGO_DOCUMENT_STORAGE_KEY_FIELD: str = "_id"
+
+
+@base_class
+class MongoDocumentStorage(AbstractDocumentStorage):
+    """A MongoDB database, a collection per kind of document, the key as
+    `_id`. Needs the `mongo` extra. The server is reached at the host given:
+    a replica set announcing names its members alone resolve is not followed
+    (`directConnection`)."""
+
+    database: str = public_field(description="Database name.")
+    host: str = public_field(description="Server host.")
+    password: str | None = public_field(default=None, description="Password.")
+    port: int = public_field(default=27017, description="Server port.")
+    timeout: int = public_field(default=10, description="Seconds a server is given to answer.")
+    user: str | None = public_field(default=None, description="User name; none for a server without authentication.")
+    _client: Any = private_field(default=None, description="MongoDB client, created on first use.")
+
+    def __repr__(self) -> str:
+        # The password must never reach a log or a traceback.
+        return f"MongoDocumentStorage(name={self.name!r}, host={self.host!r}, database={self.database!r})"
+
+    @classmethod
+    def from_credential(cls, credential: Any, **kwargs: Any) -> MongoDocumentStorage:
+        """From a `wexample-wallet` credential of type `mongo` (host, port,
+        database, user, password), named after it unless `name` is given."""
+        return cls(
+            database=credential.get("database"),
+            host=credential.get("host"),
+            name=kwargs.pop("name", credential.name),
+            password=credential.get("password", default=None),
+            port=int(credential.get("port", default=27017)),
+            user=credential.get("user", default=None),
+            **kwargs,
+        )
+
+    def check_status(self) -> RemoteStatus:
+        from wexample_remote.common.remote_status import RemoteStatus
+
+        self._get_database().command("ping")
+        return RemoteStatus.up(f"MongoDB {self._get_client().server_info()['version']}")
+
+    def delete_document(self, collection: str, key: str) -> None:
+        self._get_database()[collection].delete_one({MONGO_DOCUMENT_STORAGE_KEY_FIELD: key})
+
+    def find_documents(self, collection: str, filters: dict[str, Any] | None = None) -> list[dict[str, Any]]:
+        return [self._to_plain(document) for document in self._get_database()[collection].find(filters or {})]
+
+    def get_document(self, collection: str, key: str) -> dict[str, Any] | None:
+        document = self._get_database()[collection].find_one({MONGO_DOCUMENT_STORAGE_KEY_FIELD: key})
+        return self._to_plain(document) if document is not None else None
+
+    def save_document(self, collection: str, key: str, document: dict[str, Any]) -> None:
+        self._get_database()[collection].replace_one(
+            {MONGO_DOCUMENT_STORAGE_KEY_FIELD: key},
+            {**document, MONGO_DOCUMENT_STORAGE_KEY_FIELD: key},
+            upsert=True,
+        )
+
+    def _get_client(self) -> Any:
+        if self._client is None:
+            from pymongo import MongoClient
+
+            self._client = MongoClient(
+                host=self.host,
+                port=self.port,
+                username=self.user,
+                password=self.password,
+                directConnection=True,
+                serverSelectionTimeoutMS=self.timeout * 1000,
+            )
+        return self._client
+
+    def _get_database(self) -> Any:
+        return self._get_client()[self.database]
+
+    def _to_plain(self, document: dict[str, Any]) -> dict[str, Any]:
+        """The document without its key field, given back as the caller wrote it."""
+        return {field: value for field, value in document.items() if field != MONGO_DOCUMENT_STORAGE_KEY_FIELD}

syrtis_python_storage-2.0.0/src/syrtis_python_storage/common/mongo_file_storage.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from wexample_helpers.classes.field import public_field
+from wexample_helpers.classes.private_field import private_field
+from wexample_helpers.decorator.base_class import base_class
+
+from syrtis_python_storage.common.abstract_file_storage import AbstractFileStorage
+
+if TYPE_CHECKING:
+    from wexample_remote.common.remote_status import RemoteStatus
+
+    from syrtis_python_storage.common.mongo_document_storage import MongoDocumentStorage
+
+MONGO_FILE_STORAGE_COLLECTION_DEFAULT: str = "syrtis_storage_file"
+
+
+@base_class
+class MongoFileStorage(AbstractFileStorage):
+    """Contents written and read back by key in a MongoDB collection — the
+    key as `_id`, the content as binary —, over the same connection as
+    `MongoDocumentStorage`. A content is one document: up to MongoDB's
+    16 MB. Needs the `mongo` extra."""
+
+    collection: str = public_field(default=MONGO_FILE_STORAGE_COLLECTION_DEFAULT, description="Collection holding the contents.")
+    database: str = public_field(description="Database name.")
+    host: str = public_field(description="Server host.")
+    password: str | None = public_field(default=None, description="Password.")
+    port: int = public_field(default=27017, description="Server port.")
+    timeout: int = public_field(default=10, description="Seconds a server is given to answer.")
+    user: str | None = public_field(default=None, description="User name; none for a server without authentication.")
+    _documents: Any = private_field(default=None, description="The document storage whose connection it uses, opened on first use.")
+
+    def __repr__(self) -> str:
+        # The password must never reach a log or a traceback.
+        return f"MongoFileStorage(name={self.name!r}, host={self.host!r}, database={self.database!r})"
+
+    @classmethod
+    def from_credential(cls, credential: Any, **kwargs: Any) -> MongoFileStorage:
+        """From a `wexample-wallet` credential of type `mongo` (host, port,
+        database, user, password), named after it unless `name` is given."""
+        return cls(
+            database=credential.get("database"),
+            host=credential.get("host"),
+            name=kwargs.pop("name", credential.name),
+            password=credential.get("password", default=None),
+            port=int(credential.get("port", default=27017)),
+            user=credential.get("user", default=None),
+            **kwargs,
+        )
+
+    def check_status(self) -> RemoteStatus:
+        return self._get_documents().check_status()
+
+    def delete(self, key: str) -> None:
+        self._get_collection().delete_one({"_id": key})
+
+    def exists(self, key: str) -> bool:
+        return self._get_collection().count_documents({"_id": key}, limit=1) > 0
+
+    def read(self, key: str) -> bytes:
+        document = self._get_collection().find_one({"_id": key})
+        if document is None:
+            raise FileNotFoundError(key)
+
+        return bytes(document["content"])
+
+    def write(self, key: str, content: bytes | str) -> None:
+        from bson.binary import Binary
+
+        self._get_collection().replace_one(
+            {"_id": key},
+            {"_id": key, "content": Binary(content.encode() if isinstance(content, str) else content)},
+            upsert=True,
+        )
+
+    def _get_collection(self) -> Any:
+        return self._get_documents()._get_database()[self.collection]
+
+    def _get_documents(self) -> MongoDocumentStorage:
+        """The connection, as the document storage opens it."""
+        if self._documents is None:
+            from syrtis_python_storage.common.mongo_document_storage import MongoDocumentStorage
+
+            self._documents = MongoDocumentStorage(
+                name=self.name,
+                database=self.database,
+                host=self.host,
+                password=self.password,
+                port=self.port,
+                timeout=self.timeout,
+                user=self.user,
+            )
+
+        return self._documents

syrtis_python_storage-2.0.0/src/syrtis_python_storage/common/neo4j_graph_storage.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from wexample_helpers.classes.field import public_field
+from wexample_helpers.classes.private_field import private_field
+from wexample_helpers.decorator.base_class import base_class
+
+from syrtis_python_storage.common.abstract_graph_storage import AbstractGraphStorage
+
+if TYPE_CHECKING:
+    from wexample_remote.common.remote_status import RemoteStatus
+
+
+@base_class
+class Neo4jGraphStorage(AbstractGraphStorage):
+    """A Neo4j database, queried in Cypher. Needs the `neo4j` extra."""
+
+    database: str | None = public_field(default=None, description="Database; the server's default when None.")
+    password: str = public_field(description="Password.")
+    url: str = public_field(description="Bolt url, e.g. `bolt://localhost:7687`.")
+    user: str = public_field(description="User name.")
+    _driver: Any = private_field(default=None, description="Neo4j driver, created on first use.")
+
+    def __repr__(self) -> str:
+        # The password must never reach a log or a traceback.
+        return f"Neo4jGraphStorage(name={self.name!r}, url={self.url!r})"
+
+    @classmethod
+    def from_credential(cls, credential: Any, **kwargs: Any) -> Neo4jGraphStorage:
+        """From a `wexample-wallet` credential of type `neo4j` (url, user,
+        password), named after it unless `name` is given."""
+        return cls(
+            name=kwargs.pop("name", credential.name),
+            password=credential.get("password"),
+            url=credential.get("url"),
+            user=credential.get("user"),
+            **kwargs,
+        )
+
+    def check_status(self) -> RemoteStatus:
+        from wexample_remote.common.remote_status import RemoteStatus
+
+        self._get_driver().verify_connectivity()
+        return RemoteStatus.up()
+
+    def run_query(self, query: str, parameters: dict[str, Any] | None = None) -> list[dict[str, Any]]:
+        records, _summary, _keys = self._get_driver().execute_query(
+            query, parameters or {}, database_=self.database
+        )
+        return [self._to_plain(record.data()) for record in records]
+
+    def _get_driver(self) -> Any:
+        if self._driver is None:
+            from neo4j import GraphDatabase
+
+            self._driver = GraphDatabase.driver(self.url, auth=(self.user, self.password))
+        return self._driver
+
+    def _to_plain(self, value: Any) -> Any:
+        # Dates and spatial values become text, so that records serialize.
+        if isinstance(value, dict):
+            return {key: self._to_plain(item) for key, item in value.items()}
+        if isinstance(value, list):
+            return [self._to_plain(item) for item in value]
+        if value is None or isinstance(value, (bool, int, float, str)):
+            return value
+        return str(value)