bkndb 0.2.0__py3-none-win_amd64.whl

bkndb/__init__.py

@@ -0,0 +1,139 @@
+"""bkndb — embedded hybrid graph + relational database engine for Python.
+
+Public API. Only import from here — :mod:`bkndb._native` is the raw
+UniFFI-generated layer and is an implementation detail that may change
+shape between releases without notice.
+
+    import bkndb
+    from bkndb import col, Column, TableSchema
+
+    with bkndb.open("my.bkndb") as db:
+        doc = db.create_node("Document", {"title": "..."})
+        db.create_table(TableSchema("chunks", [Column("id", int), Column("doc", int), Column("text", str)],
+                                    primary_key="id", auto_increment=True, indexes=["doc"]))
+        with db.transaction() as tx:
+            tx.insert("chunks", {"doc": doc, "text": "..."})
+        rows = db.select("chunks", col("doc") == doc)
+"""
+from __future__ import annotations
+
+from importlib import metadata as _metadata
+
+from .database import Database, Table, Transaction
+from .errors import (
+    BackendError,
+    BknDbError,
+    ConstraintViolationError,
+    CorruptionError,
+    QueryError,
+    DatabaseClosedError,
+    DatabaseLockedError,
+    DuplicateKeyError,
+    EncodingError,
+    InvalidArgumentError,
+    NotFoundError,
+    ReservedTableNameError,
+    SchemaMismatchError,
+    TableNotFoundError,
+    TransactionAbortedError,
+    TransactionClosedError,
+    TransactionError,
+    TransactionInProgressError,
+)
+from .query import Agg, Col, Expr, col
+from .types import (
+    AggregateRow,
+    Column,
+    DbStats,
+    Direction,
+    Edge,
+    Hub,
+    IntegrityReport,
+    Neighbor,
+    NewNode,
+    Node,
+    Path,
+    PathStep,
+    Properties,
+    PropertiesLike,
+    PropertyValue,
+    QueryResult,
+    Row,
+    ScoredRow,
+    StorageStats,
+    SyncResult,
+    TableSchema,
+    VectorIndexInfo,
+    TraversalHit,
+    TypedNeighbor,
+    WeightedPath,
+    pack_vector,
+)
+
+# `bkndb.open(...)` works, but `open` is left out of `__all__` so that
+# `from bkndb import *` can't shadow the builtin.
+open = Database.open
+in_memory = Database.in_memory
+
+try:
+    __version__ = _metadata.version("bkndb")
+except _metadata.PackageNotFoundError:  # running from a source tree without an install
+    __version__ = "0.0.0+unknown"
+
+__all__ = [
+    "Database",
+    "Transaction",
+    "Table",
+    "in_memory",
+    # queries
+    "col",
+    "Col",
+    "Expr",
+    "Agg",
+    # schemas & results
+    "Column",
+    "TableSchema",
+    "Row",
+    "AggregateRow",
+    "Direction",
+    "Node",
+    "Edge",
+    "Neighbor",
+    "NewNode",
+    "WeightedPath",
+    "TypedNeighbor",
+    "TraversalHit",
+    "Path",
+    "PathStep",
+    "Hub",
+    "SyncResult",
+    "DbStats",
+    "StorageStats",
+    "IntegrityReport",
+    "QueryResult",
+    "ScoredRow",
+    "VectorIndexInfo",
+    "pack_vector",
+    "Properties",
+    "PropertiesLike",
+    "PropertyValue",
+    # errors
+    "BknDbError",
+    "BackendError",
+    "TableNotFoundError",
+    "NotFoundError",
+    "EncodingError",
+    "ReservedTableNameError",
+    "DatabaseLockedError",
+    "DatabaseClosedError",
+    "DuplicateKeyError",
+    "SchemaMismatchError",
+    "ConstraintViolationError",
+    "TransactionError",
+    "TransactionInProgressError",
+    "TransactionClosedError",
+    "TransactionAbortedError",
+    "InvalidArgumentError",
+    "CorruptionError",
+    "QueryError",
+]

bkndb/_common.py

@@ -0,0 +1,63 @@
+"""Type aliases and small helpers shared by the Database / Transaction wrappers."""
+from __future__ import annotations
+
+import typing
+
+from . import errors, types
+from ._native.bkndb_ffi import FfiNodeRef, FfiVectorMetric
+
+
+T = typing.TypeVar("T")
+
+NodeSpec = typing.Tuple[str, types.PropertiesLike]
+EdgeSpec = typing.Tuple[int, str, int, types.PropertiesLike]
+NodeRefLike = typing.Union[int, types.NewNode]
+SyncEdgeSpec = typing.Tuple[NodeRefLike, str, NodeRefLike, types.PropertiesLike]
+
+
+def _call(fn: typing.Callable[[], T]) -> T:
+    """Runs `fn`, translating anything the native layer raises into a public exception."""
+    try:
+        return fn()
+    except BaseException as exc:
+        mapped = errors.wrap(exc)
+        if mapped is exc:
+            raise
+        raise mapped from exc
+
+
+def _node_ref(r: "NodeRefLike") -> typing.Any:
+    if isinstance(r, types.NewNode):
+        return FfiNodeRef.NEW(r.index)
+    return FfiNodeRef.EXISTING(r)
+
+
+def _props(p: typing.Optional[typing.Mapping[str, types.PropertyValue]]) -> dict:
+    return types.to_ffi_properties(p or {})
+
+
+Params = typing.Union[typing.Sequence[types.PropertyValue], typing.Mapping[str, types.PropertyValue], None]
+
+
+def _params(params: Params) -> typing.Tuple[list, typing.Optional[dict]]:
+    if params is None:
+        return [], None
+    if isinstance(params, typing.Mapping):
+        return [], {str(k): types.to_ffi_value(v) for k, v in params.items()}
+    if isinstance(params, (str, bytes)):
+        raise TypeError("params must be a list/tuple or a dict, not a single value")
+    return [types.to_ffi_value(v) for v in params], None
+
+
+def _row_or_none(record) -> typing.Optional[types.Row]:
+    return types.Row._from_ffi(record) if record is not None else None
+
+
+_METRICS = {"cosine": FfiVectorMetric.COSINE, "dot": FfiVectorMetric.DOT, "euclidean": FfiVectorMetric.EUCLIDEAN}
+
+
+def _metric(name: str) -> FfiVectorMetric:
+    try:
+        return _METRICS[name]
+    except KeyError:
+        raise ValueError(f"metric must be one of {sorted(_METRICS)}") from None

bkndb/_io.py

@@ -0,0 +1,168 @@
+"""Row (de)serialization for :meth:`bkndb.Database.export_csv` and friends.
+
+Formats:
+
+* **JSONL** — one JSON object per line, ``{column: value}`` including the
+  primary key. Lists and dicts are written as JSON arrays/objects; the
+  types JSON lacks are tagged one-key objects: ``{"$bytes": "<base64>"}``,
+  ``{"$datetime": "<ISO 8601, UTC>"}``, ``{"$uuid": "<hex>"}``. Types
+  round-trip exactly (except ``float`` NaN/infinity, which Python's
+  ``json`` writes as ``NaN``/``Infinity``).
+* **CSV** — a header row of column names (schema order), then one row per
+  record. An empty cell means "not given": on import the column is left
+  out, so its DEFAULT (or NULL) applies. Booleans are ``true``/``false``,
+  bytes are base64, datetimes ISO 8601, UUIDs hex, lists/dicts JSON text.
+  On import each cell is converted to its column's type.
+"""
+from __future__ import annotations
+
+import base64
+import datetime
+import json
+import os
+import typing
+import uuid
+
+from . import errors, types
+
+PathLike = typing.Union[str, "os.PathLike[str]"]
+
+_BYTES_KEY = "$bytes"
+_DATETIME_KEY = "$datetime"
+_UUID_KEY = "$uuid"
+
+
+def _iso(dt: datetime.datetime) -> str:
+    micros = types.datetime_to_micros(dt)
+    return types.micros_to_datetime(micros).isoformat().replace("+00:00", "Z")
+
+
+def _parse_iso(text: str) -> datetime.datetime:
+    # `fromisoformat` only accepts a trailing "Z" from Python 3.11 on.
+    if text.endswith(("Z", "z")):
+        text = text[:-1] + "+00:00"
+    return datetime.datetime.fromisoformat(text)
+
+
+def to_json_value(v: types.PropertyValue) -> typing.Any:
+    if isinstance(v, (bytes, bytearray)):
+        return {_BYTES_KEY: base64.b64encode(bytes(v)).decode("ascii")}
+    if isinstance(v, datetime.datetime):
+        return {_DATETIME_KEY: _iso(v)}
+    if isinstance(v, uuid.UUID):
+        return {_UUID_KEY: str(v)}
+    if isinstance(v, (list, tuple)):
+        return [to_json_value(x) for x in v]
+    if isinstance(v, dict):
+        return {k: to_json_value(x) for k, x in v.items()}
+    return v
+
+
+def from_json_value(v: typing.Any) -> types.PropertyValue:
+    if isinstance(v, dict):
+        if len(v) == 1:
+            ((key, inner),) = v.items()
+            try:
+                if key == _BYTES_KEY:
+                    return base64.b64decode(inner, validate=True)
+                if key == _DATETIME_KEY:
+                    return _parse_iso(inner)
+                if key == _UUID_KEY:
+                    return uuid.UUID(inner)
+            except (ValueError, TypeError) as exc:
+                raise errors.InvalidArgumentError(f"bad {key} value {inner!r}: {exc}") from None
+        return {k: from_json_value(x) for k, x in v.items()}
+    if isinstance(v, list):
+        return [from_json_value(x) for x in v]
+    return v
+
+
+def row_to_json(schema: types.TableSchema, row: types.Row) -> typing.Dict[str, typing.Any]:
+    out: typing.Dict[str, typing.Any] = {schema.primary_key: to_json_value(row.pk)}
+    for k, v in row.values.items():
+        out[k] = to_json_value(v)
+    return out
+
+
+def _kind(column: types.Column) -> str:
+    t = column.type
+    return t if isinstance(t, str) else t.__name__
+
+
+def to_csv_cell(v: types.PropertyValue) -> str:
+    if v is None:
+        return ""
+    if isinstance(v, bool):
+        return "true" if v else "false"
+    if isinstance(v, (bytes, bytearray)):
+        return base64.b64encode(bytes(v)).decode("ascii")
+    if isinstance(v, float):
+        return repr(v)
+    if isinstance(v, datetime.datetime):
+        return _iso(v)
+    if isinstance(v, (list, tuple, dict)):
+        return json.dumps(to_json_value(v), ensure_ascii=False)
+    return str(v)
+
+
+_TRUE = {"true", "t", "1", "yes", "y"}
+_FALSE = {"false", "f", "0", "no", "n"}
+
+
+def from_csv_cell(column: types.Column, cell: str) -> types.PropertyValue:
+    kind = _kind(column)
+    try:
+        if kind == "str":
+            return cell
+        if kind == "int":
+            return int(cell)
+        if kind == "float":
+            return float(cell)
+        if kind == "bool":
+            low = cell.strip().lower()
+            if low in _TRUE:
+                return True
+            if low in _FALSE:
+                return False
+            raise ValueError(f"not a boolean: {cell!r}")
+        if kind == "bytes":
+            return base64.b64decode(cell, validate=True)
+        if kind in ("timestamp", "datetime"):
+            return _parse_iso(cell)
+        if kind in ("uuid", "UUID"):
+            return uuid.UUID(cell)
+        if kind in ("list", "map", "dict"):
+            value = from_json_value(json.loads(cell))
+            if not isinstance(value, list if kind == "list" else dict):
+                raise ValueError(f"expected a JSON {'array' if kind == 'list' else 'object'}")
+            return value
+    except ValueError as exc:
+        raise errors.InvalidArgumentError(f"column '{column.name}': cannot read {cell!r} as {kind}: {exc}") from None
+    raise errors.InvalidArgumentError(f"column '{column.name}' has unsupported type {kind!r}")
+
+
+def csv_header(schema: types.TableSchema) -> typing.List[str]:
+    names = [c.name for c in schema.columns]
+    if schema.primary_key in names:
+        names.remove(schema.primary_key)
+    return [schema.primary_key, *names]
+
+
+def row_to_csv(header: typing.Sequence[str], schema: types.TableSchema, row: types.Row) -> typing.List[str]:
+    return [to_csv_cell(row.pk if name == schema.primary_key else row.values.get(name)) for name in header]
+
+
+def csv_record_to_row(
+    schema: types.TableSchema, header: typing.Sequence[str], record: typing.Sequence[str], line: int
+) -> typing.Dict[str, types.PropertyValue]:
+    if len(record) != len(header):
+        raise errors.InvalidArgumentError(f"CSV line {line}: expected {len(header)} fields, got {len(record)}")
+    row: typing.Dict[str, types.PropertyValue] = {}
+    for name, cell in zip(header, record):
+        if cell == "":
+            continue
+        column = schema.column(name)
+        if column is None:
+            raise errors.SchemaMismatchError(schema.name, f"CSV column '{name}' is not in the table")
+        row[name] = from_csv_cell(column, cell)
+    return row

bkndb/_native/.gitignore

@@ -0,0 +1,6 @@
+# Everything in this directory is generated by maturin (`maturin develop` /
+# `maturin build`) from crates/bkndb-ffi: the UniFFI Python bindings, their
+# `__init__.py`, and the compiled library they are checksum-matched with.
+# Never commit or hand-edit these.
+*
+!.gitignore

bkndb/_native/__init__.py

@@ -0,0 +1 @@
+from .bkndb_ffi import *  # NOQA