execsql2 2.16.15__py3-none-any.whl → 2.16.16__py3-none-any.whl

execsql/api.py

@@ -316,6 +316,7 @@ def run(
     encoding: str = "utf-8",
     halt_on_error: bool = True,
     new_db: bool = False,
+    allow_system_cmd: bool = True,
 ) -> ScriptResult:
     """Execute a SQL script and return the result.
 
@@ -337,6 +338,8 @@ def run(
             error.  If ``False``, capture errors and continue.
         new_db: If ``True``, create the database if it does not exist
             (SQLite, PostgreSQL, DuckDB).
+        allow_system_cmd: If ``False``, the SYSTEM_CMD (SHELL) metacommand
+            is disabled and will raise an error if encountered.
 
     Returns:
         A :class:`ScriptResult` with execution outcome, timing, errors,
@@ -434,6 +437,7 @@ def run(
     ctx.subvars = subvars
     ctx.status = StatObj()
     ctx.status.halt_on_err = halt_on_error
+    conf.allow_system_cmd = allow_system_cmd
     ctx.conf = conf
 
     # Capture output to a buffer (suppress stdout/stderr)

execsql/cli/__init__.py

@@ -20,7 +20,7 @@ import typer
 
 from execsql import __version__
 from execsql.cli.dsn import _parse_connection_string, _SCHEME_TO_DBTYPE  # noqa: F401 — re-export
-from execsql.cli.help import _console, _err_console, _print_encodings, _print_metacommands  # noqa: F401 — re-export
+from execsql.cli.help import _console, _err_console, _init_config, _print_encodings, _print_metacommands  # noqa: F401 — re-export
 from execsql.cli.run import _connect_initial_db, _run  # noqa: F401 — re-export
 from execsql.exceptions import ConfigError, ErrInfo
 
@@ -29,6 +29,7 @@ __all__ = [
     "_connect_initial_db",
     "_console",
     "_err_console",
+    "_init_config",
     "_legacy_main",
     "_parse_connection_string",
     "_print_encodings",
@@ -72,28 +73,55 @@ def main(
             "name (client-server DBs) or a database file path (file-based DBs)."
         ),
     ),
-    # Named options — grouped to mirror the original argparse interface
-    sub_vars: list[str] | None = typer.Option(
+    # -- Connection --------------------------------------------------------
+    db_type: str | None = typer.Option(
         None,
-        "-a",
-        "--assign-arg",
-        metavar="VALUE",
-        help="Define the replacement string for a substitution variable [cyan]\\$ARG_x[/cyan].",
+        "-t",
+        "--type",
+        metavar="{a,d,p,s,l,m,k,o,f}",
+        help=(
+            "Database type: [bold]a[/bold]=MS-Access, [bold]p[/bold]=PostgreSQL, "
+            "[bold]s[/bold]=SQL Server, [bold]l[/bold]=SQLite, [bold]m[/bold]=MySQL/MariaDB, "
+            "[bold]k[/bold]=DuckDB, [bold]o[/bold]=Oracle, [bold]f[/bold]=Firebird, "
+            "[bold]d[/bold]=DSN."
+        ),
     ),
-    boolean_int: str | None = typer.Option(
+    dsn: str | None = typer.Option(
         None,
-        "-b",
-        "--boolean-int",
-        metavar="{0,1,t,f,y,n}",
-        help="Treat integers 0 and 1 as boolean values.",
+        "--dsn",
+        "--connection-string",
+        metavar="URL",
+        help=(
+            "Database connection URL, e.g. [cyan]postgresql://user:pass@host:5432/db[/cyan]. "
+            "Supported schemes: postgresql, mysql, mssql, oracle, firebird, sqlite, duckdb. "
+            "Overrides [cyan]-t[/cyan]/[cyan]-u[/cyan]/[cyan]-p[/cyan] and positional server/db args."
+        ),
     ),
-    make_dirs: str | None = typer.Option(
+    user: str | None = typer.Option(
         None,
-        "-d",
-        "--directories",
-        metavar="{0,1,t,f,y,n}",
-        help="Auto-create directories for EXPORT metacommand. [dim]n=no (default), y=yes[/dim]",
+        "-u",
+        "--user",
+        help="Database user name.",
     ),
+    port: int | None = typer.Option(
+        None,
+        "-p",
+        "--port",
+        help="Database server port.",
+    ),
+    no_passwd: bool = typer.Option(
+        False,
+        "-w",
+        "--no-passwd",
+        help="Skip password prompt when user is specified.",
+    ),
+    new_db: bool = typer.Option(
+        False,
+        "-n",
+        "--new-db",
+        help="Create a new SQLite or Postgres database if it does not exist.",
+    ),
+    # -- Encoding ----------------------------------------------------------
     database_encoding: str | None = typer.Option(
         None,
         "-e",
@@ -118,35 +146,13 @@ def main(
         "--import-encoding",
         help="Encoding for data files used with IMPORT.",
     ),
-    user_logfile: bool = typer.Option(
-        False,
-        "-l",
-        "--user-logfile",
-        help="Write a log file to [cyan]~/execsql.log[/cyan].",
-    ),
-    metacommands: bool = typer.Option(
-        False,
-        "-m",
-        "--metacommands",
-        help="List metacommands and exit.",
-    ),
-    new_db: bool = typer.Option(
-        False,
-        "-n",
-        "--new-db",
-        help="Create a new SQLite or Postgres database if it does not exist.",
-    ),
-    online_help: bool = typer.Option(
-        False,
-        "-o",
-        "--online-help",
-        help="Open the online documentation in the default browser.",
-    ),
-    port: int | None = typer.Option(
+    # -- Import/Export -----------------------------------------------------
+    import_buffer: int | None = typer.Option(
         None,
-        "-p",
-        "--port",
-        help="Database server port.",
+        "-z",
+        "--import-buffer",
+        metavar="KB",
+        help="Import buffer size in KB. [dim]Default: 32[/dim]",
     ),
     scanlines: int | None = typer.Option(
         None,
@@ -155,59 +161,36 @@ def main(
         metavar="N",
         help="Lines to scan for IMPORT format detection. [dim]0 = scan entire file.[/dim]",
     ),
-    db_type: str | None = typer.Option(
+    boolean_int: str | None = typer.Option(
         None,
-        "-t",
-        "--type",
-        metavar="{a,d,p,s,l,m,k,o,f}",
-        help=(
-            "Database type: [bold]a[/bold]=MS-Access, [bold]p[/bold]=PostgreSQL, "
-            "[bold]s[/bold]=SQL Server, [bold]l[/bold]=SQLite, [bold]m[/bold]=MySQL/MariaDB, "
-            "[bold]k[/bold]=DuckDB, [bold]o[/bold]=Oracle, [bold]f[/bold]=Firebird, "
-            "[bold]d[/bold]=DSN."
-        ),
+        "-b",
+        "--boolean-int",
+        metavar="{0,1,t,f,y,n}",
+        help="Treat integers 0 and 1 as boolean values.",
     ),
-    user: str | None = typer.Option(
+    make_dirs: str | None = typer.Option(
         None,
-        "-u",
-        "--user",
-        help="Database user name.",
+        "-d",
+        "--directories",
+        metavar="{0,1,t,f,y,n}",
+        help="Auto-create directories for EXPORT metacommand. [dim]n=no (default), y=yes[/dim]",
     ),
-    use_gui: str | None = typer.Option(
+    output_dir: str | None = typer.Option(
         None,
-        "-v",
-        "--visible-prompts",
-        metavar="{0,1,2,3}",
+        "--output-dir",
+        metavar="DIR",
         help=(
-            "GUI level: [bold]0[/bold]=none (default), [bold]1[/bold]=GUI for password/pause, "
-            "[bold]2[/bold]=GUI for password/pause + DB selection, [bold]3[/bold]=full GUI console."
+            "Default base directory for EXPORT output files. "
+            "Relative paths in EXPORT metacommands are joined to this directory. "
+            "Absolute paths and [cyan]stdout[/cyan] are unaffected."
         ),
     ),
-    gui_framework: str | None = typer.Option(
-        None,
-        "--gui-framework",
-        metavar="{tkinter,textual}",
-        help="GUI framework to use with [cyan]--visible-prompts[/cyan]. [dim]Default: tkinter[/dim]",
-    ),
-    no_passwd: bool = typer.Option(
-        False,
-        "-w",
-        "--no-passwd",
-        help="Skip password prompt when user is specified.",
-    ),
-    encodings: bool = typer.Option(
+    progress: bool = typer.Option(
         False,
-        "-y",
-        "--encodings",
-        help="List available encoding names and exit.",
-    ),
-    import_buffer: int | None = typer.Option(
-        None,
-        "-z",
-        "--import-buffer",
-        metavar="KB",
-        help="Import buffer size in KB. [dim]Default: 32[/dim]",
+        "--progress",
+        help="Show a progress bar for long-running IMPORT operations.",
     ),
+    # -- Execution ---------------------------------------------------------
     command: str | None = typer.Option(
         None,
         "-c",
@@ -221,7 +204,7 @@ def main(
     dry_run: bool = typer.Option(
         False,
         "--dry-run",
-        help=("Parse the script and print the command list without connecting to a database or executing anything."),
+        help="Parse the script and print the command list without connecting to a database or executing anything.",
     ),
     lint: bool = typer.Option(
         False,
@@ -232,51 +215,23 @@ def main(
             "and missing INCLUDE files (warnings). Exits 0 if no errors, 1 if errors found."
         ),
     ),
-    ping: bool = typer.Option(
+    parse_tree: bool = typer.Option(
         False,
-        "--ping",
-        help=(
-            "Test database connectivity and exit. "
-            "Prints connection details and the server version on success (exit 0), "
-            "or the error message on failure (exit 1). "
-            "No script file is required."
-        ),
-    ),
-    dsn: str | None = typer.Option(
-        None,
-        "--dsn",
-        "--connection-string",
-        metavar="URL",
-        help=(
-            "Database connection URL, e.g. [cyan]postgresql://user:pass@host:5432/db[/cyan]. "
-            "Supported schemes: postgresql, mysql, mssql, oracle, firebird, sqlite, duckdb. "
-            "Overrides [cyan]-t[/cyan]/[cyan]-u[/cyan]/[cyan]-p[/cyan] and positional server/db args."
-        ),
-    ),
-    output_dir: str | None = typer.Option(
-        None,
-        "--output-dir",
-        metavar="DIR",
+        "--parse-tree",
         help=(
-            "Default base directory for EXPORT output files. "
-            "Relative paths in EXPORT metacommands are joined to this directory. "
-            "Absolute paths and [cyan]stdout[/cyan] are unaffected."
+            "Parse the script into an abstract syntax tree and print the tree structure. "
+            "Does not connect to a database or execute anything."
         ),
     ),
-    progress: bool = typer.Option(
-        False,
-        "--progress",
-        help="Show a progress bar for long-running IMPORT operations.",
-    ),
-    dump_keywords: bool = typer.Option(
+    debug: bool = typer.Option(
         False,
-        "--dump-keywords",
-        help="Dump all metacommand keywords as JSON and exit.",
+        "--debug",
+        help="Start in step-through debug mode. The debug REPL pauses before each statement.",
     ),
-    list_plugins: bool = typer.Option(
+    no_system_cmd: bool = typer.Option(
         False,
-        "--list-plugins",
-        help="List all discovered plugins (metacommands, exporters, importers) and exit.",
+        "--no-system-cmd",
+        help="Disable the SYSTEM_CMD (SHELL) metacommand. Scripts that use SHELL will fail with an error.",
     ),
     profile: bool = typer.Option(
         False,
@@ -288,6 +243,24 @@ def main(
         "--profile-limit",
         help="Number of top statements to show in the --profile timing summary (default: 20).",
     ),
+    # -- GUI ---------------------------------------------------------------
+    use_gui: str | None = typer.Option(
+        None,
+        "-v",
+        "--visible-prompts",
+        metavar="{0,1,2,3}",
+        help=(
+            "GUI level: [bold]0[/bold]=none (default), [bold]1[/bold]=GUI for password/pause, "
+            "[bold]2[/bold]=GUI for password/pause + DB selection, [bold]3[/bold]=full GUI console."
+        ),
+    ),
+    gui_framework: str | None = typer.Option(
+        None,
+        "--gui-framework",
+        metavar="{tkinter,textual}",
+        help="GUI framework to use with [cyan]--visible-prompts[/cyan]. [dim]Default: tkinter[/dim]",
+    ),
+    # -- Configuration -----------------------------------------------------
     config_file: str | None = typer.Option(
         None,
         "--config",
@@ -298,18 +271,62 @@ def main(
             "The file may chain additional configs via its [cyan][config][/cyan] section."
         ),
     ),
-    parse_tree: bool = typer.Option(
+    init_config: bool = typer.Option(
         False,
-        "--parse-tree",
+        "--init-config",
+        help="Print a default [cyan]execsql.conf[/cyan] template to stdout and exit.",
+    ),
+    sub_vars: list[str] | None = typer.Option(
+        None,
+        "-a",
+        "--assign-arg",
+        metavar="VALUE",
+        help="Define the replacement string for a substitution variable [cyan]\\$ARG_x[/cyan].",
+    ),
+    user_logfile: bool = typer.Option(
+        False,
+        "-l",
+        "--user-logfile",
+        help="Write a log file to [cyan]~/execsql.log[/cyan].",
+    ),
+    # -- Information -------------------------------------------------------
+    metacommands: bool = typer.Option(
+        False,
+        "-m",
+        "--metacommands",
+        help="List metacommands and exit.",
+    ),
+    encodings: bool = typer.Option(
+        False,
+        "-y",
+        "--encodings",
+        help="List available encoding names and exit.",
+    ),
+    dump_keywords: bool = typer.Option(
+        False,
+        "--dump-keywords",
+        help="Dump all metacommand keywords as JSON and exit.",
+    ),
+    list_plugins: bool = typer.Option(
+        False,
+        "--list-plugins",
+        help="List all discovered plugins (metacommands, exporters, importers) and exit.",
+    ),
+    ping: bool = typer.Option(
+        False,
+        "--ping",
         help=(
-            "Parse the script into an abstract syntax tree and print the tree structure. "
-            "Does not connect to a database or execute anything."
+            "Test database connectivity and exit. "
+            "Prints connection details and the server version on success (exit 0), "
+            "or the error message on failure (exit 1). "
+            "No script file is required."
         ),
     ),
-    debug: bool = typer.Option(
+    online_help: bool = typer.Option(
         False,
-        "--debug",
-        help="Start in step-through debug mode. The debug REPL pauses before each statement.",
+        "-o",
+        "--online-help",
+        help="Open the online documentation in the default browser.",
     ),
     version: bool | None = typer.Option(
         None,
@@ -340,6 +357,10 @@ def main(
         _print_encodings()
         raise typer.Exit()
 
+    if init_config:
+        _init_config()
+        raise typer.Exit()
+
     if dump_keywords:
         import json as _json
 
@@ -580,6 +601,7 @@ def main(
         ping=ping,
         lint=lint,
         debug=debug,
+        no_system_cmd=no_system_cmd,
         config_file=config_file,
     )
 

execsql/cli/help.py

@@ -11,7 +11,7 @@ from encodings.aliases import aliases as codec_dict
 from rich.console import Console
 from rich.table import Table
 
-__all__ = ["_console", "_err_console", "_print_encodings", "_print_metacommands"]
+__all__ = ["_console", "_err_console", "_init_config", "_print_encodings", "_print_metacommands"]
 
 _console = Console()
 _err_console = Console(stderr=True)
@@ -77,6 +77,15 @@ _SKIP_FROM_DISPATCH = {
 }
 
 
+def _init_config() -> None:
+    """Print the default execsql.conf template to stdout."""
+    import importlib.resources
+    import sys
+
+    template = importlib.resources.files("execsql.data").joinpath("execsql.conf.template").read_text(encoding="utf-8")
+    sys.stdout.write(template)
+
+
 def _print_metacommands() -> None:
     """Print the metacommands table using Rich.
 

execsql/cli/run.py

@@ -532,6 +532,7 @@ def _run(
     ping: bool = False,
     lint: bool = False,
     debug: bool = False,
+    no_system_cmd: bool = False,
     config_file: str | None = None,
 ) -> None:
     """Initialise state, connect to the database, load the script, and run it.
@@ -727,6 +728,9 @@ def _run(
     if debug:
         _state.step_mode = True
 
+    if no_system_cmd:
+        conf.allow_system_cmd = False
+
     if _ast_tree is not None:
         _execute_script_ast(_ast_tree, conf, profile=profile, profile_limit=profile_limit)
 

execsql/config.py

@@ -288,6 +288,7 @@ class ConfigData:
         self.include_opt: list = []
         self.export_output_dir: str | None = None
         self.dao_flush_delay_secs = 5.0
+        self.allow_system_cmd = True
         self.zip_buffer_mb = 10
         if os.name == "posix":
             sys_config_file = str(Path("/etc") / self.config_file_name)
@@ -474,6 +475,7 @@ class ConfigData:
                 self._get_bool(cp, self._CONFIG_SECTION, "log_datavars", "log_datavars")
                 self._get_bool(cp, self._CONFIG_SECTION, "log_sql", "log_sql")
                 self._get_int(cp, self._CONFIG_SECTION, "max_log_size_mb", "max_log_size_mb")
+                self._get_bool(cp, self._CONFIG_SECTION, "allow_system_cmd", "allow_system_cmd")
                 # --- [email] ---
                 self._get_str(cp, self._EMAIL_SECTION, "host", "smtp_host")
                 self._get_int(cp, self._EMAIL_SECTION, "port", "smtp_port")