execsql2 2.30.0__py3-none-any.whl → 2.31.1__py3-none-any.whl

execsql/exporters/ods.py

@@ -13,6 +13,7 @@ import datetime
 import decimal
 import getpass
 import os
+import re
 from pathlib import Path
 from typing import Any
 
@@ -184,42 +185,25 @@ class OdsFile:
         if not sheet:
             raise OdsFileError(f"There is no sheet named {sheetname}")
 
-        def row_data(sheetrow):
-            # Adapted from http://www.marco83.com/work/wp-content/uploads/2011/11/odf-to-array.py
-            cells = sheetrow.getElementsByType(of.table.TableCell)
-            rowdata = []
-            for cell in cells:
-                p_content = []
-                repeat = cell.getAttribute("numbercolumnsrepeated")
-                if not repeat:
-                    repeat = 1
-                    spanned = int(cell.getAttribute("numbercolumnsspanned") or 0)
-                    if spanned > 1:
-                        repeat = spanned
-                ps = cell.getElementsByType(of.text.P)
-                if len(ps) == 0:
-                    for _rr in range(int(repeat)):
-                        p_content.append(None)
-                else:
-                    for p in ps:
-                        pval = str(p)
-                        if len(pval) == 0:
-                            for _rr in range(int(repeat)):
-                                p_content.append(None)
-                        else:
-                            for _rr in range(int(repeat)):
-                                p_content.append(pval)
-                if len(p_content) == 0:
-                    for _rr in range(int(repeat)):
-                        rowdata.append(None)
-                elif p_content[0] != "#":
-                    rowdata.extend(p_content)
-            return rowdata
-
-        rows = sheet.getElementsByType(of.table.TableRow)
-        if junk_header_rows > 0:
-            rows = rows[junk_header_rows:]
-        return [row_data(r) for r in rows]
+        rows: list[list | None] = []
+        pending_empty = 0
+        for sheetrow in sheet.getElementsByType(of.table.TableRow):
+            data = _row_values(sheetrow)
+            repeat = int(sheetrow.getAttribute("numberrowsrepeated") or 1)
+            if not data:
+                # Empty rows are kept only when data follows them, so the
+                # filler rows a spreadsheet writes below the data are dropped.
+                pending_empty += repeat
+                continue
+            rows.extend(None for _ in range(pending_empty))
+            pending_empty = 0
+            rows.extend(list(data) for _ in range(repeat))
+        rows = rows[junk_header_rows:]
+        # Every row is as wide as the widest, so a blank trailing header is
+        # still seen, and an empty row inside the data is a row of NULLs that
+        # EMPTY_ROWS keeps or drops.
+        width = max((len(r) for r in rows if r is not None), default=0)
+        return [(r or []) + [None] * (width - len(r or [])) for r in rows]
 
     def new_sheet(self, sheetname: str) -> Any:
         """Create and return a detached sheet object that can later be added to the workbook."""
@@ -239,7 +223,11 @@ class OdsFile:
         for item in datarow:
             if isinstance(item, bool):
                 # Booleans must be evaluated before numbers.
-                tc = of.table.TableCell(valuetype="boolean", value=1 if item else 0, stylename=style_name)
+                tc = of.table.TableCell(
+                    valuetype="boolean",
+                    booleanvalue="true" if item else "false",
+                    stylename=style_name,
+                )
             elif isinstance(item, float | int | decimal.Decimal):
                 # Decimal belongs here: PostgreSQL, MySQL and DuckDB all return it
                 # for numeric/decimal columns.  Without it the value fell to the
@@ -269,8 +257,11 @@ class OdsFile:
                     item.microsecond,
                     item.tzinfo,
                 )
-                tc = of.table.TableCell(timevalue=timeval.strftime("PT%HH%MM%S.%fS"), stylename="iso_datetime")
-                tc.addElement(of.text.P(text=timeval.strftime("%H:%M:%S.%f")))
+                tc = of.table.TableCell(
+                    valuetype="time",
+                    timevalue=timeval.strftime("PT%HH%MM%S.%fS"),
+                    stylename="iso_datetime",
+                )
             elif isinstance(item, str):
                 # An XML parser normalises a newline inside an attribute to a
                 # space, so office:string-value cannot carry one.  ODF's answer
@@ -280,16 +271,23 @@ class OdsFile:
                     tc = of.table.TableCell(valuetype="string", stylename=style_name)
                 else:
                     tc = of.table.TableCell(valuetype="string", stringvalue=item, stylename=style_name)
+            elif item is None:
+                # An empty cell: no value type, no value, no text.
+                tc = of.table.TableCell(stylename=style_name)
             else:
-                tc = of.table.TableCell(value=item, stylename=style_name)
+                tc = of.table.TableCell(valuetype="string", stringvalue=str(item), stylename=style_name)
             if item is not None:
                 if isinstance(item, str) and ("\n" in item or "\r" in item):
                     # Previously these were flattened to spaces, silently changing
                     # the exported value.
                     for line in item.replace("\r\n", "\n").replace("\r", "\n").split("\n"):
                         tc.addElement(of.text.P(text=line))
+                elif isinstance(item, datetime.time):
+                    tc.addElement(of.text.P(text=item.strftime("%H:%M:%S.%f")))
                 else:
-                    tc.addElement(of.text.P(text=item))
+                    # str(): odfpy writes no text for a falsy value, so 0 and
+                    # False showed as blank cells.
+                    tc.addElement(of.text.P(text=str(item)))
             tr.addElement(tc)
 
     def add_sheet(self, of_table: Any) -> None:
@@ -311,6 +309,113 @@ class OdsFile:
         self.wbk = None
 
 
+def _paragraph_text(node: Any) -> str:
+    """Return the text of a ``<text:p>``, expanding ODF's space, tab and line-break elements."""
+    parts: list[str] = []
+    for child in node.childNodes:
+        if child.nodeType == child.TEXT_NODE:
+            parts.append(str(child))
+        elif child.qname == (of.text.TEXTNS, "s"):
+            parts.append(" " * int(child.getAttribute("c") or 1))
+        elif child.qname == (of.text.TEXTNS, "tab"):
+            parts.append("\t")
+        elif child.qname == (of.text.TEXTNS, "line-break"):
+            parts.append("\n")
+        else:
+            parts.append(_paragraph_text(child))
+    return "".join(parts)
+
+
+def _time_text(duration: str) -> str:
+    """Convert an ODF time value (``PT13H05M09.5S``) to ``13:05:09.5``."""
+    m = re.fullmatch(r"-?PT(\d+)H(\d+)M(\d+)(\.\d*)?S", duration)
+    if not m:
+        return duration
+    hours, minutes, seconds, fraction = m.groups()
+    fraction = (fraction or "").rstrip("0").rstrip(".")
+    return f"{int(hours):02d}:{int(minutes):02d}:{int(seconds):02d}{fraction}"
+
+
+def _cell_value(cell: Any) -> str | None:
+    """Return a cell's stored value as text, or ``None`` for an empty cell.
+
+    The value comes from the cell's ``office:value-type`` and value
+    attribute, not from its displayed text, so a number formatted to two
+    places, a percentage or a date keeps its full value.
+    """
+    vtype = cell.getAttribute("valuetype")
+    value: str | None
+    if vtype in ("float", "percentage", "currency"):
+        value = cell.getAttribute("value")
+    elif vtype == "date":
+        value = cell.getAttribute("datevalue")
+    elif vtype == "time":
+        value = cell.getAttribute("timevalue")
+        value = _time_text(value) if value else value
+    elif vtype == "boolean":
+        value = cell.getAttribute("booleanvalue")
+        if not value:
+            # Files from execsql2 2.30 and earlier wrote office:value="1"/"0".
+            flag = cell.getAttribute("value")
+            value = {"1": "true", "0": "false"}.get(flag or "", flag)
+    else:
+        value = None
+    if value:
+        return value
+    if vtype == "string":
+        value = cell.getAttribute("stringvalue")
+        if value:
+            return value
+    # A string cell, a cell with no type, or a typed cell missing its value
+    # attribute: the paragraphs are the value, one line each.
+    paragraphs = [
+        _paragraph_text(child) for child in cell.childNodes if getattr(child, "qname", None) == (of.text.TEXTNS, "p")
+    ]
+    text = "\n".join(paragraphs)
+    return text or None
+
+
+def _row_values(sheetrow: Any) -> list:
+    """Return one value per column of a ``<table:table-row>``, without trailing empty cells."""
+    values: list = []
+    pending_empty = 0
+    covered_by_span = 0
+    for cell in sheetrow.childNodes:
+        qname = getattr(cell, "qname", None)
+        if qname == (of.table.TABLENS, "table-cell"):
+            covered = False
+        elif qname == (of.table.TABLENS, "covered-table-cell"):
+            covered = True
+        else:
+            continue
+        repeat = int(cell.getAttribute("numbercolumnsrepeated") or 1)
+        if covered:
+            # A horizontal merge repeats its value across the columns it
+            # covers (below); covered cells left over belong to a merge from
+            # a row above and are empty in this row.
+            skip = min(repeat, covered_by_span)
+            covered_by_span -= skip
+            repeat -= skip
+            value = None
+        else:
+            value = _cell_value(cell)
+            spanned = int(cell.getAttribute("numbercolumnsspanned") or 1)
+            if spanned > 1:
+                covered_by_span = spanned - 1
+                repeat *= spanned
+        if repeat <= 0:
+            continue
+        if value is None:
+            # Counted rather than appended, so a trailing filler cell
+            # repeated across the whole sheet width costs nothing.
+            pending_empty += repeat
+            continue
+        values.extend([None] * pending_empty)
+        pending_empty = 0
+        values.extend([value] * repeat)
+    return values
+
+
 def export_ods(
     outfile: str,
     hdrs: list[str],

execsql/exporters/values.py

@@ -9,6 +9,7 @@ for loading data into a database from a plain SQL file.
 """
 
 import decimal
+import re
 from typing import Any
 
 import execsql.state as _state
@@ -20,11 +21,146 @@ from execsql.utils.fileio import filewriter_close
 __all__ = ["export_values", "write_query_to_values"]
 
 
-def _sql_literal(value: Any) -> str:
+# How each DBMS joins strings and writes a character by its code.  A text
+# value that execsql would misread when a script runs the file with INCLUDE (see
+# _text_literal) is written as pieces joined this way.  (template, joiner, char)
+_CONCAT: dict[str, tuple[str, str, str]] = {
+    "MySQL": ("CONCAT({})", ", ", "CHAR({} USING utf8mb4)"),
+    "SQL Server": ("({})", " + ", "CHAR({})"),
+    "Access": ("({})", " & ", "Chr({})"),
+    "SQLite": ("({})", " || ", "char({})"),
+    "Firebird": ("({})", " || ", "ASCII_CHAR({})"),
+}
+# PostgreSQL, DuckDB, Oracle, and an ODBC DSN.
+_CONCAT_DEFAULT = ("({})", " || ", "CHR({})")
+
+# What execsql acts on when it runs the file: a line break (a line of the
+# value could end the statement with ';' or start a '-- !x!' metacommand)
+# and the start of a substitution variable (!!x!!, !'!x!'!, !"!x!"!, !{x}!).
+_RX_UNSAFE = re.compile(r"\r\n|\r|\n|!(?=!|'!|\"!|\{)")
+_LINE_BREAK_CODES = {"\r\n": (13, 10), "\r": (13,), "\n": (10,)}
+
+# Column names written quoted: PostgreSQL's reserved key words, which cover
+# the names other DBMSs also reject bare, plus KEY and INDEX (MySQL).
+_RESERVED = frozenset(
+    [
+        "ALL",
+        "ANALYSE",
+        "ANALYZE",
+        "AND",
+        "ANY",
+        "ARRAY",
+        "AS",
+        "ASC",
+        "ASYMMETRIC",
+        "BOTH",
+        "CASE",
+        "CAST",
+        "CHECK",
+        "COLLATE",
+        "COLUMN",
+        "CONSTRAINT",
+        "CREATE",
+        "CURRENT_CATALOG",
+        "CURRENT_DATE",
+        "CURRENT_ROLE",
+        "CURRENT_TIME",
+        "CURRENT_TIMESTAMP",
+        "CURRENT_USER",
+        "DEFAULT",
+        "DEFERRABLE",
+        "DESC",
+        "DISTINCT",
+        "DO",
+        "ELSE",
+        "END",
+        "EXCEPT",
+        "FALSE",
+        "FETCH",
+        "FOR",
+        "FOREIGN",
+        "FROM",
+        "GRANT",
+        "GROUP",
+        "HAVING",
+        "IN",
+        "INDEX",
+        "INITIALLY",
+        "INTERSECT",
+        "INTO",
+        "KEY",
+        "LATERAL",
+        "LEADING",
+        "LIMIT",
+        "LOCALTIME",
+        "LOCALTIMESTAMP",
+        "NOT",
+        "NULL",
+        "OFFSET",
+        "ON",
+        "ONLY",
+        "OR",
+        "ORDER",
+        "PLACING",
+        "PRIMARY",
+        "REFERENCES",
+        "RETURNING",
+        "SELECT",
+        "SESSION_USER",
+        "SOME",
+        "SYMMETRIC",
+        "SYSTEM_USER",
+        "TABLE",
+        "THEN",
+        "TO",
+        "TRAILING",
+        "TRUE",
+        "UNION",
+        "UNIQUE",
+        "USER",
+        "USING",
+        "VARIADIC",
+        "WHEN",
+        "WHERE",
+        "WINDOW",
+        "WITH",
+    ],
+)
+
+
+def _text_literal(text: str, dbms: str | None) -> str:
+    """*text* as a SQL string that execsql reads back unchanged when a script runs the file with INCLUDE.
+
+    execsql reads a script line by line, substituting variables and treating
+    a ``-- !x!`` line as a metacommand and a line ending in ``;`` as the end of
+    a statement, inside a string literal too.  So a value holding a line
+    break or the start of a variable reference is written as pieces, each
+    free of both, joined in *dbms*'s syntax: ``('a' || CHR(10) || 'b')``.
+    """
+    if not _RX_UNSAFE.search(text):
+        return "'" + text.replace("'", "''") + "'"
+    template, joiner, char = _CONCAT.get(dbms or "", _CONCAT_DEFAULT)
+    pieces: list[str] = []
+    start = 0
+    for m in _RX_UNSAFE.finditer(text):
+        if m.group() == "!":  # end a piece after the '!', so no piece holds the whole marker
+            pieces.append("'" + text[start : m.end()].replace("'", "''") + "'")
+        else:
+            if m.start() > start:
+                pieces.append("'" + text[start : m.start()].replace("'", "''") + "'")
+            pieces.extend(char.format(code) for code in _LINE_BREAK_CODES[m.group()])
+        start = m.end()
+    if start < len(text):
+        pieces.append("'" + text[start:].replace("'", "''") + "'")
+    return template.format(joiner.join(pieces))
+
+
+def _sql_literal(value: Any, dbms: str | None = None) -> str:
     """Render a value as a SQL literal for an INSERT ... VALUES list.
 
     Only numbers are emitted bare.  Everything else is quoted, with embedded
-    single quotes doubled — the SQL standard escape.
+    single quotes doubled — the SQL standard escape — and text execsql would
+    misread when running the file is split into pieces (:func:`_text_literal`).
 
     Quoting is the safe default rather than the exception.  Previously anything
     that was not a string went out through ``str()`` unquoted, so a date became
@@ -40,7 +176,17 @@ def _sql_literal(value: Any) -> str:
         return "TRUE" if value else "FALSE"
     if isinstance(value, int | float | decimal.Decimal):
         return str(value)
-    return "'" + str(value).replace("'", "''") + "'"
+    return _text_literal(str(value), dbms)
+
+
+def _column_name(name: str, dbtype: Any) -> str:
+    """*name* as written in the column list: quoted if it is not a plain, unreserved identifier."""
+    if re.fullmatch(r"[A-Za-z_]\w*", name) and name.upper() not in _RESERVED:
+        return name
+    opening, closing = getattr(dbtype, "quotechars", ('"', '"'))
+    if opening == closing:
+        name = name.replace(opening, opening * 2)
+    return opening + name + closing
 
 
 def export_values(
@@ -50,9 +196,17 @@ def export_values(
     append: bool = False,
     desc: str | None = None,
     zipfile: str | None = None,
+    dbtype: Any = None,
 ) -> None:
-    """Write pre-fetched rows as SQL INSERT … VALUES statements to a file or ZIP archive."""
+    """Write pre-fetched rows as SQL INSERT … VALUES statements to a file or ZIP archive.
+
+    *dbtype* is the exporting database's :class:`~execsql.types.DbType`: its
+    identifier quotes and its string syntax are used where a name or a
+    value needs them.  With no rows, the file holds a comment instead of an
+    INSERT, which would be invalid SQL.
+    """
     conf = _state.conf
+    dbms = getattr(dbtype, "dbms_id", None)
     if outfile.lower() == "stdout":
         f = _state.output
     else:
@@ -70,17 +224,20 @@ def export_values(
     try:
         if desc is not None:
             f.write(f"-- {desc}\n")
-        f.write(f"INSERT INTO !!target_table!!\n    ({', '.join(hdrs)})\n")
-        f.write("VALUES\n")
         firstrow = True
         for r in rows:
             if firstrow:
                 firstrow = False
+                columns = ", ".join(_column_name(h, dbtype) for h in hdrs)
+                f.write(f"INSERT INTO !!target_table!!\n    ({columns})\nVALUES\n")
             else:
                 f.write(",\n")
-            quoted_row = [_sql_literal(v) for v in r]
+            quoted_row = [_sql_literal(v, dbms) for v in r]
             f.write(f"    ({', '.join(quoted_row)})")
-        f.write("\n    ;\n")
+        if firstrow:
+            f.write("-- The query returned no rows: nothing to insert.\n")
+        else:
+            f.write("\n    ;\n")
     finally:
         if outfile.lower() != "stdout":
             f.close()
@@ -101,4 +258,4 @@ def write_query_to_values(
         raise
     except Exception as e:
         raise ErrInfo("db", select_stmt, exception_msg=exception_desc()) from e
-    export_values(outfile, hdrs, rows, append, desc, zipfile=zipfile)
+    export_values(outfile, hdrs, rows, append, desc, zipfile=zipfile, dbtype=getattr(db, "type", None))

execsql/importers/base.py

@@ -107,7 +107,7 @@ def import_data_table(
         if is_new == 2:
             tblspec = db.schema_qualified_table_name(schemaname, tablename)
             try:
-                db.drop_table(tblspec)
+                db.drop_table_for_replacement(schemaname, tablename)
             except ErrInfo:
                 raise
             except Exception as e:

execsql/importers/csv.py

@@ -55,7 +55,7 @@ def importtable(
         sql = inf.create_table(db.type, schemaname, tablename)
         if is_new == 2:
             try:
-                db.drop_table(db.schema_qualified_table_name(schemaname, tablename))
+                db.drop_table_for_replacement(schemaname, tablename)
             except ErrInfo:
                 raise
             except Exception as e:

execsql/importers/ods.py

@@ -39,6 +39,8 @@ def ods_data(
         alldata = wbk.sheet_data(sheetname, junk_header_rows)
     except Exception as e:
         raise ErrInfo(type="cmd", other_msg=f"{sheetname} is not a worksheet in {filename}.") from e
+    if not alldata:
+        raise ErrInfo(type="error", other_msg=f"The input file {filename}, sheet {sheetname} contains no data.")
     colhdrs = alldata[0]
     if any(x is None or len(x.strip()) == 0 for x in colhdrs):
         if conf.del_empty_cols:

execsql/lsp/diagnostics.py

@@ -8,7 +8,7 @@ from execsql.cli.lint import Issue, filter_issues, lint_source
 
 __all__ = ["LINT_DOCS_URL", "diagnostics", "to_diagnostic", "too_deep_diagnostic"]
 
-LINT_DOCS_URL = "https://execsql2.readthedocs.io/en/latest/reference/lint/"
+LINT_DOCS_URL = "https://execsql2.readthedocs.io/en/stable/reference/lint/"
 
 _SEVERITY = {
     "error": types.DiagnosticSeverity.Error,

execsql/lsp/document.py

@@ -18,6 +18,7 @@ from pygls.uris import from_fs_path
 
 from execsql.cli.lint import variables_defined_by
 from execsql.lsp._util import RX_METACOMMAND
+from execsql.utils.paths import is_network_path
 from execsql.script.ast import IncludeDirective, MetaCommandStatement, ScriptBlock
 from execsql.script.parser import parse_string
 
@@ -195,6 +196,8 @@ def file_facts(source: str, path: str | None, base_dir: str | None = None) -> Fi
             steps.append(_ScriptCall(Location(path, row, start, end), node.target.lower()))
         elif isinstance(node, IncludeDirective):
             target = node.target.strip().strip("\"'")
+            if is_network_path(target):
+                continue  # never followed: checking it would contact the named host
             start, end = _span_of(target, text) if target else (0, len(text))
             resolved = Path(target) if Path(target).is_absolute() or script_dir is None else script_dir / target
             steps.append(_Include(Location(path, row, start, end), target, str(resolved)))

execsql/metacommands/io_fileops.py

@@ -128,7 +128,7 @@ def x_copy(**kwargs: Any) -> None:
         create_tbl = tbl_desc.create_table(db2.type, schema2, table2)
         if new_tbl2 == "replacement":
             try:
-                db2.drop_table(tbl2)
+                db2.drop_table_for_replacement(schema2, table2)
             except ErrInfo:
                 raise
             except Exception as e:
@@ -215,7 +215,7 @@ def x_copy_query(**kwargs: Any) -> None:
         create_tbl = tbl_desc.create_table(db2.type, schema2, table2)
         if new_tbl2 == "replacement":
             try:
-                db2.drop_table(tbl2)
+                db2.drop_table_for_replacement(schema2, table2)
             except ErrInfo:
                 raise
             except Exception as e:
@@ -370,8 +370,14 @@ def x_serve(**kwargs: Any) -> None:
         contenttype = "application/zip"
     else:
         contenttype = "application/octet-stream"
-    print(f"Content-Type: {contenttype}")
     safe_fname = fname.replace("\r", "").replace("\n", "").replace('"', '\\"')
-    print(f'Content-Disposition: attachment; filename="{safe_fname}"\n')
+    headers = f'Content-Type: {contenttype}\nContent-Disposition: attachment; filename="{safe_fname}"\n\n'
+    # Headers and body go to the same binary stream, after anything already
+    # written as text: under CGI stdout is a pipe, and text printed into the
+    # text layer's buffer reached it after the body.
+    sys.stdout.flush()
+    out = sys.stdout.buffer
+    out.write(headers.encode(sys.stdout.encoding or "utf-8"))
     with open(infname, "rb") as f:
-        copyfileobj(f, sys.stdout.buffer)
+        copyfileobj(f, out)
+    out.flush()

execsql/metacommands/reference.py

@@ -30,7 +30,7 @@ __all__ = [
     "to_snippet",
 ]
 
-DOCS_URL = "https://execsql2.readthedocs.io/en/latest/reference/"
+DOCS_URL = "https://execsql2.readthedocs.io/en/stable/reference/"
 
 
 @dataclass(frozen=True)

execsql/metacommands/upsert.py

@@ -421,7 +421,7 @@ def _export_failures_if_requested(
 
 def _handle_pg_upsert_errors(fn: Any, metacommandline: str | None) -> Any:
     """Run *fn*, translating pg-upsert exceptions to ErrInfo."""
-    from pg_upsert import UserCancelledError
+    from pg_upsert import PgUpsertError, UserCancelledError
 
     try:
         return fn()
@@ -433,6 +433,15 @@ def _handle_pg_upsert_errors(fn: Any, metacommandline: str | None) -> Any:
         ) from exc
     except ErrInfo:
         raise
+    except PgUpsertError as exc:
+        # The run was rolled back.  The variables describe this failed run,
+        # not whatever an earlier PG_UPSERT left in them.
+        _set_subvars(exc.result)
+        raise ErrInfo(
+            "cmd",
+            command_text=metacommandline,
+            other_msg=f"PG_UPSERT rolled back after a database error: {exc.original}",
+        ) from exc
     except Exception as exc:
         raise ErrInfo(
             "exception",

execsql/utils/auth.py

@@ -88,22 +88,30 @@ _DEFAULT_PORTS = {"PostgreSQL": 5432, "MySQL": 3306, "SQL Server": 1433, "Oracle
 _plaintext_warned: bool = False
 
 
+def _storing_backend(backend: Any) -> Any:
+    """The backend a password saved through *backend* lands in.
+
+    keyring's ``ChainerBackend`` saves to the first of its backends (highest
+    priority first) that accepts it, such as the macOS Keychain ahead of a
+    ``keyrings.alt`` file.
+    """
+    chained = getattr(backend, "backends", None)
+    return chained[0] if chained else backend
+
+
 def is_plaintext_keyring() -> bool:
-    """Return True if the active keyring backend stores secrets in cleartext.
-
-    B20/F040: on headless Linux without a real Secret Service, the
-    ``keyrings.alt.file.PlaintextKeyring`` (or
-    ``EncryptedKeyring`` with a hard-coded passphrase) backend is
-    used silently. Detect by inspecting the active backend's module
-    path so callers can warn the user instead of pretending secrets
-    are encrypted.
+    """Return True if a password stored now would be written in cleartext.
+
+    That is ``keyrings.alt``'s ``PlaintextKeyring``: on headless Linux with no
+    Secret Service, keyring falls back to it silently.  Its encrypted
+    sibling (a master password protects the file), the Windows backends and
+    keyring's ``fail`` placeholder (which stores nothing) are not.
     """
     try:
         import keyring
 
-        backend = keyring.get_keyring()
-        module = type(backend).__module__
-        return "keyrings.alt" in module or "fail" in module.lower()
+        cls = type(_storing_backend(keyring.get_keyring()))
+        return cls.__module__.startswith("keyrings.alt") and cls.__name__ == "PlaintextKeyring"
     except Exception:
         return False
 
@@ -118,11 +126,10 @@ def _warn_if_plaintext_keyring() -> None:
         import keyring
         import sys
 
-        backend_name = type(keyring.get_keyring()).__name__
+        backend_name = type(_storing_backend(keyring.get_keyring())).__name__
         print(
             f"WARNING: active keyring backend ({backend_name}) stores secrets in "
-            f"cleartext or with a hard-coded key. Stored passwords are not "
-            f"meaningfully protected.",
+            f"cleartext. Stored passwords are not meaningfully protected.",
             file=sys.stderr,
         )
     except Exception:

execsql/utils/errors.py

@@ -37,7 +37,7 @@ __all__ = [
     "install_hint",
 ]
 
-_ADDING_AN_EXTRA = "https://execsql2.readthedocs.io/en/latest/getting-started/installation/#adding-an-extra-later"
+_ADDING_AN_EXTRA = "https://execsql2.readthedocs.io/en/stable/getting-started/installation/#adding-an-extra-later"
 
 
 def install_hint(extra: str) -> str: