Refactor and documentation.

dsst/dsst_gtk3/dialogs.py

@@ -1,3 +1,6 @@
+"""
+This module contains UI functions for displaying different dialogs
+"""
 import gi
 gi.require_version('Gtk', '3.0')
 from gi.repository import Gtk
@@ -42,7 +45,7 @@ def show_episode_dialog(builder: Gtk.Builder, title: str, season_id: int, episod
     dialog = builder.get_object("edit_episode_dialog")  # type: Gtk.Dialog
     dialog.set_transient_for(builder.get_object("main_window"))
     dialog.set_title(title)
-    with sql.connection.atomic():
+    with sql.db.atomic():
         if not episode:
             nxt_number = len(sql.Season.get_by_id(season_id).episodes) + 1
             episode = sql.Episode.create(seq_number=nxt_number, number=nxt_number, date=datetime.today(),
@@ -61,7 +64,7 @@ def show_episode_dialog(builder: Gtk.Builder, title: str, season_id: int, episod
         dialog.hide()
 
         if result != Gtk.ResponseType.OK:
-            sql.connection.rollback()
+            sql.db.rollback()
             return False
 
         # Save all changes to Database
@@ -79,6 +82,10 @@ def show_episode_dialog(builder: Gtk.Builder, title: str, season_id: int, episod
 
 
 def show_manage_players_dialog(builder: Gtk.Builder, title: str):
+    """Show a dialog for managing player base data.
+    :param builder: Gtk.Builder object
+    :param title: Title for the dialog
+    """
     dialog = builder.get_object("manage_players_dialog")  # type: Gtk.Dialog
     dialog.set_transient_for(builder.get_object("main_window"))
     dialog.set_title(title)
@@ -109,9 +116,15 @@ def show_manage_drinks_dialog(builder: Gtk.Builder):
 
 
 def show_edit_death_dialog(builder: Gtk.Builder, episode_id: int, death: sql.Death=None):
+    """Show a dialog for editing or creating death events.
+    :param builder: A Gtk.Builder object
+    :param episode_id: ID to witch the death event belongs to
+    :param death: (Optional) Death event witch should be edited
+    :return: Gtk.ResponseType of the dialog
+    """
     dialog = builder.get_object("edit_death_dialog")  # type: Gtk.Dialog
     dialog.set_transient_for(builder.get_object("main_window"))
-    with sql.connection.atomic():
+    with sql.db.atomic():
         if death:
             index = util.Util.get_index_of_combo_model(builder.get_object('edit_death_enemy_combo'), 0, death.enemy.id)
             builder.get_object('edit_death_enemy_combo').set_active(index)
@@ -126,10 +139,10 @@ def show_edit_death_dialog(builder: Gtk.Builder, episode_id: int, death: sql.Dea
         # Run the dialog
         result = dialog.run()
         dialog.hide()
-
         if result != Gtk.ResponseType.OK:
-            sql.connection.rollback()
-            return False
+            sql.db.rollback()
+            return result
+
         # Collect info from widgets and save to database
         player_id = util.Util.get_combo_value(builder.get_object('edit_death_player_combo'), 0)
         enemy_id = util.Util.get_combo_value(builder.get_object('edit_death_enemy_combo'), 3)
@@ -143,4 +156,4 @@ def show_edit_death_dialog(builder: Gtk.Builder, episode_id: int, death: sql.Dea
             drink_id = sql.Drink.get(sql.Drink.name == entry[2])
             sql.Penalty.create(size=size, player=entry[3], death=death.id, drink=drink_id)
 
-        return True
+        return result

dsst/dsst_gtk3/gtk_ui.py

@@ -1,17 +1,13 @@
 import gi
-import os
-
 gi.require_version('Gtk', '3.0')
 from gi.repository import Gtk
 from dsst_gtk3.handlers import handlers
 from dsst_gtk3 import util
-
 from dsst_sql import sql, sql_func
 
 
 class GtkUi:
     """ The main UI class """
-
     def __init__(self):
         # Load Glade UI files
         self.ui = Gtk.Builder()
@@ -26,13 +22,16 @@ class GtkUi:
         self.ui.connect_signals(self.handlers)
         # Show all widgets
         self.ui.get_object('main_window').show_all()
+        # Initialize the database
+        # TODO User input to select database
+        sql.db.init('dsst', user='dsst', password='dsst')
         # Create database if not exists
-        sql.create_tables()
+        sql_func.create_tables()
 
         self.reload_base_data()
-        self.reload_seasons()
 
     def reload_base_data(self):
+        """Reload function for all base data witch is not dependant on selected season or episode"""
         # Rebuild all players store
         self.ui.get_object('all_players_store').clear()
         for player in sql.Player.select():
@@ -41,8 +40,6 @@ class GtkUi:
         self.ui.get_object('drink_store').clear()
         for drink in sql.Drink.select():
             self.ui.get_object('drink_store').append([drink.id, drink.name, str(drink.vol)])
-
-    def reload_seasons(self):
         # Rebuild seasons store
         store = self.ui.get_object('seasons_store')
         store.clear()
@@ -51,6 +48,7 @@ class GtkUi:
 
     # Reload after season was changed ##################################################################################
     def reload_for_season(self):
+        """Reload all data that is dependant on a selected season"""
         season_id = self.get_selected_season_id()
         if season_id is None or season_id == -1:
             return
@@ -82,6 +80,7 @@ class GtkUi:
 
     # Reload after episode was changed #################################################################################
     def reload_for_episode(self):
+        """Reload all data that is dependant on a selected episode"""
         episode_id = self.get_selected_episode_id()
         if not episode_id:
             return
@@ -90,11 +89,17 @@ class GtkUi:
         for player in sql.Episode.get(sql.Episode.id == self.get_selected_episode_id()).players:
             store.append([player.id, player.name, player.hex_id])
 
-    def get_selected_season_id(self):
+    def get_selected_season_id(self) -> int:
+        """Read ID of the selected season from the UI
+        :return: ID of the selected season
+        """
         season_id = util.Util.get_combo_value(self.ui.get_object('season_combo_box'), 0)
         return season_id if season_id != -1 else None
 
     def get_selected_episode_id(self):
+        """Parse ID of the selected episode from the UI
+        :return: ID of the selected episode
+        """
         (model, tree_iter) = self.ui.get_object('episodes_tree_view').get_selection().get_selected()
         return model.get_value(tree_iter, 0) if tree_iter else None
 

dsst/dsst_gtk3/handlers/base_data_handlers.py

@@ -2,7 +2,8 @@ from dsst_gtk3 import dialogs, gtk_ui
 from dsst_sql import sql
 
 
-class PlayerHandlers:
+class BaseDataHandlers:
+    """Callback handlers for signals related to the manipulation of base data (players, drinks, ...)"""
     def __init__(self, app: 'gtk_ui.GtkUi'):
         self.app = app
 

dsst/dsst_gtk3/handlers/death_handlers.py

@@ -1,7 +1,8 @@
 from dsst_gtk3 import dialogs, gtk_ui
 
 
-class CenterHandlers:
+class DeathHandlers:
+    """Callback handlers for signals related to managing death events"""
     def __init__(self, app: 'gtk_ui.GtkUi'):
         self.app = app
 

dsst/dsst_gtk3/handlers/dialog_handlers.py

@@ -3,6 +3,7 @@ from dsst_sql import sql
 
 
 class DialogHandlers:
+    """ Callback handlers for signals emitted from dialogs of the main window"""
     def __init__(self, app: 'gtk_ui.GtkUi'):
         self.app = app
 

dsst/dsst_gtk3/handlers/handlers.py

@@ -1,26 +1,25 @@
 import gi
+import sql_func
 gi.require_version('Gtk', '3.0')
 from gi.repository import Gtk
-from dsst_gtk3.handlers.left_column_handlers import LeftColumnHandlers
-from dsst_gtk3.handlers.players import PlayerHandlers
+from dsst_gtk3.handlers.season_handlers import SeasonHandlers
+from dsst_gtk3.handlers.base_data_handlers import BaseDataHandlers
 from dsst_gtk3.handlers.dialog_handlers import DialogHandlers
-from dsst_gtk3.handlers.center_handlers import CenterHandlers
-
-from dsst_sql import sql
+from dsst_gtk3.handlers.death_handlers import DeathHandlers
 
 
-class Handlers(LeftColumnHandlers, PlayerHandlers, DialogHandlers, CenterHandlers):
-    """ Class containing all signal handlers for the GTK GUI """
+class Handlers(SeasonHandlers, BaseDataHandlers, DialogHandlers, DeathHandlers):
+    """Single callback handler class derived from specialized handler classes"""
     def __init__(self, app):
         """ Initialize handler class
         :param app: reference to the main application object
         """
         self.app = app
         # Call constructors of superclasses
-        LeftColumnHandlers.__init__(self, app)
-        PlayerHandlers.__init__(self, app)
+        SeasonHandlers.__init__(self, app)
+        BaseDataHandlers.__init__(self, app)
         DialogHandlers.__init__(self, app)
-        CenterHandlers.__init__(self, app)
+        DeathHandlers.__init__(self, app)
 
     @staticmethod
     def do_delete_event(*args):
@@ -33,5 +32,5 @@ class Handlers(LeftColumnHandlers, PlayerHandlers, DialogHandlers, CenterHandler
 
     @staticmethod
     def do_delete_database(*_):
-        sql.drop_tables()
-        sql.create_tables()
+        sql_func.drop_tables()
+        sql_func.create_tables()

dsst/dsst_gtk3/handlers/season_handlers.py

@@ -2,7 +2,8 @@ from dsst_sql import sql
 from dsst_gtk3 import dialogs, gtk_ui
 
 
-class LeftColumnHandlers:
+class SeasonHandlers:
+    """Callback handlers related to signals for managing seasonal data"""
     def __init__(self, app: 'gtk_ui.GtkUi'):
         self.app = app
 

dsst/dsst_gtk3/util.py

@@ -1,3 +1,7 @@
+"""
+This modules contains general utilities for the GTK application to use.
+"""
+
 import os
 from zipfile import ZipFile
 
@@ -5,7 +9,11 @@ from zipfile import ZipFile
 class Util:
     @staticmethod
     def get_combo_value(combo, index: int):
-        """ Retrieve the selected value of a combo box at the selected index in the model """
+        """ Retrieve the selected value of a combo box at the selected index in the model
+        :param combo: Any Gtk Widget that supports 'get_active_iter()'
+        :param index: Index of the value in the widgets model to be retrieved
+        :return: The value of the model at the selected index (Default -1)
+        """
         tree_iter = combo.get_active_iter()
         if tree_iter:
             return combo.get_model().get_value(tree_iter, index)
@@ -13,8 +21,14 @@ class Util:
             return -1
 
     @staticmethod
-    def get_index_of_combo_model(combo, column: int, value: int):
-        model = combo.get_model()
+    def get_index_of_combo_model(widget, column: int, value: int):
+        """Get the index of a value within a Gtk widgets model based on column an value
+        :param widget: Any Gtk widget that can be bound to a ListStore or TreeStore
+        :param column: Column in the model where to look for the value
+        :param value: Value to look for in the model
+        :return: List of the indexes where the value occurs
+        """
+        model = widget.get_model()
         return [model.index(entry) for entry in model if entry[column] == value]
 
     @staticmethod