execsql2 1.130.1__py3-none-any.whl

execsql2-1.130.1.data/data/execsql2_extras/READ_ME.rst

@@ -0,0 +1,129 @@
+Templates for execsql.py
+===================================================
+
+Several types of templates are provided that may be useful in conjunction with execsql.py.  These are:
+
+*execsql.conf*
+    An annotated version of the configuration file that includes all configuration settings
+    and notes on their usage.
+
+*script_template.sql*
+    A framework for SQL scripts that make use of several execsql features.  It includes sections
+    for custom configuration settings, custom logfile creation, and reporting of unexpected
+    script exits (through user cancellation or errors).
+
+*config_settings.sqlite* and *example_config_prompt.sql*
+    A SQLite database containing specifications for all settings configurable with the CONFIG
+    metacommand, in the form used by the PROMPT ENTRY_FORM metacommand, and a SQL script
+    illustrating how this database can be used to prompt the user for some or all of the
+    configuration settings.  *execsql* version 1.63.0 or later is needed to use this script.
+
+
+Functional Scripts for execsql.py
+=================================================
+
+These script files provide useful functionality that should be accessed by including these
+scripts in other SQL scripts and then calling the sub-scripts that they contain.
+
+Upsert Scripts
+------------------------------------------------
+
+These scripts perform automated upsert operations on any tables of
+any database in a DBMS that supports the standard
+*information_schema* views.  Currently that includes:
+
+* PostgreSQL: pg_upsert.sql;
+
+* MySQL/MariaDB: md_upsert.sql; and 
+
+* SQL Server: ss_upsert.sql.
+
+These scripts perform the upsert operation by using standard SQL
+UPDATE and INSERT statements rather than DBMS-specific implementations
+of the SQL MERGE statement.
+
+Features of these upsert scripts include:
+
+* They can be applied to any table in any database without modification.
+
+* They can be applied to multiple tables simultaneously, and will
+  perform the upsert operations in top-down order to maintain
+  referential integrity among tables.
+
+* Prior to performing the upsert operation, they check for null
+  values in the columns of each staging table that must be non-null in the
+  corresponding base table.
+
+* Prior to performing the upsert operation, they check for duplicate
+  primary key values in the staging tables.
+
+* Prior to performing the upsert operation, they check foreign keys
+  against both base tables and any other appropriate staging tables.
+
+* They will not attempt to perform the upsert operation on any
+  table if there are any violations of the non-null
+  checks, primary key checks, or foreign key checks.
+
+* They produce a table that either a) summarizes the number of
+  rows that violated each type of non-null and foreign-key check,
+  or b) summarizes the number of rows updated and the number of
+  rows inserted for each table.
+
+* Optionally, they will display all the changes to be made in a
+  GUI interface, prompting the user to approve each update and
+  insert operation.
+
+* Optionally, they will record all operations carried out in a
+  custom log file; this log may include the SQL statements executed
+  and the data values that were added or changed.
+
+* If an execsql console is active, they will use the console's
+  status bar and progress bar to indicate the activity underway.
+
+
+Complete documentation is available at
+`Read The Docs (execsql-upsert) <https://execsql-upsert.readthedocs.io/en/latest/>`_.
+
+
+Table Comparison Scripts
+----------------------------------------------------------
+
+These scripts generate SQL that can be used to identify differences
+in the content of two tables with equivalent structure.  These are
+specifically intended to be base and staging tables.  Running the
+SQL provided by these scripts will provide different summaries of
+the types of changes that would be made to the base tables by
+upserting the staging tables.
+
+These scripts work with
+any tables of any database in a DBMS that supports the standard
+*information_schema* views.  Currently that includes:
+
+* PostgreSQL: pg_compare.sql;
+
+* MySQL/MariaDB: md_compare.sql; and 
+
+* SQL Server: ss_compare.sql.
+
+Complete documentation is available at
+`Read The Docs (execsql-compare) <https://execsql-compare.readthedocs.io/en/latest/>`_.
+
+
+Glossary Creation Scripts
+------------------------------------------------------------
+
+These scripts create a glossary of column names or other terms
+that can be exported to accompany a data summary.  These scripts work with
+any tables of any database in a DBMS that supports the standard
+*information_schema* views.  Currently that includes:
+
+* PostgreSQL: pg_glossary.sql;
+
+* MySQL/MariaDB: md_glossary.sql; and 
+
+* SQL Server: ss_glossary.sql.
+
+Complete documentation is available at
+`Read The Docs (execsql-glossary) <https://execsql-compare.readthedocs.io/en/latest/>`_.
+
+

execsql2-1.130.1.data/data/execsql2_extras/example_config_prompt.sql

@@ -0,0 +1,159 @@
+-- example_config_prompt.sql
+--
+-- PURPOSE
+--	Illustrate the use of the 'config_settings.sqlite' database
+--	to prompt for configuration settings.
+--
+-- NOTES
+--	1. The initial connection is assumed to have been made to some
+--		database other than the configuration database.
+--	2. The 'prompt_config' script defined in this file will connect
+--		to the configuration database using the alias "config_db"
+--		if that alias exists, or it will connect to the (SQLite)
+--		configuration database if the "config_db" substitution
+--		variable contains a valid path and name to the configuration
+--		database.
+--	3. This requires excecsql.py version 1.63.0 or greater.
+--	4. To replicate this example (or something like it) in production code:
+--		a. Include the "prompt_config" script (defined below) in
+--			your own script.
+--		b. Either define the "sub_config" variable so that it contains
+--			the path and filename of the configuration database,
+--			or use the CONNECT metacommand to connect to that database
+--			yourself with an alias of "config_db".
+--		c. Possibly change the 'usage' argument for the 'prompt_config"
+--			script to be "Import", "Export", or "AllButDAO" instead of "All."
+--
+-- AUTHOR
+--	Dreas Nielsen (RDN)
+--
+-- HISTORY
+--	 Date		 Remarks
+--	----------	-----------------------------------------------------
+--	2020-02-15	Created.  RDN.
+--	2020-02-16	Modified documentation.  RDN.
+--	2020-02-16	Corrected assignments.  RDN.
+--	2020-02-22	Added SCAN_LINES and GUI_LEVEL.  RDN.
+--	2020-03-22	Added HDF5_TEXT_LEN and LOG_DATAVARS.  RDN.
+--	2020-03-30	Added EXPORT_ROW_BUFFER.  RDN.
+--	2020-07-30	Added DEDUP_COLUMN_HEADERS.  RDN.
+--	2020-11-08	Added ONLY_STRINGS.  RDN.
+--	2020-11-14	Added CONSOLE HEIGHT and CONSOLE WIDTH.  These are
+--				not subcommands of the CONFIG metacommand, but they
+--				now affect future consoles, and so function similarly.  RDN.
+--	2021-02-15	Added CREATE_COL_HEADERS and ZIP_BUFFER_MB.  RDN.
+--	2021-09-19	Added TRIM_STRINGS and REPLACE_NEWLINES.  RDN.
+--	2023-08-25	Changed names of a couple of sub vars.  Added
+--				DELETE_EMPTY_COLUMNS, FOLD_COLUMN_HEADERS, TRIM_COLUMN_HEADERS,
+--				WRITE_PREFIX, and WRITE_SUFFIX.  RDN.
+-- ==================================================================
+
+
+-- ##################################################################
+--		Configuration
+-- ==================================================================
+
+-- Path and name of the configuration settings database.
+-- !x! sub config_db ./config_settings.sqlite
+
+
+-- ##################################################################
+--		Usage illustration
+-- ==================================================================
+-- This makes use of the 'prompt_config' script, defined below.
+
+-- Prompt the user
+-- !x! execute script prompt_config with arguments (usage=All)
+-- Display all configuration settings (including settings not set interactively).
+-- !x! debug write config
+
+
+
+
+
+-- ##################################################################
+--		Scripts
+-- ==================================================================
+
+
+-- -----------------------------------------------------------------
+--		prompt_config
+--
+-- Creates and displays prompts for configuration settings,
+-- modifying the global settings per the user's input.
+--
+-- Argument
+--	usage	: Values of the 'usage' column in the 'configusage'
+--				table of the configuration settings database.
+--				This should be 'All', 'AllButDAO', 'Import', or 'Export'.
+--				Other values may be used if they have been added
+--				to the 'configusage' table
+--
+-- Effects
+--	1. Modifies global settings.
+--	2. Creates a temporary table with a UUID as a name in the configuration database.
+--
+-- Requirements
+--	Either:
+--		* An existing connection to the configuration database
+--			with an alias of "config_db"; or
+--		* A substitution variable named "config_db" that defines
+--			the path and filename to the (SQLite) configuration
+--			database.
+-- -----------------------------------------------------------------
+
+-- !x! begin script prompt_config with parameters (usage)
+	-- !x! sub entry_db !!$current_alias!!
+	-- !x! if(alias_defined(config_db))
+		-- !x! use config_db
+	-- !x! else
+		-- !x! if(sub_defined(config_db))
+			-- !x! connect to sqlite(file=!!config_db!!) as config_db
+			-- !x! use config_db
+		-- !x! else
+			-- !x! halt message "The configuration settings database is not open and its name is not specified."
+		-- !x! endif
+	-- !x! endif
+	-- The following SQL syntax is for SQLite.  A UUID is used for the table name
+	-- for portability to a multi-user DBMS.
+	-- !x! sub ~spectbl !!$uuid!!
+	create temporary table "!!~spectbl!!" as
+	select cs.*
+	from configspecs cs inner join configusage cu
+		on cu.sub_var = cs.sub_var
+	where
+		usage = '!!#usage!!';
+	-- !x! prompt entry_form !!~spectbl!! message "You may change any of the configuration settings below."
+	-- !x! if(sub_defined(~boolean_int)) {config boolean_int !!~boolean_int!!}
+	-- !x! if(sub_defined(~boolean_words)) {config boolean_words !!~boolean_words!!}
+	-- !x! if(sub_defined(~clean_column_headers)) {config clean_column_headers !!~clean_column_headers!!}
+	-- !x! if(sub_defined(~create_column_headers)) {config create_column_headers !!~create_column_headers!!}
+	-- !x! if(sub_defined(~dedup_col_hdrs)) {config dedup_column_headers !!~dedup_col_hdrs!!}
+	-- !x! if(sub_defined(~delete_empty_columns)) {config delete_empty_columns !!~delete_empty_columns!!}
+	-- !x! if(sub_defined(~empty_strings)) {config empty_strings !!~empty_strings!!}
+	-- !x! if(sub_defined(~fold_col_hdrs)) {config fold_column_headers !!~fold_col_hdrs!!}
+	-- !x! if(sub_defined(~trim_col_hdrs)) {config trim_column_headers !!~trim_col_hdrs!!}
+	-- !x! if(sub_defined(~only_strings)) {config only_strings !!~only_strings!!}
+	-- !x! if(sub_defined(~empty_rows)) {config empty_rows !!~empty_rows!!}
+	-- !x! if(sub_defined(~trim_strings)) {config trim_strings !!~trim_strings!!}
+	-- !x! if(sub_defined(~replace_newlines)) {config replace_newlines !!~replace_newlines!!}
+	-- !x! if(sub_defined(~scan_lines)) {config scan_lines !!~scan_lines!!}
+	-- !x! if(sub_defined(~import_common)) {config import_common_columns_only !!~import_common!!}
+	-- !x! if(sub_defined(~console_height)) {console height !!~console_height!!}
+	-- !x! if(sub_defined(~console_width)) {console width !!~console_width!!}
+	-- !x! if(sub_defined(~console_wait_done)) {config console wait_when_done !!~console_wait_done!!}
+	-- !x! if(sub_defined(~console_wait_err)) {config console wait_when_error !!~console_wait_err!!}
+	-- !x! if(sub_defined(~log_write)) {config log_write_messages !!~log_write!!}
+	-- !x! if(sub_defined(~quote_all)) {config quote_all_text !!~quote_all!!}
+	-- !x! if(sub_defined(~export_row_buffer)) {config export_row_buffer !!~export_row_buffer!!}
+	-- !x! if(sub_defined(~hdf5_len)) {config hdf5_text_len !!~hdf5_len!!}
+	-- !x! if(sub_defined(~gui_level)) {config gui_level !!~gui_level!!}
+	-- !x! if(sub_defined(~write_prefix)) {config write_prefix !!~write_prefix!!}
+	-- !x! if(sub_defined(~write_suffix)) {config write_suffix !!~write_suffix!!}
+	-- !x! if(sub_defined(~write_warnings)) {config write_warnings !!~write_warnings!!}
+	-- !x! if(sub_defined(~log_datavars)) {config log_datavars !!~log_datavars!!}
+	-- !x! if(sub_defined(~dao_flush)) {config dao_flush_delay_secs !!~dao_flush!!}
+	-- !x! if(sub_defined(~zip_buffer_mb)) {config zip_buffer_mb !!~zip_buffer_mb!!}
+	-- !x! use !!entry_db!!
+-- !x! end script prompt_config
+

execsql2-1.130.1.data/data/execsql2_extras/execsql.conf

@@ -0,0 +1,289 @@
+# execsql.conf
+#
+# PURPOSE
+#	Configuration file for execsql.py
+#	See http://execsql.osdn.io/configuration.html
+#
+# AUTHORS
+#     
+#     
+# HISTORY
+# 	 Date		 Revisions
+# 	-----------	----------------------------------------------------
+#
+#===================================================================
+
+[connect]
+# Connection information for the initial database connection.
+
+# Database type.  p: Postgres, l: SQLite, m: MySQL/MariaDB, f: Firebird, s: SQL Server,
+#                 a: Access,   o: Oracle, d: DSN
+#db_type=
+
+# Server name for client-server databases.
+#server=
+
+# Database name for client-server databases.
+#db=
+
+# Database name for file-based databases.
+#db_file=
+
+# Port number for server-based databases.  Only needed if not the default.
+#port=
+
+# User name for client-server databases.
+#username=
+
+# User name for password-protected MS-Access databases if not "Admin".
+#access_username=
+
+# Whether or not a password is necessary, and a prompt should be issued.
+# Values: Yes or No.  Default: No.
+#password_prompt=No
+
+# Whether a new PostgreSQL or SQLite database should be created.
+# Values: Yes or No.  Default: Yes
+#new_db=Yes
+
+
+[encoding]
+# Character encoding for text input and output.
+
+#database=
+#script=
+#import=
+#output=
+
+# How to handle incompatible encodings.  Values: ignore, replace, xmlcharrefreplace, or backslashreplace.
+#error_response=
+
+
+[input]
+# Settings to control the handling of different conditions or data representations in input data.
+
+# Whether or not to convert numeric values to double precision when using MS-Access.
+# Values: Yes or No.  Default: No.
+#access_use_numeric=No
+
+# Whether or not to treat integer values of 0 and 1 as Booleans.
+# Values: Yes or No.  Default: Yes.
+#boolean_int=Yes
+
+# Whether or not to recognize only full words as Boolean, not "Y", "N", "T", and "F".
+# Values: Yes or No.  Default: No.
+#boolean_words=No
+
+# Whether or not to replace non-alphanumeric characters in column names of imported data with an underscore.
+# Values: Yes or No.  Default: No.
+#clean_column_headers=No
+
+# Whether or not to create column headers when they are missing from an input file.
+# Created column headers will take the form "Col" followed by the column number.
+# Values: Yes or No.  Default: No.
+#create_column_headers=No
+
+# Whether or not to modify duplicated column names of imported data by appending an underscore and
+# the column number to make column names unique.
+# Values: Yes or No.  Default: No.
+#dedup_column_headers=No
+
+# Whether or not to completely delete columns if the headers are missing from an input file.
+# Values: Yes or No.  Default: No.
+#delete_empy_columns=No
+
+# Wehther or not to import completely empty rows.
+# Values: Yes or No.  Default: Yes.
+#empty_rows=Yes
+
+# Whether empty strings in input data are preserved or replaced by NULL.
+# Values: Yes or No.  Default: Yes.
+#empty_strings=Yes
+
+# Whether or not to fold column headers to lowercase or uppercase, or leave them unchanged during IMPORT.
+# Values: No, Lower, or Upper.  Default: No.
+#fold_column_headers=No
+
+# The size of the import buffer, in kb, to be used by the fast file reading feature of Postgres.
+#import_buffer=
+
+# Whether to ignore extra column in an imported CSV file that are not in the target table.
+# Values: Yes or No.  Default: No.
+#import_only_common_columns=No
+
+# The number of rows to buffer from a data source when importing data and when a DBMS-specific
+# fast file reading method can't be used.
+# Value: A positive non-zero integer.  Default: 1000
+#import_row_buffer=1000
+
+# The maximum value that will be assigned an integer data type when creating new tables.
+#max_int=2147483647
+
+# Whether or not the IMPORT metacommand will treat all columns as text, rather than trying
+# to evaluate the data type for each column.
+# Values: Yes or No.  Default: No.
+#only_strings=No
+
+# Whether newlines embedded in imported text should be replaced with a single space.
+# Value: Yes or No.  Default: No.
+#replace_newlines=No
+
+# The number of lines in an input data file to scan to identify delimiters and quote characters.
+# Value: a positive non-zero integer.  Default: 1000
+#scan_lines=1000
+
+# Whether leading and/or trailing spaces and underscores should be removed from column headers.
+# Value: None, Both, Left, or Right.  Default: None
+#trim_column_headers=None
+
+# Whether leading and trailing whitespace on imported text should be removed.
+# Value: Yes or No.  Default: No.
+#trim_strings=No
+
+
+[output]
+# Settings to control the output of messages and data.
+
+# Whether all output of the WRITE metacommands should also be sent to execsql's log file.
+# Values: Yes or No.  Default: No.
+#log_write_messages=No
+
+# Whether to create any non-existent directories referenced in WRITE or EXPORT metacommands.
+# Values: Yes or No.  Default: No.
+#make_export_dirs=No
+
+# Whether to quote all text values written to a delimited text file by the EXPORT metacommand.
+# Values: Yes or No.  Default: No.
+#quote_all_text=No
+
+# The number of rows to buffer from the database when exporting data.  Larger values produce
+# faster exports, up to a point, but require more memory.
+# Value: A positive non-zero integer.  Default: 1000
+#export_row_buffer=1000
+
+# The length to be assigned to 'text' data types when exporting to the HDF5 format.
+# Value: a positive non-zero integer.  Default: 1000
+# hdf5_text_len=1000
+
+# The URI of a CSS file to be used when exporting to HTML.
+#css_file=
+
+# CSS style commands to be embedded in HTML export.
+#css_style=
+
+# The duration, in seconds, for execsql to continue to try opening a file that is to be
+# written to with the WRITE metacommand, if there is an access conflict.
+# Value: A positive non-zero number.  Default: 600.
+#outfile_open_timeout=600
+
+# The name of the template processor to be used when exporting data using a template.
+# Values: jinja or airspeed.
+#template_processor=
+
+# The size of the internal buffer used when the EXPORT metacommand exports data to
+# a zipfile, in Mb.
+# Value: any positive non-zero integer that is at least as large as the longest
+# data row to be exported.  Default: 10.
+#zip_buffer_mb=10
+
+
+[interface]
+# Settings to control appearance or operation of GUI dialogs.
+
+# The approximate height, in lines, of a console window created with the CONSOLE ON metacommand.
+# Value: A positive non-zero integer greater than 3. Default: 25
+#console_height=25
+
+# Whether a console window that has been opened should remain open at the end of the script.
+# Value: Yes or No.  Default: No.
+#console_wait_when_done=No
+
+# Whether a console window that has been opened should remain open when an error occurs.
+# Value: Yes or No.  Default: No.
+#console_wait_when_error_halt=No
+
+# The approximate width, in characters, of a console window created with the CONSOLE ON metacommand.
+# Value: A positive non-zero integer.  Default: 100
+#console_width=100
+
+# Whether to write warning messages to the console as well as to the log file.
+# Value: Yes or No.  Default: No.
+#write_warnings=No
+
+# Text that will be prefixed to any output from the WRITE metacommand, with a space separator.
+#write_prefix=
+
+# Text that will be appended to any output from the WRITE metacommand, with a space separator.
+#write_suffix=
+
+# Usage of GUI dialogs.  Values: 0 - none, 1 - passwords and pause metacommands, 2 - also for the halt
+# metacommand, 3 - open a console window immediately.  Default: 0.
+#gui_level=0
+
+
+[email]
+# Settings that provide additional information that is required by the EMAIL metacommand.
+
+# SMTP host identification
+#host=
+#port=
+#username=
+#password=
+#use_ssl=
+#use_tls=
+
+# Email may be sent as plain text or as HTML.
+# Values: plain or html.  Default: plain.
+#email_format=plain
+
+# HTML email may have a set of custom CSS styles applied.
+#message_css=
+
+# Instead of using a plaintext password in a configuration file, an obfuscated version
+# ('encrypted' but not cryptographically-secure) can be used instead.  This encrypted
+# version must have been generated by execsql.
+#enc_password=
+
+
+[config]
+# The path or filename of an additional non-standard configuration file to be read.
+#config_file=
+
+# The number of seconds between using DAO to create a query in MS-Access and using ODBC
+# to access data.  This must be greater than or equal to 5.0.
+#dao_flush_delay_secs=5
+
+# The full name or path to an additional configuration file to be read if execsql.py
+# is running on Linux.
+#linux_config_file=
+
+# Whether or not to log all data variable assignments to the execsql.log file.
+# Values: Yes or No.  Default: Yes.
+#log_datavars=Yes
+
+# The full name or path to an additional configuration file to be read if execsql.py
+# is running on Windows.
+#win_config_file=
+
+# Whether to place the execsql.log logfile in the user's home directory instead of the
+# script directory.  Values: Yes or No.  Default: No.
+#user_logfile=Yes
+
+
+[variables]
+# Substitution variables that will be defined when the script starts up.  There are
+# no pre-defined setting names (variable) for this section.
+
+
+[include_required]
+# Additional script files that will be read before the main script starts.  There are no
+# pre-defined settings for this section.  Keys are integers defining the order in which
+# scripts are read; values are the names of the scripts (including paths).
+
+
+[include_optional]
+# Additional script files that may be read before the main script starts.  There are no
+# pre-defined settings for this section.  Keys are integers defining the order in which
+# scripts are read; values are the names of the scripts (including paths).
+
+