execsql2 2.19.0__tar.gz → 2.19.1__tar.gz

{execsql2-2.19.0 → execsql2-2.19.1}/CHANGELOG.md

@@ -13,6 +13,14 @@ ______________________________________________________________________
 
 ______________________________________________________________________
 
+## [2.19.1] - 2026-06-03
+
+### Fixed
+
+- `execsql-format` no longer mangles quoted substitution variables: `!'!var!'!` and `!"!var!"!` were being parsed by sqlglot as `NOT` operators (e.g. `!'!myvar!'!` → `NOT NOT '!myvar!'`). All three quote forms plus deferred `!{var}!` are now hidden from SQL formatting.
+
+______________________________________________________________________
+
 ## [2.19.0] - 2026-06-02
 
 ### Fixed

{execsql2-2.19.0 → execsql2-2.19.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: execsql2
-Version: 2.19.0
+Version: 2.19.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

{execsql2-2.19.0 → execsql2-2.19.1}/docs/about/divergence.md

@@ -147,7 +147,7 @@ New options in `execsql.conf`:
 
 ### Debugging { #debugging }
 
-execsql2 adds an interactive debug REPL (no upstream equivalent), triggered either by the `BREAKPOINT` metacommand or the `--debug` CLI flag (step-through mode). The REPL prompts with `execsql debug>` and accepts dot-prefixed commands (`.continue`, `.next`, `.vars`, `.where`, `.stack`, `.set`, `.scripts`, `.help`), bare variable names for inspection, and SQL terminated with `;` for ad-hoc queries against the live connection. `BREAKPOINT` is silently skipped when stdin is not a TTY so it does not hang CI. Full command list and behavior: [Debugging guide](../guides/debugging.md).
+execsql2 adds an interactive debug REPL (no upstream equivalent), triggered either by the `BREAKPOINT` metacommand or the `--debug` CLI flag (step-through mode). The REPL prompts with `execsql debug>` and uses two-way dispatch (as of 2.19.0): input starting with `.` is a REPL command (`.continue`, `.quit`, `.next`, `.vars`, `.vars VAR`, `.where`, `.stack`, `.set`, `.scripts`, `.cancel`, `.help`); everything else is SQL, buffered across lines until terminated with `;` and executed against the live connection (DML reports rows affected, DDL / transaction-control reports `(statement executed)`, errors print inline without ending the session). `BREAKPOINT` is silently skipped when stdin is not a TTY so it does not hang CI. Full command list and behavior: [Debugging guide](../guides/debugging.md).
 
 ### Library API
 

{execsql2-2.19.0 → execsql2-2.19.1}/docs/getting-started/installation.md

@@ -27,12 +27,14 @@ pip install "execsql2[odbc]"              # Generic ODBC DSN (pyodbc)
 pip install "execsql2[firebird]"          # Firebird
 pip install "execsql2[oracle]"            # Oracle
 pip install "execsql2[formats]"           # ODS, Excel, Jinja2, Feather/Parquet, HDF5, YAML
+pip install "execsql2[formatter]"         # SQL pass for execsql-format (sqlglot)
 pip install "execsql2[auth]"              # OS keyring integration (desktop/native)
 pip install "execsql2[auth-plaintext]"    # Headless keyring (plaintext file backend)
 pip install "execsql2[auth-encrypted]"    # Headless keyring (encrypted file backend)
 pip install "execsql2[upsert]"            # PG_UPSERT metacommand (pg-upsert)
+pip install "execsql2[map]"               # PROMPT MAP widget (tkintermapview)
 pip install "execsql2[all-db]"            # All database drivers
-pip install "execsql2[all]"               # Everything (all-db + formats + auth + upsert)
+pip install "execsql2[all]"               # Everything (all-db + formats + formatter + auth + upsert + map)
 ```
 
 In addition to the *execsql* program itself, additional Python libraries may need to be installed to use *execsql* with specific types of DBMSs and spreadsheets. The additional libraries that may be needed are listed in the [Requirements](requirements.md#requirements) section.

{execsql2-2.19.0 → execsql2-2.19.1}/docs/getting-started/requirements.md

@@ -18,11 +18,16 @@ pip install "execsql2[odbc]"        # ODBC DSN (pyodbc)
 
 # Feature bundles
 pip install "execsql2[formats]"     # ODS, Excel, Jinja2, Feather, Parquet, HDF5
-pip install "execsql2[auth]"        # OS keyring integration
+pip install "execsql2[formatter]"   # SQL pass for execsql-format (sqlglot)
+pip install "execsql2[upsert]"      # PG_UPSERT metacommand (pg-upsert)
+pip install "execsql2[map]"         # PROMPT MAP widget (tkintermapview)
+pip install "execsql2[auth]"        # OS keyring integration (desktop / native)
+pip install "execsql2[auth-plaintext]"  # Headless keyring (plaintext file backend)
+pip install "execsql2[auth-encrypted]"  # Headless keyring (encrypted file backend)
 
 # Convenience
 pip install "execsql2[all-db]"      # All database drivers
-pip install "execsql2[all]"         # Everything
+pip install "execsql2[all]"         # Everything (all-db + formats + formatter + auth + upsert + map)
 ```
 
 Multiple extras can be combined: `pip install "execsql2[postgres,duckdb,formats]"`.
@@ -55,12 +60,34 @@ The specific libraries installed by each extra are:
 | [Parquet](https://parquet.apache.org/) files                       | [polars](https://pypi.org/project/polars/)                                                              |
 | [HDF5](https://www.hdfgroup.org/solutions/hdf5/) files             | [tables](https://pypi.org/project/tables/)                                                              |
 
+### `formatter` extra
+
+Required for the SQL-formatting pass of the `execsql-format` CLI. Without this extra, `execsql-format` still normalizes metacommand indentation and keyword casing (use `--no-sql` or import scripts without SQL); the SQL pretty-printing pass calls [sqlglot](https://sqlglot.com/) and raises `ModuleNotFoundError` if it isn't installed.
+
+| Feature                               | Library                                      |
+| ------------------------------------- | -------------------------------------------- |
+| SQL reformatting via `execsql-format` | [sqlglot](https://pypi.org/project/sqlglot/) |
+
+### `upsert` extra
+
+| Feature                                   | Library                                          |
+| ----------------------------------------- | ------------------------------------------------ |
+| `PG_UPSERT` PostgreSQL upsert metacommand | [pg-upsert](https://pypi.org/project/pg-upsert/) |
+
+### `map` extra
+
+| Feature                               | Library                                                    |
+| ------------------------------------- | ---------------------------------------------------------- |
+| `PROMPT MAP` lat/lon selection widget | [tkintermapview](https://pypi.org/project/tkintermapview/) |
+
 ### `auth` bundle
 
 | Feature              | Library                                      |
 | -------------------- | -------------------------------------------- |
 | OS keyring / secrets | [keyring](https://pypi.org/project/keyring/) |
 
+The `auth-plaintext` and `auth-encrypted` variants add a fallback keyring backend for headless Linux: `auth-plaintext` adds [keyrings.alt](https://pypi.org/project/keyrings.alt/) (plaintext file storage — **secrets are not encrypted at rest**), and `auth-encrypted` adds `keyrings.alt` plus [pycryptodome](https://pypi.org/project/pycryptodome/) for an encrypted file backend. See [Keyring Platform Setup](../reference/security.md#keyring_setup).
+
 Connections to SQLite databases use Python's standard library and require no additional packages.
 
 ## Additional System Requirements { #system_requirements }

{execsql2-2.19.0 → execsql2-2.19.1}/docs/guides/debugging.md

@@ -57,22 +57,29 @@ execsql debug>
 
 | Command         | Shortcut | Description                                                               |
 | --------------- | -------- | ------------------------------------------------------------------------- |
-| `.continue`     | `.c`     | Resume normal script execution                                            |
-| `.abort`        | `.q`     | Halt the script (exit 1)                                                  |
-| `.vars`         | `.v`     | List user, system, local, and counter substitution variables              |
-| `.vars all`     | `.v all` | Include environment variables (`&`) in the listing                        |
+| `.continue`     | `.c`     | Resume script execution                                                   |
+| `.quit`         | `.q`     | Halt the script (exit 1). `.abort` is accepted as an alias.               |
+| `.vars`         | `.v`     | List all execsql substitution variables                                   |
+| `.vars VAR`     | `.v VAR` | Print the value of one variable (e.g. `.vars logfile`, `.vars $ARG_1`)    |
 | `.next`         | `.n`     | Execute the next statement, then pause again (step mode)                  |
 | `.where`        | `.w`     | Re-display the current script location and upcoming statement             |
 | `.stack`        |          | Show the command-list stack (script name, cursor position, nesting depth) |
 | `.set VAR VAL`  | `.s`     | Set or update a substitution variable                                     |
 | `.scripts`      |          | List all registered SCRIPT definitions with parameters and source         |
 | `.scripts NAME` |          | Show detail for a specific SCRIPT (parameters, source file/line range)    |
+| `.cancel`       |          | Discard the current partial multi-line SQL buffer (also Ctrl-C / EOF)     |
 | `.help`         | `.h`     | Show available commands                                                   |
 
-Anything not starting with `.` is treated as a variable lookup or SQL:
+**Dispatch is two-way** (changed in 2.19.0): input starting with `.` is a REPL command, everything else is SQL. There is no bare-name variable lookup — use `.vars VAR` to print a single variable.
 
-- A bare name (e.g. `logfile`) prints the value of that substitution variable.
-- Any input ending with `;` is executed as SQL against the current database (expects columns returned, e.g. SELECT).
+**SQL execution:**
+
+- Input is buffered as SQL until a line ends with `;`, at which point the buffered statement is sent to the live connection. Multi-line statements are accepted; the prompt switches to a continuation indicator while a partial statement is being entered.
+- `SELECT` (and other row-returning statements) print the result rows in tabular form.
+- DML (`INSERT` / `UPDATE` / `DELETE`) prints `(N rows affected)`.
+- DDL and transaction-control statements (`CREATE`, `DROP`, `BEGIN`, `COMMIT`, `ROLLBACK`, …) print `(statement executed)`.
+- A SQL error prints the database error inline and returns to the prompt — the REPL session is not terminated.
+- `.cancel` (or Ctrl-C / EOF mid-statement) discards a partial buffer without executing it.
 
 The `--debug` CLI flag starts execution in step mode, pausing before every statement.
 

{execsql2-2.19.0 → execsql2-2.19.1}/docs/guides/formatter.md

@@ -4,13 +4,19 @@
 
 ## Installation { #installation }
 
-`execsql-format` is installed automatically as part of the `execsql2` package — no extra steps required.
+The `execsql-format` command is installed automatically with the `execsql2` package and is available on your PATH after install:
 
 ```bash
 pip install execsql2
 ```
 
-After installation, the `execsql-format` command is available on your PATH.
+The metacommand-indentation and keyword-casing passes work out of the box. **SQL reformatting** (the optional sqlglot pass) requires the `[formatter]` extra, as of execsql2 2.19.0:
+
+```bash
+pip install "execsql2[formatter]"
+```
+
+Without the extra, `execsql-format` works in `--no-sql` mode (metacommand indentation and keyword casing only); invoking the SQL pass without `[formatter]` installed raises `ModuleNotFoundError: No module named 'sqlglot'`.
 
 ## Usage { #usage }
 

{execsql2-2.19.0 → execsql2-2.19.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "execsql2"
-version = "2.19.0"
+version = "2.19.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" }
@@ -170,7 +170,7 @@ skip-magic-trailing-comma = false
 line-ending = "auto"
 
 [tool.bumpversion]
-current_version = "2.19.0"
+current_version = "2.19.1"
 commit = true
 tag = true
 tag_name = "v{new_version}"

{execsql2-2.19.0 → execsql2-2.19.1}/src/execsql/format.py

@@ -129,9 +129,15 @@ def parse_keyword(payload: str) -> str:
 # SQL block formatting helpers
 # ---------------------------------------------------------------------------
 
-# Matches execsql variable substitutions: !!varname!!, !!#param!!, !!@col!!, etc.
-# and deferred substitutions !{varname}!
-_EXECSQL_VAR_RE = re.compile(r"!!([^!\s][^!]*)!!|!\{[^}]+\}!")
+# Matches execsql variable substitutions:
+#   !!varname!!     verbatim
+#   !'!varname!'!   single-quoted (apostrophes doubled at expansion)
+#   !"!varname!"!   double-quoted (quotes doubled at expansion)
+#   !{varname}!     deferred
+# The bare/quoted forms mirror src/execsql/script/variables.py:_TOKEN_RX so
+# every token the executor recognises is hidden from sqlglot — otherwise the
+# `!` in a quoted form is parsed as a NOT operator (e.g. `!'!v!'!` -> `NOT NOT '!v!'`).
+_EXECSQL_VAR_RE = re.compile(r"""!(['"]?)!([^!\s][^!]*)!\1!|!\{[^}]+\}!""")
 
 
 def _protect_variables(sql: str) -> tuple[str, list[tuple[str, str]]]:

{execsql2-2.19.0 → execsql2-2.19.1}/tests/test_format.py

@@ -279,6 +279,18 @@ class TestProtectVariables:
         assert len(replacements) == 1
         assert replacements[0][1] == "!{myvar}!"
 
+    def test_single_quoted_var(self):
+        protected, replacements = _protect_variables("WHERE a = !'!myvar!'!")
+        assert "!'!myvar!'!" not in protected
+        assert len(replacements) == 1
+        assert replacements[0][1] == "!'!myvar!'!"
+
+    def test_double_quoted_var(self):
+        protected, replacements = _protect_variables('WHERE a = !"!myvar!"!')
+        assert '!"!myvar!"!' not in protected
+        assert len(replacements) == 1
+        assert replacements[0][1] == '!"!myvar!"!'
+
     def test_multiple_vars(self):
         protected, replacements = _protect_variables("SELECT !!a!!, !!b!!")
         assert len(replacements) == 2
@@ -649,6 +661,18 @@ class TestFormatFileEdgeCases:
         assert "!!$my_var!!" in result
         assert "!!table_name!!" in result
 
+    def test_quoted_subvar_not_mangled_as_not(self):
+        # Regression: !'!var!'! used to be parsed by sqlglot as NOT NOT '!var!'.
+        source = "select * from documents where author = !'!myvar!'!;\n"
+        result = format_file(source)
+        assert "!'!myvar!'!" in result
+        assert "NOT" not in result
+
+    def test_double_quoted_subvar_preserved(self):
+        source = 'select * from t where col = !"!myvar!"!;\n'
+        result = format_file(source)
+        assert '!"!myvar!"!' in result
+
     def test_elseif_depth(self):
         source = "-- !x! IF 1=1\n-- !x! WRITE 'a'\n-- !x! ELSEIF 2=2\n-- !x! WRITE 'b'\n-- !x! ENDIF\n"
         result = format_file(source, use_sql=False)

{execsql2-2.19.0 → execsql2-2.19.1}/uv.lock

@@ -722,7 +722,7 @@ wheels = [
 
 [[package]]
 name = "execsql2"
-version = "2.19.0"
+version = "2.19.1"
 source = { editable = "." }
 dependencies = [
     { name = "python-dateutil" },