sqlite-ursula 0.11.3.dev0__py3-none-any.whl

sqlite_ursula/__init__.py

@@ -0,0 +1,77 @@
+"""SQLite replicated through an Ursula stream by the sqlite-ursula-vfs loadable extension
+(clients/sqlite-vfs), for the stdlib ``sqlite3`` module. The Python peer of the npm package
+``@tonbo/sqlite-ursula``.
+
+A commit is local: the extension appends it to a log it owns and replicates the log to the stream
+in the background. ``db.synced()`` is the output gate::
+
+    import sqlite_ursula
+
+    db = sqlite_ursula.open("https://streams.example.com/acme/notes")
+    db.execute("CREATE TABLE IF NOT EXISTS notes(body TEXT)")
+    db.execute("INSERT INTO notes VALUES (?)", ("hello",))
+    db.commit()
+    db.synced()  # this database's commits are in the stream, and this process still owns it
+
+``aopen`` and ``db.asynced()`` are the same calls for asyncio, and ``gate`` / ``agate`` wrap a
+block of work in the gate.
+
+Module map:
+
+- ``_host``: where the extension is, whether this Python can load it (``host_unsupported``), and
+  loading it.
+- ``_control``: the process's control connection, calls of the extension's SQL functions,
+  ``classify``, which asks the extension (``ursula_classify``) what a failure is, and the fork
+  state.
+- ``_events``: the events thread, which waits for the extension's events and resolves
+  ``synced()`` and ``asynced()``, completes ``open()`` and ``aopen()``, and runs the reset
+  callbacks.
+- ``_connection``: :class:`UrsulaConnection`, the ``sqlite3.Connection`` subclass ``open``
+  returns, and its cursor, whose statements classify their errors.
+- ``_open``: :func:`open`, :func:`aopen`, :func:`import_sqlite` and :func:`set_token`.
+- ``_gate``: :func:`gate` and :func:`agate`, which hold a block's outcome until ``synced()``.
+- ``_args``: the checks of their arguments, and of ``synced()``'s, as ``invalid_argument``.
+- ``_doctor``: ``python -m sqlite_ursula``, which says whether this Python can host the extension.
+- ``errors``: the four error classes.
+- ``langgraph``: LangGraph's SQLite checkpointers and stores on a replicated database, for the
+  ``langgraph`` extra. The package never imports it.
+"""
+
+from __future__ import annotations
+
+from ._connection import UrsulaConnection
+from ._connection import UrsulaCursor
+from ._gate import agate
+from ._gate import gate
+from ._open import Imported
+from ._open import aopen
+from ._open import import_sqlite
+from ._open import open  # noqa: A004 - the package's entry point, as Node's `open`
+from ._open import set_token
+from .errors import Action
+from .errors import UrsulaError
+from .errors import UrsulaResetError
+from .errors import UrsulaSetupError
+from .errors import UrsulaUnavailableError
+from .errors import UrsulaWriteRefusedError
+
+__version__ = "0.11.3.dev0"
+
+__all__ = [
+    "Action",
+    "Imported",
+    "UrsulaConnection",
+    "UrsulaCursor",
+    "UrsulaError",
+    "UrsulaResetError",
+    "UrsulaSetupError",
+    "UrsulaUnavailableError",
+    "UrsulaWriteRefusedError",
+    "__version__",
+    "agate",
+    "aopen",
+    "gate",
+    "import_sqlite",
+    "open",
+    "set_token",
+]

sqlite_ursula/__main__.py

@@ -0,0 +1,7 @@
+"""``python -m sqlite_ursula``: the host check (``_doctor``)."""
+
+import sys
+
+from ._doctor import main
+
+sys.exit(main())

sqlite_ursula/_args.py

@@ -0,0 +1,39 @@
+"""The checks of the arguments the package takes, shared by ``open`` and the connection's calls: a
+value it cannot take is ``invalid_argument`` (``fix``), never a ``TypeError`` from deeper down."""
+
+from __future__ import annotations
+
+import math
+import threading
+
+from .errors import UrsulaSetupError
+
+
+def invalid(message: str) -> UrsulaSetupError:
+    return UrsulaSetupError(f"invalid_argument: {message}", "invalid_argument", "fix")
+
+
+def seconds(name: str, value: object, *, positive: bool) -> float:
+    """``value``, a number of seconds: positive, or zero or more, and at most what a wait takes
+    (``threading.TIMEOUT_MAX``)."""
+    if isinstance(value, bool) or not isinstance(value, (int, float)) or math.isnan(value):
+        raise invalid(f"{name} must be a number of seconds, not {value!r}")
+    if value < 0 or (positive and value == 0):
+        raise invalid(f"{name} must be {'positive' if positive else 'zero or more'}, not {value!r}")
+    if value > threading.TIMEOUT_MAX:
+        raise invalid(
+            f"{name} must be at most {threading.TIMEOUT_MAX:g} s, not {value!r}: for no limit, "
+            "pass None where the call takes it"
+        )
+    return float(value)
+
+
+def limit(timeout: object) -> float | None:
+    """A wait's ``timeout``: zero or more seconds, or ``None`` for no limit."""
+    return None if timeout is None else seconds("timeout", timeout, positive=False)
+
+
+def flag(name: str, value: object) -> bool:
+    if not isinstance(value, bool):
+        raise invalid(f"{name} must be a boolean, not {value!r}")
+    return value

sqlite_ursula/_connection.py

@@ -0,0 +1,368 @@
+"""The connection ``open`` returns: a ``sqlite3.Connection`` subclass, so every library that takes
+one (LangGraph's ``SqliteSaver`` among them) takes it, and ``isinstance`` holds.
+
+``Connection.execute``, ``commit`` and ``__exit__`` call SQLite directly, not through
+``cursor()``, so the subclass overrides them along with ``cursor``, and its cursor overrides
+``execute*`` and ``fetch*``. Each raises what ``classify`` (``_control``) makes of its error: an
+:class:`UrsulaError` for a failure of the extension, every other error unchanged. On top of
+``sqlite3.Connection`` it has ``name``, ``path``, ``synced()``, ``asynced()``, ``status()`` and the
+reset callbacks.
+
+A refused write or a reset is one of SQLite's I/O errors, on which SQLite rolls back the whole
+transaction. A transaction helper's ``ROLLBACK`` then fails with "cannot rollback - no transaction
+is active", and one that runs ``COMMIT`` in a ``finally`` block, as LangGraph's ``SqliteStore``
+does, fails with "cannot commit - no transaction is active". Either would replace the error the
+caller needs. So the connection remembers an :class:`UrsulaError` after which no transaction is
+open, until a statement succeeds. A ``ROLLBACK`` run through ``execute`` that finds no transaction
+then succeeds, since nothing is left to roll back. Through ``executescript``, which may hold more
+statements after it, it raises the remembered error instead, and so do a ``COMMIT`` or ``END`` that
+finds no transaction and a ``ROLLBACK TO`` or ``RELEASE`` that finds no savepoint. The legacy
+``rollback()`` and ``commit()`` methods run nothing when no transaction is open. ``open()`` refuses
+``autocommit=False``, the mode in which the connection is always in a transaction (see ``_open``),
+and so does setting ``autocommit`` to ``False`` on a connection ``open()`` made.
+
+In a child forked after the parent made the connection, its overridden calls raise ``forked``,
+and ``close()`` does nothing: the file and its locks are the parent's. Its other methods
+(``backup``, ``blobopen``, ``serialize`` and the like) are ``sqlite3.Connection``'s, and the
+extension guards the bound file under them.
+"""
+
+from __future__ import annotations
+
+import logging
+import sqlite3
+import urllib.parse
+from collections.abc import Callable
+from typing import Any
+from typing import TypeVar
+
+from . import _control
+from . import _events
+from ._args import invalid
+from .errors import UrsulaError
+from .errors import UrsulaResetError
+from .errors import again
+
+log = logging.getLogger("sqlite_ursula")
+
+#: SQLITE_ERROR: a SQL error, and every error of an Ursula SQL function.
+SQLITE_ERROR = 1
+#: SQLite's message for a ROLLBACK and for a COMMIT or END, and the start of its message for a
+#: ROLLBACK TO or RELEASE, that finds no transaction or savepoint.
+NO_TRANSACTION = "cannot rollback - no transaction is active"
+NO_COMMIT = "cannot commit - no transaction is active"
+NO_SAVEPOINT = "no such savepoint: "
+
+T = TypeVar("T")
+
+#: ``sqlite3.Connection``'s ``autocommit`` attribute (Python 3.12 or newer), or ``None``.
+_AUTOCOMMIT: Any = vars(sqlite3.Connection).get("autocommit")
+
+
+def autocommit_false() -> UrsulaError:
+    """The refusal of ``autocommit=False``, as an ``open()`` argument or set later."""
+    return invalid(
+        "autocommit=False keeps the connection in a transaction, where a refused COMMIT is "
+        "hidden by the ROLLBACK that follows it: use the default transaction control, "
+        "isolation_level=None, or autocommit=True"
+    )
+
+
+ResetCallback = Callable[[UrsulaResetError], object]
+
+
+def database_of(path: str, read_only: bool) -> str:
+    """``sqlite3.connect``'s ``database`` for the bound file ``path``: a ``mode=ro`` URI, which
+    takes ``uri=True``, for a read-only connection."""
+    return f"file:{urllib.parse.quote(path)}?mode=ro" if read_only else path
+
+
+class UrsulaCursor(sqlite3.Cursor):
+    """A ``sqlite3.Cursor`` whose statements raise what their errors classify as."""
+
+    def _run(
+        self, f: Callable[..., T], *args: Any, rolled_back: Callable[[], T] | None = None
+    ) -> T:
+        run = getattr(self.connection, "_run", None)
+        if run is None:
+            return f(*args)
+        return run(f, *args, rolled_back=rolled_back)
+
+    def execute(self, sql: str, parameters: Any = (), /) -> UrsulaCursor:
+        return self._run(super().execute, sql, parameters, rolled_back=lambda: self)
+
+    def executemany(self, sql: str, parameters: Any, /) -> UrsulaCursor:
+        return self._run(super().executemany, sql, parameters, rolled_back=lambda: self)
+
+    def executescript(self, script: str, /) -> UrsulaCursor:
+        return self._run(super().executescript, script)
+
+    def fetchone(self) -> Any:
+        return self._run(super().fetchone)
+
+    def fetchmany(self, size: int | None = None) -> list[Any]:
+        if size is None:
+            return self._run(super().fetchmany)
+        return self._run(super().fetchmany, size)
+
+    def fetchall(self) -> list[Any]:
+        return self._run(super().fetchall)
+
+    def __next__(self) -> Any:
+        return self._run(super().__next__)
+
+
+class UrsulaConnection(sqlite3.Connection):
+    """A connection to a database a stream holds.
+
+    Statements are local: commit, then call :meth:`synced` before anything outside the process
+    acts on what you wrote or read. Keep it open while a framework uses :attr:`path`: the binding
+    retires once its last connection closes.
+
+    Made with ``sqlite3.connect(..., factory=UrsulaConnection)`` outside ``open()`` it binds
+    nothing, classifies nothing, and works as a ``sqlite3.Connection``.
+    """
+
+    #: The stream's path, such as ``/acme/notes``, or ``""`` for a connection ``open()`` did not
+    #: make.
+    name: str
+    #: The local database file the extension bound, as ``status()["path"]`` reports it: the path
+    #: a framework opens with ``sqlite3.connect`` to use the same database.
+    path: str
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        database = args[0] if args else kwargs.get("database", "")
+        self.name = ""
+        self.path = str(database)
+        self._bound = False
+        self._read_only = False
+        self._busy = 5.0
+        self._generation = _control.generation()
+        self._closed = False
+        self._listeners: list[ResetCallback] = []
+        #: The reset this connection knows of, from an event, a statement or ``synced()``.
+        self._reset: UrsulaResetError | None = None
+        self._fired = False
+        #: An UrsulaError after which no transaction was open, until a statement succeeds.
+        self._rolled_back: UrsulaError | None = None
+
+    def _bind(self, name: str, path: str, read_only: bool, busy: float) -> None:
+        """``open()``: the connection is on the binding of stream ``name``, whose file is
+        ``path``, read-only when ``read_only``, with the busy timeout ``busy`` in seconds."""
+        self.name = name
+        self.path = path
+        self._bound = True
+        self._read_only = read_only
+        self._busy = busy
+        _events.track(self)
+
+    if _AUTOCOMMIT is not None:
+
+        @property
+        def autocommit(self) -> Any:
+            return _AUTOCOMMIT.__get__(self, type(self))
+
+        @autocommit.setter
+        def autocommit(self, value: Any) -> None:
+            if self._bound and value is False:
+                raise autocommit_false()
+            _AUTOCOMMIT.__set__(self, value)
+
+    # The statements.
+
+    def cursor(self, factory: Any = None) -> Any:
+        self._check_fork()
+        return super().cursor(UrsulaCursor if factory is None else factory)
+
+    def execute(self, sql: str, parameters: Any = (), /) -> Any:
+        return self.cursor().execute(sql, parameters)
+
+    def executemany(self, sql: str, parameters: Any, /) -> Any:
+        return self.cursor().executemany(sql, parameters)
+
+    def executescript(self, script: str, /) -> Any:
+        return self.cursor().executescript(script)
+
+    def commit(self) -> None:
+        self._run(super().commit)
+
+    def rollback(self) -> None:
+        self._run(super().rollback)
+
+    def __exit__(self, *exc: Any) -> Any:
+        return self._run(super().__exit__, *exc)
+
+    def close(self) -> None:
+        """Closes the connection. Once a binding's last connection closes, replication drains in the
+        background and the binding retires. Use ``open()`` to use the database again.
+
+        In a child forked after the parent made the connection it closes nothing, since a thread of
+        the parent may have held the file's locks at the fork, and keeps the connection so that
+        collecting it closes nothing either.
+        """
+        if self._inherited():
+            if not self._closed:
+                self._closed = True
+                _control._inherited.append(self)
+            return
+        super().close()
+        if not self._closed:
+            self._closed = True
+            if self._bound:
+                _events.untrack(self)
+
+    # What the extension adds.
+
+    def synced(self, timeout: float | None = None) -> None:
+        """Returns once the stream holds every commit this process logged on this database before
+        the call, and a round trip that started after the call found this process still the owner
+        (design: Synced). Call it before anything outside the process acts on what you wrote or
+        read.
+
+        It covers every connection of the process on this database (:attr:`path`), a framework's
+        included, and no other database: gate each one an output depends on. It raises
+        ``TimeoutError`` after ``timeout`` seconds (``None``: no limit), while the commits keep
+        replicating, and an :class:`UrsulaResetError` on a reset. Network failures never raise: it
+        waits. Ctrl-C interrupts it. On a reader cache it returns at once.
+        """
+        _events.synced((self,), timeout)
+
+    async def asynced(self, timeout: float | None = None) -> None:
+        """:meth:`synced` for asyncio: the same guarantee and the same errors, and it waits on the
+        event loop instead of blocking it. Cancelling it ends the wait, while the commits keep
+        replicating."""
+        await _events.asynced((self,), timeout)
+
+    def status(self) -> dict[str, Any]:
+        """``ursula_status`` of the database (design: Status)."""
+        self._check_fork()
+        return _control.call("SELECT ursula_status(?)", self.path)
+
+    def on_reset(self, callback: ResetCallback) -> ResetCallback:
+        """Runs ``callback`` once when the database is reset, with the reset error, after its
+        pending ``synced()`` calls were rejected. It runs on a thread of the package's. Returns
+        ``callback``, so it serves as a decorator."""
+        self._check_fork()
+        self._listeners.append(callback)
+        return callback
+
+    def off_reset(self, callback: ResetCallback) -> None:
+        """Removes a callback :meth:`on_reset` added."""
+        self._check_fork()
+        if callback in self._listeners:
+            self._listeners.remove(callback)
+
+    # The events thread's.
+
+    def _reset_by(self, error: UrsulaResetError) -> None:
+        """The database was reset: its callbacks run once."""
+        self._remember(error)
+        if self._fired or self._closed:
+            return
+        self._fired = True
+        for callback in list(self._listeners):
+            try:
+                callback(self._reset)
+            except Exception:
+                log.exception("an on_reset callback of %s raised", self.name)
+
+    def _current_reset(self) -> UrsulaResetError | None:
+        """The reset ``ursula_status`` reports, if any."""
+        try:
+            reset = self.status().get("reset")
+        except Exception:
+            return None
+        return None if reset is None else _events.reset_error(reset)
+
+    # Classification.
+
+    def _inherited(self) -> bool:
+        """Whether the connection is the parent's: bound before a fork this process came from."""
+        return self._bound and self._generation != _control.generation()
+
+    def _check_fork(self) -> None:
+        if self._inherited():
+            raise _control.forked_error()
+
+    def _usable(self) -> None:
+        """Before a wait: raises ``forked`` in a forked child, and the reset the connection knows
+        of."""
+        self._check_fork()
+        if self._reset is not None:
+            raise again(self._reset)
+
+    def _remember(self, error: UrsulaResetError) -> None:
+        """The first reset the connection learns of, which every later wait raises."""
+        if self._reset is None:
+            self._reset = error
+
+    def _in_transaction(self) -> bool:
+        try:
+            return self.in_transaction
+        except sqlite3.ProgrammingError:
+            return True
+
+    def _classify(self, error: BaseException) -> BaseException:
+        if not self._bound:
+            return error
+        classified = _control.classify(error, self.path)
+        if isinstance(classified, UrsulaResetError):
+            self._remember(classified)
+        return classified
+
+    def _run(
+        self, f: Callable[..., T], *args: Any, rolled_back: Callable[[], T] | None = None
+    ) -> T:
+        """Runs ``f``, a method that runs a statement, and raises what its error classifies as.
+        ``rolled_back`` is what it returns for a ROLLBACK that found no transaction after an
+        UrsulaError, when it can report one."""
+        self._check_fork()
+        try:
+            result = f(*args)
+        except sqlite3.Error as error:
+            remembered = self._rolled_back
+            # SQLite tells these errors from others by their message alone: they are SQLITE_ERROR.
+            if remembered is not None and getattr(error, "sqlite_errorcode", None) == SQLITE_ERROR:
+                message = str(error)
+                if message == NO_TRANSACTION and rolled_back is not None:
+                    self._rolled_back = None
+                    return rolled_back()
+                if message in (NO_TRANSACTION, NO_COMMIT) or message.startswith(NO_SAVEPOINT):
+                    raise again(remembered) from remembered.__cause__
+            classified = self._classify(error)
+            if isinstance(classified, UrsulaError) and not self._in_transaction():
+                self._rolled_back = classified
+            if classified is error:
+                raise
+            raise classified from error
+        self._rolled_back = None
+        return result
+
+
+def bound(db: object, caller: str) -> UrsulaConnection:
+    """``db``, which ``caller`` (a gate, an adapter) takes: ``invalid_argument`` unless ``open()``
+    made it, and ``forked`` in a child forked after the parent made it."""
+    if not isinstance(db, UrsulaConnection) or not db._bound:
+        raise invalid(f"{caller} takes connections open() made, not {db!r}")
+    db._check_fork()
+    return db
+
+
+def on_binding(db: UrsulaConnection, cls: type[UrsulaConnection]) -> tuple[str, dict[str, Any]]:
+    """``sqlite3.connect``'s ``database`` and keywords for another connection on the binding of
+    ``db``, for an adapter's own connection, also one a library makes on a thread of its own, as
+    aiosqlite does.
+
+    The connection is of class ``cls``, a subclass of ``UrsulaConnection``, and bound as ``db``
+    is, so its statements raise what their errors classify as and it learns of a reset, it is
+    read-only when ``db`` is, and its busy timeout is ``db``'s. Like any connection on
+    ``db.path``, it keeps the binding while it is open."""
+    name, path, read_only, busy = db.name, db.path, db._read_only, db._busy
+
+    def factory(*args: Any, **kwargs: Any) -> UrsulaConnection:
+        conn = cls(*args, **kwargs)
+        conn._bind(name, path, read_only, busy)
+        return conn
+
+    return database_of(path, read_only), {"factory": factory, "uri": read_only, "timeout": busy}

sqlite_ursula/_control.py

@@ -0,0 +1,199 @@
+"""The process's control connection, the one way the package calls the extension's SQL functions
+on it, ``classify``, and what a fork leaves of the process's state.
+
+The registry of bound databases and the replication driver are the process's: one control
+connection serves every thread. Its calls are short, since every call that could wait is made with
+timeout 0, or on a connection of its own outside the lock (:func:`call_waiting`), so one lock
+serializes them. The events thread (``_events``) takes the same lock while it applies events, so a
+request or a ticket is registered before any event about it applies.
+
+A fork copies the process without its threads. A child forked after the parent started the
+extension (an open or an import) is marked forked, and the package's calls in it (``open``,
+``import_sqlite``, ``set_token``) raise ``forked`` at once, before they could touch a lock that
+another thread of the parent held at the fork. So do the calls of a connection the parent made
+(``_connection``), whose ``close()`` touches nothing. A child forked before that starts the
+extension as any process does. A platform without ``fork`` (Windows) registers no hook.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sqlite3
+import threading
+from collections.abc import Sequence
+from typing import Any
+
+from . import _host
+from .errors import UrsulaError
+from .errors import UrsulaSetupError
+from .errors import error_of
+from .errors import find_wrapped
+
+_lock = threading.RLock()
+_control: sqlite3.Connection | None = None
+_library: _host.Library | None = None
+#: Whether this process started the extension: an open or an import ran.
+_started = False
+#: Whether this process is a child forked after its parent started the extension.
+_forked = False
+#: Increases at each fork in the child: a connection made before it is the parent's.
+_generation = 0
+#: What a fork left in the child: kept, never closed, since a thread of the parent may have held
+#: their locks at the fork.
+_inherited: list[object] = []
+
+
+def lock() -> threading.RLock:
+    """The lock of the control connection and of the events' state."""
+    return _lock
+
+
+def generation() -> int:
+    """This process's generation: a connection made under another one belongs to the parent."""
+    return _generation
+
+
+def forked_error() -> UrsulaSetupError:
+    """``forked``: what the guarded calls (``open``, ``import_sqlite``, ``set_token`` and the
+    overridden calls of an inherited connection) raise in a child forked after the parent started
+    the extension."""
+    return UrsulaSetupError(
+        "forked: this process forked after its parent opened an Ursula database, and the "
+        "databases and the replication of the parent are not this process's: open databases "
+        "after the fork (gunicorn's post_fork hook, Celery's worker_process_init signal, or "
+        "multiprocessing's spawn or forkserver start method)",
+        "forked",
+        "fix",
+    )
+
+
+def check_fork() -> None:
+    """Raises ``forked`` in a child forked after the parent started the extension."""
+    if _forked:
+        raise forked_error()
+
+
+def start() -> None:
+    """Marks the extension started: a child forked from now on is forked."""
+    global _started
+    check_fork()
+    _started = True
+
+
+def library() -> _host.Library:
+    """The library the process loaded, loading it first."""
+    control()
+    assert _library is not None
+    return _library
+
+
+def control() -> sqlite3.Connection:
+    """The control connection, loading the extension at the first call."""
+    global _control, _library
+    check_fork()
+    with _lock:
+        if _control is None:
+            lib = _host.library()
+            _control = _host.connection(lib)
+            _library = lib
+        return _control
+
+
+def connection() -> sqlite3.Connection:
+    """A new connection with the process's extension loaded, for a call that waits."""
+    return _host.connection(library())
+
+
+def parsed(text: object) -> Any:
+    """A SQL function's JSON result."""
+    return json.loads(text) if isinstance(text, str) and text else None
+
+
+def call(sql: str, *args: object) -> Any:
+    """One of the extension's SQL functions on the control connection: its JSON result, or its
+    error as what :func:`classify` makes of it."""
+    db = control()
+    with _lock:
+        return _result(db, sql, args)
+
+
+def call_waiting(sql: str, *args: object) -> Any:
+    """:func:`call` for a function that can wait (``ursula_cancel`` while a disk job of the open
+    runs, ``ursula_import``): on a connection of its own, outside the lock, so the events thread
+    and the other calls go on meanwhile."""
+    db = connection()
+    try:
+        return _result(db, sql, args)
+    finally:
+        db.close()
+
+
+def _result(db: sqlite3.Connection, sql: str, args: tuple[object, ...]) -> Any:
+    try:
+        row = db.execute(sql, args).fetchone()
+    except sqlite3.Error as error:
+        classified = classify(error, None)
+        if classified is error:
+            raise
+        raise classified from error
+    return parsed(row[0] if row else None)
+
+
+def classify(error: BaseException, path: str | None) -> BaseException:
+    """What to raise for ``error``, which a statement or an Ursula SQL function raised.
+
+    The :class:`UrsulaError` of what the extension's ``ursula_classify`` makes of it, or ``error``
+    itself when the extension says it is not its failure (a constraint, a syntax error, an I/O
+    error of a database used through ``ATTACH DATABASE``). ``path`` is the bound database the
+    statement ran on, whose state names a statement's I/O error, which says nothing.
+    """
+    if isinstance(error, UrsulaError) or not isinstance(error, sqlite3.Error):
+        return error
+    code = getattr(error, "sqlite_errorcode", None)
+    db = _control
+    if not isinstance(code, int) or db is None or _forked:
+        return error
+    try:
+        with _lock:
+            row = db.execute("SELECT ursula_classify(?, ?, ?)", (str(error), code, path)).fetchone()
+        named = parsed(row[0] if row else None)
+    except (sqlite3.Error, ValueError):
+        return error
+    if not isinstance(named, dict):
+        return error
+    return error_of(named, str(named.get("message", error)), error)
+
+
+def classify_wrapped(error: BaseException, paths: Sequence[str | None]) -> BaseException:
+    """:func:`classify` for an error a library may have wrapped: the first error of the chain
+    :func:`find_wrapped` walks that is an :class:`UrsulaError`, or that the extension classifies
+    on one of ``paths`` (the first that names it), as that :class:`UrsulaError`. So a failure of the
+    extension never passes for the wrapper's own kind of error. ``error`` itself otherwise."""
+
+    def match(next_: BaseException) -> UrsulaError | None:
+        if isinstance(next_, UrsulaError):
+            return next_
+        for path in paths:
+            classified = classify(next_, path)
+            if isinstance(classified, UrsulaError):
+                return classified
+        return None
+
+    found = find_wrapped(error, match)
+    return error if found is None else found
+
+
+def _after_fork_in_child() -> None:
+    global _lock, _control, _forked, _generation
+    _lock = threading.RLock()
+    _generation += 1
+    if _control is not None:
+        _inherited.append(_control)
+    _control = None
+    if _started:
+        _forked = True
+
+
+if hasattr(os, "register_at_fork"):
+    os.register_at_fork(after_in_child=_after_fork_in_child)