linksql 0.1.0__py3-none-any.whl

linksql/__init__.py

@@ -0,0 +1,117 @@
+"""LinksQL — a Python reference implementation.
+
+LinksQL is an associative query language built on **one data primitive** (the
+link, a doublet) and **one operation** (substitution). This package is a
+faithful, behaviourally-identical port of the JavaScript reference implementation
+in ``../src``; the normative specification lives in ``../docs/SPECIFICATION.md``.
+
+The public surface mirrors the JavaScript package entry point: parse and
+serialise LiNo, build a :class:`LinksStore`, and run queries through a
+:class:`Database`.
+"""
+
+from __future__ import annotations
+
+from .lino import (
+    Link as LinkNode,
+)
+from .lino import (
+    LinoSyntaxError,
+    Node,
+    Ref,
+    Token,
+    parse,
+    serialize,
+    serialize_all,
+    tokenize,
+)
+from .names import Names, UnknownNameError
+from .protocol import (
+    JSON_CONTENT_TYPE,
+    LINO_CONTENT_TYPE,
+    decode,
+    encode,
+    escape_reference,
+    prefers_json,
+)
+from .query import (
+    Database,
+    Introspection,
+    MatchRow,
+    QueryError,
+    QueryReport,
+    SplitQuery,
+    link_to_lino,
+    patterns_of,
+    split_query,
+)
+from .schema import (
+    NamedQuery,
+    NamedSubscription,
+    Relation,
+    Schema,
+    SchemaError,
+)
+from .store import Link, LinkIntegrityError, LinksStore
+from .substitution import (
+    Context,
+    RawResult,
+    Row,
+    Slots,
+    Spec,
+    SubstitutionError,
+    execute,
+    link_matches,
+    link_slots,
+    match_restriction,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "JSON_CONTENT_TYPE",
+    "LINO_CONTENT_TYPE",
+    "Context",
+    "Database",
+    "Introspection",
+    "Link",
+    "LinkIntegrityError",
+    "LinkNode",
+    "LinksStore",
+    "LinoSyntaxError",
+    "MatchRow",
+    "NamedQuery",
+    "NamedSubscription",
+    "Names",
+    "Node",
+    "QueryError",
+    "QueryReport",
+    "RawResult",
+    "Ref",
+    "Relation",
+    "Row",
+    "Schema",
+    "SchemaError",
+    "Slots",
+    "Spec",
+    "SplitQuery",
+    "SubstitutionError",
+    "Token",
+    "UnknownNameError",
+    "__version__",
+    "decode",
+    "encode",
+    "escape_reference",
+    "execute",
+    "link_matches",
+    "link_slots",
+    "link_to_lino",
+    "match_restriction",
+    "parse",
+    "patterns_of",
+    "prefers_json",
+    "serialize",
+    "serialize_all",
+    "split_query",
+    "tokenize",
+]

linksql/lino.py

@@ -0,0 +1,289 @@
+"""Links Notation (LiNo) parser and serializer.
+
+LiNo represents associative data as nested links. Every link has the form::
+
+    (index: source target)
+
+where ``index`` (the identity) is optional and the values (``source``,
+``target``, ...) are themselves references or links. The notation is the surface
+syntax for the LinksQL substitution model.
+
+The grammar implemented here is::
+
+    document  = { value } ;
+    value     = link | reference ;
+    link      = "(" [ value ":" ] { value } ")" ;
+    reference = number | name | variable | wildcard | string ;
+    variable  = "$" name ;
+    wildcard  = "*" ;
+
+The parser produces a small, explicit AST so the rest of the engine never has to
+re-tokenize text.
+
+This module is a faithful, behaviourally-identical port of ``src/lino.js`` from
+the JavaScript reference implementation.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from typing import Union
+
+
+class LinoSyntaxError(Exception):
+    """Error raised when LiNo input cannot be parsed.
+
+    Mirrors the JavaScript ``LinoSyntaxError``: the formatted message appends a
+    position suffix only when ``position`` is non-negative, and ``position``
+    stays available as an attribute.
+    """
+
+    def __init__(self, message: str, position: int) -> None:
+        full = f"{message} (at position {position})" if position >= 0 else message
+        super().__init__(full)
+        self.position = position
+
+
+# Whitespace characters that separate tokens (otherwise insignificant).
+_WHITESPACE = frozenset((" ", "\t", "\n", "\r", "\f", "\v"))
+# Structural delimiters that break a bareword and/or carry their own meaning.
+_DELIMITERS = frozenset(("(", ")", ":", '"', "'"))
+# Characters that force a name to be quoted on output.
+_QUOTE_REQUIRED = re.compile(r"[\s():\"']")
+# A bareword that is entirely ASCII digits is a numeric reference.
+_DIGITS = re.compile(r"^\d+$")
+
+
+@dataclass(frozen=True)
+class Ref:
+    """A reference node: a number, name, variable, or wildcard.
+
+    ``kind`` is one of ``"number"``, ``"name"``, ``"variable"``, ``"wildcard"``.
+    For ``"number"`` references ``value`` is an :class:`int`; otherwise it is the
+    string label / variable name / ``"*"``.
+    """
+
+    kind: str
+    value: int | str
+
+
+@dataclass
+class Link:
+    """A link node: ``( [ id ":" ] values... )``.
+
+    ``id`` is a reference node, a nested link node, or ``None`` (absent) and
+    ``values`` is an ordered list of child nodes.
+    """
+
+    id: Node | None
+    values: list[Node]
+
+
+# A LiNo AST node is either a reference or a link.
+Node = Union[Ref, Link]
+
+
+@dataclass(frozen=True)
+class Token:
+    """A LiNo token.
+
+    ``type`` is one of ``"lparen"``, ``"rparen"``, ``"colon"``, ``"ref"``. For
+    ``"ref"`` tokens ``kind`` classifies the reference and ``value`` carries its
+    payload; ``pos`` is the source offset and ``quoted`` records whether the ref
+    came from a quoted string.
+    """
+
+    type: str
+    pos: int
+    kind: str | None = None
+    value: int | str | None = None
+    quoted: bool = field(default=False)
+
+
+def _classify_word(word: str, pos: int) -> Token:
+    """Classify a bareword into a reference token.
+
+    Numbers become numeric references, ``$x`` becomes a variable, ``*`` becomes a
+    wildcard, and everything else becomes a name.
+    """
+    if word == "*":
+        return Token(type="ref", kind="wildcard", value="*", pos=pos)
+    if word[:1] == "$":
+        return Token(type="ref", kind="variable", value=word[1:], pos=pos)
+    if _DIGITS.match(word):
+        return Token(type="ref", kind="number", value=int(word), pos=pos)
+    return Token(type="ref", kind="name", value=word, pos=pos)
+
+
+def _read_string(text: str, start: int) -> tuple[Token, int]:
+    """Read a quoted string starting at ``start`` (which points at the quote).
+
+    Returns the resulting name token and the index just past the closing quote.
+    """
+    quote = text[start]
+    i = start + 1
+    chars: list[str] = []
+    n = len(text)
+    while i < n and text[i] != quote:
+        if text[i] == "\\" and i + 1 < n:
+            chars.append(text[i + 1])
+            i += 2
+        else:
+            chars.append(text[i])
+            i += 1
+    if i >= n:
+        message = "Unterminated quoted string"
+        raise LinoSyntaxError(message, start)
+    token = Token(type="ref", kind="name", value="".join(chars), pos=start, quoted=True)
+    return token, i + 1
+
+
+def tokenize(text: str) -> list[Token]:
+    """Split LiNo source text into a flat list of tokens."""
+    tokens: list[Token] = []
+    i = 0
+    n = len(text)
+    while i < n:
+        ch = text[i]
+        if ch in _WHITESPACE:
+            i += 1
+        elif ch == "(":
+            tokens.append(Token(type="lparen", pos=i))
+            i += 1
+        elif ch == ")":
+            tokens.append(Token(type="rparen", pos=i))
+            i += 1
+        elif ch == ":":
+            tokens.append(Token(type="colon", pos=i))
+            i += 1
+        elif ch in ('"', "'"):
+            token, nxt = _read_string(text, i)
+            tokens.append(token)
+            i = nxt
+        else:
+            start = i
+            chars: list[str] = []
+            while i < n and text[i] not in _WHITESPACE:
+                if text[i] in _DELIMITERS:
+                    break
+                chars.append(text[i])
+                i += 1
+            tokens.append(_classify_word("".join(chars), start))
+    return tokens
+
+
+@dataclass
+class _Cursor:
+    """A parser cursor over a flat token list."""
+
+    tokens: list[Token]
+    index: int = 0
+
+    def peek(self) -> Token | None:
+        if self.index < len(self.tokens):
+            return self.tokens[self.index]
+        return None
+
+    def advance(self) -> Token:
+        token = self.tokens[self.index]
+        self.index += 1
+        return token
+
+
+def _reference_node(token: Token) -> Ref:
+    """Build a reference AST node from a reference token."""
+    assert token.kind is not None
+    assert token.value is not None
+    return Ref(kind=token.kind, value=token.value)
+
+
+def _parse_value(cursor: _Cursor) -> Node:
+    """Parse a single value (a reference or a parenthesized link)."""
+    token = cursor.peek()
+    if token is None:
+        message = "Unexpected end of input"
+        raise LinoSyntaxError(message, -1)
+    if token.type == "lparen":
+        return _parse_link(cursor)
+    if token.type == "ref":
+        cursor.advance()
+        return _reference_node(token)
+    message = f"Unexpected '{token.type}'"
+    raise LinoSyntaxError(message, token.pos)
+
+
+def _parse_link(cursor: _Cursor) -> Link:
+    """Parse a link: ``(`` [ value ``:`` ] values... ``)``."""
+    cursor.advance()  # consume '('
+    nxt = cursor.peek()
+    if nxt is not None and nxt.type == "rparen":
+        cursor.advance()
+        return Link(id=None, values=[])
+    first = _parse_value(cursor)
+    link_id: Node | None = None
+    values: list[Node] = []
+    nxt = cursor.peek()
+    if nxt is not None and nxt.type == "colon":
+        cursor.advance()  # consume ':'
+        link_id = first
+    else:
+        values.append(first)
+    while True:
+        nxt = cursor.peek()
+        if nxt is None or nxt.type == "rparen":
+            break
+        values.append(_parse_value(cursor))
+    closing = cursor.peek()
+    if closing is None or closing.type != "rparen":
+        message = "Expected )"
+        raise LinoSyntaxError(message, closing.pos if closing is not None else -1)
+    cursor.advance()  # consume ')'
+    return Link(id=link_id, values=values)
+
+
+def parse(text: str) -> list[Node]:
+    """Parse LiNo source text into a list of top-level AST nodes."""
+    if not isinstance(text, str):
+        message = "LiNo input must be a string"
+        raise LinoSyntaxError(message, -1)
+    cursor = _Cursor(tokens=tokenize(text))
+    values: list[Node] = []
+    while cursor.index < len(cursor.tokens):
+        values.append(_parse_value(cursor))
+    return values
+
+
+def _quote_name(name: str) -> str:
+    """Quote a name for output if it contains structure-significant characters."""
+    if name == "" or _QUOTE_REQUIRED.search(name):
+        escaped = name.replace("\\", "\\\\").replace('"', '\\"')
+        return f'"{escaped}"'
+    return name
+
+
+def _serialize_ref(node: Ref) -> str:
+    """Serialize a reference node to LiNo text."""
+    if node.kind == "variable":
+        return f"${node.value}"
+    if node.kind == "wildcard":
+        return "*"
+    if node.kind == "number":
+        return str(node.value)
+    return _quote_name(str(node.value))
+
+
+def serialize(node: Node) -> str:
+    """Serialize an AST node (reference or link) back to LiNo text."""
+    if isinstance(node, Ref):
+        return _serialize_ref(node)
+    body = " ".join(serialize(value) for value in node.values)
+    if node.id is not None:
+        link_id = serialize(node.id)
+        return f"({link_id}: {body})" if body else f"({link_id}:)"
+    return f"({body})"
+
+
+def serialize_all(nodes: list[Node], joiner: str = "\n") -> str:
+    """Serialize a list of top-level nodes to LiNo text, joined by ``joiner``."""
+    return joiner.join(serialize(node) for node in nodes)

linksql/names.py

@@ -0,0 +1,72 @@
+"""Named references.
+
+Link indices are convenient for machines but opaque to humans. A :class:`Names`
+registry maps human-readable labels to link identities (mirroring the sidecar
+``<db>.names.links`` file used by link-cli) so a query can say
+``(alice loves bob)`` instead of ``(7 9 8)``.
+
+A freshly-named identity is materialised as a *point* — the link ``(i: i i)`` —
+so that everything in the model remains a link. When ``auto_create`` is disabled,
+referring to an unknown name is an error instead, which is useful for catching
+typos in production schemas.
+
+This module is a faithful, behaviourally-identical port of ``src/names.js`` from
+the JavaScript reference implementation.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .store import LinksStore
+
+
+class UnknownNameError(Exception):
+    """Error raised when an unknown name is used while auto-creation is off."""
+
+    def __init__(self, name: str) -> None:
+        super().__init__(f"Unknown named reference: {name}")
+        self.name = name
+
+
+class Names:
+    """A bidirectional registry of label <-> link-index associations."""
+
+    def __init__(self, store: LinksStore, *, auto_create: bool = True) -> None:
+        self.store = store
+        self.auto_create = auto_create
+        self.by_name: dict[str, int] = {}
+        self.by_index: dict[int, str] = {}
+
+    def resolve(self, name: str) -> int | None:
+        """Resolve a name to its index without creating anything."""
+        return self.by_name.get(name)
+
+    def ensure(self, name: str) -> int:
+        """Resolve a name, allocating and materialising it when permitted."""
+        existing = self.by_name.get(name)
+        if existing is not None:
+            return existing
+        if not self.auto_create:
+            raise UnknownNameError(name)
+        index = self.store.allocate_index()
+        self.bind(name, index)
+        if not self.store.has(index):
+            self.store.create(index=index, source=index, target=index)
+        return index
+
+    def bind(self, name: str, index: int) -> int:
+        """Associate a name with an existing index (no materialisation)."""
+        self.by_name[name] = index
+        self.by_index[index] = name
+        self.store.reserve_index(index)
+        return index
+
+    def name_of(self, index: int) -> str | None:
+        """Look up the label associated with an index."""
+        return self.by_index.get(index)
+
+    def entries(self) -> list[tuple[str, int]]:
+        """Return all ``[name, index]`` associations in insertion order."""
+        return list(self.by_name.items())

linksql/protocol.py

@@ -0,0 +1,225 @@
+"""LinksQL wire protocol — Links Notation as the data transfer format.
+
+The issue (and the PR review) is explicit: Links Notation, not JSON, is the
+actual data protocol. Every structured value that crosses the network — query
+reports, link lists, introspection snapshots — travels as Links Notation text.
+Inside a process we still work with plain Python values (dataclasses, dicts,
+lists, scalars), so this module is the single boundary that converts between the
+two::
+
+    value   --encode-->  "((operation update) (created ()) ...)"
+    "(...)"  --decode-->  value
+
+This is a faithful, behaviourally-identical port of the ``lino-objects-codec``
+convention used by the JavaScript reference implementation (see ``js/src``):
+
+- an object becomes a link of key/value pairs: ``((key value) (key value) ...)``
+- an array becomes a link of its elements: ``(a b c)``
+- an empty object or array becomes ``()``
+- ``None`` becomes ``null``; numbers and booleans become their literal text
+- strings are escaped only when they contain whitespace, quotes, parentheses,
+  colons or newlines
+
+Decoding reuses the engine's own LiNo parser (:mod:`linksql.lino`) and then
+applies the codec's "all-pairs means object, otherwise array" rule.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import re
+
+from .lino import Link as LinkNode
+from .lino import Node, Ref, parse
+
+# The canonical content type for Links Notation payloads.
+LINO_CONTENT_TYPE = "application/lino"
+# The opt-in content type for the JSON projection of a payload.
+JSON_CONTENT_TYPE = "application/json"
+
+# A reference needs escaping when it contains whitespace, quotes, parentheses,
+# or a colon (mirrors the codec's ``/[\s()'":]/`` test plus an explicit newline).
+_NEEDS_ESCAPING = re.compile(r"[\s()'\":]")
+
+
+def escape_reference(value: object) -> str:  # noqa: PLR0911
+    """Escape a scalar value for use as a Links Notation reference.
+
+    Faithful port of ``escapeReference`` from ``lino-objects-codec``: numbers and
+    booleans pass through, and strings are wrapped only when they contain
+    structure-significant characters, preferring whichever quote minimises
+    internal escaping.
+    """
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, (int, float)):
+        return _number_to_text(value)
+
+    text = str(value)
+    if not (_NEEDS_ESCAPING.search(text) or "\n" in text):
+        return text
+
+    has_single = "'" in text
+    has_double = '"' in text
+    if has_single and not has_double:
+        return f'"{text}"'
+    if has_double and not has_single:
+        return f"'{text}'"
+    if has_single and has_double:
+        single_count = text.count("'")
+        double_count = text.count('"')
+        if double_count < single_count:
+            return '"' + text.replace('"', '""') + '"'
+        return "'" + text.replace("'", "''") + "'"
+    # Just spaces or other special characters: single-quote by default.
+    return f"'{text}'"
+
+
+def _number_to_text(value: float) -> str:
+    """Render a number the way JavaScript's ``String(value)`` would.
+
+    Integers (and integer-valued floats) print without a trailing ``.0`` so the
+    encoding matches the JavaScript reference byte-for-byte.
+    """
+    if isinstance(value, bool):  # defensive; bool handled by callers first
+        return "true" if value else "false"
+    if isinstance(value, int):
+        return str(value)
+    if value.is_integer():
+        return str(int(value))
+    return repr(value)
+
+
+def _to_jsonable(value: object) -> object:
+    """Project dataclasses (and nested ones) onto plain dict/list/scalar values.
+
+    ``encode`` accepts the engine's report dataclasses directly; this keeps the
+    conversion boundary in one place while preserving field order.
+    """
+    if dataclasses.is_dataclass(value) and not isinstance(value, type):
+        return {
+            field.name: _to_jsonable(getattr(value, field.name))
+            for field in dataclasses.fields(value)
+        }
+    if isinstance(value, dict):
+        return {key: _to_jsonable(item) for key, item in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [_to_jsonable(item) for item in value]
+    return value
+
+
+def encode(value: object) -> str:
+    """Encode a Python value (or report dataclass) as Links Notation text."""
+    return _encode_jsonable(_to_jsonable(value))
+
+
+def _encode_jsonable(value: object) -> str:  # noqa: PLR0911
+    """Encode an already-projected JSON-shaped value as Links Notation."""
+    if value is None:
+        return "null"
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, (int, float)):
+        return _number_to_text(value)
+    if isinstance(value, str):
+        return escape_reference(value)
+    if isinstance(value, list):
+        if not value:
+            return "()"
+        return "(" + " ".join(_encode_jsonable(item) for item in value) + ")"
+    if isinstance(value, dict):
+        if not value:
+            return "()"
+        pairs = [
+            f"({escape_reference(key)} {_encode_jsonable(item)})"
+            for key, item in value.items()
+        ]
+        return "(" + " ".join(pairs) + ")"
+    # Fallback for unknown types, matching the codec.
+    return escape_reference(str(value))
+
+
+def _parse_reference(ref: Ref) -> object:
+    """Parse a reference node into its primitive value (true/false/null/num/str)."""
+    if ref.kind == "number":
+        return ref.value
+    text = str(ref.value)
+    if text == "true":
+        return True
+    if text == "false":
+        return False
+    if text == "null":
+        return None
+    if text.strip() != "":
+        try:
+            number = float(text)
+        except ValueError:
+            number = None
+        if number is not None:
+            return int(number) if number.is_integer() else number
+    return text
+
+
+def _is_pair(child: Node) -> bool:
+    """Whether a node is a key/value pair with a string-like key (object entry)."""
+    if not isinstance(child, LinkNode) or len(child.values) != 2:
+        return False
+    key = child.values[0]
+    if not isinstance(key, Ref):
+        return False
+    key_value = _parse_reference(key)
+    return not isinstance(key_value, (int, float))
+
+
+def _convert(node: Node) -> object:
+    """Convert a parsed LiNo node into a JSON-shaped value (codec semantics)."""
+    if isinstance(node, Ref):
+        return _parse_reference(node)
+    # A link with no values is either the empty link () -> [] or a lone reference.
+    if not node.values:
+        if node.id is None:
+            return []
+        return (
+            _parse_reference(node.id) if isinstance(node.id, Ref) else _convert(node.id)
+        )
+    # All children are key/value pairs -> object; otherwise an array.
+    if all(_is_pair(child) for child in node.values):
+        result: dict[str, object] = {}
+        for child in node.values:
+            assert isinstance(child, LinkNode)
+            key = _parse_reference(child.values[0])  # type: ignore[arg-type]
+            result[str(key)] = _convert(child.values[1])
+        return result
+    return [_convert(value) for value in node.values]
+
+
+def decode(lino: str) -> object:
+    """Decode Links Notation text back into a JSON-shaped Python value."""
+    if not isinstance(lino, str) or not lino:
+        return None
+    nodes = parse(lino)
+    if not nodes:
+        return None
+    result = _convert(nodes[0])
+    # Unwrap a single primitive the parser wrapped in a one-element list.
+    if (
+        isinstance(result, list)
+        and len(result) == 1
+        and isinstance(result[0], (str, int, float, bool, type(None)))
+    ):
+        return result[0]
+    return result
+
+
+def prefers_json(header: str | None) -> bool:
+    """Whether a caller's ``Accept``/``Content-Type`` header opts into JSON.
+
+    Links Notation is always the default; JSON is only used when a client asks
+    for it explicitly, and Links Notation wins when both are present.
+    """
+    if not header:
+        return False
+    lower = header.lower()
+    if LINO_CONTENT_TYPE in lower:
+        return False
+    return "application/json" in lower or "text/json" in lower