fromscratch-pygraphdb 0.4.0__py3-none-any.whl

fromscratch_pygraphdb-0.4.0.dist-info/METADATA

@@ -0,0 +1,145 @@
+Metadata-Version: 2.5
+Name: fromscratch-pygraphdb
+Version: 0.4.0
+Summary: An educational graph database library built from scratch in Python
+Project-URL: Homepage, https://github.com/robcox2910/pygraphdb
+Project-URL: Repository, https://github.com/robcox2910/pygraphdb
+Project-URL: Issues, https://github.com/robcox2910/pygraphdb/issues
+Project-URL: Documentation, https://robcox2910.github.io/pygraphdb/
+Author: Rob Cox
+License: MIT
+License-File: LICENSE
+Keywords: database,education,graph,neo4j
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Education
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Education
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.14
+Provides-Extra: dev
+Requires-Dist: commitizen>=4.4.0; extra == 'dev'
+Requires-Dist: hypothesis>=6.170; extra == 'dev'
+Requires-Dist: pip-audit>=2.10.0; extra == 'dev'
+Requires-Dist: pre-commit>=4.0.1; extra == 'dev'
+Requires-Dist: pyright>=1.1.400; extra == 'dev'
+Requires-Dist: pytest-cov>=6.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.3.4; extra == 'dev'
+Requires-Dist: ruff>=0.9.3; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# PyGraphDB
+
+An educational graph database library built from scratch in Python. Part of the **PyLearn** educational platform for kids aged 12+.
+
+A graph database stores data as **nodes** (entities) and **edges** (relationships) -- like a social network map where people are dots and friendships are lines connecting them.
+
+## Features
+
+- **Nodes & Edges** -- Create entities with labels and properties, connect them with typed relationships
+- **CRUD Operations** -- Add, get, update, and delete nodes and edges
+- **Graph Traversal** -- Explore your graph with BFS (breadth-first) and DFS (depth-first) algorithms
+- **Shortest Path** -- Find the quickest route between two nodes (like GPS directions)
+- **Pattern Matching** -- Search for nodes and edges by label, type, or properties
+- **Cypher-like Queries** -- Ask questions with a simple query language inspired by Neo4j's Cypher
+- **Persistence** -- Save and load your graph to/from JSON files
+- **Neighbor & Degree** -- Find connected nodes and count connections
+
+## Quick Start
+
+```python
+from pygraphdb import Graph, bfs, shortest_path, execute_query, find_nodes
+
+# Create a social network
+g = Graph()
+g.add_node("alice", label="Person", properties={"name": "Alice", "age": 13})
+g.add_node("bob", label="Person", properties={"name": "Bob", "age": 14})
+g.add_node("charlie", label="Person", properties={"name": "Charlie", "age": 13})
+
+g.add_edge("e1", "alice", "bob", rel_type="KNOWS")
+g.add_edge("e2", "bob", "charlie", rel_type="KNOWS")
+
+# Find Alice's friends
+friends = g.get_neighbors("alice", direction="outgoing")
+print([f.properties["name"] for f in friends])  # ['Bob']
+
+# Traverse the whole network
+visited = bfs(g, "alice")
+print([n.properties["name"] for n in visited])  # ['Alice', 'Bob', 'Charlie']
+
+# Find shortest path
+path = shortest_path(g, "alice", "charlie")
+print([n.properties["name"] for n in path])  # ['Alice', 'Bob', 'Charlie']
+
+# Query with Cypher-like syntax
+results = execute_query(g, 'MATCH (n:Person) WHERE n.name = "Alice" RETURN n')
+print(results[0].properties["name"])  # 'Alice'
+
+# Pattern matching
+teenagers = find_nodes(g, label="Person")
+print(len(teenagers))  # 3
+```
+
+## Installation
+
+```bash
+# Clone and install
+git clone https://github.com/robcox2910/pygraphdb.git
+cd pygraphdb
+uv sync --all-extras
+
+# Run tests
+uv run pytest
+
+# Lint & type check
+uv run ruff check src/ tests/
+uv run pyright src tests
+```
+
+## Releasing
+
+Other projects in the series ([PyStack](https://github.com/robcox2910/pystack)) use a pinned release of this one,
+not whatever is on `main`. To publish a change for them:
+
+1. Merge the change to `main`.
+2. Tag it: `git tag -a vX.Y.Z -m vX.Y.Z && git push origin vX.Y.Z`.
+   A change to the public API bumps the minor version (`v0.1.0` → `v0.2.0`);
+   anything else bumps the patch (`v0.1.0` → `v0.1.1`).
+3. In each project that uses it, edit the tag in `[tool.uv.sources]`, run
+   `uv lock --upgrade-package <name>`, and open a pull request so CI checks
+   the pair together.
+
+<!-- series:start -->
+## Related Projects
+
+This project is one of a series that builds real systems "from scratch in Python" to teach how they work. See the [series home](https://robcox2910.github.io/) for the full story.
+
+| Project | What it teaches | Repository | Docs |
+| --- | --- | --- | --- |
+| PyOS | Operating systems | [py-os](https://github.com/robcox2910/py-os) | [Docs](https://robcox2910.github.io/py-os/) |
+| Pebble | Compilers and programming languages | [pebble-lang](https://github.com/robcox2910/pebble-lang) | [Docs](https://robcox2910.github.io/pebble-lang/) |
+| PyDB | Relational databases | [pydb](https://github.com/robcox2910/pydb) | [Docs](https://robcox2910.github.io/pydb/) |
+| PyKV | Key-value stores | [pykv](https://github.com/robcox2910/pykv) | [Docs](https://robcox2910.github.io/pykv/) |
+| PyDocDB | Document databases | [pydoc-db](https://github.com/robcox2910/pydoc-db) | [Docs](https://robcox2910.github.io/pydoc-db/) |
+| **PyGraphDB** | **Graph databases** | [pygraphdb](https://github.com/robcox2910/pygraphdb) | [Docs](https://robcox2910.github.io/pygraphdb/) |
+| PyTSDB | Time-series databases | [pytsdb](https://github.com/robcox2910/pytsdb) | [Docs](https://robcox2910.github.io/pytsdb/) |
+| PyVecDB | Vector databases | [pyvecdb](https://github.com/robcox2910/pyvecdb) | [Docs](https://robcox2910.github.io/pyvecdb/) |
+| PyColDB | Column-family databases | [pycoldb](https://github.com/robcox2910/pycoldb) | [Docs](https://robcox2910.github.io/pycoldb/) |
+| PyCrypt | Cryptography | [pycrypt](https://github.com/robcox2910/pycrypt) | [Docs](https://robcox2910.github.io/pycrypt/) |
+| PyNet | Computer networking | [pynet](https://github.com/robcox2910/pynet) | [Docs](https://robcox2910.github.io/pynet/) |
+| PyWeb | HTTP web servers | [pyweb](https://github.com/robcox2910/pyweb) | [Docs](https://robcox2910.github.io/pyweb/) |
+| PyGit | Version control | [pygit](https://github.com/robcox2910/pygit) | [Docs](https://robcox2910.github.io/pygit/) |
+| PySearch | Search engines | [pysearch](https://github.com/robcox2910/pysearch) | [Docs](https://robcox2910.github.io/pysearch/) |
+| PyMQ | Message queues | [pymq](https://github.com/robcox2910/pymq) | [Docs](https://robcox2910.github.io/pymq/) |
+| PyLLM | Language models (the brain) | [pyllm](https://github.com/robcox2910/pyllm) | [Docs](https://robcox2910.github.io/pyllm/) |
+| PyScheduler | Job scheduling | [pyscheduler](https://github.com/robcox2910/pyscheduler) | [Docs](https://robcox2910.github.io/pyscheduler/) |
+| PyStack | Full-stack integration | [pystack](https://github.com/robcox2910/pystack) | [Docs](https://robcox2910.github.io/pystack/) |
+<!-- series:end -->
+
+<!-- docs:start -->
+## Documentation
+
+Full docs (with kid-friendly explanations of every idea): https://robcox2910.github.io/pygraphdb/
+<!-- docs:end -->

fromscratch_pygraphdb-0.4.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+pygraphdb/__init__.py,sha256=yOCxmfp_KBoZis4aco7gYr_FzkDFzruvF4ZWt7i8zSw,2027
+pygraphdb/_version.py,sha256=HGBlVvZpQ8N2kh1n_LY5PM4s9ljcIgdbOCgXN-uFje4,520
+pygraphdb/atomic.py,sha256=QLLPGZqpA-TgVV5lDEKCLB7vVr05bxj97_Fwykz_gi4,2345
+pygraphdb/edge.py,sha256=7Z9je6Mm7MaHHg4pjeL-vFs90BqxxqB3fvcv27_ZP8k,5813
+pygraphdb/errors.py,sha256=Y7kvfgYSt0cL9F6WaxN8lDYuvThkZGHkF8QivAi60ws,1928
+pygraphdb/graph.py,sha256=HifGuGb9BIYgWeNRHy2cLCnb0znc7W-jzM8K2eReCos,16136
+pygraphdb/matching.py,sha256=-vfLY8vu9fpxS8J3ZKB_UgVSGYeJ72-s0GtZLpwU850,3575
+pygraphdb/node.py,sha256=aNDIxIKxRs6BTzrk1hB6UnqgkYdBZLNN-Sk-zyVkn8w,4763
+pygraphdb/pathfinding.py,sha256=3Nzq4sqY2xoeip-IzWuLRgk1DCGjAPkqAPXVkvXr3F4,4486
+pygraphdb/persistence.py,sha256=VY0jst6WDUWqOMHvuKFduoU4rGRs_iIM3HZqnnNUUWM,4368
+pygraphdb/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pygraphdb/query.py,sha256=M8O6BP6lz_EjavugomgAA3jnuTw3sycvuHGWtvqYyKQ,7629
+pygraphdb/traversal.py,sha256=KfoWw92xwNLxECFrkq_I6K0H9aTbvgx8HvU-vtW6fZU,3197
+fromscratch_pygraphdb-0.4.0.dist-info/METADATA,sha256=lAgyAlScMdPlo30u_-cXaGzVJuWRIFx1bwp-lQyDraA,7142
+fromscratch_pygraphdb-0.4.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+fromscratch_pygraphdb-0.4.0.dist-info/licenses/LICENSE,sha256=NtHM2ak--oE71VCcY50kcCoC1cKS0LRUsxq_xA89RNc,1064
+fromscratch_pygraphdb-0.4.0.dist-info/RECORD,,

fromscratch_pygraphdb-0.4.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

fromscratch_pygraphdb-0.4.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rob Cox
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pygraphdb/__init__.py

@@ -0,0 +1,72 @@
+"""PyGraphDB -- an educational graph database built from scratch in Python.
+
+A graph database stores data as nodes (entities) and edges (relationships),
+like a social network map. This library teaches you how graph databases
+work by building one step by step.
+
+Think of it like this:
+- **Nodes** are people at a party
+- **Edges** are the friendships between them
+- **The Graph** is the party itself -- it keeps track of everyone and
+  who knows whom
+- **Traversal** is walking around the party visiting people
+- **Queries** are questions you ask, like "Who are Alice's friends?"
+
+Quick start:
+    >>> from pygraphdb import Graph
+    >>> g = Graph()
+    >>> g.add_node("alice", label="Person", properties={"name": "Alice"})
+    >>> g.add_node("bob", label="Person", properties={"name": "Bob"})
+    >>> g.add_edge("e1", "alice", "bob", rel_type="KNOWS")
+    >>> friends = g.get_neighbors("alice")
+    >>> friends[0].properties["name"]
+    'Bob'
+"""
+
+from pygraphdb.edge import Edge
+from pygraphdb.errors import (
+    DuplicateEdgeError,
+    DuplicateNodeError,
+    EdgeNotFoundError,
+    GraphError,
+    NodeNotFoundError,
+    PersistenceError,
+    QuerySyntaxError,
+)
+from pygraphdb.graph import Graph
+from pygraphdb.matching import find_edges, find_nodes
+from pygraphdb.node import Node
+from pygraphdb.pathfinding import all_paths, shortest_path
+from pygraphdb.persistence import graph_from_json, graph_to_json, load_graph, save_graph
+from pygraphdb.query import execute_query
+from pygraphdb.traversal import bfs, dfs
+
+__all__ = [
+    "DuplicateEdgeError",
+    "DuplicateNodeError",
+    "Edge",
+    "EdgeNotFoundError",
+    "Graph",
+    "GraphError",
+    "Node",
+    # Errors
+    "NodeNotFoundError",
+    "PersistenceError",
+    "QuerySyntaxError",
+    "all_paths",
+    # Traversal
+    "bfs",
+    "dfs",
+    # Query
+    "execute_query",
+    "find_edges",
+    # Matching
+    "find_nodes",
+    "graph_from_json",
+    "graph_to_json",
+    "load_graph",
+    # Persistence
+    "save_graph",
+    # Pathfinding
+    "shortest_path",
+]

pygraphdb/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.4.0'
+__version_tuple__ = version_tuple = (0, 4, 0)
+
+__commit_id__ = commit_id = None

pygraphdb/atomic.py

@@ -0,0 +1,66 @@
+"""Safe saving -- never leave a half-written file behind.
+
+The usual way to save a file is: open it, wipe it, write the new
+contents. If the computer crashes after the wipe but before the writing
+finishes, your data is gone -- the old version was wiped and the new one
+never arrived.
+
+So we save like a careful student copying out their homework:
+
+1. Write the new version on a **fresh sheet** (a temporary file sitting
+   right next to the real one).
+2. Make sure the **ink is dry** -- ``fsync`` forces the bytes out of the
+   computer's memory and onto the disk.
+3. **Swap** the fresh sheet in for the old one in a single instant step
+   (``Path.replace``). There is never a moment with no complete file: you
+   see either the old version or the new one, never half of each.
+
+Real databases (SQLite, PostgreSQL, Redis) all use this same trick.
+"""
+
+import contextlib
+import os
+import stat
+import tempfile
+from pathlib import Path
+
+# Permissions for a brand-new file: owner can read/write, others can read.
+_NEW_FILE_MODE = 0o644
+
+
+def atomic_write_text(path: Path, text: str) -> None:
+    """Replace the file at *path* with *text*, so a crash can never leave it half-written.
+
+    Args:
+        path: The file to create or replace (its folder must already exist).
+        text: The new contents, saved as UTF-8.
+
+    """
+    mode = stat.S_IMODE(path.stat().st_mode) if path.exists() else _NEW_FILE_MODE
+    fd, temp_name = tempfile.mkstemp(dir=path.parent, prefix=f".{path.name}.", suffix=".tmp")
+    temp_path = Path(temp_name)
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as temp_file:
+            temp_file.write(text)
+            temp_file.flush()
+            os.fsync(temp_file.fileno())
+        temp_path.chmod(mode)
+        temp_path.replace(path)
+    except BaseException:
+        temp_path.unlink(missing_ok=True)  # don't leave the scrap sheet lying around
+        raise
+    _sync_folder(path.parent)
+
+
+def _sync_folder(folder: Path) -> None:
+    """Make the swap itself durable by syncing the folder's list of files.
+
+    Some systems (like Windows) can't sync a folder; there the swap is
+    still safe, just not guaranteed to survive a power cut.
+    """
+    with contextlib.suppress(OSError):
+        fd = os.open(folder, os.O_RDONLY)
+        try:
+            os.fsync(fd)
+        finally:
+            os.close(fd)

pygraphdb/edge.py

@@ -0,0 +1,177 @@
+"""Edge -- a relationship between two nodes in a graph database.
+
+Picture two people at a party shaking hands. That handshake is an edge!
+It connects one person (the source) to another (the target) and has a
+type that describes the relationship ("FRIENDS_WITH", "KNOWS", "WORKS_AT").
+
+Edges can also carry properties, just like friendships have qualities --
+maybe you became friends in 2024, or you're "best friends" vs "acquaintances."
+
+Edges in our graph are *directed* -- like a one-way street. "Alice FOLLOWS Bob"
+doesn't automatically mean "Bob FOLLOWS Alice." If you want both directions,
+you add two separate edges.
+
+Example:
+    >>> from pygraphdb.edge import Edge
+    >>> friendship = Edge(
+    ...     edge_id="e1",
+    ...     source_id="alice",
+    ...     target_id="bob",
+    ...     rel_type="FRIENDS_WITH",
+    ...     properties={"since": 2024},
+    ... )
+    >>> friendship.rel_type
+    'FRIENDS_WITH'
+
+"""
+
+from dataclasses import dataclass, field
+
+# The fields the graph files an edge under; they can't change once set.
+_FIXED_FIELDS = frozenset({"edge_id", "source_id", "target_id"})
+
+
+@dataclass
+class Edge:
+    """A directed relationship between two nodes.
+
+    Think of an edge like an arrow drawn between two dots on a whiteboard:
+    - ``edge_id`` is a unique label for this arrow
+    - ``source_id`` is where the arrow starts (the "from" node)
+    - ``target_id`` is where the arrow points (the "to" node)
+    - those three can't be changed once the edge is made
+    - ``rel_type`` is what the arrow means ("FRIENDS_WITH", "LIKES", etc.)
+    - ``properties`` is extra info about the relationship
+
+    Args:
+        edge_id: A unique identifier for this edge.
+        source_id: The ID of the node where this edge starts.
+        target_id: The ID of the node where this edge ends.
+        rel_type: The relationship type (e.g. "KNOWS", "WORKS_AT").
+        properties: A dictionary of key-value attributes.
+
+    """
+
+    edge_id: str
+    source_id: str
+    target_id: str
+    rel_type: str = ""
+    properties: dict[str, object] = field(default_factory=lambda: {})
+
+    def __setattr__(self, name: str, value: object) -> None:
+        """Set an attribute, except the id or either end once they've been set.
+
+        The graph files every edge under its id, and in the road lists of
+        the two nodes it joins. Changing any of those afterwards would leave
+        the edge filed in the wrong places -- so it isn't allowed.
+
+        Raises:
+            AttributeError: If ``edge_id``, ``source_id`` or ``target_id`` is
+                set a second time.
+
+        """
+        if name in _FIXED_FIELDS and name in self.__dict__:
+            msg = f"an edge's {name} can't be changed: it files the edge in the graph"
+            raise AttributeError(msg)
+        super().__setattr__(name, value)
+
+    def has_property(self, key: str) -> bool:
+        """Check whether this edge 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 edge.
+
+        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 edge.
+
+        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 edge onto an index card.
+
+        Like noting on a card who shook hands with whom, what kind of
+        relationship it was, and when -- turns the edge into a plain
+        dictionary you can save to a file.
+
+        Returns:
+            A dictionary representation of this edge.
+
+        """
+        return {
+            "edge_id": self.edge_id,
+            "source_id": self.source_id,
+            "target_id": self.target_id,
+            "rel_type": self.rel_type,
+            "properties": dict(self.properties),
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, object]) -> Edge:
+        """Rebuild an edge from the index card that to_dict wrote.
+
+        Like reading a filed-away card and re-drawing that handshake
+        (arrow) between two people -- turns a plain dictionary back into
+        a real Edge.
+
+        Args:
+            data: A dictionary with edge fields.
+
+        Returns:
+            A new Edge instance.
+
+        """
+        edge_id = str(data.get("edge_id", ""))
+        source_id = str(data.get("source_id", ""))
+        target_id = str(data.get("target_id", ""))
+        rel_type = str(data.get("rel_type", ""))
+        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(
+            edge_id=edge_id,
+            source_id=source_id,
+            target_id=target_id,
+            rel_type=rel_type,
+            properties=props,
+        )

pygraphdb/errors.py

@@ -0,0 +1,63 @@
+"""Custom exceptions for PyGraphDB.
+
+Think of these like warning signs at a playground -- they tell you when
+something went wrong so you can fix it instead of getting confused by
+a mysterious crash.
+
+Each exception type describes a specific kind of problem:
+- A node you asked for doesn't exist
+- An edge you asked for doesn't exist
+- You tried to add something that's already there
+- A query you wrote has a mistake in it
+"""
+
+
+class GraphError(Exception):
+    """Base exception for all graph database errors."""
+
+
+class NodeNotFoundError(GraphError):
+    """Raise when a requested node does not exist in the graph.
+
+    Like looking for a person at a party who never showed up.
+    """
+
+
+class EdgeNotFoundError(GraphError):
+    """Raise when a requested edge does not exist in the graph.
+
+    Like looking for a friendship between two people who don't know each other.
+    """
+
+
+class DuplicateNodeError(GraphError):
+    """Raise when trying to add a node with an ID that already exists.
+
+    Like trying to give two different people the exact same name tag at a party.
+    """
+
+
+class DuplicateEdgeError(GraphError):
+    """Raise when trying to add an edge whose id is already taken.
+
+    Like giving two different roads the exact same street sign -- an edge
+    with this id already exists. (Two separate roads between the same pair
+    of buildings are fine, as long as each has its own sign.)
+    """
+
+
+class QuerySyntaxError(GraphError):
+    """Raise when a query string has invalid syntax.
+
+    Like writing a sentence with the words in the wrong order --
+    the computer can't understand what you're asking.
+    """
+
+
+class PersistenceError(GraphError):
+    """Raise when a saved graph can't be read back from disk.
+
+    Like opening your saved game and finding the file missing or
+    scrambled -- rather than starting an empty game and pretending all is
+    well, we stop and say which file is the problem.
+    """