From 03551d55e935c6a615796a4e60a6cdb76be5c45a Mon Sep 17 00:00:00 2001
From: Corban-Lee Jones <corbz.jones@gmail.com>
Date: Tue, 9 Jul 2024 23:17:58 +0100
Subject: [PATCH] RSSItem documentation

---
 src/feed.py | 74 ++++++++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 65 insertions(+), 9 deletions(-)

diff --git a/src/feed.py b/src/feed.py
index 65fabc6..9fcbfa1 100644
--- a/src/feed.py
+++ b/src/feed.py
@@ -1,3 +1,4 @@
+from __future__ import annotations
 
 import json
 import copy
@@ -10,13 +11,11 @@ import aiohttp
 import validators
 from discord import Embed, Colour
 from bs4 import BeautifulSoup as bs4
-from feedparser import FeedParserDict, parse
+from feedparser import FeedParserDict
 from markdownify import markdownify
 from textwrap import shorten
-from feedparser import parse
 
 from mutators import registry as mutator_registry
-from utils import get_unparsed_feed
 from api import API
 
 log = logging.getLogger(__name__)
@@ -25,6 +24,7 @@ dumps = lambda _dict: json.dumps(_dict, indent=8)
 
 @dataclass(slots=True)
 class RSSItem:
+    """Represents an entry from an RSS feed item list."""
 
     guid: str
     link: str
@@ -34,7 +34,19 @@ class RSSItem:
     image_url: str
 
     @classmethod
-    def from_parsed_entry(cls, entry):
+    def from_parsed_entry(cls, entry: FeedParserDict) -> RSSItem:
+        """Returns an instance of `RSSItem` from a given `FeedParserDict`.
+
+        Parameters
+        ----------
+        entry: FeedParserDict
+            The represented entry.
+
+        Returns
+        -------
+        RSSItem
+        """
+
         guid = entry.get('id', None) or entry.get("guid", None)
         link = entry.get('link', None)
         title = entry.get('title', None)
@@ -47,15 +59,42 @@ class RSSItem:
 
         return cls(guid, link, title, description, pub_date, image_url)
 
-    def create_mutated_copy(self, mutators):
+    def create_mutated_copy(self, mutators: dict[str, dict[str, str]]) -> RSSItem:
+        """Returns a copy of `self` with the specified `mutations`.
+
+        Parameters
+        ----------
+        mutators: dict[str, dict[str, str]]
+            Mutations to apply on the copy.
+
+        Returns
+        -------
+        RSSItem
+            The copy of self.
+        """
+
         item_copy = copy.copy(self)
 
-        def apply_mutation(item, attr: str, mutator: dict[str, str]):
-            val = mutator["value"]
+        def apply_mutation(item: RSSItem, attr: str, mutator: dict[str, str]):
+            """Applies a specified `mutator` on the given `item`'s `attr`.
+
+            Parameters
+            ----------
+            item: RSSItem
+                An RSSItem to mutate.
+
+            attr: str
+                The attribute of the RSSItem to mutate.
+
+            mutator: dict[str, str]
+                The mutator to apply.
+            """
+            
             try:
-                mutator = mutator_registry.get_mutator(val)
+                mutator = mutator_registry.get_mutator(mutator["value"])
             except ValueError as err:
                 log.error(err)
+                return  # mutator couldn't be found, so early return
 
             setattr(item, attr, mutator.mutate(getattr(item, attr)))
 
@@ -65,7 +104,24 @@ class RSSItem:
 
         return item_copy
 
-    async def to_embed(self, sub, feed, session):
+    async def to_embed(self, sub: Subscription, feed: RSSFeed, session: aiohttp.ClientSession) -> Embed:
+        """Creates and returns a Discord Embed for this instance.
+
+        Parameters
+        ----------
+        sub: Subscription
+            The subscription that this RSSItem derived from.
+
+        feed: RSSFeed
+            The feed containing this RSSItem in its entries.
+
+        session: aiohttp.ClientSession
+            A client session used to fetch thumbnail url if set.
+
+        Returns
+        -------
+        discord.Embed
+        """
 
         # Replace HTML with Markdown, and shorten text.
         title = shorten(markdownify(self.title, strip=["img", "a"]), 256)