execsql2 2.25.0__tar.gz → 2.25.1__tar.gz

{execsql2-2.25.0 → execsql2-2.25.1}/CHANGELOG.md

@@ -13,6 +13,15 @@ ______________________________________________________________________
 
 ______________________________________________________________________
 
+## [2.25.1] - 2026-10-09
+
+### Fixed
+
+- **`execsql lint` `V001` / `V002` and nested variable names:** `!!N_!!CHECK_GROUP!!_CHECKS!!` no longer reports `!!N_!!` and `!!_CHECKS!!` as undefined; the inner `!!CHECK_GROUP!!` is checked, and counts as used.
+- **`execsql lint` and `SUB_INI`:** a script whose `SUB_INI` names a FIFO or device (`/dev/zero`) no longer hangs lint, and an INI file that does not parse no longer stops it.
+
+______________________________________________________________________
+
 ## [2.25.0] - 2026-10-09
 
 ### Added

{execsql2-2.25.0 → execsql2-2.25.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: execsql2
-Version: 2.25.0
+Version: 2.25.1
 Summary: Runs a SQL script against a PostgreSQL, SQLite, MariaDB/MySQL, DuckDB, Firebird, MS-Access, MS-SQL-Server, or Oracle database, or an ODBC DSN. Provides metacommands to import and export data, copy data between databases, conditionally execute SQL and metacommands, and dynamically alter SQL and metacommands with substitution variables.
 Project-URL: Homepage, https://execsql2.readthedocs.io
 Project-URL: Repository, https://github.com/geocoug/execsql
@@ -451,7 +451,7 @@ execsql format --no-sql --in-place scripts/
 ```yaml
 repos:
   - repo: https://github.com/geocoug/execsql
-    rev: v2.25.0
+    rev: v2.25.1
     hooks:
       - id: execsql-format
       - id: execsql-lint

{execsql2-2.25.0 → execsql2-2.25.1}/README.md

@@ -320,7 +320,7 @@ execsql format --no-sql --in-place scripts/
 ```yaml
 repos:
   - repo: https://github.com/geocoug/execsql
-    rev: v2.25.0
+    rev: v2.25.1
     hooks:
       - id: execsql-format
       - id: execsql-lint

{execsql2-2.25.0 → execsql2-2.25.1}/docs/guides/formatter.md

@@ -233,7 +233,7 @@ select id,name,created_at from users where active = true order by name;
 ```yaml
 repos:
   - repo: https://github.com/geocoug/execsql
-    rev: v2.25.0
+    rev: v2.25.1
     hooks:
       - id: execsql-format
       - id: execsql-lint # optional: fail the commit on lint errors

{execsql2-2.25.0 → execsql2-2.25.1}/docs/reference/lint.md

@@ -158,7 +158,7 @@ The `execsql-lint` [pre-commit](https://pre-commit.com/) hook runs `execsql lint
 ```yaml
 repos:
   - repo: https://github.com/geocoug/execsql
-    rev: v2.25.0
+    rev: v2.25.1
     hooks:
       - id: execsql-lint
         args: [--ignore, V002] # optional: any execsql lint option
@@ -313,7 +313,7 @@ A `!!variable!!` is referenced, but nothing in the script defines it. At run tim
 
 A definition is any metacommand in the same file that sets a variable:
 
-- the SUB family: `SUB`, `SUB_EMPTY`, `SUB_ADD`, `SUB_APPEND`, `SUBDATA`, `SUB_LOCAL`, `SUB_TEMPFILE`, `SUB_ENCRYPT`, `SUB_DECRYPT`, the keys of `SUB_QUERYSTRING`, and the keys of a `SUB_INI` file that exists at lint time;
+- the SUB family: `SUB`, `SUB_EMPTY`, `SUB_ADD`, `SUB_APPEND`, `SUBDATA`, `SUB_LOCAL`, `SUB_TEMPFILE`, `SUB_ENCRYPT`, `SUB_DECRYPT`, the keys of `SUB_QUERYSTRING`, and the keys of a `SUB_INI` file that lint can read (a regular file of at most 1 MiB that parses as INI);
 - the prompts that store an answer: `PROMPT ENTER_SUB`, `ASK ... SUB`, `PROMPT ASK ... SUB` (with or without `COMPARE`), `PROMPT OPENFILE SUB`, `PROMPT SAVEFILE SUB` and `PROMPT DIRECTORY SUB` (every variable named after `SUB`), and both variables of `PROMPT CREDENTIALS`.
 
 Definitions inside `BEGIN SCRIPT` blocks that the file runs with `EXECUTE SCRIPT` count too, and so does a definition that comes after the first use.
@@ -324,6 +324,7 @@ Not reported:
 
 - System variables (`!!$DATE_TAG!!`, `!!$DB_NAME!!`, …), `!!$ARG_n!!` set with `-a`, and `!!$COUNTER_n!!`.
 - References with the `&` (environment), `@` (column), `~` (local), `#` and `+` prefixes, which resolve only at run time.
+- A name built from another variable, such as `!!N_!!CHECK_GROUP!!_CHECKS!!`. execsql substitutes `!!CHECK_GROUP!!` first, so the outer name is only known at run time. Lint checks the inner variable: if `CHECK_GROUP` is undefined, `!!CHECK_GROUP!!` is reported, not the fragments `!!N_!!` and `!!_CHECKS!!`.
 
 Variables defined somewhere lint cannot see are reported: in a configuration file, on the command line other than as `$ARG_n`, or in a file pulled in with `INCLUDE` (lint does not read `INCLUDE`d files for definitions). If that is how a library works, `--ignore V001` for those scripts.
 

{execsql2-2.25.0 → execsql2-2.25.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "execsql2"
-version = "2.25.0"
+version = "2.25.1"
 description = "Runs a SQL script against a PostgreSQL, SQLite, MariaDB/MySQL, DuckDB, Firebird, MS-Access, MS-SQL-Server, or Oracle database, or an ODBC DSN. Provides metacommands to import and export data, copy data between databases, conditionally execute SQL and metacommands, and dynamically alter SQL and metacommands with substitution variables."
 readme = { file = "README.md", content-type = "text/markdown" }
 license = { file = "LICENSE.txt" }
@@ -177,7 +177,7 @@ skip-magic-trailing-comma = false
 line-ending = "auto"
 
 [tool.bumpversion]
-current_version = "2.25.0"
+current_version = "2.25.1"
 commit = true
 tag = true
 tag_name = "v{new_version}"

{execsql2-2.25.0 → execsql2-2.25.1}/src/execsql/cli/lint.py

@@ -243,6 +243,12 @@ _RX_PROMPT_CREDENTIALS = re.compile(
 )
 
 _RX_VAR_REF = re.compile(r"!!([$@&~#+]?\w+)!!", re.I)
+# Every candidate reference, including one nested in another's name
+# (``!!N_!!GROUP!!_CHECKS!!``), which _RX_VAR_REF's left-to-right scan skips.
+_RX_VAR_REF_ANY = re.compile(r"(?=!!([$@&~#+]?\w+)!!)")
+# Stands for a substituted value in _unresolved_var_refs: a word character
+# (so an enclosing name still matches) that no script name contains.
+_SUBSTITUTED = "ª"
 
 
 # ---------------------------------------------------------------------------
@@ -424,54 +430,108 @@ def _extract_var_definition(
             _read_ini_vars(ini_file, ini_section, script_dir, defined)
 
 
+# Larger than any real SUB_INI file; lint reads no more than this.
+_MAX_INI_BYTES = 1024 * 1024
+
+
 def _read_ini_vars(
     ini_file: str,
     section: str,
     script_dir: Path | None,
     defined_vars: set[str],
 ) -> None:
-    """Read an INI file and register its section keys as defined variables."""
+    """Read an INI file and register its section keys as defined variables.
+
+    Only a regular file up to :data:`_MAX_INI_BYTES` is read, so a script
+    naming a FIFO or a device (``/dev/zero``) cannot hang lint or the
+    language server; a file that is unreadable or not valid INI defines
+    nothing.
+    """
     from configparser import ConfigParser
+    from configparser import Error as ConfigError
 
     p = Path(ini_file)
     if not p.is_absolute() and script_dir is not None:
         p = script_dir / p
 
-    if not p.exists():
-        return
-
     cp = ConfigParser()
-    cp.read(p)
+    try:
+        if not p.is_file() or p.stat().st_size > _MAX_INI_BYTES:
+            return
+        cp.read_string(p.read_text(encoding="utf-8"), source=str(p))
+    except (OSError, UnicodeDecodeError, ConfigError):
+        return
     if cp.has_section(section):
         for key, _value in cp.items(section):
             defined_vars.add(key.upper())
 
 
-def _check_var_ref(
-    raw_name: str,
-    source: str,
-    line_no: int,
-    defined_vars: set[str],
-    issues: list[_Issue],
-) -> None:
-    """Emit a warning if *raw_name* looks like an undefined user variable."""
-    if not raw_name:
-        return
-
+def _is_known_var(raw_name: str, defined_vars: set[str]) -> bool:
+    """Whether execsql may substitute *raw_name* (as written, with its sigil) at run time."""
     sigil = raw_name[0] if raw_name[0] in ("$", "@", "&", "~", "#", "+") else ""
     name = raw_name[len(sigil) :]
 
     # Skip non-$ sigil prefixes — resolved at runtime
     if sigil in ("@", "&", "~", "#", "+"):
-        return
+        return True
 
     if sigil == "$":
         # System variables: $ARG_N is set with -a/--assign-arg, $COUNTER_N by
         # CounterVars, the rest by execsql itself.  A SUB cannot define one.
-        if re.match(r"^(?:ARG|COUNTER)_\d+$", name, re.I) or name.upper() in _get_builtin_vars():
-            return
-    elif name.upper() in defined_vars:
-        # User variables, defined by a SUB-family metacommand or a prompt.
+        return bool(re.match(r"^(?:ARG|COUNTER)_\d+$", name, re.I)) or name.upper() in _get_builtin_vars()
+    # User variables, defined by a SUB-family metacommand or a prompt.
+    return name.upper() in defined_vars
+
+
+def _unresolved_var_refs(text: str, defined_vars: set[str]) -> list[str]:
+    """The variable names in *text* that execsql would leave unsubstituted, as written.
+
+    execsql substitutes a known variable wherever ``!!name!!`` appears and
+    repeats until nothing changes, so a variable written inside another's
+    name (``!!N_!!GROUP!!_CHECKS!!``) is replaced first, and the outer name
+    is only known at run time: it is not checked.  Here each known variable
+    is replaced by a placeholder character, a name holding one counts as
+    known, and that repeats until nothing is replaced.
+
+    In a run of unknown candidates that share delimiters, the inner ones
+    (every second, from the second) are reported: with ``GROUP`` undefined,
+    ``!!N_!!GROUP!!_CHECKS!!`` reports ``GROUP``, not the fragments ``N_``
+    and ``_CHECKS``.
+    """
+    while True:
+        parts: list[str] = []
+        end = 0
+        for m in _RX_VAR_REF_ANY.finditer(text):
+            name = m.group(1)
+            if m.start() >= end and (_SUBSTITUTED in name or _is_known_var(name, defined_vars)):
+                parts += [text[end : m.start()], _SUBSTITUTED]
+                end = m.start() + len(name) + 4
+        if not parts:
+            break
+        text = "".join([*parts, text[end:]])
+
+    unresolved: list[str] = []
+    run: list[str] = []
+    end = -1
+    for m in _RX_VAR_REF_ANY.finditer(text):
+        if run and m.start() != end - 2:  # not sharing the previous candidate's closing !!
+            unresolved.extend(run if len(run) == 1 else run[1::2])
+            run = []
+        run.append(m.group(1))
+        end = m.start() + len(m.group(1)) + 4
+    unresolved.extend(run if len(run) == 1 else run[1::2])
+    return unresolved
+
+
+def _check_var_ref(
+    raw_name: str,
+    source: str,
+    line_no: int,
+    defined_vars: set[str],
+    issues: list[_Issue],
+) -> None:
+    """Emit a warning if *raw_name* looks like an undefined user variable."""
+    if not raw_name or _is_known_var(raw_name, defined_vars):
         return
 
     issues.append(
@@ -735,7 +795,7 @@ def _collect_var_references(nodes: list[Node], seen: set[str]) -> None:
     """Record every variable read anywhere beneath *nodes*: ``!!var!!``, or ``sub_defined(var)`` / ``sub_empty(var)``."""
     for node in nodes:
         for text in _referencing_text(node):
-            for m in _RX_VAR_REF.finditer(text):
+            for m in _RX_VAR_REF_ANY.finditer(text):
                 seen.add(m.group(1).lstrip("$@&~#+").upper())
             for m in _RX_VAR_TEST.finditer(text):
                 seen.add(m.group(1).lstrip("$@&~#+").upper())
@@ -826,14 +886,14 @@ def _lint_nodes(
 
         # -- Variable references in SQL --
         if isinstance(node, SqlStatement):
-            for m in _RX_VAR_REF.finditer(node.text):
-                _check_var_ref(m.group(1), src, lno, defined_vars, issues)
+            for name in _unresolved_var_refs(node.text, defined_vars):
+                _check_var_ref(name, src, lno, defined_vars, issues)
 
         # -- Metacommand checks --
         elif isinstance(node, MetaCommandStatement):
             _check_metacommand(node, issues)
-            for m in _RX_VAR_REF.finditer(node.command):
-                _check_var_ref(m.group(1), src, lno, defined_vars, issues)
+            for name in _unresolved_var_refs(node.command, defined_vars):
+                _check_var_ref(name, src, lno, defined_vars, issues)
 
         # -- IncludeDirective checks --
         elif isinstance(node, IncludeDirective):

{execsql2-2.25.0 → execsql2-2.25.1}/tests/cli/test_lint.py

@@ -17,6 +17,7 @@ on every node).
 
 from __future__ import annotations
 
+import os
 from pathlib import Path
 
 import pytest
@@ -716,6 +717,78 @@ class TestUnusedVariables:
         unused = [i for i in issues if i.code == "V002"]
         assert unused and unused[0].line == 2, unused
 
+    def test_a_reference_inside_another_name_counts(self, tmp_path):
+        body = "-- !x! SUB grp east\n-- !x! SUB N_east_CHECKS 12\nSELECT !!N_!!grp!!_CHECKS!!;\n"
+        unused = [i.message for i in _lint(tmp_path, body) if i.code == "V002"]
+        assert not any("grp" in m for m in unused), unused
+
+
+class TestSubIniDefinitions:
+    """SUB_INI defines the keys of a section in an INI file that lint can read."""
+
+    @staticmethod
+    def _undefined(tmp_path, ini_name):
+        body = f"-- !x! SUB_INI FILE {ini_name} SECTION vars\nSELECT !!region!!;\n"
+        return [i.message for i in _lint(tmp_path, body) if i.code == "V001"]
+
+    def test_keys_of_the_section_are_defined(self, tmp_path):
+        (tmp_path / "vars.ini").write_text("[vars]\nregion = north\n", encoding="utf-8")
+        assert self._undefined(tmp_path, "vars.ini") == []
+
+    def test_a_missing_file_defines_nothing(self, tmp_path):
+        assert self._undefined(tmp_path, "missing.ini") == ["undefined variable !!region!!"]
+
+    def test_a_file_that_is_not_ini_defines_nothing(self, tmp_path):
+        (tmp_path / "vars.ini").write_text("region = north\n", encoding="utf-8")  # no section header
+        assert self._undefined(tmp_path, "vars.ini") == ["undefined variable !!region!!"]
+
+    def test_an_oversized_file_is_not_read(self, tmp_path, monkeypatch):
+        import execsql.cli.lint as lint_module
+
+        (tmp_path / "vars.ini").write_text("[vars]\nregion = north\n", encoding="utf-8")
+        monkeypatch.setattr(lint_module, "_MAX_INI_BYTES", 8)
+        assert self._undefined(tmp_path, "vars.ini") == ["undefined variable !!region!!"]
+
+    @pytest.mark.skipif(not hasattr(os, "mkfifo"), reason="needs os.mkfifo")
+    def test_a_fifo_is_not_opened(self, tmp_path):
+        os.mkfifo(tmp_path / "vars.ini")  # opening it would block until a writer appears
+        assert self._undefined(tmp_path, "vars.ini") == ["undefined variable !!region!!"]
+
+
+class TestNestedVariableNames:
+    """``!!N_!!GROUP!!_CHECKS!!`` names the variable N_<value of GROUP>_CHECKS; execsql substitutes the inner one first."""
+
+    @staticmethod
+    def _undefined(tmp_path, body):
+        return [i.message for i in _lint(tmp_path, body) if i.code == "V001"]
+
+    def test_a_defined_inner_variable_is_not_reported(self, tmp_path):
+        body = (
+            "-- !x! SUB grp east\n"
+            "-- !x! SUB N_!!grp!!_CHECKS 12\n"
+            "-- !x! WRITE !!N_!!grp!!_CHECKS!!\n"
+            "SELECT !!N_!!grp!!_CHECKS!!;\n"
+        )
+        assert self._undefined(tmp_path, body) == []
+
+    def test_an_undefined_inner_variable_is_reported_not_the_fragments(self, tmp_path):
+        assert self._undefined(tmp_path, "SELECT !!N_!!nogrp!!_CHECKS!!;\n") == ["undefined variable !!nogrp!!"]
+
+    def test_three_levels(self, tmp_path):
+        assert self._undefined(tmp_path, "-- !x! SUB c X\nSELECT !!A_!!B_!!c!!_D!!_E!!;\n") == []
+
+    def test_a_system_variable_inside_a_name(self, tmp_path):
+        assert self._undefined(tmp_path, "SELECT !!N_!!$counter_1!!_X!!;\n") == []
+
+    def test_adjacent_references_are_each_checked(self, tmp_path):
+        assert self._undefined(tmp_path, "-- !x! SUB a 1\nSELECT !!a!!!!b!!;\n") == ["undefined variable !!b!!"]
+
+    def test_a_plain_undefined_variable_is_still_reported(self, tmp_path):
+        assert self._undefined(tmp_path, "SELECT !!a!!, !!b!!;\n") == [
+            "undefined variable !!a!!",
+            "undefined variable !!b!!",
+        ]
+
 
 class TestTheProjectsOwnScriptsStayQuiet:
     """A rule that fires on correct scripts is worse than no rule.

{execsql2-2.25.0 → execsql2-2.25.1}/uv.lock

@@ -905,7 +905,7 @@ wheels = [
 
 [[package]]
 name = "execsql2"
-version = "2.25.0"
+version = "2.25.1"
 source = { editable = "." }
 dependencies = [
     { name = "python-dateutil" },