fromscratch-pygraphdb 0.4.0__py3-none-any.whl

pygraphdb/node.py

@@ -0,0 +1,149 @@
+"""Node -- a single entity in a graph database.
+
+Imagine a party where every guest wears a name tag. Each person (node)
+has a unique ID (like their phone number), a label (like "Student" or
+"Teacher"), and properties (like their name, age, or favorite color).
+
+A node is the building block of a graph. By itself it's just a dot on
+a whiteboard -- but connect it to other nodes with edges, and suddenly
+you have a map of relationships!
+
+Example:
+    >>> from pygraphdb.node import Node
+    >>> alice = Node(node_id="1", label="Person", properties={"name": "Alice", "age": 13})
+    >>> alice.label
+    'Person'
+    >>> alice.properties["name"]
+    'Alice'
+
+"""
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class Node:
+    """A single entity in the graph with an ID, label, and properties.
+
+    Think of a node like a person at a party:
+    - ``node_id`` is their unique wristband number (no two people share one,
+      and it can't be changed once it's on)
+    - ``label`` is the group they belong to ("Student", "Teacher", "Parent")
+    - ``properties`` is everything about them (name, age, hobbies)
+
+    Args:
+        node_id: A unique identifier for this node.
+        label: A category or type label (e.g. "Person", "City").
+        properties: A dictionary of key-value attributes.
+
+    """
+
+    node_id: str
+    label: str = ""
+    properties: dict[str, object] = field(default_factory=lambda: {})
+
+    def __setattr__(self, name: str, value: object) -> None:
+        """Set an attribute, except ``node_id`` once it has been set.
+
+        The graph files every node under its id. Changing the id afterwards
+        would leave the node filed under the old one, like swapping your
+        wristband after the guest list was written -- so it isn't allowed.
+
+        Raises:
+            AttributeError: If ``node_id`` is set a second time.
+
+        """
+        if name == "node_id" and "node_id" in self.__dict__:
+            msg = "a node's node_id can't be changed: it files the node in the graph"
+            raise AttributeError(msg)
+        super().__setattr__(name, value)
+
+    def has_property(self, key: str) -> bool:
+        """Check whether this node has a given property key.
+
+        Args:
+            key: The property name to look for.
+
+        Returns:
+            True if the property exists, False otherwise.
+
+        """
+        return key in self.properties
+
+    def get_property(self, key: str, default: object = None) -> object:
+        """Get a property value by key, with an optional default.
+
+        Args:
+            key: The property name to retrieve.
+            default: Value to return if the key is missing.
+
+        Returns:
+            The property value, or the default.
+
+        """
+        return self.properties.get(key, default)
+
+    def set_property(self, key: str, value: object) -> None:
+        """Set a property on this node.
+
+        Args:
+            key: The property name.
+            value: The property value.
+
+        """
+        self.properties[key] = value
+
+    def remove_property(self, key: str) -> object:
+        """Remove and return a property from this node.
+
+        Args:
+            key: The property name to remove.
+
+        Returns:
+            The removed value.
+
+        Raises:
+            KeyError: If the property does not exist.
+
+        """
+        return self.properties.pop(key)
+
+    def to_dict(self) -> dict[str, object]:
+        """Write everything about this node onto an index card.
+
+        Like copying a party guest's wristband number, group, and details
+        onto a card you can file away -- turns the node into a plain
+        dictionary you can save to a file.
+
+        Returns:
+            A dictionary representation of this node.
+
+        """
+        return {
+            "node_id": self.node_id,
+            "label": self.label,
+            "properties": dict(self.properties),
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, object]) -> Node:
+        """Rebuild a node from the index card that to_dict wrote.
+
+        Like reading a filed-away card and bringing that party guest back --
+        turns a plain dictionary back into a real Node.
+
+        Args:
+            data: A dictionary with node_id, label, and properties keys.
+
+        Returns:
+            A new Node instance.
+
+        """
+        node_id = str(data.get("node_id", ""))
+        label = str(data.get("label", ""))
+        raw_props = data.get("properties")
+        props: dict[str, object] = {}
+        if isinstance(raw_props, dict):
+            for k, v in raw_props.items():  # pyright: ignore[reportUnknownVariableType]
+                props[str(k)] = v  # pyright: ignore[reportUnknownArgumentType]
+        return cls(node_id=node_id, label=label, properties=props)

pygraphdb/pathfinding.py

@@ -0,0 +1,147 @@
+"""Shortest path finding -- like GPS directions for your graph.
+
+When you ask Google Maps for directions, it finds the route with the
+fewest turns (or shortest distance). Our pathfinding does the same
+thing for graphs -- it finds the path with the fewest edges between
+two nodes.
+
+We use BFS (breadth-first search) because it naturally finds the
+shortest path in an unweighted graph. It explores nodes layer by
+layer, so the first time it reaches the destination, that path is
+guaranteed to be the shortest!
+
+Example:
+    >>> from pygraphdb.graph import Graph
+    >>> from pygraphdb.pathfinding import shortest_path
+    >>> g = Graph()
+    >>> for nid in ["a", "b", "c", "d"]:
+    ...     g.add_node(nid)
+    >>> g.add_edge("e1", "a", "b")
+    >>> g.add_edge("e2", "b", "c")
+    >>> g.add_edge("e3", "a", "d")
+    >>> g.add_edge("e4", "d", "c")
+    >>> path = shortest_path(g, "a", "c")
+    >>> [n.node_id for n in path]
+    ['a', 'b', 'c']
+
+"""
+
+from collections import deque
+
+from pygraphdb.graph import Graph
+from pygraphdb.node import Node
+
+
+def shortest_path(graph: Graph, start_id: str, end_id: str) -> list[Node]:
+    """Find the shortest path between two nodes using BFS.
+
+    Like asking for GPS directions: find the route with the fewest
+    stops between your starting point and your destination.
+
+    Args:
+        graph: The graph to search.
+        start_id: The ID of the starting node.
+        end_id: The ID of the destination node.
+
+    Returns:
+        A list of nodes forming the shortest path (including start and end).
+        An empty list if no path exists.
+
+    Raises:
+        NodeNotFoundError: If start or end node does not exist.
+
+    """
+    graph.get_node(start_id)  # Validate existence
+    graph.get_node(end_id)  # Validate existence
+
+    if start_id == end_id:
+        return [graph.get_node(start_id)]
+
+    visited: set[str] = {start_id}
+    # Each queue entry is (current_node_id, path_so_far)
+    queue: deque[tuple[str, list[str]]] = deque([(start_id, [start_id])])
+
+    while queue:
+        current_id, path = queue.popleft()
+        for edge in graph.get_outgoing_edges(current_id):
+            neighbor_id = edge.target_id
+            if neighbor_id == end_id:
+                full_path = [*path, neighbor_id]
+                return [graph.get_node(nid) for nid in full_path]
+            if neighbor_id not in visited:
+                visited.add(neighbor_id)
+                queue.append((neighbor_id, [*path, neighbor_id]))
+
+    return []
+
+
+def all_paths(
+    graph: Graph,
+    start_id: str,
+    end_id: str,
+    *,
+    max_depth: int = 10,
+) -> list[list[Node]]:
+    """Find all paths between two nodes up to a maximum depth.
+
+    Like finding every possible route between your house and school,
+    not just the shortest one.
+
+    Args:
+        graph: The graph to search.
+        start_id: The ID of the starting node.
+        end_id: The ID of the destination node.
+        max_depth: Maximum path length to consider.
+
+    Returns:
+        A list of paths, where each path is a list of nodes.
+
+    Raises:
+        NodeNotFoundError: If start or end node does not exist.
+
+    """
+    graph.get_node(start_id)  # Validate existence
+    graph.get_node(end_id)  # Validate existence
+
+    results: list[list[str]] = []
+    _all_paths_helper(graph, start_id, end_id, [start_id], set(), results, max_depth)
+    return [[graph.get_node(nid) for nid in path] for path in results]
+
+
+def _all_paths_helper(
+    graph: Graph,
+    current_id: str,
+    end_id: str,
+    current_path: list[str],
+    visited: set[str],
+    results: list[list[str]],
+    max_depth: int,
+) -> None:
+    """Recursive helper for finding all paths.
+
+    Args:
+        graph: The graph to search.
+        current_id: Current position in the traversal.
+        end_id: The destination node ID.
+        current_path: Path taken so far.
+        visited: Set of visited node IDs.
+        results: Accumulator for found paths.
+        max_depth: Maximum remaining depth.
+
+    """
+    if current_id == end_id:
+        results.append(list(current_path))
+        return
+
+    if max_depth <= 0:
+        return
+
+    visited.add(current_id)
+    for edge in graph.get_outgoing_edges(current_id):
+        if edge.target_id not in visited:
+            current_path.append(edge.target_id)
+            _all_paths_helper(
+                graph, edge.target_id, end_id, current_path, visited, results, max_depth - 1
+            )
+            current_path.pop()
+    visited.discard(current_id)

pygraphdb/persistence.py

@@ -0,0 +1,129 @@
+"""Persistence -- save and load graphs to/from JSON files.
+
+Think of persistence like saving a video game. When you're done
+playing, you save your progress to a file. Next time you start
+the game, you load that file and pick up exactly where you left off.
+
+Our graph database works the same way: you can save your entire
+graph (all nodes and edges) to a JSON file, and later load it
+back into memory to continue working with it.
+
+JSON is a text format that both humans and computers can read --
+it looks like a nicely organized list with curly braces and colons.
+
+Example:
+    >>> from pygraphdb.graph import Graph
+    >>> from pygraphdb.persistence import save_graph, load_graph
+    >>> g = Graph()
+    >>> g.add_node("alice", label="Person")
+    >>> save_graph(g, "/tmp/my_graph.json")
+    >>> g2 = load_graph("/tmp/my_graph.json")
+    >>> g2.get_node("alice").label
+    'Person'
+
+"""
+
+import json
+from pathlib import Path
+from typing import cast
+
+from pygraphdb.atomic import atomic_write_text
+from pygraphdb.errors import GraphError, PersistenceError
+from pygraphdb.graph import Graph
+
+# Every real save file has these top-level keys; anything else isn't one of ours.
+_REQUIRED_KEYS = frozenset({"nodes", "edges"})
+
+
+def save_graph(graph: Graph, file_path: str | Path) -> None:
+    """Save a graph to a JSON file.
+
+    Like saving your game progress -- writes all nodes and edges
+    to a file so you can load them later.
+
+    Args:
+        graph: The graph to save.
+        file_path: The path to write the JSON file to.
+
+    """
+    path = Path(file_path)
+    data = graph.to_dict()
+    atomic_write_text(path, json.dumps(data, indent=2, default=str))
+
+
+def load_graph(file_path: str | Path) -> Graph:
+    """Load a graph from a JSON file.
+
+    Like loading a saved game -- reads nodes and edges from a file
+    and rebuilds the graph in memory.
+
+    Args:
+        file_path: The path to read the JSON file from.
+
+    Returns:
+        A new Graph populated with the saved data.
+
+    Raises:
+        PersistenceError: If the file is missing, unreadable, not valid JSON,
+            or not a valid save file.
+
+    """
+    path = Path(file_path)
+    try:
+        raw = path.read_text(encoding="utf-8")
+    # A file that isn't UTF-8 text (an image, a zip, a corrupted save) fails
+    # while decoding, not while reading, so it needs catching too.
+    except (OSError, UnicodeDecodeError) as exc:
+        msg = f"Could not read {path}: {exc}"
+        raise PersistenceError(msg) from exc
+    try:
+        data: object = json.loads(raw)
+    # JSONDecodeError is a kind of ValueError; a plain ValueError also means a
+    # number too long for Python to read, and RecursionError means lists or
+    # objects nested too deep. Each one is a file we can't load.
+    except (ValueError, RecursionError) as exc:
+        msg = f"Invalid JSON in {path}: {exc}"
+        raise PersistenceError(msg) from exc
+    if not isinstance(data, dict):
+        msg = f"{path} is not a valid save file: the top level must be an object"
+        raise PersistenceError(msg)
+    saved: dict[str, object] = {str(k): v for k, v in cast("dict[object, object]", data).items()}
+    missing = _REQUIRED_KEYS - saved.keys()
+    if missing:
+        msg = f"{path} is not a valid save file: missing {sorted(missing)}"
+        raise PersistenceError(msg)
+    try:
+        return Graph.from_dict(saved)
+    # GraphError covers an edge whose end isn't one of the saved nodes, and two
+    # nodes or edges sharing an id: files save_graph never writes, so they're
+    # refused like any other bad file.
+    except (GraphError, KeyError, TypeError, ValueError, AttributeError) as exc:
+        msg = f"{path} is not a valid save file: {exc}"
+        raise PersistenceError(msg) from exc
+
+
+def graph_to_json(graph: Graph) -> str:
+    """Serialize a graph to a JSON string (without writing to disk).
+
+    Args:
+        graph: The graph to serialize.
+
+    Returns:
+        A JSON string representation of the graph.
+
+    """
+    return json.dumps(graph.to_dict(), indent=2, default=str)
+
+
+def graph_from_json(json_string: str) -> Graph:
+    """Deserialize a graph from a JSON string.
+
+    Args:
+        json_string: A JSON string representing a graph.
+
+    Returns:
+        A new Graph populated from the JSON data.
+
+    """
+    data: dict[str, object] = json.loads(json_string)
+    return Graph.from_dict(data)

pygraphdb/query.py

@@ -0,0 +1,241 @@
+"""Simple Cypher-like query language parser and executor.
+
+Real graph databases like Neo4j use a language called Cypher to ask
+questions about the graph. It's like SQL but for graphs! Our version
+is simplified but follows the same idea.
+
+Think of it like asking questions in a specific format:
+- "MATCH" means "find me..."
+- "(n:Person)" means "a node labeled Person, call it n"
+- "-[:KNOWS]->" means "connected by a KNOWS relationship"
+- "WHERE n.name = 'Alice'" means "but only if the name is Alice"
+- "RETURN m" means "give me back the thing called m"
+
+Supported query format:
+    MATCH (n:Label)-[:REL_TYPE]->(m) WHERE n.prop = "value" RETURN m
+    MATCH (n:Label) RETURN n
+    MATCH (n:Label) WHERE n.prop = "value" RETURN n
+
+Example:
+    >>> from pygraphdb.graph import Graph
+    >>> from pygraphdb.query import execute_query
+    >>> g = Graph()
+    >>> g.add_node("1", label="Person", properties={"name": "Alice"})
+    >>> g.add_node("2", label="Person", properties={"name": "Bob"})
+    >>> g.add_edge("e1", "1", "2", rel_type="KNOWS")
+    >>> results = execute_query(g, 'MATCH (n:Person) WHERE n.name = "Alice" RETURN n')
+    >>> len(results)
+    1
+
+"""
+
+import re
+
+from pygraphdb.errors import QuerySyntaxError
+from pygraphdb.graph import Graph
+from pygraphdb.node import Node
+
+# Pattern for: MATCH (var:Label)-[:REL]->(var2) WHERE var.prop = "val" RETURN var2
+_PATTERN_WITH_EDGE = re.compile(
+    r"MATCH\s+\((\w+):(\w+)\)"  # (n:Label)
+    r"\s*-\[:(\w+)\]->\s*"  # -[:REL]->
+    r"\((\w+)\)"  # (m)
+    r"(?:\s+WHERE\s+(.+?))?"  # optional WHERE clause
+    r"\s+RETURN\s+(\w+)",  # RETURN var
+    re.IGNORECASE,
+)
+
+# Pattern for: MATCH (var:Label) WHERE var.prop = "val" RETURN var
+_PATTERN_NODE_ONLY = re.compile(
+    r"MATCH\s+\((\w+):(\w+)\)"  # (n:Label)
+    r"(?:\s+WHERE\s+(.+?))?"  # optional WHERE clause
+    r"\s+RETURN\s+(\w+)",  # RETURN var
+    re.IGNORECASE,
+)
+
+# Pattern for WHERE conditions: var.prop = "value" or var.prop = 'value'
+_WHERE_CONDITION = re.compile(
+    r"(\w+)\.(\w+)\s*=\s*[\"']([^\"']*)[\"']",
+)
+
+
+def execute_query(graph: Graph, query: str) -> list[Node]:
+    """Execute a simple Cypher-like query against the graph.
+
+    Parse and run a query string to find matching nodes.
+
+    Supported patterns:
+        - ``MATCH (n:Label) RETURN n``
+        - ``MATCH (n:Label) WHERE n.prop = "value" RETURN n``
+        - ``MATCH (n:Label)-[:REL]->(m) RETURN m``
+        - ``MATCH (n:Label)-[:REL]->(m) WHERE n.prop = "value" RETURN m``
+
+    Args:
+        graph: The graph to query.
+        query: A Cypher-like query string.
+
+    Returns:
+        A list of nodes matching the query.
+
+    Raises:
+        QuerySyntaxError: If the query cannot be parsed.
+
+    """
+    query = query.strip()
+
+    # Try edge pattern first (more specific)
+    match = _PATTERN_WITH_EDGE.match(query)
+    if match:
+        return _execute_edge_query(graph, match)
+
+    # Try node-only pattern
+    match = _PATTERN_NODE_ONLY.match(query)
+    if match:
+        return _execute_node_query(graph, match)
+
+    msg = f"Cannot parse query: {query}"
+    raise QuerySyntaxError(msg)
+
+
+def _execute_node_query(graph: Graph, match: re.Match[str]) -> list[Node]:
+    """Execute a node-only query (no edge pattern).
+
+    Args:
+        graph: The graph to query.
+        match: The regex match object.
+
+    Returns:
+        A list of matching nodes.
+
+    """
+    var_name = match.group(1)
+    label = match.group(2)
+    where_clause = match.group(3)
+    return_var = match.group(4)
+
+    if return_var != var_name:
+        msg = f"RETURN variable '{return_var}' not defined in MATCH"
+        raise QuerySyntaxError(msg)
+
+    conditions = _parse_conditions(where_clause, {var_name})
+
+    results: list[Node] = []
+    for node in graph.get_all_nodes():
+        if node.label != label:
+            continue
+        if not _node_matches(node, var_name, conditions):
+            continue
+        results.append(node)
+    return results
+
+
+def _execute_edge_query(graph: Graph, match: re.Match[str]) -> list[Node]:
+    """Execute a query with an edge pattern.
+
+    Args:
+        graph: The graph to query.
+        match: The regex match object.
+
+    Returns:
+        A list of matching nodes.
+
+    """
+    source_var = match.group(1)
+    source_label = match.group(2)
+    rel_type = match.group(3)
+    target_var = match.group(4)
+    where_clause = match.group(5)
+    return_var = match.group(6)
+
+    if return_var not in (source_var, target_var):
+        msg = f"RETURN variable '{return_var}' not defined in MATCH"
+        raise QuerySyntaxError(msg)
+
+    # WHERE conditions may reference either the source or the target variable.
+    conditions = _parse_conditions(where_clause, {source_var, target_var})
+
+    results: list[Node] = []
+    seen_ids: set[str] = set()
+
+    for node in graph.get_all_nodes():
+        if node.label != source_label:
+            continue
+        if not _node_matches(node, source_var, conditions):
+            continue
+
+        for edge in graph.get_outgoing_edges(node.node_id):
+            if edge.rel_type != rel_type:
+                continue
+            target = graph.get_node(edge.target_id)
+            if not _node_matches(target, target_var, conditions):
+                continue
+
+            if return_var == source_var:
+                # One matching edge is enough to keep the source node.
+                if node.node_id not in seen_ids:
+                    seen_ids.add(node.node_id)
+                    results.append(node)
+                break
+            if target.node_id not in seen_ids:
+                seen_ids.add(target.node_id)
+                results.append(target)
+
+    return results
+
+
+def _parse_conditions(
+    where_clause: str | None,
+    valid_vars: set[str],
+) -> list[tuple[str, str, str]]:
+    """Turn a raw WHERE clause into a list of (var, prop, value) conditions.
+
+    Args:
+        where_clause: The raw WHERE clause string, or None if there was no WHERE.
+        valid_vars: The variable names the query actually defines.
+
+    Returns:
+        A list of parsed conditions (empty if there was no WHERE clause).
+
+    Raises:
+        QuerySyntaxError: If a WHERE clause is present but nothing parses
+            (for example an unquoted value), or a condition refers to a
+            variable the query never defined.
+
+    """
+    if where_clause is None:
+        return []
+    conditions: list[tuple[str, str, str]] = _WHERE_CONDITION.findall(where_clause)
+    if not conditions:
+        msg = (
+            f"Cannot understand WHERE clause: {where_clause!r} "
+            '(values must be quoted, e.g. n.name = "Alice")'
+        )
+        raise QuerySyntaxError(msg)
+    for cond_var, _prop_name, _prop_value in conditions:
+        if cond_var not in valid_vars:
+            msg = f"WHERE refers to unknown variable '{cond_var}'"
+            raise QuerySyntaxError(msg)
+    return conditions
+
+
+def _node_matches(node: Node, var_name: str, conditions: list[tuple[str, str, str]]) -> bool:
+    """Check whether a node satisfies the conditions aimed at its variable.
+
+    Only conditions whose variable equals ``var_name`` apply here; conditions
+    for other variables are checked against their own nodes elsewhere.
+
+    Args:
+        node: The node to test.
+        var_name: The variable this node is bound to.
+        conditions: All parsed WHERE conditions.
+
+    Returns:
+        True if the node satisfies every condition aimed at ``var_name``.
+
+    """
+    for cond_var, prop_name, prop_value in conditions:
+        if cond_var != var_name:
+            continue
+        if str(node.get_property(prop_name)) != prop_value:
+            return False
+    return True