GH-29: Adding pylint config and initial progress on pylint fixes for the pygame_gui package. Deleted unused pygame_gui.Cursor element.

Author: ben-ryder

.pylintrc

@@ -0,0 +1,7 @@
+[MASTER]
+
+# Custom pylint overrides for the project
+disable=
+    too-many-arguments,
+    too-many-instance-attributes,
+    too-few-public-methods

pygame_gui/__init__.py

@@ -1,8 +1,20 @@
+"""
+A custom set of general UI elements.
+
+Classes:
+    Text
+    Image
+    Button
+    Checkbox
+    Entry
+    Panel
+    TextButton
+"""
+
 from pygame_gui.text import *
 from pygame_gui.image import *
 from pygame_gui.button import *
 from pygame_gui.checkbox import *
 from pygame_gui.entry import *
-from pygame_gui.cursor import *
 from pygame_gui.panel import *
 from pygame_gui.text_button import *

pygame_gui/button.py

@@ -1,9 +1,25 @@
+"""
+A module holding the pygame_gui Button class.
+
+Classes:
+    Button
+"""
+
 import pygame
 import pygame_gui.image
 
 
 class Button:
+    """ The Button class which changes display when hovered and runs a function when clicked. """
     def __init__(self, rest_image, hover_image, x, y):
+        """
+        Parameters:
+            rest_image - The default image which is used for the button.
+            hover_image - The image to use when the button is being hovered over.
+            x - The x position to use for the button, in px.
+            y - The y position to use for the button, in px
+        """
+
         self.rest_image = pygame_gui.Image(rest_image, x, y)
         self.hover_image = pygame_gui.Image(hover_image, x, y)
         self.rect = self.rest_image.image.get_rect()
@@ -12,21 +28,43 @@ def __init__(self, rest_image, hover_image, x, y):
         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 Button.mouse_over to determine if the mouse is within the button's area.
+        If the mouse is within the button then Button.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):
+        """
+        Draws the button to the given pygame display.
+
+        Parameters:
+            display - A pygame.display instance.
+        """
+
         if self.mouse_over():
             self.hover_image.draw(display)
         else:

pygame_gui/checkbox.py

@@ -1,9 +1,27 @@
+"""
+A module holding the pygame_gui Checkbox class.
+
+Classes:
+    Checkbox
+"""
+
 import pygame
 import pygame_gui.image
 
 
 class Checkbox:
+    """ The Checkbox class which when clicked will toggle a Checkbox.active property. """
     def __init__(self, rest_image, hover_image, active_image, active_hover_image, x, y):
+        """
+        Parameters:
+            rest_image - The default image which is used for an in-active checkbox.
+            hover_image - The hover image to use for an in-active checkbox.
+            active_image - The image to use when the checkbox is active (checked).
+            active_hover_image - The hover image to show when the checkbox is active (checked).
+            x - The x position to use for the checkbox, in px.
+            y - The y position to use for the checkbox, in px
+        """
+
         self.rest_image = pygame_gui.Image(rest_image, x, y)
         self.hover_image = pygame_gui.Image(hover_image, x, y)
         self.active_image = pygame_gui.Image(active_image, x, y)
@@ -14,17 +32,33 @@ def __init__(self, rest_image, hover_image, active_image, active_hover_image, x,
         self.active = False
 
     def mouse_over(self):
+        """ Checks if the current mouse position is within the checkboxes area. """
+
         if self.rect.collidepoint(pygame.mouse.get_pos()):
             return True
         return False
 
     def check_clicked(self):
+        """
+        Uses Checkbox.mouse_over to determine if the mouse is within the checkboxes area.
+        If the mouse is within the checkbox then Checkbox.active will be set to not Checkbox.active.
+
+        NOTE: It is assumed that this will be run while testing a pygame.MOUSEBUTTONDOWN event.
+        """
+
         if self.mouse_over():
             self.active = not self.active
             return True
         return False
-    
+
     def draw(self, display):
+        """
+        Draws the checkbox to the given pygame display.
+
+        Parameters:
+            display - A pygame.display instance.
+        """
+
         if self.mouse_over():
             if self.active:
                 self.active_hover_image.draw(display)

pygame_gui/cursor.py

@@ -1,12 +1,34 @@
+"""
+A module holding the pygame_gui Image class.
+
+Classes:
+    Image
+"""
+
 import pygame
 
 
 class Image:
+    """ An Image class to hold and display a pygame.image instance. """
     def __init__(self, image_ref, x, y):
+        """
+        Parameters:
+            image_ref - A file path to the image to load and use.
+            x - The x position to use for the image, in px.
+            y - The y position to use for the image, in px.
+        """
+
         self.image = pygame.image.load(image_ref).convert_alpha()
         self.rect = self.image.get_rect()
         self.rect.x = x
         self.rect.y = y
 
     def draw(self, display):
+        """
+        Blit the image to the given pygame display.
+
+        Parameters:
+            display - A pygame.display instance.
+        """
+
         display.blit(self.image, self.rect.topleft)

pygame_gui/image.py

@@ -1,26 +1,65 @@
+"""
+A module holding the pygame_gui Panel class.
+
+Classes:
+    Panel
+"""
+
 import pygame
 
 
 class Panel:
+    """
+    A Panel class used to display a simple rectangle 'panel' element.
+    """
     def __init__(self, rect, transparency, colour):
+        """
+        Parameters:
+            rect - A pygame.Rect compatible declaration such as [x, y, width, height].
+            transparency - An alpha value 0 to 255 used to set the Panel opacity.
+            colour - A valid pygame colour in the form (red, green blue).
+        """
+
         self.rect = pygame.Rect(rect)
         self.colour = colour
         self.transparency = transparency
         self.surface = self.make_surface()
 
     def reset_rect(self, rect):
+        """
+        Reset the Panel.rect value using the new rect value supplied.
+
+        Parameters:
+            rect - Should be a valid pygame.Rect argument.
+        """
+
         self.rect = pygame.Rect(rect)
         self.surface = self.make_surface()
 
     def reset_width(self, width):
+        """
+        Reset the Panel.rect.width value using the new width value supplied.
+
+        Parameters:
+            width - The new width as an integer.
+        """
+
         self.rect.width = width
         self.surface = self.make_surface()
 
     def make_surface(self):
+        """ Create a surface that is used when displaying the Panel itself. """
         surface = pygame.Surface([self.rect[2], self.rect[3]])
         surface.set_alpha(self.transparency)
         return surface
 
     def draw(self, display):
+        """
+        Blit the panel surface to the given pygame display.
+
+        Arguments:
+            display - A pygame.display instance.
+        """
+
         self.surface.fill(self.colour)
         display.blit(self.surface, [self.rect[0], self.rect[1]])