simplify class docstring formatting

castero/config.py

@@ -21,7 +21,7 @@ class ConfigDuplicateError(ConfigError):
 
 
 class _Config(DataFile):
-    """The Config class.
+    """The user's config settings.
 
     Reads the configuration file. Instances of this class can generally be
     treated like dictionaries, accessing a variable with config_instance[key].
@@ -33,7 +33,8 @@ class _Config(DataFile):
     DEFAULT_PATH = os.path.join(DataFile.PACKAGE, 'templates/castero.conf')
 
     def __init__(self) -> None:
-        """Initializes the object.
+        """
+        Note: the config class is a singleton.
         """
         super().__init__(self.PATH, self.DEFAULT_PATH)
 

castero/database.py

@@ -12,7 +12,7 @@ from castero.queue import Queue
 
 
 class Database():
-    """The Database class.
+    """The user's database.
 
     This class provides an API for storing and retrieving data from an sqlite
     database file.
@@ -28,8 +28,7 @@ class Database():
     MIGRATIONS_DIR = os.path.join(DataFile.PACKAGE, 'templates/migrations')
 
     def __init__(self):
-        """Initializes the object.
-
+        """
         If the database file does not exist but the old Feeds file does, we
         create the database using the old format.
         """

castero/datafile.py

@@ -9,7 +9,7 @@ from castero.net import Net
 
 
 class DataFile:
-    """The DataFile class.
+    """Extendable class for objects with filesystem data.
 
     Used when handling files with data that can reasonably be stored in a
     dictionary. Particularly used in the Config class and the Feeds class.
@@ -27,8 +27,7 @@ class DataFile:
     DEFAULT_DOWNLOADED_DIR = os.path.join(DATA_DIR, "downloaded")
 
     def __init__(self, path, default_path) -> None:
-        """Initializes the object.
-
+        """
         Args:
             path: the path to the data file
             default_path: the path to the default data file

castero/display.py

@@ -29,7 +29,7 @@ class DisplaySizeError(DisplayError):
 
 
 class Display:
-    """The Display class.
+    """The user-facing display.
 
     This class is used to handle all user-interaction. It creates and handles
     all aspects of the application's interface, including windows and menus. It
@@ -64,8 +64,7 @@ class Display:
     AVAILABLE_PLAYERS = {}
 
     def __init__(self, stdscr, database) -> None:
-        """Initializes the object.
-
+        """
         Args:
             stdscr: a stdscr from curses.initscr()
             database: a connected castero.Database

castero/downloadqueue.py

@@ -4,14 +4,10 @@ from castero.episode import Episode
 
 
 class DownloadQueue:
-    """The DownloadQueue class.
-
-    A FIFO ordered queue for handling episode downloads.
+    """A FIFO ordered queue for handling episode downloads.
     """
 
     def __init__(self, display=None) -> None:
-        """Initializes the object.
-        """
         self._episodes = []
         self._display = display
 

castero/episode.py

@@ -7,15 +7,12 @@ from castero.datafile import DataFile
 
 
 class Episode:
-    """The Episode class.
-
-    This class represents a single episode from a podcast feed.
+    """A single episode from a podcast feed.
     """
 
     def __init__(self, feed, ep_id=None, title=None, description=None, link=None,
                  pubdate=None, copyright=None, enclosure=None, played=False) -> None:
-        """Initializes the object.
-
+        """
         At least one of a title or description must be specified.
 
         Args:

castero/feed.py

@@ -37,7 +37,7 @@ class FeedStructureError(FeedError):
 
 
 class Feed:
-    """The Feed class.
+    """A podcast feed.
 
     This class uses a provided url to retrieve all data and metadata for a
     podcast feed. It creates and is a parent to all episode objects which are
@@ -47,8 +47,7 @@ class Feed:
     """
 
     def __init__(self, url=None, file=None, **kwargs) -> None:
-        """Initializes the object.
-
+        """
         A feed can be provided as either a url or a file, but exactly one must
         be given. Realistically, users will almost universally use a url to
         retrieve feeds from. However, having support for handling files makes

castero/menu.py

@@ -4,7 +4,7 @@ from typing import List
 
 
 class Menu(ABC):
-    """The Menu class.
+    """A navigable menu in the display.
 
     This class is used to display interactable menus. It displays a list of
     items to its window and allows the user to cycle through them.
@@ -16,8 +16,7 @@ class Menu(ABC):
 
     @abstractmethod
     def __init__(self, window, source, child=None, active=False) -> None:
-        """Initializes the object.
-
+        """
         Args:
             window: the curses.window which this menu is placed on
             items: a 2D array where rows represent indices of the parent menu

castero/net.py

@@ -3,7 +3,7 @@ import requests
 
 
 class Net:
-    """The Net class.
+    """Manager for network requests.
 
     This class provides helper methods for network requests. Generally just a
     wrapper around the requests library.

castero/perspective.py

@@ -9,7 +9,7 @@ from castero.menu import Menu
 
 
 class Perspective(ABC):
-    """The Perspective class.
+    """Extendable class for display "screens".
 
     This class is extended by perspectives -- classes which offer methods to
     handle display elements with a certain layout. Perspectives only control
@@ -27,8 +27,7 @@ class Perspective(ABC):
 
     @abstractmethod
     def __init__(self, display):
-        """Initializes the object.
-
+        """
         This method does not automatically create configure some of its
         necessary elements, i.e. the windows. Instead, for some methods it is
         expected that the Display instance will call identically-named methods

castero/perspectives/primaryperspective.py

@@ -10,7 +10,7 @@ from castero.player import Player
 
 
 class PrimaryPerspective(Perspective):
-    """The PrimaryPerspective class.
+    """The primary/default perspective.
 
     This class handles display elements while in the primary perspective, which
     is the default perspective.
@@ -18,8 +18,7 @@ class PrimaryPerspective(Perspective):
     ID = 1
 
     def __init__(self, display) -> None:
-        """Initializes the object.
-
+        """
         Overrides method from Perspective; see documentation in that class.
         """
         super().__init__(display)

castero/perspectives/queueperspective.py

@@ -8,7 +8,7 @@ from castero.perspective import Perspective
 
 
 class QueuePerspective(Perspective):
-    """The QueuePerspective class.
+    """The queue-list perspective.
 
     This class handles display elements while in the queue perspective, which
     is a listing of the user's current Queue in which they can directly modify
@@ -17,8 +17,7 @@ class QueuePerspective(Perspective):
     ID = 2
 
     def __init__(self, display) -> None:
-        """Initializes the object.
-
+        """
         Overrides method from Perspective; see documentation in that class.
         """
         super().__init__(display)

castero/perspectives/simpleperspective.py

@@ -10,7 +10,7 @@ from castero.player import Player
 
 
 class SimplePerspective(Perspective):
-    """The SimplePerspective class.
+    """The simple perspective, similar to the primary one.
 
     This class handles display elements while in the simple perspective, which
     is similar to the primary perspective but without a metadata window.
@@ -18,8 +18,7 @@ class SimplePerspective(Perspective):
     ID = 3
 
     def __init__(self, display) -> None:
-        """Initializes the object.
-
+        """
         Overrides method from Perspective; see documentation in that class.
         """
         super().__init__(display)

castero/player.py

@@ -20,15 +20,14 @@ class PlayerCreateError(PlayerError):
 
 
 class Player:
-    """The Player class.
+    """Extendable class for media players.
 
     This class is extended by players -- classes which offer methods to handle
     media operations for a specific external player (i.e. VLC, mpv).
     """
 
     def __init__(self, title, path, episode) -> None:
-        """Initializes the object.
-
+        """
         Args:
             title: the title of the media (usually an episode title)
             path: a URL or file-path of a media file (usually an audio file)

castero/players/mpvplayer.py

@@ -4,13 +4,12 @@ from castero.player import Player, PlayerDependencyError
 
 
 class MPVPlayer(Player):
-    """The MPVPlayer class.
+    """Interface for the mpv media player.
     """
     NAME = "mpv"
 
     def __init__(self, title, path, episode) -> None:
-        """Initializes the object.
-
+        """
         Overrides method from Player; see documentation in that class.
         """
         super().__init__(title, path, episode)

castero/players/vlcplayer.py

@@ -4,13 +4,12 @@ from castero.player import Player, PlayerDependencyError
 
 
 class VLCPlayer(Player):
-    """The VLCPlayer class.
+    """Interface for the vlc media player.
     """
     NAME = "vlc"
 
     def __init__(self, title, path, episode) -> None:
-        """Initializes the object.
-
+        """
         Overrides method from Player; see documentation in that class.
         """
         super().__init__(title, path, episode)

castero/queue.py

@@ -3,15 +3,13 @@ from castero.player import Player
 
 
 class Queue:
-    """The Queue class.
+    """A FIFO ordered queue of Player instances. 
 
-    A FIFO ordered queue of Player instances. This class is also the display
-    class' main interface for accessing information about the current player.
+    This class is also the display class' main interface for accessing
+    information about the current player.
     """
 
     def __init__(self, display) -> None:
-        """Initializes the object.
-        """
         self._players = []
         self._display = display
 
@@ -96,7 +94,8 @@ class Queue:
         assert direction == 1 or direction == -1
 
         if self.first is not None:
-            distance = int(Config["seek_distance_forward" if direction == 1 else "seek_distance_backward"])
+            distance = int(
+                Config["seek_distance_forward" if direction == 1 else "seek_distance_backward"])
             self.first.seek(direction, distance)
 
     def change_rate(self, direction, display=None) -> None:

castero/subscriptions.py

@@ -26,15 +26,13 @@ class SubscriptionsStructureError(SubscriptionsError):
 
 
 class Subscriptions():
-    """The Subscriptions class.
+    """The user's podcast subscriptions.
 
     Instances of this class represent a list of podcast subscriptions, which
     the user can import from (and export to) OPML-formatted documents.
     """
 
     def __init__(self) -> None:
-        """Initializes the object.
-        """
         self._tree = None
         self._feeds = []