GH-29: Finishing pylint fixes for pygame_gui package.

Author: ben-ryder

.pylintrc

@@ -4,4 +4,5 @@
 disable=
     too-many-arguments,
     too-many-instance-attributes,
-    too-few-public-methods
+    too-few-public-methods,
+    duplicate-code

pygame_gui/__init__.py

@@ -1,5 +1,5 @@
 """
-A custom set of general UI elements.
+A custom set of general UI elements that rely on external image assets for display.
 
 Classes:
     Text

pygame_gui/entry.py

@@ -1,13 +1,37 @@
+"""
+A module holding the pygame_gui Entry class.
+
+Classes:
+    Entry
+"""
+
 import pygame
 import pygame_gui.text
 import pygame_gui.image
 
 
 class Entry:
+    """ The Entry class which allows users to enter text input. """
     def __init__(self, rest_image, hover_image,
                  rest_focused_image, hover_focused_image,
                  initial_text, text_size, text_colour, text_font, text_padx, text_pady,
                  sticky, x, y):
+        """
+        Parameters:
+            rest_image - The default image which is used for the entry.
+            hover_image - The image to use when the entry is being hovered over.
+            rest_focused_image - The image to show when the entry is focused.
+            hover_focused_image - The image to show when the entry is focused and being hovered.
+            initial_text - The initial text to pre-populate the entry with.
+            text_size - The desired size of the text.
+            text_colour - The desired colour of the text, as a tuple (r, g, b).
+            text_font - The desired font for the text.
+            text_padx - The x padding that should be applied around the text.
+            text_pady - The y padding that should be applied around the text.
+            sticky - A boolean representing if text should remain when entry re-clicked.
+            x - The x position to use for the entry, in px.
+            y - The y position to use for the entry, in px
+        """
 
         self.rest_image = pygame_gui.Image(rest_image, x, y)
         self.hover_image = pygame_gui.Image(hover_image, x, y)
@@ -20,22 +44,35 @@ def __init__(self, rest_image, hover_image,
         self.text_padx = text_padx
         self.text_pady = text_pady
         self.active = False
-        self.sticky = sticky  # sticky if text should remain when entry re-clicked on.
+        self.sticky = sticky
         self.text = pygame_gui.Text(initial_text, text_size, text_colour, text_font,
                                     self.rect.x+self.text_padx, self.rect.y+self.text_pady)
-        self.backspace = False  # allows for continuous backspace. (as long as handle_event_up() is also called)
-        self.backspace_delay = 7  # READ ME!! - works as delayed by x frames, for higher frame rates increase delay.
+        # backspace allows for continuous backspace. (as long as handle_event_up() is also called)
+        self.backspace = False
+        # backspace_delay works as delayed by x frames, for higher frame rates increase delay.
+        self.backspace_delay = 7
         self.backspace_counter = 0
 
     def get_text(self):
+        """ Return the current text entered into the entry. """
+
         return self.text.text
 
     def mouse_over(self):
+        """ Checks if the current mouse position is within the entry's area. """
+
         if self.rect.collidepoint(pygame.mouse.get_pos()):
             return True
         return False
 
     def check_clicked(self):
+        """
+        Uses Entry.mouse_over to determine if the mouse is within the entry's area.
+        If it is then the entry will become active, if not the entry will deactivate.
+
+        NOTE: It is assumed that this will be run while testing a pygame.MOUSEBUTTONDOWN event.
+        """
+
         if self.mouse_over():
             self.active = True
             if not self.sticky:
@@ -45,29 +82,63 @@ def check_clicked(self):
             self.backspace = False
 
     def handle_event(self, event):
+        """
+        Handle the given KEYDOWN event. Used to process text entry.
+
+        Parameters:
+            event - A pygame.event instance of type KEYDOWN.
+
+        NOTE: It is assumed that this will be run while testing a pygame.KEYDOWN event.
+        """
+
         if self.active:
             key_uni = event.unicode
             key_str = pygame.key.name(event.key)
 
             if key_str == "backspace":
                 self.backspace = True  # deletes characters in draw()
-            elif key_str == "space" and self.text.graphic_text.get_width() < self.rect[2] - self.text_padx*3:
+            elif (
+                key_str == "space"
+                and self.text.graphic_text.get_width() < self.rect[2] - self.text_padx*3
+            ):
                 self.text.change_text(self.text.text + " ")
             else:
-                if self.text.graphic_text.get_width() < self.rect[2]-self.text_padx*3 and key_uni.isprintable():
-                    if pygame.key.get_mods() & pygame.KMOD_CAPS or pygame.key.get_mods() & pygame.KMOD_SHIFT:
+                if (
+                    self.text.graphic_text.get_width() < self.rect[2]-self.text_padx*3
+                    and key_uni.isprintable()
+                ):
+                    if (
+                        pygame.key.get_mods() & pygame.KMOD_CAPS
+                        or pygame.key.get_mods() & pygame.KMOD_SHIFT
+                    ):
                         self.text.change_text(self.text.text+key_uni.upper())
                     else:
                         self.text.change_text(self.text.text+key_uni.lower())
 
     def handle_event_up(self, event):
+        """
+        Handle the given pygame.KEYUP event. Used to detect the backspace lifting.
+
+        Parameters:
+            event - A pygame.event instance of type KEYUP.
+
+        NOTE: It is assumed that this will be run while testing a pygame.KEYUP event.
+        """
+
         if self.active:
             key_str = pygame.key.name(event.key)
 
             if key_str == "backspace":
                 self.backspace = False
 
     def draw(self, display):
+        """
+        Draws the entry to the given pygame display.
+
+        Parameters:
+            display - A pygame.display instance.
+        """
+
         # Delete character if suppose to. (done here as definitely called every game loop)
         if self.backspace:
             if self.backspace_counter >= self.backspace_delay:

pygame_gui/text.py

@@ -1,33 +1,70 @@
+"""
+A module holding the pygame_gui Text class.
+
+Classes:
+    Text
+"""
+
 import pygame
 
 
 class Text:
+    """ The Text class which can be used to create a font and display text. """
     def __init__(self, text, size, colour, font, x, y):
+        """
+        Parameters:
+            text - The text to display.
+            size - The font size to use.
+            colour - The colour to use when rendering the text.
+            font - The font to use for the text, supplied as a path to a font file.
+            x - The x position for the text, in px.
+            y - The y position for the text, in px.
+        """
+
         self.text = text
-        self.x = x
-        self.y = y
+        self.x = x  # pylint: disable=invalid-name
+        self.y = y  # pylint: disable=invalid-name
         self.size = size
         self.colour = colour
         self.font = font
         self._config_font()
         self._config_text()
 
     def _config_font(self):
+        """ Used internally to configure the required font. """
+
         try:
             self.graphic_font = pygame.font.Font(self.font, self.size)
         except OSError:  # can't read font file.
             self.graphic_font = pygame.font.SysFont(self.font, self.size)
 
     def _config_text(self):
+        """ Used internally to render the required text using the current font. """
+
         self.graphic_text = self.graphic_font.render(self.text, True, self.colour)
         self.rect = self.graphic_text.get_rect().move(self.x, self.y)
 
     def get_rect(self):
+        """ Return the rect of the current text rendered. """
+
         return self.rect
 
     def change_text(self, text):
+        """
+        Update the displayed text to the new text supplied.
+
+        Parameters:
+            text - The new text to display.
+        """
         self.text = text
         self._config_text()
 
     def draw(self, display):
+        """
+        Blit the text to the given pygame display.
+
+        Parameters:
+            display - A pygame.display instance.
+        """
+
         display.blit(self.graphic_text, [self.x, self.y])

pygame_gui/text_button.py

@@ -1,39 +1,83 @@
+"""
+A module holding the pygame_gui TextButton class.
+
+Classes:
+    TextButton
+"""
+
 import pygame
 import pygame_gui.text
 
 
 class TextButton:
-    def __init__(self, rect, start_transparency, hover_transparancy,
+    """ The TextButton which acts like the Button class but doesn't use image assets. """
+    def __init__(self, rect, start_transparency, hover_transparency,
                  text, text_size, text_color, text_font):
+        """
+        Parameters:
+            rect - A valid parameter for pygame.Rect. Determines the size & position of the button.
+            start_transparency - The initial transparency for the button.
+            hover_transparency - The transparency to give the button on hover.
+            text - The text to display within the button.
+            text_size - The size of the text.
+            text_color - The text colour to use. Given as an rgb tuple.
+            text_font - The font to use for the text, supplied as a path to a font file.
+        """
+
         self.rect = pygame.Rect(rect)
 
-        self.text = pygame_gui.Text(text, text_size, text_color, text_font, self.rect.x, self.rect.y)
+        self.text = pygame_gui.Text(
+            text, text_size, text_color, text_font,
+            self.rect.x, self.rect.y
+        )
         # Moving text to center in button
         padding_x = (self.rect.width - self.text.rect.width) / 2
         padding_y = (self.rect.height - self.text.rect.height) / 2
         self.text.x += padding_x
         self.text.y += padding_y
 
         self.panel = pygame_gui.Panel(self.rect, start_transparency, (0, 0, 0))
-        self.hover_panel = pygame_gui.Panel(self.rect, hover_transparancy, (0, 0, 0))
+        self.hover_panel = pygame_gui.Panel(self.rect, hover_transparency, (0, 0, 0))
         self.function = None
 
     def set_function(self, function):
+        """
+        Used to set the function to be run when the button is clicked.
+
+        Parameters:
+            function - Should be callable as a function.
+        """
+
         self.function = function
 
     def mouse_over(self):
+        """ Checks if the current mouse position is within the button's area. """
         if self.rect.collidepoint(pygame.mouse.get_pos()):
             return True
         return False
 
     def check_clicked(self):
+        """
+        Uses TextButton.mouse_over to determine if the mouse is within the button's area.
+        If the mouse is within the button then TextButton.function will be ran if set.
+
+        NOTE: It is assumed that this will be run while testing a pygame.MOUSEBUTTONDOWN event.
+        """
+
         if self.mouse_over():
             if self.function is not None:
                 self.function()
             return True
         return False
-    
+
     def draw(self, display):
+        """
+        Draw the text button to the given pygame display.
+
+        Parameters:
+            display - A pygame.display instance.
+        """
+
         if self.mouse_over():
             self.hover_panel.draw(display)
         else: