Merge branch 'development'

# Conflicts:
#	README.md
#	VERSIONS.md
#	examples/address_book.py
#	examples/journal_external.py
#	examples/journal_internal.py
#	examples/journal_with_data_manipulation.py
#	examples/many_to_many.py
#	examples/password_callback.py
#	examples/restaurants.py
#	examples/selectors_demo.py
#	examples/settings.py
#	examples/tutorial_files/Journal/tutorial.md
#	examples/tutorial_files/Journal/v1/journal.py
#	examples/tutorial_files/Journal/v2/journal.py
#	examples/tutorial_files/Journal/v3/journal.py
#	examples/tutorial_files/Journal/v4/journal.py
#	pysimplesql/pysimplesql.py

Author: jondecker76

README.md

@@ -0,0 +1,14 @@
+# **pysimplesql** Version Information
+
+## <develop>
+### Released <release_date>
+- Big change, moving from a Database/Table topology to a Form/Query topology.  Aliases for Database/Table will be available to avoid breaking code as much as possible.
+I had to kick this around quite a bit, and in the end the new topology makes more sense, especially when you get into using multiple Forms and Queries against the same tables.
+- The above being said, the way records are created is chaging slightly, as well as how the Form is bound to the Window.  
+- By default, auto-generated queries have the same name as the underlying table
+- Tons of documentation improvements
+- Prompt saves when dirty records are present.  This will also be an option for Query object so that the feature can be turned on and off.
+- Forms and Queries now track created instances.  They can be accessed with Form.instances and Query.instances
+- pysimplesql.update_elements() master function will update elements for all forms.  Form.update_elements() still remains, and only updates elements for that specific Form instance.
+- pysimplesql.process_events() master function will process events for all forms.  Form.process_events() still remains, and only processes events for that specific Form instance.
+- Examples and tutorials updated to work with new changes

VERSIONS.md

@@ -60,34 +60,35 @@ def validate_zip():
 headings=['pk','First name:    ','Last name:     ','City:        ','State']
 visible=[0,1,1,1,1] # Hide the primary key column
 layout=[
-    ss.selector("sel","Addresses",sg.Table, headings=headings,visible_column_map=visible, columns=columns,num_rows=10),
-    ss.record("Addresses.fkGroupName",sg.Combo,auto_size_text=False, size=(30,10)),
-    ss.record("Addresses.firstName", label="First name:"),
-    ss.record("Addresses.lastName", label="Last name:"),
-    ss.record("Addresses.address1", label="Address 1:"),
-    ss.record("Addresses.address2", label="Address 2:"),
-    ss.record("Addresses.city", label="City/State:", size=(23,1)) + ss.record("Addresses.fkState",element=sg.Combo, no_label=True, quick_editor=False, size=(3,10)),
-    [sg.Text("Zip:"+" "*63)] + ss.record("Addresses.zip", no_label=True,size=(6,1)),
-    ss.actions("browser","Addresses",edit_protect=False)
+    [ss.selector("sel","Addresses",sg.Table, headings=headings,visible_column_map=visible, columns=columns,num_rows=10)],
+    [ss.record("Addresses.fkGroupName",sg.Combo,auto_size_text=False, size=(30,10))],
+    [ss.record("Addresses.firstName", label="First name:")],
+    [ss.record("Addresses.lastName", label="Last name:")],
+    [ss.record("Addresses.address1", label="Address 1:")],
+    [ss.record("Addresses.address2", label="Address 2:")],
+    [ss.record("Addresses.city", label="City/State:", size=(23,1)) ,ss.record("Addresses.fkState",element=sg.Combo, no_label=True, quick_editor=False, size=(3,10))],
+    [sg.Text("Zip:"+" "*63), ss.record("Addresses.zip", no_label=True,size=(6,1))],
+    [ss.actions("browser","Addresses",edit_protect=False)]
 ]
+
 win=sg.Window('Journal example', layout, finalize=True)
-db=ss.Database(':memory:', win,  sql_commands=sql) #<=== Here is the magic!
-# Note:  sql_commands in only run if journal.db does not exist!  This has the effect of creating a new blank
-# database as defined by the sql_commands if the database does not yet exist, otherwise it will use the database!
+# Create our frm
+frm=ss.Form(':memory:', sql_commands=sql, bind=win)
+
 
 # Use a callback to validate the zip code
-db['Addresses'].set_callback('before_save',validate_zip)
+frm['Addresses'].set_callback('before_save',validate_zip)
 
 # ---------
 # MAIN LOOP
 # ---------
 while True:
     event, values = win.read()
 
-    if db.process_events(event, values):                  # <=== let PySimpleSQL process its own events! Simple!
+    if ss.process_events(event, values):                  # <=== let PySimpleSQL process its own events! Simple!
         logger.info(f'PySimpleDB event handler handled the event {event}!')
     elif event == sg.WIN_CLOSED or event == 'Exit':
-        db=None              # <= ensures proper closing of the sqlite database and runs a database optimization
+        frm=None              # <= ensures proper closing of the sqlite database and runs a database optimization
         break
     else:
         logger.info(f'This event ({event}) is not yet handled.')
@@ -100,11 +101,11 @@ def validate_zip():
 usable program! The combination of PySimpleSQL and PySimpleGUI is very fun, fast and powerful!
 
 Learnings from this example:
-- Using Table.set_search_order() to set the search order of the table for search operations.
+- Using Query.set_search_order() to set the search order of the table for search operations.
 - embedding sql commands in code for table creation
-- creating a default/empty database with sql commands with the sql_commands keyword argument to ss.Database()
+- creating a default/empty database with sql commands with the sql_commands keyword argument to ss.Form()
 - using ss.record() and ss.selector() functions for easy GUI element creation
 - using the label keyword argument to ss.record() to define a custom label
 - using Tables as ss.selector() element types
-- changing the sort order of database tables
+- changing the sort order of database queries
 """

examples/address_book.py

@@ -4,40 +4,41 @@
 logger=logging.getLogger(__name__)
 logging.basicConfig(level=logging.INFO)               # <=== You can set the logging level here (NOTSET,DEBUG,INFO,WARNING,ERROR,CRITICAL)
 
+
 # -------------------------
 # CREATE PYSIMPLEGUI LAYOUT
 # -------------------------
 # Define the columns for the table selector
 headings=['id','Date:              ','Mood:      ','Title:                                 ']
 visible=[0,1,1,1] # Hide the id column
 layout=[
-    ss.selector('sel_journal','Journal',sg.Table,num_rows=10,headings=headings,visible_column_map=visible),
-    ss.actions('act_journal','Journal'),
-    ss.record('Journal.entry_date'),
-    ss.record('Journal.mood_id', sg.Combo, label='My mood:', size=(30,10), auto_size_text=False),
-    ss.record('Journal.title'),
-    ss.record('Journal.entry', sg.MLine, size=(71,20))
+    [ss.selector('sel_journal','Journal',sg.Table,num_rows=10,headings=headings,visible_column_map=visible)],
+    [ss.actions('act_journal','Journal')],
+    [ss.record('Journal.entry_date')],
+    [ss.record('Journal.mood_id', sg.Combo, label='My mood:', size=(30,10), auto_size_text=False)],
+    [ss.record('Journal.title')],
+    [ss.record('Journal.entry', sg.MLine, size=(71,20))]
 ]
-win=sg.Window('Journal example', layout, finalize=True)
-db=ss.Database('journal.db', win,  sql_script='journal.sql') #<=== Here is the magic!
-# Note:  sql_script is only run if journal.db does not exist!  This has the effect of creating a new blank
+win=sg.Window('Journal (external)  example', layout, finalize=True)
+frm=ss.Form('journal.db', sql_script='journal.sql', bind=win)   #<=== Here is the magic!
+# Note:  sql_script is only run if journal.frm does not exist!  This has the effect of creating a new blank
 # database as defined by the sql_script file if the database does not yet exist, otherwise it will use the database!
 
 # Reverse the default sort order so new journal entries appear at the top
-db['Journal'].set_order_clause('ORDER BY entry_date DESC')
+frm['Journal'].set_order_clause('ORDER BY entry_date DESC')
 # Set the column order for search operations.  By default, only the column designated as the description column is searched
-db['Journal'].set_search_order(['entry_date','title','entry'])
+frm['Journal'].set_search_order(['entry_date','title','entry'])
 
 # ---------
 # MAIN LOOP
 # ---------
 while True:
     event, values = win.read()
 
-    if db.process_events(event, values):                  # <=== let PySimpleSQL process its own events! Simple!
+    if ss.process_events(event, values):                  # <=== let PySimpleSQL process its own events! Simple!
         logger.info(f'PySimpleDB event handler handled the event {event}!')
     elif event == sg.WIN_CLOSED or event == 'Exit':
-        db=None              # <= ensures proper closing of the sqlite database and runs a database optimization
+        frm=None              # <= ensures proper closing of the sqlite database and runs a database optimization
         break
     else:
         logger.info(f'This event ({event}) is not yet handled.')
@@ -48,10 +49,10 @@
 usable program! The combination of PySimpleSQL and PySimpleGUI is very fun, fast and powerful!
 
 Learnings from this example:
-- Using Table.set_search_order() to set the search order of the table for search operations.
-- creating a default/empty database with an external sql script with the sql_script keyword argument to ss.Database()
-- using ss.record() and ss.selector() functions for easy GUI element creation
-- using the label keyword argument to ss.record() to define a custom label
-- using Tables as ss.selector() element types
-- changing the sort order of database tables
+- Using Query.set_search_order() to set the search order of the query for search operations.
+- creating a default/empty database with an external sql script with the sql_script keyword argument to ss.Form()
+- using Form.record() and Form.selector() functions for easy GUI element creation
+- using the label keyword argument to Form.record() to define a custom label
+- using Tables as Form.selector() element type
+- changing the sort order of Queries
 """

examples/journal_external.py

@@ -34,33 +34,33 @@
 headings=['id','Date:              ','Mood:      ','Title:                                 ']
 visible=[0,1,1,1] # Hide the id column
 layout=[
-    ss.selector('sel_journal','Journal',sg.Table,num_rows=10,headings=headings,visible_column_map=visible),
-    ss.actions('act_journal','Journal'),
-    ss.record('Journal.entry_date'),
-    ss.record('Journal.mood_id', sg.Combo, label='My mood:', size=(30,10), auto_size_text=False),
-    ss.record('Journal.title'),
-    ss.record('Journal.entry', sg.MLine, size=(71,20))
+    [ss.selector('sel_journal','Journal',sg.Table,num_rows=10,headings=headings,visible_column_map=visible)],
+    [ss.actions('act_journal','Journal')],
+    [ss.record('Journal.entry_date')],
+    [ss.record('Journal.mood_id', sg.Combo, label='My mood:', size=(30,10), auto_size_text=False)],
+    [ss.record('Journal.title')],
+    [ss.record('Journal.entry', sg.MLine, size=(71,20))]
 ]
-win=sg.Window('Journal example', layout, finalize=True)
-db=ss.Database('journal.db', win,  sql_commands=sql) #<=== Here is the magic!
-# Note:  sql_commands in only run if journal.db does not exist!  This has the effect of creating a new blank
+win=sg.Window('Journal (internal) example', layout, finalize=True)
+frm=ss.Form('::memory::', sql_commands=sql, bind=win) #<=== Here is the magic!
+# Note:  sql_commands in only run if journal.frm does not exist!  This has the effect of creating a new blank
 # database as defined by the sql_commands if the database does not yet exist, otherwise it will use the database!
 
 # Reverse the default sort order so new journal entries appear at the top
-db['Journal'].set_order_clause('ORDER BY entry_date DESC')
+frm['Journal'].set_order_clause('ORDER BY entry_date DESC')
 # Set the column order for search operations.  By default, only the column designated as the description column is searched
-db['Journal'].set_search_order(['entry_date','title','entry'])
+frm['Journal'].set_search_order(['entry_date','title','entry'])
 
 # ---------
 # MAIN LOOP
 # ---------
 while True:
     event, values = win.read()
 
-    if db.process_events(event, values):                  # <=== let PySimpleSQL process its own events! Simple!
+    if ss.process_events(event, values):                  # <=== let PySimpleSQL process its own events! Simple!
         logger.info(f'PySimpleDB event handler handled the event {event}!')
     elif event == sg.WIN_CLOSED or event == 'Exit':
-        db=None              # <= ensures proper closing of the sqlite database and runs a database optimization
+        frm=None              # <= ensures proper closing of the sqlite database and runs a database optimization
         break
     else:
         logger.info(f'This event ({event}) is not yet handled.')
@@ -71,11 +71,11 @@
 usable program! The combination of PySimpleSQL and PySimpleGUI is very fun, fast and powerful!
 
 Learnings from this example:
-- Using Table.set_search_order() to set the search order of the table for search operations.
+- Using Query.set_search_order() to set the search order of the query for search operations.
 - embedding sql commands in code for table creation
-- creating a default/empty database with sql commands with the sql_commands keyword argument to ss.Database()
-- using ss.record() and ss.selector() functions for easy GUI element creation
-- using the label keyword argument to ss.record() to define a custom label
-- using Tables as ss.selector() element types
-- changing the sort order of database tables
+- creating a default/empty database with sql commands with the sql_commands keyword argument to ss.Form()
+- using Form.record() and Form.selector() functions for easy GUI element creation
+- using the label keyword argument to Form.record() to define a custom label
+- using Tables as Form.selector() element types
+- changing the sort order of database queries
 """