async-sonic 0.1.0__py3-none-any.whl

async_sonic/__init__.py

@@ -0,0 +1,548 @@
+"""Asyncio client for Sonic (https://github.com/valeriansaliou/sonic), zero dependencies.
+
+Usage: ``async with Sonic("localhost", 1491, "password") as sonic: await sonic.query(...)``.
+Full documentation in README.md and llms.txt.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import re
+from collections import deque
+from typing import Self
+
+__all__ = [
+    "Sonic",
+    "SonicConnectionError",
+    "SonicError",
+    "SonicProtocolError",
+    "SonicServerError",
+    "SonicTimeout",
+    "quote",
+]
+
+
+class SonicError(Exception):
+    """Base class of every error raised by this library."""
+
+
+class SonicConnectionError(SonicError):
+    """Could not connect, or the connection dropped or is closed.
+
+    In-flight commands on that connection fail with this; the next command opens a new one.
+    """
+
+
+class SonicTimeout(SonicConnectionError):
+    """`connect_timeout` (while connecting) or `timeout` (per command) expired."""
+
+
+class SonicServerError(SonicError):
+    """Sonic answered `ERR <code>(<detail>)`. `.code` is the code, `.line` the whole line."""
+
+    def __init__(self, line: str) -> None:
+        match = re.match(r"ERR (\w+)", line)
+        self.line = line
+        self.code = match.group(1) if match else ""
+        hint = _HINTS.get(self.code, "")
+        super().__init__(f"Sonic rejected the command: {line}" + (f". {hint}" if hint else ""))
+
+
+class SonicProtocolError(SonicError):
+    """Sonic said something PROTOCOL.md does not cover (incompatible version?). The connection is closed."""
+
+
+_HINTS = {
+    "authentication_failed": "Wrong password: use `channel.auth_password` from sonic.cfg.",
+    "invalid_format": "Invalid command format: if you only use the public API this is an "
+    "async-sonic bug; please open an issue with the text you sent.",
+    "policy_reject": "Value outside the server limits (limit/offset/text): check "
+    "`[search]` and `[store]` in sonic.cfg.",
+    "unknown_command": "This Sonic version does not know that command.",
+    "not_found": "Sonic does not know that resource or action (e.g. trigger: consolidate, backup, restore).",
+}
+_BUFFER = re.compile(r"buffer\((\d+)\)")
+_KV = re.compile(r"(\w+)\((-?\d+)\)")
+
+
+def quote(text: str) -> str:
+    """Quote text for PUSH/POP/QUERY/SUGGEST. E.g. ``quote('say "hi"')``.
+
+    PROTOCOL.md only requires `\\"` for quotes; the backslash is doubled so that a trailing
+    backslash cannot swallow the closing quote. Newlines become spaces: a raw newline would
+    end the command halfway (Sonic tokenizes on spaces, so no word is lost).
+    """
+    flat = text.replace("\r\n", " ").replace("\n", " ").replace("\r", " ")
+    return '"' + flat.replace("\\", "\\\\").replace('"', '\\"') + '"'
+
+
+def _token(value: str, what: str) -> str:
+    if not value or any(c.isspace() or c == '"' or not c.isprintable() for c in value):
+        raise ValueError(
+            f"Invalid {what} {value!r}: it cannot be empty or contain whitespace, quotes or "
+            "control characters. Use a short name such as 'videos' or 'video:42'."
+        )
+    return value
+
+
+def _opts(*, limit: int | None = None, offset: int | None = None, lang: str | None = None) -> str:
+    out = ""
+    if limit is not None:
+        out += f" LIMIT({int(limit)})"
+    if offset is not None:
+        out += f" OFFSET({int(offset)})"
+    if lang is not None:
+        if not lang.isalpha():
+            raise ValueError(f"Invalid lang {lang!r}: use an ISO 639-3 code ('eng') or 'none'.")
+        out += f" LANG({lang})"
+    return out
+
+
+def _settle(fut: asyncio.Future[str], value: str | Exception) -> None:
+    if not fut.done():
+        if isinstance(value, Exception):
+            fut.set_exception(value)
+        else:
+            fut.set_result(value)
+
+
+class _Conn:
+    """One TCP connection in one mode, with a background reader.
+
+    Pipelining: every command is written without waiting. Immediate replies (OK, RESULT,
+    PONG, PENDING <id>, ERR) arrive in order, so a FIFO of futures matches them. The `EVENT`
+    lines of QUERY/SUGGEST/LIST (PROTOCOL.md: they may arrive out of order) are matched by id.
+    A command whose timeout expires leaves its slot in the queue/table: the late reply is
+    discarded on arrival, so the connection never gets out of sync.
+    """
+
+    def __init__(self, reader: asyncio.StreamReader, writer: asyncio.StreamWriter) -> None:
+        self._reader, self._writer = reader, writer
+        self.buffer = 0
+        self.load = 0  # active calls, used to pick a connection
+        self.timeout = 10.0
+        self.gate: asyncio.Semaphore | None = None
+        self._fifo: deque[tuple[asyncio.Future[str], str | None]] = deque()
+        self._events: dict[str, tuple[asyncio.Future[str], str]] = {}
+        self._task: asyncio.Task[None] | None = None
+        self.closed = False
+
+    @classmethod
+    async def open(
+        cls,
+        host: str,
+        port: int,
+        password: str,
+        mode: str,
+        *,
+        connect_timeout: float,
+        timeout: float,
+        max_in_flight: int | None,
+    ) -> _Conn:
+        where = f"{host}:{port}"
+        try:
+            async with asyncio.timeout(connect_timeout):
+                reader, writer = await asyncio.open_connection(host, port, limit=1 << 20)
+                conn = cls(reader, writer)
+                try:
+                    greeting = await conn._readline()
+                    if not greeting.startswith("CONNECTED "):
+                        raise SonicProtocolError(
+                            f"{where} does not speak the Sonic protocol (greeting {greeting!r}): "
+                            "check that the port is the Sonic Channel one (1491 by default)."
+                        )
+                    writer.write(f"START {mode} {password}\n".encode())
+                    started = await conn._readline()
+                    match = _BUFFER.search(started)
+                    if not started.startswith(f"STARTED {mode} ") or match is None:
+                        raise SonicProtocolError(f"Unexpected reply to START: {started!r}")
+                    conn.buffer = int(match.group(1))
+                except BaseException:
+                    writer.close()
+                    raise
+        except TimeoutError:
+            raise SonicTimeout(
+                f"Timeout ({connect_timeout}s) connecting to Sonic at {where}: check "
+                "host/port or raise `connect_timeout`."
+            ) from None
+        except OSError as exc:
+            raise SonicConnectionError(
+                f"Could not connect to Sonic at {where} ({exc}): check that Sonic is "
+                "running and that host and port are correct."
+            ) from exc
+        conn.timeout = timeout
+        conn.gate = asyncio.Semaphore(max_in_flight) if max_in_flight else None
+        conn._task = asyncio.create_task(conn._run())
+        return conn
+
+    async def _readline(self) -> str:
+        try:
+            raw = await self._reader.readline()
+        except ValueError as exc:  # longer than `limit`
+            raise SonicProtocolError("Sonic sent a line longer than 1 MiB") from exc
+        except OSError as exc:
+            raise SonicConnectionError(f"Lost the connection to Sonic ({exc}).") from exc
+        if not raw.endswith(b"\n"):
+            raise SonicConnectionError(
+                "Sonic closed the connection (restart, `tcp_timeout` or crash): the next "
+                "command will open a new connection."
+            )
+        line = raw.decode(errors="replace").rstrip("\r\n")
+        if line.startswith("ENDED authentication_failed") and self._task is None:
+            raise SonicServerError("ERR authentication_failed")  # this is how Sonic answers START
+        if line.startswith("ENDED "):
+            raise SonicConnectionError(f"Sonic ended the session ({line}).")
+        if line.startswith("ERR ") and self._task is None:  # during the handshake
+            raise SonicServerError(line)
+        return line
+
+    async def _run(self) -> None:
+        exc: Exception
+        try:
+            while True:
+                self._dispatch(await self._readline())
+        except SonicError as e:
+            exc = e
+        except Exception as e:  # ponytail: anything unexpected also closes the connection
+            exc = SonicProtocolError(f"Internal error while reading from Sonic: {e!r}")
+        self._shutdown(exc)
+
+    def _dispatch(self, line: str) -> None:
+        if line.startswith("EVENT "):
+            parts = line.split(" ", 3)
+            entry = self._events.pop(parts[2], None) if len(parts) > 2 else None
+            if entry is None:
+                raise SonicProtocolError(f"EVENT without a previous PENDING: {line!r}")
+            fut, name = entry
+            if parts[1] != name:
+                _settle(fut, SonicProtocolError(f"Expected EVENT {name}, got {line!r}"))
+            else:
+                _settle(fut, parts[3] if len(parts) > 3 else "")
+            return
+        if not self._fifo:
+            raise SonicProtocolError(f"Reply with no pending command: {line!r}")
+        fut, event = self._fifo.popleft()
+        if line.startswith("ERR "):
+            _settle(fut, SonicServerError(line))
+        elif event is None and not line.startswith("PENDING "):
+            _settle(fut, line)
+        elif event is not None and line.startswith("PENDING "):
+            self._events[line.removeprefix("PENDING ").strip()] = (fut, event)
+        else:
+            _settle(fut, SonicProtocolError(f"Unexpected reply: {line!r}"))
+
+    def _shutdown(self, exc: Exception) -> None:
+        self.closed = True
+        self._writer.close()
+        pending = [f for f, _ in self._fifo] + [f for f, _ in self._events.values()]
+        self._fifo.clear()
+        self._events.clear()
+        for fut in pending:
+            _settle(fut, exc)
+
+    async def call(self, line: str, event: str | None = None) -> str:
+        """One command. With `event`, returns what follows `EVENT <event> <id>`; without it, the
+        first reply line."""
+        if self.closed:
+            raise SonicConnectionError(
+                "Connection closed: open a new `async with Sonic(...)`, or call again "
+                "(the pool opens a new connection)."
+            )
+        data = line.encode() + b"\n"
+        if len(data) > self.buffer:
+            raise ValueError(
+                f"Command of {len(data)} bytes; the buffer Sonic announces is {self.buffer}. "
+                "Shorten the text (PUSH splits it on its own; QUERY/SUGGEST/POP do not)."
+            )
+        self.load += 1
+        try:
+            if self.gate is not None:
+                await self.gate.acquire()
+            try:
+                fut: asyncio.Future[str] = asyncio.get_running_loop().create_future()
+                self._fifo.append(
+                    (fut, event)
+                )  # queue and write with no await in between: same order
+                self._writer.write(data)
+                try:
+                    async with asyncio.timeout(self.timeout):
+                        await self._writer.drain()
+                        return await fut
+                except TimeoutError:
+                    raise SonicTimeout(
+                        f"Sonic did not answer {line[:40]!r} within {self.timeout}s: raise `timeout=` "
+                        "or check the server load. The connection is still usable."
+                    ) from None
+                except OSError as exc:
+                    raise SonicConnectionError(f"Lost the connection to Sonic ({exc}).") from exc
+                finally:
+                    fut.cancel()
+            finally:
+                if self.gate is not None:
+                    self.gate.release()
+        finally:
+            self.load -= 1
+
+    async def close(self, timeout: float) -> None:
+        if self.closed or self._task is None:
+            return
+        self._writer.write(b"QUIT\n")
+        try:
+            async with asyncio.timeout(timeout):
+                await self._task  # the server answers ENDED and closes
+        except TimeoutError, OSError:
+            pass
+        finally:
+            self._task.cancel()
+            self._shutdown(SonicConnectionError("Connection closed by the client."))
+
+
+class _Pool:
+    """Up to `pool_size` connections of one mode, opened on demand. Picks the least loaded."""
+
+    def __init__(self, mode: str, sonic: Sonic) -> None:
+        self.mode, self.sonic = mode, sonic
+        self.conns: list[_Conn] = []
+        self._lock = asyncio.Lock()
+
+    def _best(self) -> _Conn | None:
+        self.conns = [c for c in self.conns if not c.closed]
+        best = min(self.conns, key=lambda c: c.load, default=None)
+        if best is not None and (best.load == 0 or len(self.conns) >= self.sonic.pool_size):
+            return best
+        return None
+
+    async def get(self) -> _Conn:
+        if (conn := self._best()) is not None:
+            return conn
+        async with self._lock:
+            if (conn := self._best()) is not None:
+                return conn
+            s = self.sonic
+            conn = await _Conn.open(
+                s.host,
+                s.port,
+                s.password,
+                self.mode,
+                connect_timeout=s.connect_timeout,
+                timeout=s.timeout,
+                max_in_flight=s.max_in_flight,
+            )
+            self.conns.append(conn)
+            return conn
+
+    async def call(self, line: str, event: str | None = None) -> str:
+        return await (await self.get()).call(line, event)
+
+    async def close(self) -> None:
+        await asyncio.gather(*(c.close(self.sonic.connect_timeout) for c in self.conns))
+        self.conns.clear()
+
+
+def _ok(reply: str) -> None:
+    if reply != "OK":
+        raise SonicProtocolError(f"Expected OK, got {reply!r}")
+
+
+def _result(reply: str) -> str:
+    if not reply.startswith("RESULT "):
+        raise SonicProtocolError(f"Expected RESULT, got {reply!r}")
+    return reply.removeprefix("RESULT ")
+
+
+def _int(reply: str) -> int:
+    text = _result(reply)
+    if not text.isdecimal():
+        raise SonicProtocolError(f"Expected an integer, got {reply!r}")
+    return int(text)
+
+
+def _split(escaped: str, room: int) -> list[str]:
+    """Split on spaces into chunks of <= room UTF-8 bytes (escaping never creates spaces)."""
+    if room < 1:
+        raise ValueError("The buffer Sonic announces leaves no room for the text")
+    chunks: list[str] = []
+    cur = ""
+    for word in escaped.split(" "):
+        size = len(word.encode())
+        if size > room:
+            raise ValueError(
+                f"A {size}-byte word does not fit in the Sonic buffer ({room} usable): "
+                "shorten or remove it before indexing."
+            )
+        joined = f"{cur} {word}" if cur else word
+        if len(joined.encode()) <= room:
+            cur = joined
+        else:
+            chunks.append(cur)
+            cur = word
+    chunks.append(cur)
+    return chunks
+
+
+class Sonic:
+    """Sonic client. Everything is a flat method; the mode (search/ingest/control), the
+    handshake and the connection pool are handled by the class.
+
+    >>> async with Sonic("localhost", 1491, "SecretPassword") as sonic:  # doctest: +SKIP
+    ...     await sonic.push("videos", "catalog", "video:1", "cats and dogs", lang="eng")
+
+    Connections: opened on first use, up to `pool_size` per channel, with pipelining (each
+    connection allows `max_in_flight` simultaneous commands; `None` = unlimited). No retries:
+    if a connection drops, its in-flight commands fail with `SonicConnectionError` and the
+    next command opens a new connection. `timeout` is per command; when it expires
+    `SonicTimeout` is raised but the connection stays alive.
+    """
+
+    def __init__(
+        self,
+        host: str = "localhost",
+        port: int = 1491,
+        password: str = "",
+        *,
+        pool_size: int = 4,
+        max_in_flight: int | None = None,
+        timeout: float = 10.0,
+        connect_timeout: float = 5.0,
+    ) -> None:
+        self.host, self.port = host, port
+        self.password = _token(password, "password") if password else ""
+        self.pool_size, self.max_in_flight = max(1, pool_size), max_in_flight
+        self.timeout, self.connect_timeout = timeout, connect_timeout
+        self._search = _Pool("search", self)
+        self._ingest = _Pool("ingest", self)
+        self._control = _Pool("control", self)
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.close()
+
+    async def close(self) -> None:
+        """Close every connection (QUIT). E.g. ``await sonic.close()``. Never raises."""
+        await asyncio.gather(self._search.close(), self._ingest.close(), self._control.close())
+
+    # -- search ---------------------------------------------------------------------
+
+    async def query(
+        self,
+        collection: str,
+        bucket: str,
+        terms: str,
+        *,
+        limit: int | None = None,
+        offset: int | None = None,
+        lang: str | None = None,
+    ) -> list[str]:
+        """Object ids matching `terms`, best first. E.g. ``await sonic.query("videos", "catalog", "cats", limit=10)``."""
+        line = (
+            f"QUERY {_token(collection, 'collection')} {_token(bucket, 'bucket')} {quote(terms)}"
+            + _opts(limit=limit, offset=offset, lang=lang)
+        )
+        return (await self._search.call(line, "QUERY")).split()
+
+    async def suggest(
+        self, collection: str, bucket: str, word: str, *, limit: int | None = None
+    ) -> list[str]:
+        """Words that complete `word`. E.g. ``await sonic.suggest("videos", "catalog", "ca")``."""
+        line = (
+            f"SUGGEST {_token(collection, 'collection')} {_token(bucket, 'bucket')} {quote(word)}"
+            + _opts(limit=limit)
+        )
+        return (await self._search.call(line, "SUGGEST")).split()
+
+    async def list_words(
+        self, collection: str, bucket: str, *, limit: int | None = None, offset: int | None = None
+    ) -> list[str]:
+        """Indexed words of the bucket (LIST enumerates words, not objects). E.g. ``await sonic.list_words("videos", "catalog", limit=50)``."""
+        line = f"LIST {_token(collection, 'collection')} {_token(bucket, 'bucket')}" + _opts(
+            limit=limit, offset=offset
+        )
+        return (await self._search.call(line, "LIST")).split()
+
+    # -- ingest ----------------------------------------------------------------------
+
+    async def push(
+        self, collection: str, bucket: str, object: str, text: str, *, lang: str | None = None
+    ) -> None:
+        """Index `text` for `object`. If it does not fit in the Sonic buffer it is split on words. E.g. ``await sonic.push("videos", "catalog", "video:1", "cats and dogs", lang="eng")``."""
+        head = f"PUSH {_token(collection, 'collection')} {_token(bucket, 'bucket')} "
+        head += f"{_token(object, 'object')} "
+        tail = _opts(lang=lang)
+        conn = await self._ingest.get()
+        room = conn.buffer - len((head + tail).encode()) - 3  # 2 quotes + newline
+        for chunk in _split(quote(text)[1:-1], room):
+            _ok(await conn.call(f'{head}"{chunk}"{tail}'))
+
+    async def pop(self, collection: str, bucket: str, object: str, text: str) -> int:
+        """Remove the words of `text` from the object; returns how many. E.g. ``await sonic.pop("videos", "catalog", "video:1", "cats")``."""
+        line = (
+            f"POP {_token(collection, 'collection')} {_token(bucket, 'bucket')} "
+            f"{_token(object, 'object')} {quote(text)}"
+        )
+        return _int(await self._ingest.call(line))
+
+    async def count(
+        self, collection: str, bucket: str | None = None, object: str | None = None
+    ) -> int:
+        """Buckets of the collection, objects of the bucket or terms of the object. E.g. ``await sonic.count("videos", "catalog")``.
+
+        Uses `COUNT`, not `COUNTC/B/O`: PROTOCOL.md lists them but Sonic v1.9.1 answers
+        `ERR unknown_command`. Note: on v1.9.1 `count(collection, bucket)` returns distinct
+        words, not objects.
+        """
+        if bucket is None and object is not None:
+            raise ValueError("count: `object` requires `bucket`.")
+        parts = [_token(collection, "collection")]
+        if bucket is not None:
+            parts.append(_token(bucket, "bucket"))
+        if object is not None:
+            parts.append(_token(object, "object"))
+        return _int(await self._ingest.call("COUNT " + " ".join(parts)))
+
+    async def flush_collection(self, collection: str) -> int:
+        """Delete the whole collection; returns how many items. E.g. ``await sonic.flush_collection("videos")``."""
+        return _int(await self._ingest.call(f"FLUSHC {_token(collection, 'collection')}"))
+
+    async def flush_bucket(self, collection: str, bucket: str) -> int:
+        """Delete a bucket. E.g. ``await sonic.flush_bucket("videos", "catalog")``."""
+        line = f"FLUSHB {_token(collection, 'collection')} {_token(bucket, 'bucket')}"
+        return _int(await self._ingest.call(line))
+
+    async def flush_object(self, collection: str, bucket: str, object: str) -> int:
+        """Delete an object (does not clean SUGGEST). E.g. ``await sonic.flush_object("videos", "catalog", "video:1")``."""
+        line = (
+            f"FLUSHO {_token(collection, 'collection')} {_token(bucket, 'bucket')} "
+            f"{_token(object, 'object')}"
+        )
+        return _int(await self._ingest.call(line))
+
+    # -- control ----------------------------------------------------------------------
+
+    async def trigger(self, action: str | None = None, data: str | None = None) -> str:
+        """`TRIGGER [action] [data]`; actions: consolidate, backup, restore. Returns the result ("" if Sonic answers OK; with no action, the list of actions). E.g. ``await sonic.trigger("consolidate")``."""
+        if action is None and data is not None:
+            raise ValueError("trigger: `data` requires `action`.")
+        line = "TRIGGER"
+        if action is not None:
+            line += " " + _token(action, "action")
+        if data is not None:
+            line += " " + _token(data, "data")
+        reply = await self._control.call(line)
+        return "" if reply == "OK" else _result(reply)
+
+    async def info(self) -> dict[str, int]:
+        """Server metrics (`uptime`, `clients_connected`...). E.g. ``(await sonic.info())["uptime"]``."""
+        return {k: int(v) for k, v in _KV.findall(_result(await self._control.call("INFO")))}
+
+    async def ping(self) -> None:
+        """Check that Sonic answers (raises otherwise). E.g. ``await sonic.ping()``."""
+        reply = await self._control.call("PING")
+        if reply != "PONG":
+            raise SonicProtocolError(f"Expected PONG, got {reply!r}")
+
+    async def help(self, manual: str | None = None) -> str:
+        """`HELP [manual]` as is. E.g. ``await sonic.help("commands")``."""
+        line = "HELP" if manual is None else f"HELP {_token(manual, 'manual')}"
+        return _result(await self._control.call(line))

async_sonic-0.1.0.dist-info/METADATA

@@ -0,0 +1,269 @@
+Metadata-Version: 2.5
+Name: async-sonic
+Version: 0.1.0
+Summary: A zero-dependency, fully typed asyncio client for the Sonic search index, with connection pooling and pipelining.
+Project-URL: Homepage, https://github.com/cr0hn/async-sonic
+Project-URL: Repository, https://github.com/cr0hn/async-sonic
+Project-URL: Issues, https://github.com/cr0hn/async-sonic/issues
+Author-email: Daniel Alfocea <cr0hn@cr0hn.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: async,asyncio,client,connection-pool,pipelining,search,sonic,sonic-search,typed
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Database :: Front-Ends
+Classifier: Topic :: Internet
+Classifier: Typing :: Typed
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+# async-sonic
+
+A zero-dependency, fully typed asyncio client for the [Sonic](https://github.com/valeriansaliou/sonic) search index, with connection pooling and pipelining.
+
+[![CI](https://github.com/cr0hn/async-sonic/actions/workflows/ci.yml/badge.svg)](https://github.com/cr0hn/async-sonic/actions/workflows/ci.yml)
+![Python 3.14+](https://img.shields.io/badge/python-3.14%2B-blue)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+LLM-friendly reference: [`llms.txt`](llms.txt).
+
+## Table of contents
+
+- [Why async-sonic](#why-async-sonic)
+- [Installation](#installation)
+- [Quickstart](#quickstart)
+- [API reference](#api-reference)
+- [Concurrency and performance](#concurrency-and-performance)
+- [Error handling](#error-handling)
+- [Escaping and limits](#escaping-and-limits)
+- [Compatibility and limitations](#compatibility-and-limitations)
+- [Development](#development)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Why async-sonic
+
+Sonic is a fast, lightweight search index that speaks a plain-text protocol
+([`PROTOCOL.md`](https://github.com/valeriansaliou/sonic/blob/master/PROTOCOL.md)).
+The asyncio client that existed on PyPI (`asonic`, last released in 2020) does not work, and
+the other clients are synchronous. `async-sonic` implements the protocol from its specification
+on top of `asyncio.open_connection` and nothing else.
+
+- **One class**: `Sonic(host, port, password)` used as `async with`, with flat, obviously named
+  methods (`push`, `query`, `suggest`, ...). Channels, handshake and pool are hidden.
+- **Fast**: a lazy per-channel connection pool plus pipelining (one background reader per
+  connection). See [the numbers](#concurrency-and-performance).
+- **Zero runtime dependencies**, Python 3.14+, strict typing, `py.typed`.
+- **Honest errors**: no hidden retries; every exception message says what happened and what to do.
+- **LLM-friendly**: short docstrings with a one-line example on every public method, plus
+  [`llms.txt`](llms.txt).
+
+## Installation
+
+```bash
+uv add async-sonic        # or: pip install async-sonic
+```
+
+The package is not on PyPI yet; until then install from Git:
+
+```bash
+uv add git+https://github.com/cr0hn/async-sonic
+# or: pip install git+https://github.com/cr0hn/async-sonic
+```
+
+## Quickstart
+
+<!-- quickstart -->
+```python
+import asyncio
+from async_sonic import Sonic
+
+
+async def main() -> None:
+    async with Sonic("localhost", 1491, "SecretPassword") as sonic:
+        await sonic.push("videos", "catalog", "video:1", "cats and dogs are funny", lang="eng")
+        await sonic.push("videos", "catalog", "video:2", "stray dogs", lang="eng")
+        print(await sonic.query("videos", "catalog", "cats", lang="eng"))
+        await sonic.trigger(
+            "consolidate"
+        )  # SUGGEST reads a graph that is only updated on consolidate
+        print(await sonic.suggest("videos", "catalog", "fun"))
+        await sonic.flush_collection("videos")
+
+
+asyncio.run(main())
+```
+Output:
+```text
+['video:1']
+['funny']
+```
+<!-- /quickstart -->
+
+This block is executed as a test against a real Sonic
+(`tests/test_integration.py::test_readme_quickstart_runs`), so it cannot drift from the code.
+To try it, start Sonic (see [Development](#development)) and use its host, port and password.
+
+## API reference
+
+`Sonic` opens nothing on construction or on `async with` entry: connections are opened lazily on
+the first command, one pool per channel.
+
+```python
+Sonic(host="localhost", port=1491, password="", *,
+      pool_size=4, max_in_flight=None, timeout=10.0, connect_timeout=5.0)
+```
+
+| Method | Sonic command | Channel | Returns |
+|---|---|---|---|
+| `query(collection, bucket, terms, *, limit, offset, lang)` | `QUERY` | search | `list[str]` object ids, best first |
+| `suggest(collection, bucket, word, *, limit)` | `SUGGEST` | search | `list[str]` words |
+| `list_words(collection, bucket, *, limit, offset)` | `LIST` | search | `list[str]` words |
+| `push(collection, bucket, object, text, *, lang)` | `PUSH` | ingest | `None` |
+| `pop(collection, bucket, object, text)` | `POP` | ingest | `int` |
+| `count(collection, bucket=None, object=None)` | `COUNT` | ingest | `int` |
+| `flush_collection(collection)` | `FLUSHC` | ingest | `int` |
+| `flush_bucket(collection, bucket)` | `FLUSHB` | ingest | `int` |
+| `flush_object(collection, bucket, object)` | `FLUSHO` | ingest | `int` |
+| `trigger(action=None, data=None)` | `TRIGGER` | control | `str` |
+| `info()` | `INFO` | control | `dict[str, int]` |
+| `ping()` | `PING` | control | `None` |
+| `help(manual=None)` | `HELP` | control | `str` |
+
+`close()` (or leaving the `async with`) sends `QUIT` on every connection. `quote(text)` is public.
+
+`lang` is an ISO 639-3 code (`"eng"`, `"spa"`) or `"none"`. If omitted, Sonic guesses the
+language of the text, and may guess differently at index and query time: pass it on both sides.
+
+Deliberate differences from the protocol:
+
+- `list_words`: Sonic's `LIST` enumerates **words** of the index, not objects.
+- `count` uses `COUNT` rather than `COUNTC/COUNTB/COUNTO` (see [Compatibility](#compatibility-and-limitations)).
+
+## Concurrency and performance
+
+A Sonic channel is a TCP connection in one mode (search, ingest or control).
+
+- **Pool**: up to `pool_size` connections per channel, opened when needed (an idle connection is
+  reused before a new one is opened). A command goes to the least loaded connection.
+- **Pipelining**: each connection writes commands without waiting for replies, and a background
+  reader task hands the replies to futures. `PROTOCOL.md` allows this: immediate replies (`OK`,
+  `RESULT`, `PONG`, `PENDING <id>`, `ERR`) arrive **in order** (a FIFO of futures), while the
+  `EVENT` lines of `QUERY`/`SUGGEST`/`LIST` may arrive **out of order** and are matched by the
+  id of their `PENDING`. `max_in_flight` caps simultaneous commands per connection
+  (`None` = unlimited, `1` = no pipelining).
+- **No retries, no magic reconnection.** If a connection drops, its in-flight commands fail with
+  `SonicConnectionError`; the *next* command opens a fresh connection. What to retry, and when,
+  is your decision (a `PUSH` is idempotent if you `flush_object` first; a `POP` is not).
+- **Per-command timeout** (`timeout`) raises `SonicTimeout`, but the connection stays usable: the
+  late reply is discarded when it arrives and nothing gets out of sync.
+
+### Measured numbers
+
+`benchmarks/bench.py`: 2000 operations per row, Sonic v1.9.1 in Docker Desktop (4 CPUs) on an
+Apple M2 Max, over localhost. **It is a single run and numbers vary from run to run**: trust the
+orders of magnitude, not the decimals.
+
+| Scenario | QUERY ops/s | PUSH ops/s |
+|---|---:|---:|
+| 1 connection, sequential | 2205 | 3061 |
+| pool of 8, concurrent, no pipelining | 10549 | 7559 |
+| 1 connection, pipelining | 13464 | 12795 |
+| pool of 8 + pipelining | 14843 | 11104 |
+
+Pipelining is the big lever: 4x to 6x over sequential. On top of it the pool did not help in
+this run (an earlier run showed +40% for queries and nothing for writes), so with pipelining one
+connection is often enough; the pool mostly matters when `max_in_flight` is capped. Over a real
+network with latency the gap to the sequential case is larger, because a round trip is paid once
+per burst instead of once per command; that was not measured.
+
+## Error handling
+
+Every exception inherits from `SonicError`; messages say what happened and what to do.
+
+| Exception | When |
+|---|---|
+| `SonicConnectionError` | could not connect, or the connection dropped, was closed or received `ENDED` |
+| `SonicTimeout` (subclass of the previous one) | `connect_timeout` or `timeout` expired |
+| `SonicServerError` | Sonic answered `ERR ...` (`.code`, `.line`); also a wrong password (`authentication_failed`) |
+| `SonicProtocolError` | Sonic said something outside `PROTOCOL.md`; the connection is closed |
+| `ValueError` (builtin) | invalid argument, or a command that does not fit in the buffer; nothing is sent |
+
+```python
+from async_sonic import Sonic, SonicServerError, SonicTimeout
+
+async with Sonic(password="SecretPassword") as sonic:
+    try:
+        await sonic.query("videos", "catalog", "cats", limit=0)
+    except SonicServerError as exc:
+        print(exc.code)  # policy_reject
+    except SonicTimeout:
+        ...  # Sonic did not answer in time; the connection is still usable
+```
+
+## Escaping and limits
+
+`quote(text)` wraps text in quotes: `"` becomes `\"`, `\` becomes `\\` (so a trailing backslash
+cannot swallow the closing quote) and newlines (`\n`, `\r`) become a space, because a raw newline
+would cut the command in two; Sonic tokenizes on whitespace, so no word is lost. Unicode goes
+through as UTF-8. `collection`, `bucket`, `object`, `action`... cannot be empty or contain
+whitespace, quotes or control characters (`ValueError`).
+
+**Buffer.** `STARTED ... buffer(N)` (20000 by default) is the limit of a whole command line,
+newline included. `PROTOCOL.md` asks clients to split: `push` does it for you, emitting several
+`PUSH` commands for the same object, always cutting **between words**. `query`, `suggest` and
+`pop` are not split (splitting would change their meaning) and raise `ValueError`, as does a
+single word longer than the buffer.
+
+## Compatibility and limitations
+
+- **Verified**: Sonic **v1.9.1** (official image `valeriansaliou/sonic:v1.9.1`) on Docker
+  Desktop, macOS arm64, Python 3.14. Every command in the table above; text with quotes,
+  backslashes, newlines, accents, CJK and emoji; a 48 KB text (split by the buffer); real `ERR`
+  replies; a wrong password; and 200 concurrent queries over the pool with pipelining.
+- **Deviations from `PROTOCOL.md` found on v1.9.1**:
+  - `COUNTC`, `COUNTB` and `COUNTO` answer `ERR unknown_command`; `COUNT` is used instead, and
+    `count(collection, bucket)` returns the number of **distinct words**, not of objects
+    (measured: 2 objects, 4 words, `count` returned 4).
+  - `SUGGEST` and `LIST` only see new words after `trigger("consolidate")`.
+  - A wrong password is answered with `ENDED authentication_failed` (surfaced as `SonicServerError`).
+  - Replies end in `\r\n`.
+- **Not verified**: other Sonic versions (the `COUNTC/B/O` commands may exist in later ones);
+  `TRIGGER backup` and `restore` (they are sent, never tested against real data); Linux and
+  Windows (CI covers Linux); sustained load or a server with many clients; network latency.
+- No TLS: Sonic Channel is plain TCP. Do not expose it to an untrusted network.
+- Searching without accents (`cancion` for `canción`) depends on the server configuration
+  (`diacritic_folding_enabled`), not on this client; the test `sonic.cfg` does not enable it.
+
+## Development
+
+```bash
+uv sync
+uv run ruff check . && uv run ruff format --check .
+uv run pyright
+uv run pytest                      # everything
+uv run pytest tests/test_unit.py   # unit tests only, no docker needed
+uv run python benchmarks/bench.py  # benchmark against a real Sonic
+```
+
+- `tests/test_unit.py` runs against a fake asyncio server (`tests/fake_sonic.py`) that speaks the
+  real protocol: handshake, out-of-order `PENDING`/`EVENT`, `ERR`, abrupt close, `ENDED`, slow
+  replies (timeouts and late replies), buffer splitting, pool and pipelining with latency.
+- `tests/test_integration.py` runs against a **real Sonic**. If `docker` is available, the
+  fixture starts `valeriansaliou/sonic:v1.9.1` with `tests/sonic.cfg` (password `SecretPassword`)
+  on a free port. **Without docker these tests are skipped with an explicit reason**
+  (`SKIPPED: docker is not available...`): always check the `skipped` count, because a green run
+  with every integration test skipped does not prove the real wiring. CI fails if any test is skipped.
+
+## Contributing
+
+Issues and pull requests are welcome; see [CONTRIBUTING.md](CONTRIBUTING.md). Please follow the
+[Code of Conduct](CODE_OF_CONDUCT.md). Security reports: [SECURITY.md](SECURITY.md).
+
+## License
+
+[MIT](LICENSE) (c) 2026 Daniel Alfocea.

async_sonic-0.1.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+async_sonic/__init__.py,sha256=OZyebH9FsTWS5nMD_AlLLFUNg0lX5GLaAE1bDsCDAwc,23088
+async_sonic/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+async_sonic-0.1.0.dist-info/METADATA,sha256=CAFhVF-rhf_uJYZdMsJAN8s1ZtZoctg99U3anfwN9w0,12948
+async_sonic-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+async_sonic-0.1.0.dist-info/licenses/LICENSE,sha256=OGBqg3l9A_6jtIsMPWPhYxqneTDWvByYlB6B_lGY_zc,1071
+async_sonic-0.1.0.dist-info/RECORD,,

async_sonic-0.1.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

async_sonic-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daniel Alfocea
+
+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.