execsql2 2.4.4__py3-none-any.whl → 2.5.0__py3-none-any.whl

execsql/metacommands/__init__.py

@@ -212,6 +212,212 @@ from execsql.utils.regex import (
 )
 from execsql.script import MetaCommandList  # noqa: F401
 
+__all__ = [
+    # execsql.state
+    "_state",
+    # connect handlers
+    "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",
+    # control handlers
+    "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",
+    # data handlers
+    "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",
+    # debug handlers
+    "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",
+    # io handlers
+    "x_export",
+    "x_export_query",
+    "x_export_query_with_template",
+    "x_export_with_template",
+    "x_export_ods_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_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",
+    # prompt handlers
+    "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",
+    # script_ext handlers
+    "x_extendscript",
+    "x_extendscript_metacommand",
+    "x_extendscript_sql",
+    "x_executescript",
+    # system handlers
+    "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",
+    # regex helpers
+    "ins_rxs",
+    "ins_quoted_rx",
+    "ins_schema_rxs",
+    "ins_table_rxs",
+    "ins_table_list_rxs",
+    "ins_fn_rxs",
+    # MetaCommandList
+    "MetaCommandList",
+    # format constants
+    "DELIMITED_FORMATS",
+    "TEXT_FORMATS",
+    "JSON_VARIANT_FORMATS",
+    "QUERY_EXPORT_FORMATS",
+    "TABLE_EXPORT_FORMATS",
+    "SERVE_FORMATS",
+    "METADATA_FORMATS",
+    "ALL_EXPORT_FORMATS",
+    "DATABASE_TYPES",
+    # dispatch
+    "build_dispatch_table",
+    "DISPATCH_TABLE",
+]
+
 # ---------------------------------------------------------------------------
 # Export format constants — single source of truth.
 # Used in dispatch table regex patterns and by io_export.py for validation.

execsql/metacommands/dispatch.py

@@ -169,6 +169,7 @@ from execsql.metacommands.system import (
     x_cancel_halt,
     x_cancel_halt_email,
     x_cancel_halt_email_clear,
+    x_cancel_halt_exec,
     x_cancel_halt_exec_clear,
     x_cancel_halt_write,
     x_cancel_halt_write_clear,
@@ -185,6 +186,7 @@ from execsql.metacommands.system import (
     x_email,
     x_error_halt_email,
     x_error_halt_email_clear,
+    x_error_halt_exec,
     x_error_halt_exec_clear,
     x_error_halt_write,
     x_error_halt_write_clear,
@@ -219,6 +221,8 @@ from execsql.metacommands import (
     TABLE_EXPORT_FORMATS,
 )
 
+__all__ = ["build_dispatch_table"]
+
 
 def build_dispatch_table() -> MetaCommandList:
     """Construct and return the complete metacommand dispatch table."""
@@ -1030,6 +1034,10 @@ def build_dispatch_table() -> MetaCommandList:
         x_error_halt_email,
     )
     mcl.add(r"^\s*ON\s+ERROR_HALT\s+EXEC\s+CLEAR\s*$", x_error_halt_exec_clear)
+    mcl.add(
+        r'^\s*ON\s+ERROR_HALT\s+EXEC(?:UTE)?\s+SCRIPT(?:\s+(?P<exists>IF\s+EXISTS))?\s+(?P<script_id>\w+)(?:(?:\s+WITH)?(?:\s+ARG(?:UMENT)?S?)?\s*\(\s*(?P<argexp>#?\w+\s*=\s*(?:(?:[^"\'\[][^,\)]*)|(?:"[^"]*")|(?:\'[^\']*\')|(?:\[[^\]]*\]))(?:\s*,\s*#?\w+\s*=\s*(?:(?:[^"\'\[][^,\)]*)|(?:"[^"]*")|(?:\'[^\']*\')|(?:\[[^\]]*\])))*)\s*\))?(?:\s+(?P<looptype>WHILE|UNTIL)\s*\(\s*(?P<loopcond>.+)\s*\))?\s*$',
+        x_error_halt_exec,
+    )
     mcl.add(
         r"^\s*ON\s+CANCEL_HALT\s+WRITE\s+CLEAR\s*$",
         x_cancel_halt_write_clear,
@@ -1077,6 +1085,10 @@ def build_dispatch_table() -> MetaCommandList:
         x_cancel_halt_email,
     )
     mcl.add(r"^\s*ON\s+CANCEL_HALT\s+EXEC\s+CLEAR\s*$", x_cancel_halt_exec_clear)
+    mcl.add(
+        r'^\s*ON\s+CANCEL_HALT\s+EXEC(?:UTE)?\s+SCRIPT(?:\s+(?P<exists>IF\s+EXISTS))?\s+(?P<script_id>\w+)(?:(?:\s+WITH)?(?:\s+ARG(?:UMENT)?S?)?\s*\(\s*(?P<argexp>#?\w+\s*=\s*(?:(?:[^"\'\[][^,\)]*)|(?:"[^"]*")|(?:\'[^\']*\')|(?:\[[^\]]*\]))(?:\s*,\s*#?\w+\s*=\s*(?:(?:[^"\'\[][^,\)]*)|(?:"[^"]*")|(?:\'[^\']*\')|(?:\[[^\]]*\])))*)\s*\))?(?:\s+(?P<looptype>WHILE|UNTIL)\s*\(\s*(?P<loopcond>.+)\s*\))?\s*$',
+        x_cancel_halt_exec,
+    )
 
     # ------------------------------------------------------------------
     # SUB_TEMPFILE
@@ -1680,16 +1692,54 @@ def build_dispatch_table() -> MetaCommandList:
     )
     mcl.add(
         (
+            # SERVER unquoted, DB unquoted, PASSWORD unquoted
             r"^CONNECT\s+TO\s+SQLSERVER\s*\(\s*SERVER\s*=\s*(?P<server>[A-Z0-9][A-Z0-9_\/\\\-\.]*)\s*,\s*"
             r"DB\s*=\s*(?P<db_name>[A-Z][A-Z0-9_\-]*)(?:\s*,\s*USER\s*=\s*(?P<user>[A-Z][A-Z0-9_~`!@#$%^&\*\+=\/\?\.-]*)"
             r"\s*,\s*NEED_PWD\s*=\s*(?P<need_pwd>TRUE|FALSE))?(?:\s*,\s*PORT\s*=\s*(?P<port>\d+))?"
             r"(?:\s*,\s+PASSWORD\s*=\s*(?P<password>[^\s\)]+))?"
             r"(?:\s*,\s*ENCODING\s*=\s*(?P<encoding>[A-Z][A-Z0-9_-]+))?\s*\)\s+AS\s+(?P<db_alias>[A-Z][A-Z0-9_]*)\s*$",
+            # SERVER quoted, DB quoted, PASSWORD unquoted
             r'^CONNECT\s+TO\s+SQLSERVER\s*\(\s*SERVER\s*=\s*"(?P<server>[A-Z0-9][A-Z0-9_\/\\\s\-\.]*)"\s*,\s*'
             r'DB\s*=\s*"(?P<db_name>[A-Z][A-Z0-9_\-\s]*)"(?:\s*,\s*USER\s*=\s*(?P<user>[A-Z][A-Z0-9_~`!@#$%^&\*\+=\/\?\.-]*)'
             r"\s*,\s*NEED_PWD\s*=\s*(?P<need_pwd>TRUE|FALSE))?(?:\s*,\s*PORT\s*=\s*(?P<port>\d+))?"
             r"(?:\s*,\s+PASSWORD\s*=\s*(?P<password>[^\s\)]+))?"
             r"(?:\s*,\s*ENCODING\s*=\s*(?P<encoding>[A-Z][A-Z0-9_-]+))?\s*\)\s+AS\s+(?P<db_alias>[A-Z][A-Z0-9_]*)\s*$",
+            # SERVER quoted, DB unquoted, PASSWORD unquoted
+            r'^CONNECT\s+TO\s+SQLSERVER\s*\(\s*SERVER\s*=\s*"(?P<server>[A-Z0-9][A-Z0-9_\/\\\s\-\.]*)"\s*,\s*'
+            r"DB\s*=\s*(?P<db_name>[A-Z][A-Z0-9_\-]*)(?:\s*,\s*USER\s*=\s*(?P<user>[A-Z][A-Z0-9_~`!@#$%^&\*\+=\/\?\.-]*)"
+            r"\s*,\s*NEED_PWD\s*=\s*(?P<need_pwd>TRUE|FALSE))?(?:\s*,\s*PORT\s*=\s*(?P<port>\d+))?"
+            r"(?:\s*,\s+PASSWORD\s*=\s*(?P<password>[^\s\)]+))?"
+            r"(?:\s*,\s*ENCODING\s*=\s*(?P<encoding>[A-Z][A-Z0-9_-]+))?\s*\)\s+AS\s+(?P<db_alias>[A-Z][A-Z0-9_]*)\s*$",
+            # SERVER unquoted, DB quoted, PASSWORD unquoted
+            r"^CONNECT\s+TO\s+SQLSERVER\s*\(\s*SERVER\s*=\s*(?P<server>[A-Z0-9][A-Z0-9_\/\\\-\.]*)\s*,\s*"
+            r'DB\s*=\s*"(?P<db_name>[A-Z][A-Z0-9_\- ]*)"(?:\s*,\s*USER\s*=\s*(?P<user>[A-Z][A-Z0-9_~`!@#$%^&\*\+=\/\?\.-]*)'
+            r"\s*,\s*NEED_PWD\s*=\s*(?P<need_pwd>TRUE|FALSE))?(?:\s*,\s*PORT\s*=\s*(?P<port>\d+))?"
+            r"(?:\s*,\s+PASSWORD\s*=\s*(?P<password>[^\s\)]+))?"
+            r"(?:\s*,\s*ENCODING\s*=\s*(?P<encoding>[A-Z][A-Z0-9_-]+))?\s*\)\s+AS\s+(?P<db_alias>[A-Z][A-Z0-9_]*)\s*$",
+            # SERVER unquoted, DB unquoted, PASSWORD quoted
+            r"^CONNECT\s+TO\s+SQLSERVER\s*\(\s*SERVER\s*=\s*(?P<server>[A-Z0-9][A-Z0-9_\/\\\-\.]*)\s*,\s*"
+            r"DB\s*=\s*(?P<db_name>[A-Z][A-Z0-9_\-]*)(?:\s*,\s*USER\s*=\s*(?P<user>[A-Z][A-Z0-9_~`!@#$%^&\*\+=\/\?\.-]*)"
+            r"\s*,\s*NEED_PWD\s*=\s*(?P<need_pwd>TRUE|FALSE))?(?:\s*,\s*PORT\s*=\s*(?P<port>\d+))?"
+            r'(?:\s*,\s+PASSWORD\s*=\s*(?P<password>"[^\s\)]+"))?'
+            r"(?:\s*,\s*ENCODING\s*=\s*(?P<encoding>[A-Z][A-Z0-9_-]+))?\s*\)\s+AS\s+(?P<db_alias>[A-Z][A-Z0-9_]*)\s*$",
+            # SERVER quoted, DB quoted, PASSWORD quoted
+            r'^CONNECT\s+TO\s+SQLSERVER\s*\(\s*SERVER\s*=\s*"(?P<server>[A-Z0-9][A-Z0-9_\/\\\s\-\.]*)"\s*,\s*'
+            r'DB\s*=\s*"(?P<db_name>[A-Z][A-Z0-9_\-\s]*)"(?:\s*,\s*USER\s*=\s*(?P<user>[A-Z][A-Z0-9_~`!@#$%^&\*\+=\/\?\.-]*)'
+            r"\s*,\s*NEED_PWD\s*=\s*(?P<need_pwd>TRUE|FALSE))?(?:\s*,\s*PORT\s*=\s*(?P<port>\d+))?"
+            r'(?:\s*,\s+PASSWORD\s*=\s*(?P<password>"[^\s\)]+"))?'
+            r"(?:\s*,\s*ENCODING\s*=\s*(?P<encoding>[A-Z][A-Z0-9_-]+))?\s*\)\s+AS\s+(?P<db_alias>[A-Z][A-Z0-9_]*)\s*$",
+            # SERVER quoted, DB unquoted, PASSWORD quoted
+            r'^CONNECT\s+TO\s+SQLSERVER\s*\(\s*SERVER\s*=\s*"(?P<server>[A-Z0-9][A-Z0-9_\/\\\s\-\.]*)"\s*,\s*'
+            r"DB\s*=\s*(?P<db_name>[A-Z][A-Z0-9_\-]*)(?:\s*,\s*USER\s*=\s*(?P<user>[A-Z][A-Z0-9_~`!@#$%^&\*\+=\/\?\.-]*)"
+            r"\s*,\s*NEED_PWD\s*=\s*(?P<need_pwd>TRUE|FALSE))?(?:\s*,\s*PORT\s*=\s*(?P<port>\d+))?"
+            r'(?:\s*,\s+PASSWORD\s*=\s*(?P<password>"[^\s\)]+"))?'
+            r"(?:\s*,\s*ENCODING\s*=\s*(?P<encoding>[A-Z][A-Z0-9_-]+))?\s*\)\s+AS\s+(?P<db_alias>[A-Z][A-Z0-9_]*)\s*$",
+            # SERVER unquoted, DB quoted, PASSWORD quoted
+            r"^CONNECT\s+TO\s+SQLSERVER\s*\(\s*SERVER\s*=\s*(?P<server>[A-Z0-9][A-Z0-9_\/\\\-\.]*)\s*,\s*"
+            r'DB\s*=\s*"(?P<db_name>[A-Z][A-Z0-9_\- ]*)"(?:\s*,\s*USER\s*=\s*(?P<user>[A-Z][A-Z0-9_~`!@#$%^&\*\+=\/\?\.-]*)'
+            r"\s*,\s*NEED_PWD\s*=\s*(?P<need_pwd>TRUE|FALSE))?(?:\s*,\s*PORT\s*=\s*(?P<port>\d+))?"
+            r'(?:\s*,\s+PASSWORD\s*=\s*(?P<password>"[^\s\)]+"))?'
+            r"(?:\s*,\s*ENCODING\s*=\s*(?P<encoding>[A-Z][A-Z0-9_-]+))?\s*\)\s+AS\s+(?P<db_alias>[A-Z][A-Z0-9_]*)\s*$",
         ),
         x_connect_ssvr,
     )
@@ -1722,6 +1772,12 @@ def build_dispatch_table() -> MetaCommandList:
     # ------------------------------------------------------------------
     # APPEND/EXTEND SCRIPT
     # ------------------------------------------------------------------
+    mcl.add(
+        r"\s*EXTEND\s+SCRIPT\s+(?P<script2>\w+)\s+WITH\s+SCRIPT\s+(?P<script1>\w+)\s*$",
+        x_extendscript,
+        description="EXTEND SCRIPT",
+        category="action",
+    )
     mcl.add(
         r"\s*APPEND\s+SCRIPT\s+(?P<script1>\w+)\s+TO\s+(?P<script2>\w+)\s*$",
         x_extendscript,
@@ -1897,13 +1953,48 @@ def build_dispatch_table() -> MetaCommandList:
     # ------------------------------------------------------------------
     mcl.add(
         ins_table_rxs(
-            r'^\s*PROMPT\s+ASK\s+"(?P<question>[^"]+)"\s+SUB\s+(?P<match>~?\w+)(?:\s+DISPLAY\s+',
-            r')?(?:\s+HELP\s+"(?P<help>[^"]+)")?\s*$',
+            r"^\s*PROMPT\s+ASK\s+'(?P<question>[^']+)'\s+SUB\s+(?P<match>~?\w+)(?:\s+DISPLAY\s+",
+            r")?(?:\s+HELP\s+(?P<help>[^\s]+))?\s*$",
         ),
         x_prompt_ask,
         description="PROMPT ASK",
         category="prompt",
     )
+    mcl.add(
+        ins_table_rxs(
+            r"^\s*PROMPT\s+ASK\s+'(?P<question>[^']+)'\s+SUB\s+(?P<match>~?\w+)(?:\s+DISPLAY\s+",
+            r')?(?:\s+HELP\s+"(?P<help>[^"]+)")?\s*$',
+        ),
+        x_prompt_ask,
+    )
+    mcl.add(
+        ins_table_rxs(
+            r"^\s*PROMPT\s+ASK\s+\[(?P<question>[^\]]+)\]\s+SUB\s+(?P<match>~?\w+)(?:\s+DISPLAY\s+",
+            r")?(?:\s+HELP\s+(?P<help>[^\s]+))?\s*$",
+        ),
+        x_prompt_ask,
+    )
+    mcl.add(
+        ins_table_rxs(
+            r"^\s*PROMPT\s+ASK\s+\[(?P<question>[^\]]+)\]\s+SUB\s+(?P<match>~?\w+)(?:\s+DISPLAY\s+",
+            r')?(?:\s+HELP\s+"(?P<help>[^"]+)")?\s*$',
+        ),
+        x_prompt_ask,
+    )
+    mcl.add(
+        ins_table_rxs(
+            r'^\s*PROMPT\s+ASK\s+"(?P<question>[^"]+)"\s+SUB\s+(?P<match>~?\w+)(?:\s+DISPLAY\s+',
+            r")?(?:\s+HELP\s+(?P<help>[^\s]+))?\s*$",
+        ),
+        x_prompt_ask,
+    )
+    mcl.add(
+        ins_table_rxs(
+            r'^\s*PROMPT\s+ASK\s+"(?P<question>[^"]+)"\s+SUB\s+(?P<match>~?\w+)(?:\s+DISPLAY\s+',
+            r')?(?:\s+HELP\s+"(?P<help>[^"]+)")?\s*$',
+        ),
+        x_prompt_ask,
+    )
 
     # ------------------------------------------------------------------
     # PROMPT DISPLAY (table viewer)

execsql/metacommands/io.py

@@ -68,3 +68,44 @@ from execsql.metacommands.io_fileops import (  # noqa: F401
     x_zip,
     x_zip_buffer_mb,
 )
+
+__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_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_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",
+]

execsql/models.py

@@ -49,13 +49,18 @@ __all__ = [
 
 
 class Column:
+    """Compile data-type match statistics for a single column of imported data."""
+
     # Column objects are used to compile information about the data types that a set of data
     # values may match.  A Column object is intended to be used to identify the data type of a column
     # when scanning a data stream (such as a CSV file) to create a new data table.
 
     class Accum:
+        """Accumulate match counts and length statistics for a single data type."""
+
         # Accumulates the count of matches for each data type, plus the maximum length if appropriate.
         def __init__(self, data_type_obj: DataType) -> None:
+            """Initialise the accumulator for the given data type."""
             self.dt = data_type_obj
             self.failed = False
             self.count = 0
@@ -72,6 +77,7 @@ class Column:
             )
 
         def check(self, datavalue: Any) -> None:
+            """Test whether a non-null value matches this data type and update statistics."""
             # datavalue must be non-null
             if not self.failed:
                 is_match = self.dt.matches(datavalue)
@@ -105,6 +111,7 @@ class Column:
                     self.failed = True
 
     def __init__(self, colname: str) -> None:
+        """Create a column characteriser for the named column."""
         from execsql.exceptions import ErrInfo
         import execsql.state as _state
 
@@ -150,6 +157,7 @@ class Column:
         return f"Column({self.name!r})"
 
     def eval_types(self, column_value: Any) -> None:
+        """Evaluate which data types the value matches and update counters."""
         # Evaluate which data type(s) the value matches, and increment the appropriate counter(s).
         import execsql.state as _state
 
@@ -170,6 +178,7 @@ class Column:
             dt.check(column_value)
 
     def column_type(self) -> tuple:
+        """Return the inferred type of this column as a 6-tuple."""
         # Return the type of this column as a tuple of:
         #   column name, data type class, max length or None, bool for null values,
         #   precision or None, scale or None.
@@ -212,7 +221,10 @@ class Column:
 
 
 class DataTable:
+    """Scan a row source and infer column types for CREATE TABLE generation."""
+
     def __init__(self, column_names: list[str], rowsource: Any) -> None:
+        """Scan all rows from the source and infer a column type for each column."""
         import execsql.state as _state
 
         self.inputrows = 0  # Total number of rows in the row source.
@@ -264,6 +276,7 @@ class DataTable:
         return f"DataTable({[col.name for col in self.cols]!r}, rowsource)"
 
     def column_declarations(self, database_type: DbType) -> list[str]:
+        """Return a list of SQL column-declaration strings for the given DBMS."""
         # Returns a list of column specifications.
         spec = []
         for col in self.cols:
@@ -277,6 +290,7 @@ class DataTable:
         tablename: str,
         pretty: bool = False,
     ) -> str:
+        """Generate a CREATE TABLE statement for the given DBMS and table name."""
         tb = (
             f"{database_type.quoted(schemaname)}.{database_type.quoted(tablename)}"
             if schemaname
@@ -292,7 +306,10 @@ class DataTable:
 
 
 class JsonDatatype:
+    """Namespace mapping Python DataType subclasses to JSON Schema type strings."""
+
     def __init__(self) -> None:
+        """Create an empty JsonDatatype namespace instance."""
         pass