littlegraph-python 0.2.1

Python extension module for the littlegraph embedded graph database
Documentation
from __future__ import annotations

from pathlib import Path

import pytest

import littlegraph


def writable_database(path: Path, *, limits: littlegraph.Limits | None = None):
    return littlegraph.open(path, read_only=False, create=True, limits=limits)


def test_parameterized_execute_and_detached_records(tmp_path: Path) -> None:
    path = tmp_path / "database"
    with writable_database(path) as database:
        result = database.execute(
            "CREATE (n:Person {name: $name, active: $active, tags: $tags}) RETURN n",
            {"name": "Alice", "active": True, "tags": ["rust", "graph"]},
        )
        assert result.columns == ("n",)
        assert len(result) == 1
        record = result[0]
        node = record["n"]
        assert isinstance(node, littlegraph.Node)
        assert node.element_id
        assert node.record_id is not None
        assert node.labels == frozenset({"Person"})
        assert node["name"] == "Alice"
        assert node.get("missing", 42) == 42
        assert dict(node.properties) == {
            "active": True,
            "name": "Alice",
            "tags": ["rust", "graph"],
        }
        assert record.keys() == ("n",)
        assert record.values() == (node,)
        assert record.data() == {"n": node}

    assert record[0] is node
    assert list(result) == [record]


def test_nested_parameter_values_and_integer_boundaries(tmp_path: Path) -> None:
    with writable_database(tmp_path / "database") as database:
        result = database.execute(
            "RETURN $payload, $low, $high, $not_an_integer",
            {
                "payload": {"items": [None, True, 3.5, "x\x00y"]},
                "low": -(2**63),
                "high": 2**63 - 1,
                "not_an_integer": False,
            },
        )

    assert result[0][0] == {"items": [None, True, 3.5, "x\x00y"]}
    assert result[0].values()[1:] == (-(2**63), 2**63 - 1, False)


def test_parameter_errors_are_path_aware(tmp_path: Path) -> None:
    with writable_database(tmp_path / "database") as database:
        cyclic: list[object] = []
        cyclic.append(cyclic)
        with pytest.raises(littlegraph.ParameterValueError) as cycle_error:
            database.execute("RETURN $value", {"value": cyclic})
        assert "parameters.value[0]" in cycle_error.value.message

        with pytest.raises(littlegraph.ParameterValueError) as integer_error:
            database.execute("RETURN $value", {"value": 2**63})
        assert "parameters.value" in integer_error.value.message

        with pytest.raises(littlegraph.ParameterTypeError):
            database.execute("RETURN $value", {"value": object()})


def test_read_only_write_raises_access_mode_error(tmp_path: Path) -> None:
    path = tmp_path / "database"
    writable_database(path).close()

    with littlegraph.open(path) as database:
        with pytest.raises(littlegraph.AccessModeError):
            database.execute("CREATE (:Denied)")


def test_result_limit_rolls_back_write(tmp_path: Path) -> None:
    path = tmp_path / "database"
    limits = littlegraph.Limits(max_result_bytes=1)
    with writable_database(path, limits=limits) as database:
        with pytest.raises(littlegraph.TransactionResourceLimitError):
            database.execute("CREATE (n:TooLarge {value: 'large'}) RETURN n")

    with littlegraph.open(path) as database:
        assert len(database.execute("MATCH (n:TooLarge) RETURN n")) == 0


def test_relationship_value(tmp_path: Path) -> None:
    with writable_database(tmp_path / "database") as database:
        database.execute("CREATE (:Person {name: 'Alice'})")
        database.execute("CREATE (:Person {name: 'Bob'})")
        result = database.execute(
            "MATCH (a:Person {name: 'Alice'}), (b:Person {name: 'Bob'}) "
            "CREATE (a)-[r:KNOWS {since: $since}]->(b) RETURN r",
            {"since": 2026},
        )

    relationship = result[0]["r"]
    assert isinstance(relationship, littlegraph.Relationship)
    assert relationship.type == "KNOWS"
    assert relationship["since"] == 2026