execsql2 2.39.1__py3-none-any.whl → 2.41.0__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 (54) hide show
  1. execsql/__init__.py +4 -2
  2. execsql/api.py +40 -27
  3. execsql/cli/commands/__init__.py +1 -0
  4. execsql/cli/commands/inspect.py +292 -0
  5. execsql/cli/dispatch.py +3 -3
  6. execsql/cli/inspection.py +276 -0
  7. execsql/cli/lint.py +3 -4
  8. execsql/cli/options.py +15 -7
  9. execsql/config.py +15 -2
  10. execsql/db/access.py +6 -5
  11. execsql/db/base.py +14 -0
  12. execsql/db/dsn.py +3 -2
  13. execsql/db/duckdb.py +2 -1
  14. execsql/db/firebird.py +3 -2
  15. execsql/db/mysql.py +3 -2
  16. execsql/db/oracle.py +3 -2
  17. execsql/db/postgres.py +3 -2
  18. execsql/db/sqlite.py +2 -1
  19. execsql/db/sqlserver.py +3 -2
  20. execsql/ddl.py +310 -0
  21. execsql/exporters/xls.py +18 -4
  22. execsql/file_inspection.py +393 -0
  23. execsql/importers/base.py +19 -12
  24. execsql/importers/feather.py +16 -21
  25. execsql/importers/json.py +26 -32
  26. execsql/importers/xls.py +9 -4
  27. execsql/metacommands/control.py +21 -23
  28. execsql/metacommands/script_ext.py +6 -2
  29. execsql/schema.py +816 -0
  30. execsql/script/executor.py +11 -0
  31. execsql/script/parser.py +31 -0
  32. execsql/script/variables.py +14 -2
  33. execsql/utils/errors.py +21 -3
  34. {execsql2-2.39.1.data → execsql2-2.41.0.data}/data/execsql2_extras/README.md +7 -0
  35. execsql2-2.41.0.data/data/execsql2_extras/inspect/README.md +116 -0
  36. execsql2-2.41.0.data/data/execsql2_extras/inspect/make_demo.py +106 -0
  37. {execsql2-2.39.1.dist-info → execsql2-2.41.0.dist-info}/METADATA +84 -19
  38. {execsql2-2.39.1.dist-info → execsql2-2.41.0.dist-info}/RECORD +54 -47
  39. {execsql2-2.39.1.data → execsql2-2.41.0.data}/data/execsql2_extras/config_settings.sqlite +0 -0
  40. {execsql2-2.39.1.data → execsql2-2.41.0.data}/data/execsql2_extras/example_config_prompt.sql +0 -0
  41. {execsql2-2.39.1.data → execsql2-2.41.0.data}/data/execsql2_extras/make_config_db.sql +0 -0
  42. {execsql2-2.39.1.data → execsql2-2.41.0.data}/data/execsql2_extras/md_compare.sql +0 -0
  43. {execsql2-2.39.1.data → execsql2-2.41.0.data}/data/execsql2_extras/md_glossary.sql +0 -0
  44. {execsql2-2.39.1.data → execsql2-2.41.0.data}/data/execsql2_extras/md_upsert.sql +0 -0
  45. {execsql2-2.39.1.data → execsql2-2.41.0.data}/data/execsql2_extras/pg_compare.sql +0 -0
  46. {execsql2-2.39.1.data → execsql2-2.41.0.data}/data/execsql2_extras/pg_glossary.sql +0 -0
  47. {execsql2-2.39.1.data → execsql2-2.41.0.data}/data/execsql2_extras/script_template.sql +0 -0
  48. {execsql2-2.39.1.data → execsql2-2.41.0.data}/data/execsql2_extras/ss_compare.sql +0 -0
  49. {execsql2-2.39.1.data → execsql2-2.41.0.data}/data/execsql2_extras/ss_glossary.sql +0 -0
  50. {execsql2-2.39.1.data → execsql2-2.41.0.data}/data/execsql2_extras/ss_upsert.sql +0 -0
  51. {execsql2-2.39.1.dist-info → execsql2-2.41.0.dist-info}/WHEEL +0 -0
  52. {execsql2-2.39.1.dist-info → execsql2-2.41.0.dist-info}/entry_points.txt +0 -0
  53. {execsql2-2.39.1.dist-info → execsql2-2.41.0.dist-info}/licenses/LICENSE.txt +0 -0
  54. {execsql2-2.39.1.dist-info → execsql2-2.41.0.dist-info}/licenses/NOTICE +0 -0
execsql/ddl.py ADDED
@@ -0,0 +1,310 @@
1
+ """Read-only CREATE statements and IMPORT-based file declarations."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import re
6
+ from enum import Enum
7
+ from typing import Any
8
+
9
+ from execsql.db.base import Database
10
+ from execsql.models import DataTable
11
+ from execsql.types import DbType
12
+
13
+
14
+ class SqlDialect(str, Enum):
15
+ """Explicit destination dialects for inferred file SQL."""
16
+
17
+ sqlite = "sqlite"
18
+ duckdb = "duckdb"
19
+ postgres = "postgres"
20
+ mysql = "mysql"
21
+ mssql = "mssql"
22
+ oracle = "oracle"
23
+ firebird = "firebird"
24
+ access = "access"
25
+
26
+
27
+ class DdlError(Exception):
28
+ """A fixed, nonsecret explanation for unavailable SQL output."""
29
+
30
+ def __init__(self, code: str, message: str):
31
+ super().__init__(message)
32
+ self.code, self.message = code, message
33
+
34
+
35
+ def _quote(name: str, dialect: str) -> str:
36
+ opening, closing = (
37
+ ("`", "`") if dialect == "MySQL" else ("[", "]") if dialect in ("SQL Server", "Access") else ('"', '"')
38
+ )
39
+ return opening + name.replace(closing, closing * 2) + closing
40
+
41
+
42
+ class _FileDialect(DbType):
43
+ """Share IMPORT declarations, preserving its unquoted-name folding."""
44
+
45
+ def __init__(self, source: DbType):
46
+ super().__init__(source.dbms_id)
47
+ self.source = source
48
+ self.dialect = source.dialect
49
+
50
+ def spec_type(self, data_type: Any) -> Any:
51
+ return self.source.spec_type(data_type)
52
+
53
+ def quoted(self, dbms_object: str) -> str:
54
+ if not re.search(r"\W", dbms_object):
55
+ if not dbms_object.isascii():
56
+ # Let the engine apply its existing locale/Unicode folding.
57
+ return self.source.quoted(dbms_object)
58
+ if self.dbms_id == "PostgreSQL":
59
+ dbms_object = dbms_object.lower()
60
+ elif self.dbms_id in ("Oracle", "Firebird"):
61
+ dbms_object = dbms_object.upper()
62
+ return _quote(dbms_object, self.dbms_id)
63
+
64
+
65
+ def file_sql(table: DataTable, dialect: str, schema: str | None, name: str) -> str:
66
+ """Use the existing type and observed-nullability inference, without rescanning."""
67
+ from execsql import types
68
+
69
+ target = {
70
+ "sqlite": types.dbt_sqlite,
71
+ "duckdb": types.dbt_duckdb,
72
+ "postgres": types.dbt_postgres,
73
+ "mysql": types.dbt_mysql,
74
+ "mssql": types.dbt_sqlserver,
75
+ "oracle": types.dbt_oracle,
76
+ "firebird": types.dbt_firebird,
77
+ "access": types.dbt_access,
78
+ }[dialect]
79
+ if not table.cols:
80
+ raise DdlError("sql_error", "SQL output requires at least one inferred column.")
81
+ if any(not isinstance(column.name, str) or not column.name or "\x00" in column.name for column in table.cols):
82
+ raise DdlError("sql_error", "Inferred SQL column names must be nonempty and contain no NUL characters.")
83
+ return table.create_table(_FileDialect(target), schema, name, pretty=True) + "\n"
84
+
85
+
86
+ SUPPORTED_TABLE_SQL = {"SQLite", "DuckDB", "MySQL", "PostgreSQL"}
87
+
88
+
89
+ def _statement(sql: Any) -> str:
90
+ if not isinstance(sql, str) or not sql.strip() or "\x00" in sql:
91
+ raise DdlError("sql_error", "The database did not return a complete object definition.")
92
+ text = sql.rstrip()
93
+ # A final line comment must not consume an appended statement terminator.
94
+ return text + ("\n" if text.endswith(";") else "\n;\n")
95
+
96
+
97
+ def table_sql(db: Database, tables: list[dict[str, Any]]) -> str:
98
+ """Read exactly one selected object's definition; never fetch its data."""
99
+ from execsql.schema import _rows
100
+
101
+ if not tables:
102
+ raise DdlError("object_not_found", "SQL output requires one matching table or view; none was found.")
103
+ if len(tables) != 1:
104
+ raise DdlError(
105
+ "ambiguous_object",
106
+ "SQL output requires one matching table or view; use --schema to qualify it.",
107
+ )
108
+ item = tables[0]
109
+ namespace, name, kind = item["schema"], item["name"], item["kind"]
110
+ dialect = db.type.dbms_id
111
+ if dialect == "SQLite":
112
+ rows = _rows(
113
+ db,
114
+ f"SELECT sql FROM {db.quote_identifier(namespace)}.sqlite_master WHERE name = ? AND type = ?",
115
+ [name, kind],
116
+ )
117
+ return _statement(rows[0][0] if rows else None)
118
+ if dialect == "DuckDB":
119
+ function, column = ("duckdb_views", "view_name") if kind == "view" else ("duckdb_tables", "table_name")
120
+ rows = _rows(
121
+ db,
122
+ f"SELECT sql FROM {function}() WHERE database_name = current_database() AND schema_name = ? AND {column} = ?",
123
+ [namespace, name],
124
+ )
125
+ return _statement(rows[0][0] if rows else None)
126
+ if dialect == "MySQL":
127
+ mode, collation, timezone = _rows(
128
+ db,
129
+ "SELECT @@sql_mode, @@collation_connection, @@time_zone",
130
+ )[0]
131
+ if set(mode.upper().split(",")) & {"NO_FIELD_OPTIONS", "NO_KEY_OPTIONS", "NO_TABLE_OPTIONS"}:
132
+ raise DdlError("unsupported_sql_feature", "Current MySQL/MariaDB SQL mode omits definition details.")
133
+ if not all(isinstance(value, str) and re.fullmatch(r"[A-Za-z0-9_,]*", value) for value in (mode, collation)):
134
+ raise DdlError("sql_error", "The database returned invalid SQL session metadata.")
135
+ if timezone == "SYSTEM":
136
+ # Even UTC/GMT startup abbreviations cannot establish the system
137
+ # zone's historical rules (for example, London's summer BST).
138
+ raise DdlError(
139
+ "unsupported_sql_feature",
140
+ "SQL output requires an explicit MySQL/MariaDB session time_zone; SYSTEM is unsupported.",
141
+ )
142
+ if not isinstance(timezone, str) or not re.fullmatch(r"[A-Za-z0-9_+:/-]+", timezone):
143
+ raise DdlError("sql_error", "The database returned invalid SQL session metadata.")
144
+ command = "VIEW" if kind == "view" else "TABLE"
145
+ rows = _rows(db, f"SHOW CREATE {command} {db.quote_identifier(namespace)}.{db.quote_identifier(name)}")
146
+ sql = _statement(rows[0][1] if rows else None)
147
+ if kind == "view" and len(rows[0]) >= 4:
148
+ collation = rows[0][3] # The view's creation context, not this session's default.
149
+ if not isinstance(collation, str) or not re.fullmatch(r"[A-Za-z0-9_]+", collation):
150
+ raise DdlError("sql_error", "The database returned invalid SQL session metadata.")
151
+ # Leave client encoding to the destination driver. SET NAMES would change
152
+ # the server's decoder without updating that driver's own text encoder.
153
+ return (
154
+ f"SET SESSION sql_mode = '{mode}';\nSET collation_connection = '{collation}';\n"
155
+ f"SET SESSION time_zone = '{timezone}';\n" + sql
156
+ )
157
+ if dialect == "PostgreSQL":
158
+ return _postgres_sql(db, namespace, name)
159
+ raise DdlError("unsupported_sql", "SQL output supports SQLite, DuckDB, MySQL/MariaDB and PostgreSQL tables/views.")
160
+
161
+
162
+ _PG_DEFINITION = """SELECT to_jsonb(c), n.nspname, am.amname, pg_catalog.current_schemas(true),
163
+ COALESCE((SELECT jsonb_agg(to_jsonb(a) || jsonb_build_object(
164
+ 'type_sql', pg_catalog.format_type(a.atttypid, a.atttypmod),
165
+ 'default_sql', pg_catalog.pg_get_expr(d.adbin, d.adrelid, false),
166
+ 'base_storage', t.typstorage,
167
+ 'collation_schema', cn.nspname, 'collation_name', co.collname,
168
+ 'different_collation', a.attcollation <> t.typcollation,
169
+ 'sequence', (SELECT to_jsonb(s) FROM pg_catalog.pg_sequence s
170
+ JOIN pg_catalog.pg_depend dep ON dep.objid = s.seqrelid AND dep.classid = 'pg_catalog.pg_class'::regclass
171
+ WHERE dep.refclassid = 'pg_catalog.pg_class'::regclass AND dep.refobjid = c.oid
172
+ AND dep.refobjsubid = a.attnum AND dep.deptype = 'i')) ORDER BY a.attnum)
173
+ FROM pg_catalog.pg_attribute a JOIN pg_catalog.pg_type t ON t.oid = a.atttypid
174
+ LEFT JOIN pg_catalog.pg_attrdef d ON d.adrelid = a.attrelid AND d.adnum = a.attnum
175
+ LEFT JOIN pg_catalog.pg_collation co ON co.oid = a.attcollation
176
+ LEFT JOIN pg_catalog.pg_namespace cn ON cn.oid = co.collnamespace
177
+ WHERE a.attrelid = c.oid AND a.attnum > 0 AND NOT a.attisdropped), '[]'::jsonb),
178
+ COALESCE((SELECT jsonb_agg(to_jsonb(k) || jsonb_build_object(
179
+ 'definition', pg_catalog.pg_get_constraintdef(k.oid, false)) ORDER BY k.conname)
180
+ FROM pg_catalog.pg_constraint k WHERE k.conrelid = c.oid), '[]'::jsonb),
181
+ CASE WHEN c.relkind = 'v' THEN pg_catalog.pg_get_viewdef(c.oid, false) END,
182
+ EXISTS(SELECT 1 FROM pg_catalog.pg_inherits i WHERE i.inhrelid = c.oid OR i.inhparent = c.oid),
183
+ (SELECT jsonb_object_agg(setting, pg_catalog.current_setting(setting)) FROM unnest(ARRAY[
184
+ 'DateStyle', 'IntervalStyle', 'standard_conforming_strings', 'lc_monetary',
185
+ 'TimeZone', 'backslash_quote', 'extra_float_digits']) AS settings(setting))
186
+ FROM pg_catalog.pg_class c JOIN pg_catalog.pg_namespace n ON n.oid = c.relnamespace
187
+ LEFT JOIN pg_catalog.pg_am am ON am.oid = c.relam
188
+ WHERE n.nspname = ? AND c.relname = ?"""
189
+
190
+
191
+ def _postgres_sql(db: Database, namespace: str, name: str) -> str:
192
+ from execsql.schema import _rows
193
+
194
+ if int(_rows(db, "SELECT pg_catalog.current_setting('server_version_num')")[0][0]) < 140000:
195
+ raise DdlError("unsupported_sql_feature", "PostgreSQL SQL output requires PostgreSQL 14 or newer.")
196
+ rows = _rows(db, _PG_DEFINITION, [namespace, name])
197
+ if len(rows) != 1:
198
+ raise DdlError("sql_error", "The selected object changed during SQL inspection; retry the command.")
199
+ relation, namespace, access_method, search_path, columns, constraints, view, inherited, settings = rows[0]
200
+ if int(settings["extra_float_digits"]) <= 0:
201
+ raise DdlError(
202
+ "unsupported_sql_feature",
203
+ "PostgreSQL SQL output requires extra_float_digits greater than zero to preserve floating-point literals.",
204
+ )
205
+ kind = relation["relkind"]
206
+ if kind not in ("r", "v") or relation.get("relispartition") or int(relation["reloftype"]) or inherited:
207
+ raise DdlError(
208
+ "unsupported_sql_feature",
209
+ "PostgreSQL SQL output covers ordinary tables and views, not partitioned, inherited, typed, foreign or materialized objects.",
210
+ )
211
+ temporary = relation["relpersistence"] == "t"
212
+ if temporary and kind == "r":
213
+ raise DdlError(
214
+ "unsupported_sql_feature",
215
+ "PostgreSQL temporary-table ON COMMIT policy is unavailable through read-only catalog inspection.",
216
+ )
217
+ qualified = db.quote_identifier(name) if temporary else db.quote_qualified_identifier(namespace, name)
218
+ # Keep server-decompiled expressions resolved as in the source, without SET
219
+ # on the inspected connection. Required dependency objects are not recreated.
220
+ paths = ["pg_temp" if path.startswith("pg_temp_") else path for path in search_path]
221
+ context = "SET search_path TO " + ", ".join(db.quote_identifier(path) for path in paths) + ";\n"
222
+ for setting, value in settings.items():
223
+ # E strings with doubled backslashes/quotes work regardless of the
224
+ # destination's standard_conforming_strings setting.
225
+ literal = value.replace("\\", "\\\\").replace("'", "''")
226
+ context += f"SET {setting} TO E'{literal}';\n"
227
+ if kind == "v":
228
+ view_options = []
229
+ for option in relation["reloptions"] or []:
230
+ key, _, value = option.partition("=")
231
+ if key not in ("security_barrier", "security_invoker", "check_option") or value not in (
232
+ "true",
233
+ "false",
234
+ "local",
235
+ "cascaded",
236
+ ):
237
+ raise DdlError("unsupported_sql_feature", "This PostgreSQL view has unsupported creation options.")
238
+ view_options.append(f"{key}={value}")
239
+ names = ", ".join(db.quote_identifier(column["attname"]) for column in columns)
240
+ header = f"CREATE {'TEMP ' if temporary else ''}VIEW {qualified}" + (f" ({names})" if names else "")
241
+ if view_options:
242
+ header += " WITH (" + ", ".join(view_options) + ")"
243
+ return context + _statement(header + " AS\n" + view)
244
+ if (
245
+ relation["reloptions"]
246
+ or int(relation["reltablespace"])
247
+ or access_method != "heap"
248
+ or relation["relrowsecurity"]
249
+ or relation["relforcerowsecurity"]
250
+ or relation["relreplident"] != "d"
251
+ ):
252
+ raise DdlError(
253
+ "unsupported_sql_feature",
254
+ "This PostgreSQL table has storage, row-security or replica-identity settings outside CREATE output's supported scope.",
255
+ )
256
+ if any(
257
+ not constraint["convalidated"] or constraint["contype"] not in ("p", "u", "f", "c", "x", "n")
258
+ for constraint in constraints
259
+ ):
260
+ raise DdlError("unsupported_sql_feature", "This PostgreSQL table has an unsupported or unvalidated constraint.")
261
+ named_not_null = {
262
+ number for constraint in constraints if constraint["contype"] == "n" for number in constraint["conkey"]
263
+ }
264
+ declarations = []
265
+ for column in columns:
266
+ if column["attstorage"] != column["base_storage"] or column.get("attcompression"):
267
+ raise DdlError(
268
+ "unsupported_sql_feature",
269
+ "This PostgreSQL column has unsupported storage or compression options.",
270
+ )
271
+ datatype = column["type_sql"]
272
+ if datatype.endswith("[]") and column["attndims"] > 1:
273
+ datatype += "[]" * (column["attndims"] - 1)
274
+ declaration = db.quote_identifier(column["attname"]) + " " + datatype
275
+ if column["different_collation"]:
276
+ declaration += " COLLATE " + db.quote_qualified_identifier(
277
+ column["collation_schema"],
278
+ column["collation_name"],
279
+ )
280
+ identity, generated = column.get("attidentity"), column.get("attgenerated")
281
+ if identity:
282
+ sequence = column["sequence"]
283
+ if identity not in ("a", "d") or not sequence:
284
+ raise DdlError("unsupported_sql_feature", "The PostgreSQL identity definition is unavailable.")
285
+ options = " ".join(
286
+ f"{label} {int(sequence[key])}"
287
+ for label, key in (
288
+ ("START WITH", "seqstart"),
289
+ ("INCREMENT BY", "seqincrement"),
290
+ ("MINVALUE", "seqmin"),
291
+ ("MAXVALUE", "seqmax"),
292
+ ("CACHE", "seqcache"),
293
+ )
294
+ )
295
+ options += " CYCLE" if sequence["seqcycle"] else " NO CYCLE"
296
+ declaration += f" GENERATED {'ALWAYS' if identity == 'a' else 'BY DEFAULT'} AS IDENTITY ({options})"
297
+ elif generated:
298
+ if generated not in ("s", "v") or not column["default_sql"]:
299
+ raise DdlError("unsupported_sql_feature", "The PostgreSQL generated-column definition is unavailable.")
300
+ declaration += (
301
+ f" GENERATED ALWAYS AS ({column['default_sql']}) {'STORED' if generated == 's' else 'VIRTUAL'}"
302
+ )
303
+ elif column["default_sql"] is not None:
304
+ declaration += " DEFAULT " + column["default_sql"]
305
+ if column["attnotnull"] and column["attnum"] not in named_not_null:
306
+ declaration += " NOT NULL"
307
+ declarations.append(declaration)
308
+ declarations += ["CONSTRAINT " + db.quote_identifier(c["conname"]) + " " + c["definition"] for c in constraints]
309
+ modifier = "TEMP " if temporary else "UNLOGGED " if relation["relpersistence"] == "u" else ""
310
+ return context + f"CREATE {modifier}TABLE {qualified} (\n " + ",\n ".join(declarations) + "\n);\n"
execsql/exporters/xls.py CHANGED
@@ -19,7 +19,7 @@ Both back-ends are optional dependencies; install via
19
19
 
20
20
  import datetime
21
21
  from pathlib import Path
22
- from typing import Any, cast
22
+ from typing import Any, BinaryIO, cast
23
23
 
24
24
  from execsql.exceptions import XlsFileError, XlsxFileError
25
25
  from execsql.utils.errors import fatal_error, install_hint
@@ -195,6 +195,7 @@ class XlsxFile:
195
195
  self.encoding: str | None = None
196
196
  self.wbk: Any = None
197
197
  self.read_only = False
198
+ self._source: BinaryIO | None = None
198
199
  self.errlog = self.XlsxLog()
199
200
 
200
201
  def open(self, filename: str, encoding: str | None = None, read_only: bool = False) -> None:
@@ -208,7 +209,15 @@ class XlsxFile:
208
209
 
209
210
  check_zip_decompression_ratio(filename)
210
211
  if read_only:
211
- self.wbk = self._openpyxl.load_workbook(filename, read_only=True)
212
+ # The caller has selected the format. A binary stream also
213
+ # supports explicitly identified XLSX content with another suffix.
214
+ self._source = open(filename, "rb") # noqa: SIM115 -- owned until close()
215
+ try:
216
+ self.wbk = self._openpyxl.load_workbook(self._source, read_only=True)
217
+ except BaseException:
218
+ self._source.close()
219
+ self._source = None
220
+ raise
212
221
  else:
213
222
  self.wbk = self._openpyxl.load_workbook(filename)
214
223
  else:
@@ -216,8 +225,13 @@ class XlsxFile:
216
225
 
217
226
  def close(self) -> None:
218
227
  """Close the open workbook and reset all state attributes."""
219
- if self.wbk is not None:
220
- self.wbk.close()
228
+ try:
229
+ if self.wbk is not None:
230
+ self.wbk.close()
231
+ finally:
232
+ if self._source is not None:
233
+ self._source.close()
234
+ self._source = None
221
235
  self.wbk = None
222
236
  self.filename = None
223
237
  self.encoding = None