Skip to content

Metacommands

Dispatch table

build_dispatch_table() (in execsql.metacommands.dispatch) populates a MetaCommandList with every metacommand regex and its handler. __init__.py calls it at import time and exposes the result as DISPATCH_TABLE; runtime consumes it via _state.metacommandlist.

If you are adding a new metacommand, start with the Adding Metacommands guide.

execsql metacommand dispatch table.

Importing this module populates a MetaCommandList (DISPATCH_TABLE) with every metacommand regex and its handler function. The dispatch table is consumed by :func:execsql.script.executor._exec_metacommand via _state.metacommandlist.

The table itself is built by build_dispatch_table() in :mod:execsql.metacommands.dispatch. Handler functions are organized into sibling modules by topic:

  • :mod:~execsql.metacommands.connect — CONNECT / USE / DISCONNECT / AUTOCOMMIT / PG_VACUUM.
  • :mod:~execsql.metacommands.conditions — xf_* predicates used by IF / ELSEIF / ASSERT.
  • :mod:~execsql.metacommands.control — IF / ELSEIF / ELSE / ENDIF / ANDIF / ORIF, ASSERT, LOOP, BATCH, HALT, BREAK, WAIT_UNTIL, error-halt directives.
  • :mod:~execsql.metacommands.data — SUB family, counters, IMPORT config metacommands.
  • :mod:~execsql.metacommands.debug — DEBUG WRITE/LOG variants and SHOW SCRIPTS.
  • :mod:~execsql.metacommands.io_export — EXPORT and EXPORT QUERY.
  • :mod:~execsql.metacommands.io_import — IMPORT and IMPORT_FILE.
  • :mod:~execsql.metacommands.io_write — WRITE, WRITE SCRIPT, WRITE CREATE_TABLE.
  • :mod:~execsql.metacommands.io_fileops — INCLUDE, COPY, ZIP, RM_FILE, CD, SERVE.
  • :mod:~execsql.metacommands.io — re-export façade for the four io_* modules above (kept for backward-compatible import paths).
  • :mod:~execsql.metacommands.prompt — PROMPT family, ASK, PAUSE.
  • :mod:~execsql.metacommands.script_ext — EXECUTE SCRIPT, RUN SCRIPT, EXTEND SCRIPT.
  • :mod:~execsql.metacommands.system — SYSTEM_CMD, LOG, EMAIL, CONSOLE, ON ERROR_HALT / ON CANCEL_HALT directives, TIMER.
  • :mod:~execsql.metacommands.upsert — PG_UPSERT (optional, requires execsql2[upsert]).

ALL_EXPORT_FORMATS = sorted(set(QUERY_EXPORT_FORMATS + TABLE_EXPORT_FORMATS + JSON_VARIANT_FORMATS)) module-attribute

DATABASE_TYPES = ['POSTGRESQL', 'MYSQL', 'MARIADB', 'ORACLE', 'SQLSERVER', 'FIREBIRD', 'ACCESS', 'DUCKDB', 'SQLITE', 'DSN'] module-attribute

DELIMITED_FORMATS = ['CSV', 'TAB', 'TSV', 'TABQ', 'TSVQ', 'UNITSEP', 'US'] module-attribute

DISPATCH_TABLE = build_dispatch_table() module-attribute

JSON_VARIANT_FORMATS = ['JSON_TS', 'JSON_TABLESCHEMA'] module-attribute

METADATA_FORMATS = ['CSV', 'TAB', 'TSV', 'TABQ', 'TSVQ', 'TXT', 'TEXT'] module-attribute

QUERY_EXPORT_FORMATS = DELIMITED_FORMATS + TEXT_FORMATS + ['ODS', 'XLSX', 'JSON', 'HTML', 'CGI-HTML', 'VALUES', 'LATEX', 'RAW', 'B64', 'FEATHER', 'YAML', 'MARKDOWN', 'MD'] module-attribute

SERVE_FORMATS = ['BINARY', 'CSV', 'TXT', 'TEXT', 'ODS', 'JSON', 'HTML', 'PDF', 'ZIP'] module-attribute

TABLE_EXPORT_FORMATS = DELIMITED_FORMATS + TEXT_FORMATS + ['JSON', 'XML', 'VALUES', 'HTML', 'CGI-HTML', 'SQLITE', 'DUCKDB', 'LATEX', 'RAW', 'B64', 'FEATHER', 'HDF5', 'XLSX', 'YAML', 'MARKDOWN', 'MD'] module-attribute

TEXT_FORMATS = ['TXT', 'TXT-AND', 'PLAIN'] module-attribute

__all__ = ['_state', 'x_connect_pg', 'x_connect_user_pg', 'x_connect_ssvr', 'x_connect_user_ssvr', 'x_connect_mysql', 'x_connect_user_mysql', 'x_connect_access', 'x_connect_fb', 'x_connect_user_fb', 'x_connect_ora', 'x_connect_user_ora', 'x_connect_duckdb', 'x_connect_sqlite', 'x_connect_dsn', 'x_use', 'x_disconnect', 'x_autocommit_on', 'x_autocommit_off', 'x_pg_vacuum', 'x_daoflushdelay', 'x_assert', 'x_if', 'x_if_orif', 'x_if_andif', 'x_if_elseif', 'x_if_else', 'x_if_block', 'x_if_end', 'x_loop', 'x_halt', 'x_halt_msg', 'x_error_halt', 'x_metacommand_error_halt', 'x_begin_batch', 'x_end_batch', 'x_rollback', 'x_break', 'x_wait_until', 'x_sub', 'x_sub_add', 'x_sub_append', 'x_sub_empty', 'x_rm_sub', 'x_sub_local', 'x_sub_tempfile', 'x_sub_ini', 'x_sub_querystring', 'x_sub_encrypt', 'x_sub_decrypt', 'x_subdata', 'x_selectsub', 'x_prompt_selectsub', 'x_empty_strings', 'x_trim_strings', 'x_replace_newlines', 'x_empty_rows', 'x_only_strings', 'x_boolean_int', 'x_boolean_words', 'x_fold_col_hdrs', 'x_trim_col_hdrs', 'x_clean_col_hdrs', 'x_del_empty_cols', 'x_create_col_hdrs', 'x_dedup_col_hdrs', 'x_import_common_cols_only', 'x_quote_all_text', 'x_reset_counter', 'x_reset_counters', 'x_set_counter', 'x_max_int', 'x_debug_write_metacommands', 'x_debug_commandliststack', 'x_debug_iflevels', 'x_debug_write_odbc_drivers', 'x_debug_log_subvars', 'x_debug_log_config', 'x_debug_write_subvars', 'x_debug_write_config', 'x_breakpoint', 'x_export', 'x_export_query', 'x_export_query_with_template', 'x_export_with_template', 'x_export_ods_multiple', 'x_export_xlsx_multiple', 'x_export_metadata', 'x_export_metadata_table', 'x_import', 'x_import_file', 'x_import_ods', 'x_import_ods_pattern', 'x_import_xls', 'x_import_xls_pattern', 'x_import_parquet', 'x_import_feather', 'x_import_json', 'x_import_row_buffer', 'x_show_progress', 'x_export_row_buffer', 'x_write', 'x_write_create_table', 'x_write_create_table_ods', 'x_write_create_table_xls', 'x_write_create_table_alias', 'x_write_prefix', 'x_write_suffix', 'x_writescript', 'x_include', 'x_copy', 'x_copy_query', 'x_zip', 'x_zip_buffer_mb', 'x_rm_file', 'x_make_export_dirs', 'x_cd', 'x_scan_lines', 'x_hdf5_text_len', 'x_serve', 'x_prompt', 'x_prompt_enter', 'x_prompt_entryform', 'x_prompt_pause', 'x_prompt_compare', 'x_prompt_ask_compare', 'x_prompt_ask', 'x_prompt_map', 'x_prompt_action', 'x_prompt_savefile', 'x_prompt_openfile', 'x_prompt_directory', 'x_prompt_select_rows', 'x_prompt_credentials', 'x_prompt_connect', 'x_ask', 'x_pause', 'x_msg', 'x_reset_dialog_canceled', 'x_extendscript', 'x_extendscript_metacommand', 'x_extendscript_sql', 'x_executescript', 'x_system_cmd', 'x_email', 'x_timer', 'x_log', 'x_logwritemessages', 'x_log_datavars', 'x_log_sql', 'x_console', 'x_consoleprogress', 'x_consolewait', 'x_consolewait_onerror', 'x_consolewait_whendone', 'x_console_hideshow', 'x_consolewidth', 'x_consoleheight', 'x_consolestatus', 'x_consolesave', 'x_cancel_halt', 'x_cancel_halt_write_clear', 'x_cancel_halt_write', 'x_cancel_halt_email_clear', 'x_cancel_halt_email', 'x_cancel_halt_exec', 'x_cancel_halt_exec_clear', 'x_error_halt_write_clear', 'x_error_halt_write', 'x_error_halt_email_clear', 'x_error_halt_email', 'x_error_halt_exec', 'x_error_halt_exec_clear', 'x_write_warnings', 'x_gui_level', 'x_execute', 'x_pg_upsert', 'x_pg_upsert_check', 'x_pg_upsert_qa', 'ins_rxs', 'ins_quoted_rx', 'ins_schema_rxs', 'ins_table_rxs', 'ins_table_list_rxs', 'ins_fn_rxs', 'MetaCommandList', 'DELIMITED_FORMATS', 'TEXT_FORMATS', 'JSON_VARIANT_FORMATS', 'QUERY_EXPORT_FORMATS', 'TABLE_EXPORT_FORMATS', 'SERVE_FORMATS', 'METADATA_FORMATS', 'ALL_EXPORT_FORMATS', 'DATABASE_TYPES', 'build_dispatch_table', 'DISPATCH_TABLE'] module-attribute

MetaCommandList()

Ordered list of :class:MetaCommand entries with keyword-indexed dispatch.

Commands are stored with the most-recently-added entry first, matching the original linked-list prepend semantics. A keyword index (_by_keyword) groups entries by their leading keyword so that eval() and get_match() test only the small subset of regexes that could possibly match, reducing dispatch from O(N) to O(K) where K is the number of patterns sharing the same leading keyword (typically 1–5 vs. 205 total).

__iter__()

add(matching_regexes, exec_func, description=None, set_error_flag=True, category=None)

Register one or more regex patterns as a new :class:MetaCommand entry.

matching_regexes may be a single pattern string or a list/tuple of patterns; each compiles into a separate :class:MetaCommand prepended to the dispatch list so that later registrations take priority.

eval(cmd_str)

Evaluate cmd_str against the registered metacommands.

Returns (True, return_value) if a matching command was found and run, (False, None) if no command matched.

get_match(cmd)

Return (MetaCommand, re.Match) for the first entry matching cmd, or None if no entry matches.

keywords_by_category()

Return {category: [keyword, ...]} from entries that have both.

Used by --dump-keywords to introspect the dispatch table.

build_dispatch_table()

Construct and return the complete metacommand dispatch table.

ins_fn_rxs(fragment1, fragment2, symbolicname='filename')

ins_quoted_rx(fragment1, fragment2, rx)

ins_rxs(rx_list, fragment1, fragment2)

ins_schema_rxs(fragment1, fragment2, suffix=None)

ins_table_list_rxs(fragment1, fragment2)

ins_table_rxs(fragment1, fragment2, suffix=None)

x_ask(**kwargs)

x_assert(**kwargs)

Evaluate a condition and raise ErrInfo if it is false.

Syntax::

-- !x! ASSERT <condition> ["message"]
-- !x! ASSERT <condition> ['message']
-- !x! ASSERT <condition>

Parameters:

Name Type Description Default
**kwargs Any

Keyword arguments injected by the dispatch table. condtest — the condition expression string. message — optional user-supplied failure message; may be None.

 {}

Raises:

Type Description
ErrInfo

When the condition evaluates to False (or raises internally for an unrecognized condition).

x_autocommit_off(**kwargs)

x_autocommit_on(**kwargs)

x_begin_batch(**kwargs)

x_boolean_int(**kwargs)

x_boolean_words(**kwargs)

x_break(**kwargs)

x_breakpoint(**kwargs)

Pause execution and enter the interactive debug REPL.

If sys.stdin is not a TTY (CI, piped input), the metacommand is silently skipped — scripts will not hang in automation.

Parameters:

Name Type Description Default
**kwargs Any

Keyword arguments injected by the dispatch table (unused).

 {}

x_cancel_halt(**kwargs)

x_cancel_halt_email(**kwargs)

x_cancel_halt_email_clear(**kwargs)

x_cancel_halt_exec(**kwargs)

x_cancel_halt_exec_clear(**kwargs)

x_cancel_halt_write(**kwargs)

x_cancel_halt_write_clear(**kwargs)

x_cd(**kwargs)

x_clean_col_hdrs(**kwargs)

x_connect_access(**kwargs)

x_connect_dsn(**kwargs)

x_connect_duckdb(**kwargs)

x_connect_fb(**kwargs)

x_connect_mysql(**kwargs)

x_connect_ora(**kwargs)

x_connect_pg(**kwargs)

x_connect_sqlite(**kwargs)

x_connect_ssvr(**kwargs)

x_connect_user_fb(**kwargs)

x_connect_user_mysql(**kwargs)

x_connect_user_ora(**kwargs)

x_connect_user_pg(**kwargs)

x_connect_user_ssvr(**kwargs)

x_console(**kwargs)

x_console_hideshow(**kwargs)

x_consoleheight(**kwargs)

x_consoleprogress(**kwargs)

x_consolesave(**kwargs)

x_consolestatus(**kwargs)

x_consolewait(**kwargs)

x_consolewait_onerror(**kwargs)

x_consolewait_whendone(**kwargs)

x_consolewidth(**kwargs)

x_copy(**kwargs)

x_copy_query(**kwargs)

x_create_col_hdrs(**kwargs)

x_daoflushdelay(**kwargs)

x_debug_commandliststack(**kwargs)

Dump the unified AST execution stack.

Shows every nesting construct the executor is currently inside: <main> script, EXECUTE SCRIPT calls, INCLUDE'd files, IF/ELSEIF/ELSE branches, LOOP iterations (with iteration count), and BATCH blocks. Each frame shows source file and line.

The legacy commandliststack is reported separately as a secondary view because it only records SCRIPT call frames; the unified ast_exec_stack is the authoritative debugger view.

x_debug_iflevels(**kwargs)

x_debug_log_config(**kwargs)

x_debug_log_subvars(**kwargs)

x_debug_write_config(**kwargs)

x_debug_write_metacommands(**kwargs)

x_debug_write_odbc_drivers(**kwargs)

x_debug_write_subvars(**kwargs)

x_dedup_col_hdrs(**kwargs)

x_del_empty_cols(**kwargs)

x_disconnect(**kwargs)

x_email(**kwargs)

x_empty_rows(**kwargs)

x_empty_strings(**kwargs)

x_end_batch(**kwargs)

x_error_halt(**kwargs)

x_error_halt_email(**kwargs)

x_error_halt_email_clear(**kwargs)

x_error_halt_exec(**kwargs)

x_error_halt_exec_clear(**kwargs)

x_error_halt_write(**kwargs)

x_error_halt_write_clear(**kwargs)

x_execute(**kwargs)

Run a database function, view, or action query. Returns None.

x_executescript(**kwargs)

x_export(**kwargs)

x_export_metadata(**kwargs)

x_export_metadata_table(**kwargs)

x_export_ods_multiple(**kwargs)

x_export_query(**kwargs)

x_export_query_with_template(**kwargs)

x_export_row_buffer(**kwargs)

x_export_with_template(**kwargs)

x_export_xlsx_multiple(**kwargs)

Export multiple tables to separate worksheets in a single XLSX workbook.

x_extendscript(**kwargs)

Append the body of one SCRIPT to another, merging parameter names.

x_extendscript_metacommand(**kwargs)

Append a single metacommand line to an existing SCRIPT body.

x_extendscript_sql(**kwargs)

Append a single SQL statement to an existing SCRIPT body.

x_fold_col_hdrs(**kwargs)

x_gui_level(**kwargs)

x_halt(**kwargs)

x_halt_msg(**kwargs)

x_hdf5_text_len(**kwargs)

x_if(**kwargs)

x_if_andif(**kwargs)

x_if_block(**kwargs)

x_if_else(**kwargs)

x_if_elseif(**kwargs)

x_if_end(**kwargs)

x_if_orif(**kwargs)

x_import(**kwargs)

x_import_common_cols_only(**kwargs)

x_import_feather(**kwargs)

x_import_file(**kwargs)

x_import_json(**kwargs)

x_import_ods(**kwargs)

x_import_ods_pattern(**kwargs)

x_import_parquet(**kwargs)

x_import_row_buffer(**kwargs)

x_import_xls(**kwargs)

x_import_xls_pattern(**kwargs)

x_include(**kwargs)

x_log(**kwargs)

x_log_datavars(**kwargs)

x_log_sql(**kwargs)

x_logwritemessages(**kwargs)

x_loop(**kwargs)

x_make_export_dirs(**kwargs)

x_max_int(**kwargs)

x_metacommand_error_halt(**kwargs)

x_msg(**kwargs)

x_only_strings(**kwargs)

x_pause(**kwargs)

x_pg_upsert(**kwargs)

PG_UPSERT FROM TO TABLES , [options]

Full pipeline: QA checks → upsert → optional commit.

x_pg_upsert_check(**kwargs)

PG_UPSERT CHECK FROM TO TABLES ,

Schema check only: column existence + type mismatch.

x_pg_upsert_qa(**kwargs)

PG_UPSERT QA FROM TO TABLES , [options]

QA-only mode: run all QA checks without upserting.

x_pg_vacuum(**kwargs)

x_prompt(**kwargs)

x_prompt_action(**kwargs)

x_prompt_ask(**kwargs)

x_prompt_ask_compare(**kwargs)

x_prompt_compare(**kwargs)

x_prompt_connect(**kwargs)

x_prompt_credentials(**kwargs)

x_prompt_directory(**kwargs)

x_prompt_enter(**kwargs)

x_prompt_entryform(**kwargs)

x_prompt_map(**kwargs)

x_prompt_openfile(**kwargs)

x_prompt_pause(**kwargs)

x_prompt_savefile(**kwargs)

x_prompt_select_rows(**kwargs)

x_prompt_selectsub(**kwargs)

x_quote_all_text(**kwargs)

x_replace_newlines(**kwargs)

x_reset_counter(**kwargs)

x_reset_counters(**kwargs)

x_reset_dialog_canceled(**kwargs)

x_rm_file(**kwargs)

x_rm_sub(**kwargs)

x_rollback(**kwargs)

Roll back all DBs registered in the innermost batch level.

x_scan_lines(**kwargs)

x_selectsub(**kwargs)

x_serve(**kwargs)

x_set_counter(**kwargs)

x_show_progress(**kwargs)

x_sub(**kwargs)

x_sub_add(**kwargs)

x_sub_append(**kwargs)

x_sub_decrypt(**kwargs)

x_sub_empty(**kwargs)

x_sub_encrypt(**kwargs)

x_sub_ini(**kwargs)

x_sub_local(**kwargs)

x_sub_querystring(**kwargs)

x_sub_tempfile(**kwargs)

x_subdata(**kwargs)

x_system_cmd(**kwargs)

x_timer(**kwargs)

x_trim_col_hdrs(**kwargs)

x_trim_strings(**kwargs)

x_use(**kwargs)

x_wait_until(**kwargs)

x_write(**kwargs)

x_write_create_table(**kwargs)

x_write_create_table_alias(**kwargs)

x_write_create_table_ods(**kwargs)

x_write_create_table_xls(**kwargs)

x_write_prefix(**kwargs)

x_write_suffix(**kwargs)

x_write_warnings(**kwargs)

x_writescript(**kwargs)

Dump a registered SCRIPT block's source to stdout or a file.

Reads from the AST script registry (ctx.ast_scripts) and walks the full block tree — including nested IF / LOOP / BATCH structures — reconstructing source between BEGIN SCRIPT and END SCRIPT delimiters so the output is re-includable.

x_zip(**kwargs)

x_zip_buffer_mb(**kwargs)

Build function for the execsql metacommand dispatch table.

This module contains build_dispatch_table(), which constructs and returns a :class:~execsql.script.MetaCommandList populated with every metacommand regex and its handler function.

It is imported by execsql.metacommands where the module-level DISPATCH_TABLE is assigned.

__all__ = ['build_dispatch_table'] module-attribute

build_dispatch_table()

Construct and return the complete metacommand dispatch table.

Handler modules

x_autocommit_off(**kwargs)

x_autocommit_on(**kwargs)

x_connect_access(**kwargs)

x_connect_dsn(**kwargs)

x_connect_duckdb(**kwargs)

x_connect_fb(**kwargs)

x_connect_mysql(**kwargs)

x_connect_ora(**kwargs)

x_connect_pg(**kwargs)

x_connect_sqlite(**kwargs)

x_connect_ssvr(**kwargs)

x_connect_user_fb(**kwargs)

x_connect_user_mysql(**kwargs)

x_connect_user_ora(**kwargs)

x_connect_user_pg(**kwargs)

x_connect_user_ssvr(**kwargs)

x_daoflushdelay(**kwargs)

x_disconnect(**kwargs)

x_pg_vacuum(**kwargs)

x_use(**kwargs)

CONDITIONAL_TABLE = build_conditional_table() module-attribute

build_conditional_table()

Construct and return the conditional predicate dispatch table.

xcmd_test(teststr)

xf_aliasdefined(**kwargs)

xf_boolliteral(**kwargs)

xf_columnexists(**kwargs)

xf_console(**kwargs)

xf_contains(**kwargs)

xf_dbms(**kwargs)

xf_dbname(**kwargs)

xf_dialogcanceled(**kwargs)

xf_direxists(**kwargs)

xf_endswith(**kwargs)

xf_equals(**kwargs)

xf_fileexists(**kwargs)

xf_hasrows(**kwargs)

xf_identical(**kwargs)

xf_isfalse(**kwargs)

xf_isgt(**kwargs)

xf_isgte(**kwargs)

xf_isnull(**kwargs)

xf_istrue(**kwargs)

xf_iszero(**kwargs)

xf_metacommanderror(**kwargs)

xf_newer_date(**kwargs)

xf_newer_file(**kwargs)

xf_roleexists(**kwargs)

xf_row_count_eq(**kwargs)

Return True if the row count of queryname equals N exactly.

Parameters:

Name Type Description Default
**kwargs Any

Named groups from the regex match, plus metacommandline. Required keys: queryname, n.

 {}

Returns:

Type Description
bool

True if count(*) == N.

xf_row_count_gt(**kwargs)

Return True if the row count of queryname is strictly greater than N.

Parameters:

Name Type Description Default
**kwargs Any

Named groups from the regex match, plus metacommandline. Required keys: queryname, n.

 {}

Returns:

Type Description
bool

True if count(*) > N.

xf_row_count_gte(**kwargs)

Return True if the row count of queryname is greater than or equal to N.

Parameters:

Name Type Description Default
**kwargs Any

Named groups from the regex match, plus metacommandline. Required keys: queryname, n.

 {}

Returns:

Type Description
bool

True if count(*) >= N.

xf_row_count_lt(**kwargs)

Return True if the row count of queryname is strictly less than N.

Parameters:

Name Type Description Default
**kwargs Any

Named groups from the regex match, plus metacommandline. Required keys: queryname, n.

 {}

Returns:

Type Description
bool

True if count(*) < N.

xf_schemaexists(**kwargs)

xf_script_exists(**kwargs)

xf_sqlerror(**kwargs)

xf_startswith(**kwargs)

xf_sub_defined(**kwargs)

xf_sub_empty(**kwargs)

xf_tableexists(**kwargs)

xf_viewexists(**kwargs)

x_assert(**kwargs)

Evaluate a condition and raise ErrInfo if it is false.

Syntax::

-- !x! ASSERT <condition> ["message"]
-- !x! ASSERT <condition> ['message']
-- !x! ASSERT <condition>

Parameters:

Name Type Description Default
**kwargs Any

Keyword arguments injected by the dispatch table. condtest — the condition expression string. message — optional user-supplied failure message; may be None.

 {}

Raises:

Type Description
ErrInfo

When the condition evaluates to False (or raises internally for an unrecognized condition).

x_begin_batch(**kwargs)

x_break(**kwargs)

x_end_batch(**kwargs)

x_error_halt(**kwargs)

x_halt(**kwargs)

x_halt_msg(**kwargs)

x_if(**kwargs)

x_if_andif(**kwargs)

x_if_block(**kwargs)

x_if_else(**kwargs)

x_if_elseif(**kwargs)

x_if_end(**kwargs)

x_if_orif(**kwargs)

x_loop(**kwargs)

x_metacommand_error_halt(**kwargs)

x_rollback(**kwargs)

Roll back all DBs registered in the innermost batch level.

x_wait_until(**kwargs)

x_boolean_int(**kwargs)

x_boolean_words(**kwargs)

x_clean_col_hdrs(**kwargs)

x_create_col_hdrs(**kwargs)

x_dedup_col_hdrs(**kwargs)

x_del_empty_cols(**kwargs)

x_empty_rows(**kwargs)

x_empty_strings(**kwargs)

x_fold_col_hdrs(**kwargs)

x_import_common_cols_only(**kwargs)

x_max_int(**kwargs)

x_only_strings(**kwargs)

x_prompt_selectsub(**kwargs)

x_quote_all_text(**kwargs)

x_replace_newlines(**kwargs)

x_reset_counter(**kwargs)

x_reset_counters(**kwargs)

x_rm_sub(**kwargs)

x_selectsub(**kwargs)

x_set_counter(**kwargs)

x_sub(**kwargs)

x_sub_add(**kwargs)

x_sub_append(**kwargs)

x_sub_decrypt(**kwargs)

x_sub_empty(**kwargs)

x_sub_encrypt(**kwargs)

x_sub_ini(**kwargs)

x_sub_local(**kwargs)

x_sub_querystring(**kwargs)

x_sub_tempfile(**kwargs)

x_subdata(**kwargs)

x_trim_col_hdrs(**kwargs)

x_trim_strings(**kwargs)

Export metacommand handlers.

  • x_export — EXPORT (table → file in any supported format).
  • x_export_query — EXPORT QUERY (ad-hoc SELECT → file).
  • x_export_with_template / x_export_query_with_template — template-rendered EXPORT (Jinja or string.Template).
  • x_export_ods_multiple / x_export_xlsx_multiple — multi-sheet ODS / XLSX workbooks.
  • x_export_metadata / x_export_metadata_table — EXPORT_METADATA (dump the in-process export-record log).
  • x_export_row_buffer — CONFIG EXPORT_ROW_BUFFER (set the per-export row-buffer size).

Per-format dispatch happens inside x_export's if filefmt in (...): ... elif ... chain, which calls the appropriate writer in :mod:execsql.exporters.

x_export(**kwargs)

x_export_metadata(**kwargs)

x_export_metadata_table(**kwargs)

x_export_ods_multiple(**kwargs)

x_export_query(**kwargs)

x_export_query_with_template(**kwargs)

x_export_row_buffer(**kwargs)

x_export_with_template(**kwargs)

x_export_xlsx_multiple(**kwargs)

Export multiple tables to separate worksheets in a single XLSX workbook.

Import metacommand handlers.

  • x_import — IMPORT (delimited text / CSV; dispatches by extension for .ods/.xls/.xlsx in the same handler).
  • x_import_file — IMPORT_FILE (insert a binary file blob as a row).
  • x_import_ods / x_import_ods_pattern — IMPORT … FROM ODS, single-sheet and SHEETS MATCHING .
  • x_import_xls / x_import_xls_pattern — same for XLS/XLSX.
  • x_import_parquet — IMPORT … FROM PARQUET (via polars).
  • x_import_feather — IMPORT … FROM FEATHER (via polars).
  • x_import_json — IMPORT … FROM JSON (array of objects or JSON Lines).
  • x_import_row_buffer — CONFIG IMPORT_ROW_BUFFER.
  • x_show_progress — CONFIG SHOW_PROGRESS (toggle the import progress bar).

x_import(**kwargs)

x_import_feather(**kwargs)

x_import_file(**kwargs)

x_import_json(**kwargs)

x_import_ods(**kwargs)

x_import_ods_pattern(**kwargs)

x_import_parquet(**kwargs)

x_import_row_buffer(**kwargs)

x_import_xls(**kwargs)

x_import_xls_pattern(**kwargs)

x_show_progress(**kwargs)

WRITE metacommand handlers.

  • x_write — WRITE "" [TEE TO ] (text output).
  • x_writescript — WRITE SCRIPT [TO ] (dump a named script block).
  • x_write_create_table — WRITE CREATE_TABLE … (emit a CREATE TABLE statement inferred from a data source); plus the format-specific variants x_write_create_table_ods, x_write_create_table_xls, x_write_create_table_alias.
  • x_write_prefix / x_write_suffix — CONFIG WRITE_PREFIX / CONFIG WRITE_SUFFIX (set text prepended / appended to every WRITE).

x_write(**kwargs)

x_write_create_table(**kwargs)

x_write_create_table_alias(**kwargs)

x_write_create_table_ods(**kwargs)

x_write_create_table_xls(**kwargs)

x_write_prefix(**kwargs)

x_write_suffix(**kwargs)

x_writescript(**kwargs)

Dump a registered SCRIPT block's source to stdout or a file.

Reads from the AST script registry (ctx.ast_scripts) and walks the full block tree — including nested IF / LOOP / BATCH structures — reconstructing source between BEGIN SCRIPT and END SCRIPT delimiters so the output is re-includable.

File and system operation metacommand handlers.

Implements x_include, x_copy, x_copy_query, x_zip, x_zip_buffer_mb, x_rm_file, x_make_export_dirs, x_cd, x_scan_lines, x_hdf5_text_len, and x_serve.

x_cd(**kwargs)

x_copy(**kwargs)

x_copy_query(**kwargs)

x_hdf5_text_len(**kwargs)

x_include(**kwargs)

x_make_export_dirs(**kwargs)

x_rm_file(**kwargs)

x_scan_lines(**kwargs)

x_serve(**kwargs)

x_zip(**kwargs)

x_zip_buffer_mb(**kwargs)

Input/output metacommand handlers for execsql.

This module is a re-export façade: the actual implementations live in the sibling submodules listed below. All public names are imported here so that existing from execsql.metacommands.io import x_* paths continue to work without changes.

Submodules

  • :mod:~execsql.metacommands.io_export — EXPORT handlers
  • :mod:~execsql.metacommands.io_import — IMPORT handlers
  • :mod:~execsql.metacommands.io_write — WRITE / WRITESCRIPT handlers
  • :mod:~execsql.metacommands.io_fileops — file ops, COPY, ZIP, INCLUDE, SERVE, etc.

__all__ = ['_apply_output_dir', 'x_cd', 'x_copy', 'x_copy_query', 'x_export', 'x_export_metadata', 'x_export_metadata_table', 'x_export_ods_multiple', 'x_export_xlsx_multiple', 'x_export_query', 'x_export_query_with_template', 'x_export_row_buffer', 'x_export_with_template', 'x_hdf5_text_len', 'x_import', 'x_import_feather', 'x_import_file', 'x_import_json', 'x_import_ods', 'x_import_ods_pattern', 'x_import_parquet', 'x_import_row_buffer', 'x_import_xls', 'x_import_xls_pattern', 'x_include', 'x_make_export_dirs', 'x_rm_file', 'x_scan_lines', 'x_serve', 'x_show_progress', 'x_write', 'x_write_create_table', 'x_write_create_table_alias', 'x_write_create_table_ods', 'x_write_create_table_xls', 'x_write_prefix', 'x_write_suffix', 'x_writescript', 'x_zip', 'x_zip_buffer_mb'] module-attribute

x_cd(**kwargs)

x_copy(**kwargs)

x_copy_query(**kwargs)

x_export(**kwargs)

x_export_metadata(**kwargs)

x_export_metadata_table(**kwargs)

x_export_ods_multiple(**kwargs)

x_export_query(**kwargs)

x_export_query_with_template(**kwargs)

x_export_row_buffer(**kwargs)

x_export_with_template(**kwargs)

x_export_xlsx_multiple(**kwargs)

Export multiple tables to separate worksheets in a single XLSX workbook.

x_hdf5_text_len(**kwargs)

x_import(**kwargs)

x_import_feather(**kwargs)

x_import_file(**kwargs)

x_import_json(**kwargs)

x_import_ods(**kwargs)

x_import_ods_pattern(**kwargs)

x_import_parquet(**kwargs)

x_import_row_buffer(**kwargs)

x_import_xls(**kwargs)

x_import_xls_pattern(**kwargs)

x_include(**kwargs)

x_make_export_dirs(**kwargs)

x_rm_file(**kwargs)

x_scan_lines(**kwargs)

x_serve(**kwargs)

x_show_progress(**kwargs)

x_write(**kwargs)

x_write_create_table(**kwargs)

x_write_create_table_alias(**kwargs)

x_write_create_table_ods(**kwargs)

x_write_create_table_xls(**kwargs)

x_write_prefix(**kwargs)

x_write_suffix(**kwargs)

x_writescript(**kwargs)

Dump a registered SCRIPT block's source to stdout or a file.

Reads from the AST script registry (ctx.ast_scripts) and walks the full block tree — including nested IF / LOOP / BATCH structures — reconstructing source between BEGIN SCRIPT and END SCRIPT delimiters so the output is re-includable.

x_zip(**kwargs)

x_zip_buffer_mb(**kwargs)

prompt_compare(button_list, **kwargs)

prompt_select_rows(button_list, **kwargs)

x_ask(**kwargs)

x_msg(**kwargs)

x_pause(**kwargs)

x_prompt(**kwargs)

x_prompt_action(**kwargs)

x_prompt_ask(**kwargs)

x_prompt_ask_compare(**kwargs)

x_prompt_compare(**kwargs)

x_prompt_connect(**kwargs)

x_prompt_credentials(**kwargs)

x_prompt_directory(**kwargs)

x_prompt_enter(**kwargs)

x_prompt_entryform(**kwargs)

x_prompt_map(**kwargs)

x_prompt_openfile(**kwargs)

x_prompt_pause(**kwargs)

x_prompt_savefile(**kwargs)

x_prompt_select_rows(**kwargs)

x_reset_dialog_canceled(**kwargs)

x_cancel_halt(**kwargs)

x_cancel_halt_email(**kwargs)

x_cancel_halt_email_clear(**kwargs)

x_cancel_halt_exec(**kwargs)

x_cancel_halt_exec_clear(**kwargs)

x_cancel_halt_write(**kwargs)

x_cancel_halt_write_clear(**kwargs)

x_console(**kwargs)

x_console_hideshow(**kwargs)

x_consoleheight(**kwargs)

x_consoleprogress(**kwargs)

x_consolesave(**kwargs)

x_consolestatus(**kwargs)

x_consolewait(**kwargs)

x_consolewait_onerror(**kwargs)

x_consolewait_whendone(**kwargs)

x_consolewidth(**kwargs)

x_email(**kwargs)

x_error_halt_email(**kwargs)

x_error_halt_email_clear(**kwargs)

x_error_halt_exec(**kwargs)

x_error_halt_exec_clear(**kwargs)

x_error_halt_write(**kwargs)

x_error_halt_write_clear(**kwargs)

x_execute(**kwargs)

Run a database function, view, or action query. Returns None.

x_gui_level(**kwargs)

x_log(**kwargs)

x_log_datavars(**kwargs)

x_log_sql(**kwargs)

x_logwritemessages(**kwargs)

x_system_cmd(**kwargs)

x_timer(**kwargs)

x_write_warnings(**kwargs)

x_executescript(**kwargs)

x_extendscript(**kwargs)

Append the body of one SCRIPT to another, merging parameter names.

x_extendscript_metacommand(**kwargs)

Append a single metacommand line to an existing SCRIPT body.

x_extendscript_sql(**kwargs)

Append a single SQL statement to an existing SCRIPT body.

PG_UPSERT metacommand handler.

Integrates pg-upsert (https://pg-upsert.readthedocs.io/) as an optional dependency, providing QA-checked, FK-dependency-ordered upserts from a staging schema to a base schema on PostgreSQL.

Requires: pip install execsql2[upsert]

register(mcl)

Register PG_UPSERT metacommands as a plugin.

Called by execsql's plugin discovery via the execsql.metacommands entry point. The CHECK and QA variants are registered first so their more-specific regexes take priority over the general form.

x_pg_upsert(**kwargs)

PG_UPSERT FROM TO TABLES , [options]

Full pipeline: QA checks → upsert → optional commit.

x_pg_upsert_check(**kwargs)

PG_UPSERT CHECK FROM TO TABLES ,

Schema check only: column existence + type mismatch.

x_pg_upsert_qa(**kwargs)

PG_UPSERT QA FROM TO TABLES , [options]

QA-only mode: run all QA checks without upserting.

x_debug_commandliststack(**kwargs)

Dump the unified AST execution stack.

Shows every nesting construct the executor is currently inside: <main> script, EXECUTE SCRIPT calls, INCLUDE'd files, IF/ELSEIF/ELSE branches, LOOP iterations (with iteration count), and BATCH blocks. Each frame shows source file and line.

The legacy commandliststack is reported separately as a secondary view because it only records SCRIPT call frames; the unified ast_exec_stack is the authoritative debugger view.

x_debug_iflevels(**kwargs)

x_debug_log_config(**kwargs)

x_debug_log_subvars(**kwargs)

x_debug_write_config(**kwargs)

x_debug_write_metacommands(**kwargs)

x_debug_write_odbc_drivers(**kwargs)

x_debug_write_subvars(**kwargs)

x_show_scripts(**kwargs)

List all registered scripts, or show detail for one script.

Without a name argument, lists all registered SCRIPT definitions with their parameter signatures and source locations. With a name, shows detail for that script including parameters, source, and docstring.