execsql2 2.37.0__py3-none-any.whl → 2.39.1__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (77) hide show
  1. execsql/api.py +95 -45
  2. execsql/cli/commands/run.py +2 -2
  3. execsql/cli/lint.py +46 -9
  4. execsql/cli/run.py +128 -56
  5. execsql/config.py +7 -0
  6. execsql/data/execsql.conf.template +26 -2
  7. execsql/db/base.py +61 -24
  8. execsql/db/dsn.py +2 -3
  9. execsql/db/duckdb.py +43 -4
  10. execsql/db/firebird.py +39 -22
  11. execsql/db/mysql.py +22 -23
  12. execsql/db/oracle.py +11 -4
  13. execsql/db/postgres.py +15 -20
  14. execsql/db/sqlite.py +117 -10
  15. execsql/db/sqlserver.py +11 -7
  16. execsql/db/target_types.py +151 -4
  17. execsql/debug/repl.py +2 -1
  18. execsql/exceptions.py +19 -0
  19. execsql/exporters/html.py +26 -42
  20. execsql/exporters/ods.py +93 -21
  21. execsql/exporters/sqlite.py +82 -47
  22. execsql/format.py +12 -4
  23. execsql/gui/__init__.py +13 -10
  24. execsql/gui/base.py +131 -8
  25. execsql/gui/console.py +77 -30
  26. execsql/gui/desktop.py +290 -119
  27. execsql/gui/tui.py +384 -129
  28. execsql/importers/base.py +15 -19
  29. execsql/importers/csv.py +3 -5
  30. execsql/importers/json.py +37 -13
  31. execsql/importers/ods.py +22 -2
  32. execsql/lsp/document.py +6 -1
  33. execsql/lsp/hover.py +2 -1
  34. execsql/metacommands/conditions.py +3 -1
  35. execsql/metacommands/connect.py +18 -3
  36. execsql/metacommands/control.py +20 -5
  37. execsql/metacommands/data.py +11 -9
  38. execsql/metacommands/dispatch.py +10 -0
  39. execsql/metacommands/io.py +1 -0
  40. execsql/metacommands/io_export.py +1 -2
  41. execsql/metacommands/io_fileops.py +27 -91
  42. execsql/metacommands/io_import.py +26 -8
  43. execsql/metacommands/io_write.py +0 -9
  44. execsql/metacommands/prompt.py +94 -42
  45. execsql/metacommands/reference.py +7 -0
  46. execsql/metacommands/system.py +0 -2
  47. execsql/parser.py +132 -45
  48. execsql/script/control.py +17 -7
  49. execsql/script/engine.py +1 -1
  50. execsql/script/executor.py +184 -37
  51. execsql/script/preparation.py +42 -0
  52. execsql/types.py +6 -5
  53. execsql/utils/auth.py +11 -6
  54. execsql/utils/errors.py +2 -2
  55. execsql/utils/fileio.py +342 -134
  56. execsql/utils/gui.py +162 -53
  57. execsql/utils/spreadsheet.py +74 -0
  58. execsql/utils/strings.py +13 -7
  59. {execsql2-2.37.0.data → execsql2-2.39.1.data}/data/execsql2_extras/README.md +5 -5
  60. {execsql2-2.37.0.data → execsql2-2.39.1.data}/data/execsql2_extras/example_config_prompt.sql +2 -2
  61. {execsql2-2.37.0.dist-info → execsql2-2.39.1.dist-info}/METADATA +32 -119
  62. {execsql2-2.37.0.dist-info → execsql2-2.39.1.dist-info}/RECORD +77 -75
  63. {execsql2-2.37.0.dist-info → execsql2-2.39.1.dist-info}/WHEEL +1 -1
  64. {execsql2-2.37.0.data → execsql2-2.39.1.data}/data/execsql2_extras/config_settings.sqlite +0 -0
  65. {execsql2-2.37.0.data → execsql2-2.39.1.data}/data/execsql2_extras/make_config_db.sql +0 -0
  66. {execsql2-2.37.0.data → execsql2-2.39.1.data}/data/execsql2_extras/md_compare.sql +0 -0
  67. {execsql2-2.37.0.data → execsql2-2.39.1.data}/data/execsql2_extras/md_glossary.sql +0 -0
  68. {execsql2-2.37.0.data → execsql2-2.39.1.data}/data/execsql2_extras/md_upsert.sql +0 -0
  69. {execsql2-2.37.0.data → execsql2-2.39.1.data}/data/execsql2_extras/pg_compare.sql +0 -0
  70. {execsql2-2.37.0.data → execsql2-2.39.1.data}/data/execsql2_extras/pg_glossary.sql +0 -0
  71. {execsql2-2.37.0.data → execsql2-2.39.1.data}/data/execsql2_extras/script_template.sql +0 -0
  72. {execsql2-2.37.0.data → execsql2-2.39.1.data}/data/execsql2_extras/ss_compare.sql +0 -0
  73. {execsql2-2.37.0.data → execsql2-2.39.1.data}/data/execsql2_extras/ss_glossary.sql +0 -0
  74. {execsql2-2.37.0.data → execsql2-2.39.1.data}/data/execsql2_extras/ss_upsert.sql +0 -0
  75. {execsql2-2.37.0.dist-info → execsql2-2.39.1.dist-info}/entry_points.txt +0 -0
  76. {execsql2-2.37.0.dist-info → execsql2-2.39.1.dist-info}/licenses/LICENSE.txt +0 -0
  77. {execsql2-2.37.0.dist-info → execsql2-2.39.1.dist-info}/licenses/NOTICE +0 -0
execsql/exporters/ods.py CHANGED
@@ -24,6 +24,7 @@ from execsql.script import current_script_line
24
24
  from execsql.utils.errors import exception_desc, fatal_error, install_hint
25
25
  from execsql.utils.fileio import filewriter_close
26
26
  from execsql.utils.strings import unquoted
27
+ from execsql.utils.spreadsheet import CellTextBudget, SheetBudget
27
28
 
28
29
  __all__ = ["OdsFile", "export_ods", "write_query_to_ods", "write_queries_to_ods"]
29
30
 
@@ -179,26 +180,36 @@ class OdsFile:
179
180
  return sheet
180
181
  return None
181
182
 
182
- def sheet_data(self, sheetname: Any, junk_header_rows: int = 0) -> list:
183
- """Return all row data from the named sheet, optionally skipping leading junk rows."""
183
+ def sheet_data(self, sheetname: Any, junk_header_rows: int = 0, *, budget: SheetBudget | None = None) -> list:
184
+ """Read a sheet after SKIP, checking optional budgets before expanding rows or padding."""
184
185
  sheet = self.sheet_named(sheetname)
185
186
  if not sheet:
186
187
  raise OdsFileError(f"There is no sheet named {sheetname}")
187
188
 
188
189
  rows: list[list | None] = []
189
190
  pending_empty = 0
191
+ skip_rows = max(0, junk_header_rows)
190
192
  for sheetrow in sheet.getElementsByType(of.table.TableRow):
191
- data = _row_values(sheetrow)
192
- repeat = int(sheetrow.getAttribute("numberrowsrepeated") or 1)
193
+ repeat = _expansion_count(sheetrow, "numberrowsrepeated")
194
+ skipped = min(skip_rows, repeat)
195
+ skip_rows -= skipped
196
+ repeat -= skipped
197
+ if repeat == 0:
198
+ _validate_expansion_counts(sheetrow)
199
+ continue
200
+ data = _row_values(sheetrow, budget, row_repeat=repeat, pending_rows=pending_empty)
193
201
  if not data:
194
202
  # Empty rows are kept only when data follows them, so the
195
203
  # filler rows a spreadsheet writes below the data are dropped.
196
204
  pending_empty += repeat
197
205
  continue
206
+ if budget is not None:
207
+ budget.add_row(data, repeat, pending_empty)
198
208
  rows.extend(None for _ in range(pending_empty))
199
209
  pending_empty = 0
200
210
  rows.extend(list(data) for _ in range(repeat))
201
- rows = rows[junk_header_rows:]
211
+ if junk_header_rows < 0:
212
+ rows = rows[junk_header_rows:]
202
213
  # Every row is as wide as the widest, so a blank trailing header is
203
214
  # still seen, and an empty row inside the data is a row of NULLs that
204
215
  # EMPTY_ROWS keeps or drops.
@@ -309,20 +320,55 @@ class OdsFile:
309
320
  self.wbk = None
310
321
 
311
322
 
312
- def _paragraph_text(node: Any) -> str:
323
+ def _expansion_count(node: Any, attribute: str) -> int:
324
+ """Read a non-negative ODS repeat/span/space count without expanding it."""
325
+ value = node.getAttribute(attribute) or "1"
326
+ try:
327
+ count = int(value)
328
+ if count < 0:
329
+ raise ValueError("negative count")
330
+ except (ValueError, TypeError) as exc:
331
+ shown = value[:120] + "..." if isinstance(value, str) and len(value) > 120 else value
332
+ raise ErrInfo(type="error", other_msg=f"Invalid ODS expansion count {shown!r} for {attribute}.") from exc
333
+ return count
334
+
335
+
336
+ def _validate_expansion_counts(node: Any) -> None:
337
+ """Validate skipped content without allocating its repeated rows or text."""
338
+ qname = getattr(node, "qname", None)
339
+ if qname == (of.table.TABLENS, "table-row"):
340
+ _expansion_count(node, "numberrowsrepeated")
341
+ elif qname in ((of.table.TABLENS, "table-cell"), (of.table.TABLENS, "covered-table-cell")):
342
+ _expansion_count(node, "numbercolumnsrepeated")
343
+ if qname == (of.table.TABLENS, "table-cell"):
344
+ _expansion_count(node, "numbercolumnsspanned")
345
+ _expansion_count(node, "numberrowsspanned")
346
+ elif qname == (of.text.TEXTNS, "s"):
347
+ _expansion_count(node, "c")
348
+ for child in getattr(node, "childNodes", ()):
349
+ _validate_expansion_counts(child)
350
+
351
+
352
+ def _paragraph_text(node: Any, budget: CellTextBudget | None = None) -> str:
313
353
  """Return the text of a ``<text:p>``, expanding ODF's space, tab and line-break elements."""
314
354
  parts: list[str] = []
315
355
  for child in node.childNodes:
316
356
  if child.nodeType == child.TEXT_NODE:
317
- parts.append(str(child))
357
+ value = str(child)
358
+ if budget is not None:
359
+ budget.add(len(value))
318
360
  elif child.qname == (of.text.TEXTNS, "s"):
319
- parts.append(" " * int(child.getAttribute("c") or 1))
320
- elif child.qname == (of.text.TEXTNS, "tab"):
321
- parts.append("\t")
322
- elif child.qname == (of.text.TEXTNS, "line-break"):
323
- parts.append("\n")
361
+ count = _expansion_count(child, "c")
362
+ if budget is not None:
363
+ budget.add(count)
364
+ value = " " * count
365
+ elif child.qname in ((of.text.TEXTNS, "tab"), (of.text.TEXTNS, "line-break")):
366
+ if budget is not None:
367
+ budget.add(1)
368
+ value = "\t" if child.qname == (of.text.TEXTNS, "tab") else "\n"
324
369
  else:
325
- parts.append(_paragraph_text(child))
370
+ value = _paragraph_text(child, budget)
371
+ parts.append(value)
326
372
  return "".join(parts)
327
373
 
328
374
 
@@ -336,7 +382,7 @@ def _time_text(duration: str) -> str:
336
382
  return f"{int(hours):02d}:{int(minutes):02d}:{int(seconds):02d}{fraction}"
337
383
 
338
384
 
339
- def _cell_value(cell: Any) -> str | None:
385
+ def _cell_value(cell: Any, budget: CellTextBudget | None = None) -> str | None:
340
386
  """Return a cell's stored value as text, or ``None`` for an empty cell.
341
387
 
342
388
  The value comes from the cell's ``office:value-type`` and value
@@ -361,25 +407,39 @@ def _cell_value(cell: Any) -> str | None:
361
407
  else:
362
408
  value = None
363
409
  if value:
410
+ if budget is not None:
411
+ budget.add(len(value))
364
412
  return value
365
413
  if vtype == "string":
366
414
  value = cell.getAttribute("stringvalue")
367
415
  if value:
416
+ if budget is not None:
417
+ budget.add(len(value))
368
418
  return value
369
419
  # A string cell, a cell with no type, or a typed cell missing its value
370
420
  # attribute: the paragraphs are the value, one line each.
371
- paragraphs = [
372
- _paragraph_text(child) for child in cell.childNodes if getattr(child, "qname", None) == (of.text.TEXTNS, "p")
373
- ]
421
+ paragraphs: list[str] = []
422
+ for child in cell.childNodes:
423
+ if getattr(child, "qname", None) == (of.text.TEXTNS, "p"):
424
+ if paragraphs and budget is not None:
425
+ budget.add(1)
426
+ paragraphs.append(_paragraph_text(child, budget))
374
427
  text = "\n".join(paragraphs)
375
428
  return text or None
376
429
 
377
430
 
378
- def _row_values(sheetrow: Any) -> list:
431
+ def _row_values(
432
+ sheetrow: Any,
433
+ budget: SheetBudget | None = None,
434
+ *,
435
+ row_repeat: int = 1,
436
+ pending_rows: int = 0,
437
+ ) -> list:
379
438
  """Return one value per column of a ``<table:table-row>``, without trailing empty cells."""
380
439
  values: list = []
381
440
  pending_empty = 0
382
441
  covered_by_span = 0
442
+ row_text = 0
383
443
  for cell in sheetrow.childNodes:
384
444
  qname = getattr(cell, "qname", None)
385
445
  if qname == (of.table.TABLENS, "table-cell"):
@@ -388,7 +448,7 @@ def _row_values(sheetrow: Any) -> list:
388
448
  covered = True
389
449
  else:
390
450
  continue
391
- repeat = int(cell.getAttribute("numbercolumnsrepeated") or 1)
451
+ repeat = _expansion_count(cell, "numbercolumnsrepeated")
392
452
  if covered:
393
453
  # A horizontal merge repeats its value across the columns it
394
454
  # covers (below); covered cells left over belong to a merge from
@@ -398,11 +458,20 @@ def _row_values(sheetrow: Any) -> list:
398
458
  repeat -= skip
399
459
  value = None
400
460
  else:
401
- value = _cell_value(cell)
402
- spanned = int(cell.getAttribute("numbercolumnsspanned") or 1)
461
+ spanned = _expansion_count(cell, "numbercolumnsspanned")
462
+ _expansion_count(cell, "numberrowsspanned")
403
463
  if spanned > 1:
404
464
  covered_by_span = spanned - 1
405
465
  repeat *= spanned
466
+ if repeat == 0:
467
+ _validate_expansion_counts(cell)
468
+ continue
469
+ text_budget = (
470
+ CellTextBudget(budget, budget.text_chars + row_text * row_repeat, repeat * row_repeat)
471
+ if budget is not None
472
+ else None
473
+ )
474
+ value = _cell_value(cell, text_budget)
406
475
  if repeat <= 0:
407
476
  continue
408
477
  if value is None:
@@ -410,6 +479,9 @@ def _row_values(sheetrow: Any) -> list:
410
479
  # repeated across the whole sheet width costs nothing.
411
480
  pending_empty += repeat
412
481
  continue
482
+ if budget is not None:
483
+ budget.check_row(len(values) + pending_empty + repeat, row_repeat, pending_rows)
484
+ row_text += len(value) * repeat
413
485
  values.extend([None] * pending_empty)
414
486
  pending_empty = 0
415
487
  values.extend([value] * repeat)
@@ -7,11 +7,10 @@ Provides :func:`write_query_to_sqlite`, which writes a query result set
7
7
  to a table in an SQLite database file. Used by ``EXPORT … FORMAT sqlite``.
8
8
  """
9
9
 
10
- import math
11
10
  from decimal import Decimal
12
- from pathlib import Path
13
11
  from typing import Any
14
12
 
13
+ from execsql.db.sqlite import sqlite_affinity as _affinity
15
14
  from execsql.exceptions import ErrInfo
16
15
  from execsql.types import dbt_sqlite
17
16
 
@@ -20,6 +19,23 @@ _SQLITE_SAFE = (int, float, str, bytes)
20
19
  __all__ = ["export_sqlite", "write_query_to_sqlite"]
21
20
 
22
21
 
22
+ def _exact_number(value: Decimal, affinity: str) -> int | float:
23
+ """Bind a Decimal only if its numeric readback retains the source value."""
24
+ if value.is_nan():
25
+ raise ValueError("NaN has no SQLite numeric representation")
26
+ if value.is_infinite():
27
+ return float(value)
28
+ if -(2**63) <= value <= 2**63 - 1 and value == value.to_integral_value():
29
+ number = int(value)
30
+ if affinity == "REAL" and Decimal(repr(float(number))) != value:
31
+ raise ValueError("the integer is not exactly representable in a SQLite REAL")
32
+ return number
33
+ result = float(value)
34
+ if Decimal(repr(result)) != value:
35
+ raise ValueError("the decimal cannot be read back without losing digits")
36
+ return result
37
+
38
+
23
39
  def export_sqlite(
24
40
  outfile: str,
25
41
  hdrs: list[str],
@@ -27,60 +43,79 @@ def export_sqlite(
27
43
  append: bool,
28
44
  tablename: str,
29
45
  ) -> None:
30
- """Write pre-fetched rows to a table in an SQLite database file, creating it if necessary."""
46
+ """Export rows, rejecting lossy decimals before opening the destination.
47
+
48
+ Numeric Decimal values must read back equal to their source; spelling and
49
+ scale are not retained. Text columns retain their string representation.
50
+ Replacement DDL and inserts share a transaction, restored on any failure.
51
+ APPEND still refuses an existing table.
52
+ """
31
53
  import sqlite3
32
54
 
33
55
  from execsql.models import DataTable
34
56
 
35
- chunksize = 10000
36
- # B07a/F025: tablename is substituted from user input — use the
37
- # existing dbt_sqlite.quoted helper to identifier-quote every site
38
- # rather than f-string-interpolating into SQL.
57
+ rowdata = list(rows)
58
+ # Non-finite Decimals cannot pass the general-purpose integer scanner.
59
+ # A fractional placeholder preserves numeric inference without changing data.
60
+ scanrows = (
61
+ tuple(Decimal("0.5") if isinstance(v, Decimal) and not v.is_finite() else v for v in row) for row in rowdata
62
+ )
63
+ tablespec = DataTable(hdrs, scanrows, infer_strings=False)
64
+ create_sql = tablespec.create_table(dbt_sqlite, schemaname=None, tablename=tablename)
39
65
  qtable = dbt_sqlite.quoted(tablename)
40
- pre_exist = Path(outfile).is_file()
41
- sdb = sqlite3.connect(outfile)
66
+ # Let SQLite expose the generated declarations, including quoted identifiers.
67
+ probe = sqlite3.connect(":memory:")
42
68
  try:
43
- if pre_exist:
44
- curs = sdb.cursor()
45
- # Existence check: the table name is a value here (not an
46
- # identifier), so use a parameter rather than string concat.
47
- res = curs.execute(
48
- "select name from sqlite_master where type='table' and name=?;",
49
- (tablename,),
50
- )
51
- rv = res.fetchone()
52
- if not (rv is None or rv[0] == 0):
53
- if append:
54
- raise ErrInfo(type="error", other_msg=f"The table {tablename} already exists in {outfile}.")
69
+ probe.execute(create_sql)
70
+ affinities = [_affinity(col[2]) for col in probe.execute(f"PRAGMA table_info({qtable})")]
71
+ converted = []
72
+ for row in rowdata:
73
+ bound: list[Any] = []
74
+ for i, value in enumerate(row):
75
+ if isinstance(value, Decimal) and i < len(affinities) and affinities[i] not in ("TEXT", "BLOB"):
76
+ try:
77
+ number = _exact_number(value, affinities[i])
78
+ if value.is_finite():
79
+ # Preserve the previous stored value too: SQLite's text
80
+ # parser can round differently from Python's conversion.
81
+ cast_type = "REAL" if affinities[i] == "REAL" else "NUMERIC"
82
+ previous = probe.execute(f"SELECT CAST(? AS {cast_type})", (str(value),)).fetchone()[0]
83
+ if Decimal(repr(previous)) != value:
84
+ raise ValueError("SQLite's numeric conversion loses source digits")
85
+ bound.append(number)
86
+ except ValueError as exc:
87
+ raise ErrInfo(
88
+ type="error",
89
+ other_msg=(
90
+ f"Can't export column {hdrs[i]} to SQLite table {tablename}: {value} "
91
+ f"cannot be stored without losing digits. Nothing was written. "
92
+ "To preserve the exact text, export CAST(column AS VARCHAR)."
93
+ ),
94
+ ) from exc
55
95
  else:
56
- curs.execute(f"drop table {qtable};")
57
- curs.close()
58
- # Construct and run the CREATE TABLE statement
59
- rowdata = list(rows)
60
- tablespec = DataTable(hdrs, rowdata, infer_strings=False)
61
- rowdata = [
62
- tuple(
63
- str(v) if isinstance(v, Decimal) else v if (v is None or isinstance(v, _SQLITE_SAFE)) else str(v)
64
- for v in row
65
- )
66
- for row in rowdata
67
- ]
68
- sql = tablespec.create_table(dbt_sqlite, schemaname=None, tablename=tablename)
69
- curs = sdb.cursor()
70
- curs.execute(sql)
71
- # Export all rows of data
72
- columns = [dbt_sqlite.quoted(col) for col in hdrs]
73
- colspec = ",".join(columns)
74
- paramspec = ",".join(("?",) * len(columns))
75
- sql = f"insert into {qtable} ({colspec}) values ({paramspec});"
76
- n_chunks = math.ceil(len(rowdata) / chunksize)
77
- for i in range(n_chunks):
78
- start = i * chunksize
79
- end = start + chunksize
80
- curs.executemany(sql, rowdata[start:end])
96
+ bound.append(value if value is None or isinstance(value, _SQLITE_SAFE) else str(value))
97
+ converted.append(tuple(bound))
98
+ finally:
99
+ probe.close()
100
+
101
+ sdb = sqlite3.connect(outfile, isolation_level=None)
102
+ try:
103
+ sdb.execute("BEGIN")
104
+ exists = sdb.execute("SELECT name FROM sqlite_master WHERE type='table' AND name=?", (tablename,)).fetchone()
105
+ if exists is not None:
106
+ if append:
107
+ raise ErrInfo(type="error", other_msg=f"The table {tablename} already exists in {outfile}.")
108
+ sdb.execute(f"DROP TABLE {qtable}")
109
+ sdb.execute(create_sql)
110
+ columns = ",".join(dbt_sqlite.quoted(col) for col in hdrs)
111
+ parameters = ",".join("?" for _ in hdrs)
112
+ insert_sql = f"INSERT INTO {qtable} ({columns}) VALUES ({parameters})"
113
+ chunksize = 10000
114
+ for start in range(0, len(converted), chunksize):
115
+ sdb.executemany(insert_sql, converted[start : start + chunksize])
81
116
  sdb.commit()
82
- curs.close()
83
117
  finally:
118
+ # close() rolls back an open transaction, including on BaseException.
84
119
  sdb.close()
85
120
 
86
121
 
execsql/format.py CHANGED
@@ -1032,12 +1032,20 @@ def format_sql_block(
1032
1032
  layout_lines = [line for i, line in enumerate(lines) if line.strip() and i not in interior]
1033
1033
  base = min((len(line) - len(line.lstrip()) for line in layout_lines), default=0)
1034
1034
  target_prefix = " " * (depth * indent)
1035
- rebased = [line if i in interior else (line[base:] if line.strip() else "") for i, line in enumerate(lines)]
1035
+ rebased = []
1036
+ for i, line in enumerate(lines):
1037
+ if i in interior:
1038
+ rebased.append(line)
1039
+ elif line.strip():
1040
+ rebased.append(line[base:])
1041
+ else:
1042
+ rebased.append("")
1036
1043
 
1037
1044
  if not use_sql:
1038
- return [
1039
- line if i in interior else (target_prefix + line if line.strip() else "") for i, line in enumerate(rebased)
1040
- ]
1045
+ for i, line in enumerate(rebased):
1046
+ if i not in interior and line.strip():
1047
+ rebased[i] = target_prefix + line
1048
+ return rebased
1041
1049
 
1042
1050
  # When comments appear mid-statement, use the marker-based approach
1043
1051
  # which preserves both comments AND sqlglot formatting. When all
execsql/gui/__init__.py CHANGED
@@ -1,16 +1,19 @@
1
- """The GUI manager thread for execsql.
1
+ """GUI backend dispatch and the terminal fallback's manager loop.
2
2
 
3
- Usage
4
- -----
5
- Call ``enable_gui()`` (via ``execsql.utils.gui``) to initialise the backend
6
- and start the manager thread. All dialog requests are then placed on
7
- ``_state.gui_manager_queue`` as ``GuiSpec`` objects and dispatched by
8
- ``gui_manager_loop()``.
3
+ ``execsql.utils.gui.enable_gui()`` selects a backend by configured framework::
9
4
 
10
- ``enable_gui()`` picks the backend by framework, not by level:
5
+ tkinter -> TkinterBackend -> TextualBackend -> ConsoleBackend
6
+ textual -> TextualBackend -> ConsoleBackend
11
7
 
12
- framework "tkinter" → TkinterBackend → TextualBackend → ConsoleBackend
13
- framework "textual" → TextualBackend → ConsoleBackend
8
+ Native Tk and ordinary Textual dialogs use synchronous queue adapters that run
9
+ in the calling thread. Only the ConsoleBackend fallback starts
10
+ ``gui_manager_loop()`` on a daemon manager thread. The persistent Textual CLI
11
+ console instead runs its UI on the main thread and its script on a worker,
12
+ with ``_ConsoleDialogQueue`` carrying modal requests and responses.
13
+
14
+ Every request contains a return queue. Script-side consumers receive checked
15
+ results through ``get_gui_response()`` and own error/cancellation policy. See
16
+ ``docs/dev/architecture.md`` for execution modes and shutdown ownership.
14
17
  """
15
18
 
16
19
  from __future__ import annotations
execsql/gui/base.py CHANGED
@@ -4,7 +4,7 @@ from __future__ import annotations
4
4
 
5
5
  from abc import ABC, abstractmethod
6
6
  from dataclasses import dataclass, field
7
- from typing import TYPE_CHECKING, Any
7
+ from typing import TYPE_CHECKING, Any, TypedDict
8
8
 
9
9
  if TYPE_CHECKING:
10
10
  pass
@@ -14,6 +14,102 @@ __all__ = ["DiffResult", "GuiBackend", "compare_stats", "compute_row_diffs", "fo
14
14
  DIFF_MARKER = "● "
15
15
 
16
16
 
17
+ FILE_DATABASES = frozenset(("l", "k", "a"))
18
+ CONNECTION_ENCODINGS = ("UTF8", "LATIN1", "ASCII", "UTF16")
19
+
20
+
21
+ class ConnectResult(TypedDict):
22
+ """Confirmed connection inputs; a blank password never requests another prompt."""
23
+
24
+ db_type: str | None
25
+ server: str | None
26
+ database: str | None
27
+ db_file: str | None
28
+ username: str | None
29
+ password: str | None
30
+ port: int | None
31
+ encoding: str | None
32
+
33
+
34
+ def connection_result(
35
+ db_type: str,
36
+ server: str = "",
37
+ database: str = "",
38
+ username: str = "",
39
+ password: str = "",
40
+ port: str | int | None = None,
41
+ encoding: str = "",
42
+ ) -> ConnectResult:
43
+ """Normalize visible connection fields and reject invalid ports before connecting.
44
+
45
+ File databases ignore hidden network controls. DSNs use their configured host
46
+ and port. Password whitespace is significant and is never stripped.
47
+ """
48
+ if db_type not in "pslmkofad" or len(db_type) != 1:
49
+ raise ValueError("Select a database type.")
50
+ file_based = db_type in FILE_DATABASES
51
+ port_number = None
52
+ if isinstance(port, str):
53
+ port = port.strip()
54
+ if not file_based and db_type != "d" and port not in (None, ""):
55
+ try:
56
+ port_number = int(str(port).strip())
57
+ except ValueError as exc:
58
+ raise ValueError("Port must be an integer from 1 to 65535.") from exc
59
+ if not 1 <= port_number <= 65535:
60
+ raise ValueError("Port must be an integer from 1 to 65535.")
61
+ return ConnectResult(
62
+ db_type=db_type,
63
+ server=None if file_based or db_type == "d" else server.strip() or None,
64
+ database=None if file_based else database.strip() or None,
65
+ db_file=(database.strip() or None) if file_based else None,
66
+ username=None if file_based else username.strip() or None,
67
+ password=None if file_based else password or None,
68
+ port=port_number,
69
+ encoding=None if file_based else encoding.strip() or None,
70
+ )
71
+
72
+
73
+ def normalize_text_entry(value: str, entry_type: str | None = None, entry_case: str | None = None) -> str:
74
+ """Validate an ENTER_SUB value, expand BOOL prefixes, then apply requested case.
75
+
76
+ Empty values are allowed for every type. Numeric values remain textual,
77
+ preserving leading zeros and the entered decimal representation.
78
+ Validation errors do not include the value, which may be a password.
79
+ """
80
+ import re
81
+
82
+ kind = (entry_type or "text").lower()
83
+ if not isinstance(value, str):
84
+ raise ValueError("The entered value must be text.")
85
+ if value:
86
+ if kind == "int" and not re.fullmatch(r"-?[0-9]+", value):
87
+ raise ValueError("Enter digits with an optional leading minus sign.")
88
+ if kind == "float" and not re.fullmatch(r"-?(?:[0-9]+(?:\.[0-9]*)?|\.[0-9]+)", value):
89
+ raise ValueError("Enter digits with at most one decimal point and an optional leading minus sign.")
90
+ if kind == "ident" and not re.fullmatch(r"[A-Za-z][A-Za-z0-9_]*", value):
91
+ raise ValueError("Start with a letter and use only letters, digits and underscores.")
92
+ if kind == "bool":
93
+ if "true".startswith(value.lower()):
94
+ value = "True"
95
+ elif "false".startswith(value.lower()):
96
+ value = "False"
97
+ else:
98
+ raise ValueError("Enter True or False, or a nonempty prefix of either word.")
99
+ case = (entry_case or "any").lower()
100
+ if case == "lcase":
101
+ return value.lower()
102
+ if case == "ucase":
103
+ return value.upper()
104
+ return value
105
+
106
+
107
+ def selected_row_values(headers: list, row: list | tuple, destination_headers: list) -> list:
108
+ """Project a selected source row into the destination's display column order."""
109
+ values = dict(zip(headers, row))
110
+ return [values.get(header) for header in destination_headers]
111
+
112
+
17
113
  # ---------------------------------------------------------------------------
18
114
  # Plain-text table rendering (shared by the console backend and by
19
115
  # non-interactive metacommand fallbacks such as HALT ... DISPLAY)
@@ -130,6 +226,13 @@ class DiffResult:
130
226
  summary: str = ""
131
227
 
132
228
 
229
+ def _key_column_indices(headers: list[str], keylist: list) -> list[int]:
230
+ """Return every key column's index in declared order, or no indices if incomplete."""
231
+ if any(key not in headers for key in keylist):
232
+ return []
233
+ return [headers.index(key) for key in keylist]
234
+
235
+
133
236
  def compute_row_diffs(
134
237
  headers1: list,
135
238
  rows1: list,
@@ -158,8 +261,8 @@ def compute_row_diffs(
158
261
  return None
159
262
  headers1_str = [str(h) for h in headers1]
160
263
  headers2_str = [str(h) for h in headers2]
161
- key_idx1 = [i for i, h in enumerate(headers1_str) if h in keylist]
162
- key_idx2 = [i for i, h in enumerate(headers2_str) if h in keylist]
264
+ key_idx1 = _key_column_indices(headers1_str, keylist)
265
+ key_idx2 = _key_column_indices(headers2_str, keylist)
163
266
  if not key_idx1 or not key_idx2:
164
267
  return None
165
268
 
@@ -275,9 +378,17 @@ class GuiBackend(ABC):
275
378
  - ``show_display`` → ``{"button": int|None, "return_value": str|None}``
276
379
  - ``show_entry_form`` → ``{"button": int|None, "return_value": list[EntrySpec]}``
277
380
  - ``show_compare`` → ``{"button": int|None}``
278
- - ``show_select_rows``→ ``{"button": int|None}``
279
- - ``show_select_sub`` → ``{"button": int|None, "row": dict|None}``
280
- - ``show_action`` → ``{"button": int|None}``
381
+ - ``show_select_rows``→ ``{"button": int|None, "rows": list|None}``
382
+ ``rows`` contains new selections in source column order, with original
383
+ Python values and duplicates retained. ``[]`` means no selections;
384
+ ``None`` means cancelled or unavailable (console fallback).
385
+ - ``show_select_sub`` → ``{"button": int|None, "row": list|None}``
386
+ ``row`` contains the original Python values in source column order;
387
+ button 1 confirms it, 2 continues without selecting, None cancels.
388
+ - ``show_action`` → ``{"button": int|None, "row": list|None}``
389
+ Buttons 1..N identify the action in ``button_specs``; 0 continues
390
+ without an action, None cancels. Only data-required actions return
391
+ original source-row values, in source column order.
281
392
  - ``show_map`` → ``{"button": int|None}``
282
393
  - ``show_open_file`` → ``{"filename": str|None}``
283
394
  - ``show_save_file`` → ``{"filename": str|None}``
@@ -349,6 +460,9 @@ class GuiBackend(ABC):
349
460
  def console_show(self) -> None:
350
461
  """Show the console window (if applicable)."""
351
462
 
463
+ def console_resize(self, width: int, height: int) -> None:
464
+ """Resize a native console in characters/lines; terminal backends do nothing."""
465
+
352
466
  def console_progress(self, num: float, total: float | None = None) -> None:
353
467
  """Update the progress indicator."""
354
468
 
@@ -423,8 +537,17 @@ class GuiBackend(ABC):
423
537
 
424
538
  @abstractmethod
425
539
  def show_credentials(self, args: dict) -> dict:
426
- """Show a credentials (username + password) dialog."""
540
+ """Show a credentials dialog returning username and password strings.
541
+
542
+ GUI backends return button=1 for OK or button=None for cancellation;
543
+ confirming empty credentials is distinct from cancelling.
544
+ """
427
545
 
428
546
  @abstractmethod
429
547
  def show_connect(self, args: dict) -> dict:
430
- """Show a database connection selection dialog."""
548
+ """Collect connection inputs using the shared ConnectResult field names.
549
+
550
+ Confirmed inputs pass through connection_result; cancellation omits
551
+ db_type or returns None for it. Blank passwords do not request a
552
+ secondary password prompt. Password strings retain their whitespace.
553
+ """