lora-python 0.2.0__cp38-abi3-macosx_10_12_x86_64.whl

lora_python/__init__.py

@@ -0,0 +1,133 @@
+"""lora-python — typed Python bindings for the Lora graph engine.
+
+Two public classes:
+
+- ``Database``     : synchronous, PyO3-backed. Holds an in-memory graph and
+                     runs queries with the GIL released.
+- ``AsyncDatabase``: pure-Python asyncio wrapper. Delegates to a
+                     background thread via ``asyncio.to_thread`` so the
+                     event loop stays responsive during heavier queries.
+
+Both classes share the same public result / value / param shapes (see
+``lora_python.types``) so switching between sync and async usage is a
+method-name change, nothing else.
+
+Example
+-------
+    >>> from lora_python import Database
+    >>> db = Database.create()
+    >>> db.execute("CREATE (:Person {name: $n})", {"n": "Alice"})
+    >>> r = db.execute("MATCH (n:Person) RETURN n.name AS name")
+    >>> r["rows"]
+    [{'name': 'Alice'}]
+
+Async:
+
+    >>> import asyncio
+    >>> from lora_python import AsyncDatabase
+    >>> async def main():
+    ...     db = await AsyncDatabase.create()
+    ...     await db.execute("CREATE (:Person {name: 'Alice'})")
+    ...     return await db.execute("MATCH (n:Person) RETURN n.name AS name")
+    >>> asyncio.run(main())["rows"]
+    [{'name': 'Alice'}]
+"""
+
+from __future__ import annotations
+
+from ._native import (
+    Database,
+    LoraError,
+    LoraQueryError,
+    InvalidParamsError,
+    __version__,
+)
+from ._async import AsyncDatabase
+from . import types
+from .types import (
+    LoraParam,
+    LoraParams,
+    LoraValue,
+    QueryResult,
+    LoraNode,
+    LoraRelationship,
+    LoraPath,
+    LoraDate,
+    LoraTime,
+    LoraLocalTime,
+    LoraDateTime,
+    LoraLocalDateTime,
+    LoraDuration,
+    LoraPoint,
+    LoraCartesianPoint,
+    LoraCartesianPoint3D,
+    LoraWgs84Point,
+    LoraWgs84Point3D,
+    LoraVector,
+    LoraVectorCoordinateType,
+    date,
+    time,
+    localtime,
+    datetime,
+    localdatetime,
+    duration,
+    cartesian,
+    cartesian_3d,
+    wgs84,
+    wgs84_3d,
+    vector,
+    is_node,
+    is_relationship,
+    is_path,
+    is_point,
+    is_temporal,
+    is_vector,
+)
+
+__all__ = [
+    "Database",
+    "AsyncDatabase",
+    "LoraError",
+    "LoraQueryError",
+    "InvalidParamsError",
+    "__version__",
+    "types",
+    # re-exports
+    "LoraParam",
+    "LoraParams",
+    "LoraValue",
+    "QueryResult",
+    "LoraNode",
+    "LoraRelationship",
+    "LoraPath",
+    "LoraDate",
+    "LoraTime",
+    "LoraLocalTime",
+    "LoraDateTime",
+    "LoraLocalDateTime",
+    "LoraDuration",
+    "LoraPoint",
+    "LoraCartesianPoint",
+    "LoraCartesianPoint3D",
+    "LoraWgs84Point",
+    "LoraWgs84Point3D",
+    "LoraVector",
+    "LoraVectorCoordinateType",
+    "date",
+    "time",
+    "localtime",
+    "datetime",
+    "localdatetime",
+    "duration",
+    "cartesian",
+    "cartesian_3d",
+    "wgs84",
+    "wgs84_3d",
+    "vector",
+    "is_node",
+    "is_relationship",
+    "is_path",
+    "is_point",
+    "is_temporal",
+    "is_vector",
+]

lora_python/_async.py

@@ -0,0 +1,113 @@
+"""Async-compatible Database wrapper.
+
+The PyO3 ``Database`` is synchronous — the engine itself is synchronous
+Rust — but it releases the GIL while running a query, which means the
+heavy work can safely be hoisted off the asyncio event-loop thread.
+
+``AsyncDatabase`` does exactly that: each ``await db.execute(...)`` call
+dispatches the sync ``Database.execute`` onto a worker thread via
+``asyncio.to_thread`` on Python 3.9+, or the equivalent
+``loop.run_in_executor`` polyfill on 3.8. The event loop stays free to
+service other coroutines while the engine runs.
+
+This is the pragmatic, well-understood pattern for async-wrapping a
+CPU-bound Rust function in Python. It requires no unsafe lifetime
+juggling and stays trivially debuggable.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextvars
+import functools
+import sys
+from typing import Any, Callable, Mapping, Optional, TypeVar
+
+from ._native import Database as _Database
+from .types import LoraParams, QueryResult
+
+_T = TypeVar("_T")
+
+
+# `asyncio.to_thread` landed in Python 3.9 (bpo-32309). Provide a direct
+# equivalent on 3.8 so the non-blocking behaviour is identical: dispatch
+# the call onto the running loop's default executor with the current
+# context copied over, just like the CPython implementation.
+if sys.version_info >= (3, 9):
+    _to_thread = asyncio.to_thread  # type: ignore[attr-defined]
+else:  # pragma: no cover — exercised in the 3.8 CI leg
+
+    async def _to_thread(
+        func: Callable[..., _T], /, *args: Any, **kwargs: Any
+    ) -> _T:
+        loop = asyncio.get_running_loop()
+        ctx = contextvars.copy_context()
+        return await loop.run_in_executor(
+            None, functools.partial(ctx.run, func, *args, **kwargs)
+        )
+
+
+class AsyncDatabase:
+    """asyncio-compatible handle to an in-memory Lora database.
+
+    All methods delegate to the sync ``Database`` on a worker thread so
+    the event loop is never blocked by engine work. Methods are coroutines
+    so normal async usage looks like::
+
+        db = await AsyncDatabase.create()
+        result = await db.execute("MATCH (n) RETURN n")
+
+    Concurrency: a single ``AsyncDatabase`` wraps a single ``Database``;
+    concurrent ``execute`` coroutines serialise on the underlying engine's
+    mutex but do not block the event loop while waiting.
+    """
+
+    __slots__ = ("_inner",)
+
+    def __init__(self, inner: _Database) -> None:
+        self._inner = inner
+
+    @classmethod
+    async def create(cls) -> "AsyncDatabase":
+        """Construct a fresh in-memory database. Async for API symmetry."""
+        # Construction is cheap (Arc::new + Mutex::new) so we stay on-thread.
+        return cls(_Database())
+
+    async def execute(
+        self,
+        query: str,
+        params: Optional[Mapping[str, Any]] = None,
+    ) -> QueryResult:
+        """Run a Lora query on a background thread.
+
+        Returns ``{"columns": [...], "rows": [...]}``. Raises
+        ``LoraQueryError`` on engine failure or ``InvalidParamsError``
+        on a malformed parameter.
+        """
+        # The helper runs the callable on the loop's default
+        # ThreadPoolExecutor. Since Database.execute releases the GIL,
+        # other coroutines on the same event loop are free to progress.
+        return await _to_thread(
+            self._inner.execute,
+            query,
+            dict(params) if params is not None else None,
+        )
+
+    async def clear(self) -> None:
+        """Drop every node and relationship."""
+        await _to_thread(self._inner.clear)
+
+    @property
+    def node_count(self) -> int:
+        return self._inner.node_count
+
+    @property
+    def relationship_count(self) -> int:
+        return self._inner.relationship_count
+
+    def __repr__(self) -> str:  # pragma: no cover — cosmetic
+        return (
+            f"<lora_python.AsyncDatabase "
+            f"nodes={self._inner.node_count} "
+            f"relationships={self._inner.relationship_count}>"
+        )

lora_python/_native.pyi

@@ -0,0 +1,39 @@
+"""Type stubs for the PyO3 extension module.
+
+Mirrors what the native ``_native`` module exposes. The high-level
+``lora_python`` package re-exports these with richer types from
+``lora_python.types``.
+"""
+
+from typing import Any, Mapping, Optional
+
+from .types import QueryResult
+
+__version__: str
+
+class LoraError(Exception):
+    """Base class for Lora engine errors."""
+
+class LoraQueryError(LoraError):
+    """Parse / analyze / execute failure."""
+
+class InvalidParamsError(LoraError):
+    """A parameter value could not be mapped to a Lora value."""
+
+class Database:
+    """In-memory Lora graph database (sync, PyO3)."""
+
+    def __init__(self) -> None: ...
+    @staticmethod
+    def create() -> "Database": ...
+    def execute(
+        self,
+        query: str,
+        params: Optional[Mapping[str, Any]] = None,
+    ) -> QueryResult: ...
+    def clear(self) -> None: ...
+    @property
+    def node_count(self) -> int: ...
+    @property
+    def relationship_count(self) -> int: ...
+    def __repr__(self) -> str: ...

lora_python/types.py

@@ -0,0 +1,342 @@
+"""Typed Python value model for lora-python.
+
+Kept conceptually aligned with the shared TS contract used by
+``lora-node`` / ``lora-wasm`` (see ``crates/shared-ts/types.ts``).
+Python uses pragmatic representations:
+
+- Scalars pass through as Python natives (``None``, ``bool``, ``int``,
+  ``float``, ``str``).
+- Lists and maps come back as ``list`` / ``dict``.
+- Graph, temporal, and spatial values come back as ``TypedDict``s with
+  a ``kind`` discriminator. They're plain dicts at runtime — no class
+  wrappers to unpack — and narrow cleanly under ``typing.TYPE_CHECKING``.
+
+If a caller wants structured objects, the ``is_node`` / ``is_temporal``
+helpers make narrowing explicit.
+"""
+
+from __future__ import annotations
+
+from typing import Any, List, Literal, Mapping, TypedDict, Union
+
+# ---------------------------------------------------------------------------
+# Forward-declare the recursive value union.
+# ---------------------------------------------------------------------------
+
+# ``LoraValue`` is recursive; PEP 604 union syntax works on 3.10+, but we
+# fall back to ``Union`` for 3.8/3.9 support.
+LoraValue = Union[
+    None,
+    bool,
+    int,
+    float,
+    str,
+    List["LoraValue"],
+    Mapping[str, "LoraValue"],
+    "LoraNode",
+    "LoraRelationship",
+    "LoraPath",
+    "LoraDate",
+    "LoraTime",
+    "LoraLocalTime",
+    "LoraDateTime",
+    "LoraLocalDateTime",
+    "LoraDuration",
+    "LoraPoint",
+    "LoraVector",
+]
+
+LoraParam = Union[
+    None,
+    bool,
+    int,
+    float,
+    str,
+    List["LoraParam"],
+    Mapping[str, "LoraParam"],
+    "LoraDate",
+    "LoraTime",
+    "LoraLocalTime",
+    "LoraDateTime",
+    "LoraLocalDateTime",
+    "LoraDuration",
+    "LoraPoint",
+    "LoraVector",
+]
+
+LoraParams = Mapping[str, LoraParam]
+
+# ---------------------------------------------------------------------------
+# Structural values — TypedDicts with a `kind` discriminator.
+# ---------------------------------------------------------------------------
+
+
+class LoraNode(TypedDict):
+    kind: Literal["node"]
+    id: int
+    labels: List[str]
+    properties: Mapping[str, LoraValue]
+
+
+class LoraRelationship(TypedDict):
+    kind: Literal["relationship"]
+    id: int
+    startId: int
+    endId: int
+    type: str
+    properties: Mapping[str, LoraValue]
+
+
+class LoraPath(TypedDict):
+    kind: Literal["path"]
+    nodes: List[int]
+    rels: List[int]
+
+
+# ---------------------------------------------------------------------------
+# Temporal — ISO-8601 tagged.
+# ---------------------------------------------------------------------------
+
+
+class LoraDate(TypedDict):
+    kind: Literal["date"]
+    iso: str
+
+
+class LoraTime(TypedDict):
+    kind: Literal["time"]
+    iso: str
+
+
+class LoraLocalTime(TypedDict):
+    kind: Literal["localtime"]
+    iso: str
+
+
+class LoraDateTime(TypedDict):
+    kind: Literal["datetime"]
+    iso: str
+
+
+class LoraLocalDateTime(TypedDict):
+    kind: Literal["localdatetime"]
+    iso: str
+
+
+class LoraDuration(TypedDict):
+    kind: Literal["duration"]
+    iso: str
+
+
+# ---------------------------------------------------------------------------
+# Spatial
+# ---------------------------------------------------------------------------
+
+
+# ---------------------------------------------------------------------------
+# Point variants.
+#
+# Python's ``TypedDict`` cannot model "required only on some variants" the
+# way a TS discriminated union can, so we declare one dict per CRS and
+# union them into ``LoraPoint``. Narrow via ``is_point`` + ``srid`` / ``crs``.
+# ---------------------------------------------------------------------------
+
+
+class LoraCartesianPoint(TypedDict):
+    kind: Literal["point"]
+    srid: Literal[7203]
+    crs: Literal["cartesian"]
+    x: float
+    y: float
+
+
+class LoraCartesianPoint3D(TypedDict):
+    kind: Literal["point"]
+    srid: Literal[9157]
+    crs: Literal["cartesian-3D"]
+    x: float
+    y: float
+    z: float
+
+
+class LoraWgs84Point(TypedDict):
+    kind: Literal["point"]
+    srid: Literal[4326]
+    crs: Literal["WGS-84-2D"]
+    x: float
+    y: float
+    longitude: float
+    latitude: float
+
+
+class LoraWgs84Point3D(TypedDict):
+    kind: Literal["point"]
+    srid: Literal[4979]
+    crs: Literal["WGS-84-3D"]
+    x: float
+    y: float
+    z: float
+    longitude: float
+    latitude: float
+    height: float
+
+
+LoraPoint = Union[
+    LoraCartesianPoint,
+    LoraCartesianPoint3D,
+    LoraWgs84Point,
+    LoraWgs84Point3D,
+]
+
+
+# ---------------------------------------------------------------------------
+# Vector
+# ---------------------------------------------------------------------------
+
+
+LoraVectorCoordinateType = Literal[
+    "FLOAT64", "FLOAT32", "INTEGER", "INTEGER32", "INTEGER16", "INTEGER8"
+]
+
+
+class LoraVector(TypedDict):
+    kind: Literal["vector"]
+    dimension: int
+    coordinateType: LoraVectorCoordinateType
+    values: List[float]
+
+
+# ---------------------------------------------------------------------------
+# Query result
+# ---------------------------------------------------------------------------
+
+
+class QueryResult(TypedDict):
+    columns: List[str]
+    rows: List[Mapping[str, LoraValue]]
+
+
+# ---------------------------------------------------------------------------
+# Constructors for param-side temporal/spatial values.
+# ---------------------------------------------------------------------------
+
+
+def date(iso: str) -> LoraDate:
+    return {"kind": "date", "iso": iso}
+
+
+def time(iso: str) -> LoraTime:
+    return {"kind": "time", "iso": iso}
+
+
+def localtime(iso: str) -> LoraLocalTime:
+    return {"kind": "localtime", "iso": iso}
+
+
+def datetime(iso: str) -> LoraDateTime:
+    return {"kind": "datetime", "iso": iso}
+
+
+def localdatetime(iso: str) -> LoraLocalDateTime:
+    return {"kind": "localdatetime", "iso": iso}
+
+
+def duration(iso: str) -> LoraDuration:
+    return {"kind": "duration", "iso": iso}
+
+
+def vector(
+    values: List[float],
+    dimension: int,
+    coordinate_type: LoraVectorCoordinateType,
+) -> LoraVector:
+    """Build a LoraVector param/value in the canonical tagged shape."""
+    return {
+        "kind": "vector",
+        "dimension": dimension,
+        "coordinateType": coordinate_type,
+        "values": list(values),
+    }
+
+
+def cartesian(x: float, y: float) -> LoraCartesianPoint:
+    return {"kind": "point", "srid": 7203, "crs": "cartesian", "x": x, "y": y}
+
+
+def cartesian_3d(x: float, y: float, z: float) -> LoraCartesianPoint3D:
+    return {
+        "kind": "point",
+        "srid": 9157,
+        "crs": "cartesian-3D",
+        "x": x,
+        "y": y,
+        "z": z,
+    }
+
+
+def wgs84(longitude: float, latitude: float) -> LoraWgs84Point:
+    return {
+        "kind": "point",
+        "srid": 4326,
+        "crs": "WGS-84-2D",
+        "x": longitude,
+        "y": latitude,
+        "longitude": longitude,
+        "latitude": latitude,
+    }
+
+
+def wgs84_3d(
+    longitude: float, latitude: float, height: float
+) -> LoraWgs84Point3D:
+    return {
+        "kind": "point",
+        "srid": 4979,
+        "crs": "WGS-84-3D",
+        "x": longitude,
+        "y": latitude,
+        "z": height,
+        "longitude": longitude,
+        "latitude": latitude,
+        "height": height,
+    }
+
+
+# ---------------------------------------------------------------------------
+# Narrowing helpers.
+# ---------------------------------------------------------------------------
+
+
+def _is_tagged(v: Any, expected: str) -> bool:
+    return isinstance(v, dict) and v.get("kind") == expected
+
+
+def is_node(v: Any) -> bool:
+    """Return True if ``v`` is a Lora node value."""
+    return _is_tagged(v, "node")
+
+
+def is_relationship(v: Any) -> bool:
+    return _is_tagged(v, "relationship")
+
+
+def is_path(v: Any) -> bool:
+    return _is_tagged(v, "path")
+
+
+def is_point(v: Any) -> bool:
+    return _is_tagged(v, "point")
+
+
+_TEMPORAL_KINDS = frozenset(
+    {"date", "time", "localtime", "datetime", "localdatetime", "duration"}
+)
+
+
+def is_temporal(v: Any) -> bool:
+    return isinstance(v, dict) and v.get("kind") in _TEMPORAL_KINDS
+
+
+def is_vector(v: Any) -> bool:
+    """Return True if ``v`` is a Lora VECTOR value."""
+    return _is_tagged(v, "vector")