Documented PycordGuild and partially documented PycordEventStage (#4)

classes/pycord_event.py

@@ -317,7 +317,7 @@ class PycordEvent:
     async def update(
         self,
         cache: Optional[Cache] = None,
-        **kwargs,
+        **kwargs: Any,
     ) -> None:
         """Update attribute(s) on the object and save the updated entry into the database.
 
@@ -332,7 +332,7 @@ class PycordEvent:
 
     async def reset(
         self,
-        *args,
+        *args: str,
         cache: Optional[Cache] = None,
     ) -> None:
         """Remove attribute(s) on the object, replace them with a default value and save the updated entry into the database.

classes/pycord_event_stage.py

@@ -45,17 +45,18 @@ class PycordEventStage:
 
     @classmethod
     async def from_id(cls, stage_id: str | ObjectId, cache: Optional[Cache] = None) -> "PycordEventStage":
-        """Find event stage in the database.
+        """Find the event stage by its ID and construct PycordEventStage from database entry.
 
         Args:
-            stage_id (str | ObjectId): Stage's ID
+            stage_id (str | ObjectId): ID of the event stage to look up.
-            cache (:obj:`Cache`, optional): Cache engine to get the cache from
+            cache (:obj:`Cache`, optional): Cache engine that will be used to fetch and update the cache.
 
         Returns:
-            PycordEventStage: Event stage object
+            PycordEventStage: Object of the found event stage.
 
         Raises:
-             EventStageNotFoundError: Event stage was not found
+             EventStageNotFoundError: Event stage with such ID does not exist.
+             InvalidId: Provided event stage ID is of invalid format.
         """
         cached_entry: Dict[str, Any] | None = restore_from_cache(cls.__short_name__, stage_id, cache=cache)
 
@@ -172,13 +173,13 @@ class PycordEventStage:
         cache.delete(self._get_cache_key())
 
     def to_dict(self, json_compatible: bool = False) -> Dict[str, Any]:
-        """Convert PycordEventStage object to a JSON representation.
+        """Convert the object to a JSON representation.
 
         Args:
-            json_compatible (bool): Whether the JSON-incompatible objects like ObjectId need to be converted
+            json_compatible (bool): Whether the JSON-incompatible objects like ObjectId need to be converted.
 
         Returns:
-            Dict[str, Any]: JSON representation of PycordEventStage
+            Dict[str, Any]: JSON representation of the object.
         """
         return {
             "_id": self._id if not json_compatible else str(self._id),
@@ -192,9 +193,13 @@ class PycordEventStage:
             "media": self.media,
         }
 
-    # TODO Add documentation
     @staticmethod
     def get_defaults() -> Dict[str, Any]:
+        """Get default values for the object attributes.
+
+        Returns:
+            Dict[str, Any]: Mapping of attributes and their respective values in format `{"attribute_name:" attribute_value}`.
+        """
         return {
             "event_id": None,
             "guild_id": None,
@@ -206,29 +211,55 @@ class PycordEventStage:
             "media": [],
         }
 
-    # TODO Add documentation
     @staticmethod
     def get_default_value(key: str) -> Any:
+        """Get default value of the attribute for the object.
+
+        Args:
+            key (str): Name of the attribute.
+
+        Returns:
+            Any: Default value of the attribute.
+
+        Raises:
+            KeyError: There's no default value for the provided attribute.
+        """
         if key not in PycordEventStage.get_defaults():
             raise KeyError(f"There's no default value for key '{key}' in PycordEventStage")
 
         return PycordEventStage.get_defaults()[key]
 
-    # TODO Add documentation
     async def update(
         self,
         cache: Optional[Cache] = None,
-        **kwargs,
+        **kwargs: Any,
-    ):
+    ) -> None:
+        """Update attribute(s) on the object and save the updated entry into the database.
+
+        Args:
+            cache (:obj:`Cache`, optional): Cache engine that will be used to update the cache.
+            **kwargs (Any): Mapping of attributes in format `attribute_name=attribute_value` to update.
+
+        Raises:
+            AttributeError: Provided attribute does not exist in the class.
+        """
         await self._set(cache=cache, **kwargs)
 
-    # TODO Add documentation
     async def reset(
         self,
+        *args: str,
         cache: Optional[Cache] = None,
-        *args,
+    ) -> None:
-    ):
+        """Remove attribute(s) on the object, replace them with a default value and save the updated entry into the database.
-        await self._remove(cache, *args)
+
+        Args:
+            *args (str): List of attributes to remove.
+            cache (:obj:`Cache`, optional): Cache engine that will be used to update the cache.
+
+        Raises:
+            AttributeError: Provided attribute does not exist in the class.
+        """
+        await self._remove(*args, cache=cache)
 
     async def purge(self, cache: Optional[Cache] = None) -> None:
         """Completely remove event stage data from database. Currently only removes the event stage record from events collection.

classes/pycord_guild.py

@@ -32,18 +32,18 @@ class PycordGuild:
     async def from_id(
         cls, guild_id: int, allow_creation: bool = True, cache: Optional[Cache] = None
     ) -> "PycordGuild":
-        """Find guild in database and create new record if guild does not exist.
+        """Find the guild by its ID and construct PycordEventStage from database entry.
 
         Args:
-            guild_id (int): User's Discord ID
+            guild_id (int): ID of the guild to look up.
-            allow_creation (:obj:`bool`, optional): Create new guild record if none found in the database
+            allow_creation (:obj:`bool`, optional): Create a new record if none found in the database.
-            cache (:obj:`Cache`, optional): Cache engine to get the cache from
+            cache (:obj:`Cache`, optional): Cache engine that will be used to fetch and update the cache.
 
         Returns:
-            PycordGuild: User object
+            PycordGuild: Object of the found or newly created guild.
 
         Raises:
-             GuildNotFoundError: User was not found and creation was not allowed
+             GuildNotFoundError: Guild with such ID does not exist and creation was not allowed.
         """
         cached_entry: Dict[str, Any] | None = restore_from_cache(cls.__short_name__, guild_id, cache=cache)
 
@@ -68,12 +68,6 @@ class PycordGuild:
         return cls(**db_entry)
 
     async def _set(self, cache: Optional[Cache] = None, **kwargs: Any) -> None:
-        """Set attribute data and save it into the database.
-
-        Args:
-            cache (:obj:`Cache`, optional): Cache engine to write the update into
-            **kwargs (Any): Mapping of attribute names and respective values to be set
-        """
         for key, value in kwargs.items():
             if not hasattr(self, key):
                 raise AttributeError()
@@ -87,12 +81,6 @@ class PycordGuild:
         logger.info("Set attributes of guild %s to %s", self.id, kwargs)
 
     async def _remove(self, *args: str, cache: Optional[Cache] = None) -> None:
-        """Remove attribute data and save it into the database.
-
-        Args:
-            cache (:obj:`Cache`, optional): Cache engine to write the update into
-            *args (str): List of attributes to remove
-        """
         attributes: Dict[str, Any] = {}
 
         for key in args:
@@ -132,13 +120,13 @@ class PycordGuild:
         cache.delete(self._get_cache_key())
 
     def to_dict(self, json_compatible: bool = False) -> Dict[str, Any]:
-        """Convert PycordGuild object to a JSON representation.
+        """Convert the object to a JSON representation.
 
         Args:
-            json_compatible (bool): Whether the JSON-incompatible objects like ObjectId need to be converted
+            json_compatible (bool): Whether the JSON-incompatible objects like ObjectId need to be converted.
 
         Returns:
-            Dict[str, Any]: JSON representation of PycordGuild
+            Dict[str, Any]: JSON representation of the object.
         """
         return {
             "_id": self._id if not json_compatible else str(self._id),
@@ -149,9 +137,13 @@ class PycordGuild:
             "prefer_emojis": self.prefer_emojis,
         }
 
-    # TODO Add documentation
     @staticmethod
     def get_defaults(guild_id: Optional[int] = None) -> Dict[str, Any]:
+        """Get default values for the object attributes.
+
+        Returns:
+            Dict[str, Any]: Mapping of attributes and their respective values in format `{"attribute_name:" attribute_value}`.
+        """
         return {
             "id": guild_id,
             "channel_id": None,
@@ -162,26 +154,53 @@ class PycordGuild:
 
     @staticmethod
     def get_default_value(key: str) -> Any:
+        """Get default value of the attribute for the object.
+
+        Args:
+            key (str): Name of the attribute.
+
+        Returns:
+            Any: Default value of the attribute.
+
+        Raises:
+            KeyError: There's no default value for the provided attribute.
+        """
         if key not in PycordGuild.get_defaults():
             raise KeyError(f"There's no default value for key '{key}' in PycordGuild")
 
         return PycordGuild.get_defaults()[key]
 
-    # TODO Add documentation
     async def update(
         self,
         cache: Optional[Cache] = None,
-        **kwargs,
+        **kwargs: Any,
-    ):
+    ) -> None:
+        """Update attribute(s) on the object and save the updated entry into the database.
+
+        Args:
+            cache (:obj:`Cache`, optional): Cache engine that will be used to update the cache.
+            **kwargs (Any): Mapping of attributes in format `attribute_name=attribute_value` to update.
+
+        Raises:
+            AttributeError: Provided attribute does not exist in the class.
+        """
         await self._set(cache=cache, **kwargs)
 
-    # TODO Add documentation
     async def reset(
         self,
+        *args: str,
         cache: Optional[Cache] = None,
-        *args,
+    ) -> None:
-    ):
+        """Remove attribute(s) on the object, replace them with a default value and save the updated entry into the database.
-        await self._remove(cache, *args)
+
+        Args:
+            *args (str): List of attributes to remove.
+            cache (:obj:`Cache`, optional): Cache engine that will be used to update the cache.
+
+        Raises:
+            AttributeError: Provided attribute does not exist in the class.
+        """
+        await self._remove(*args, cache=cache)
 
     async def purge(self, cache: Optional[Cache] = None) -> None:
         """Completely remove guild data from database. Currently only removes the guild record from guilds collection.
@@ -195,35 +214,16 @@ class PycordGuild:
 
         logger.info("Purged guild %s (%s) from the database", self.id, self._id)
 
-    # TODO Add documentation
     def is_configured(self) -> bool:
+        """Return whether all attributes required for bot's use on the server are set.
+
+        Returns:
+            bool: `True` if yes and `False` if not.
+        """
         return (
             (self.id is not None)
             and (self.channel_id is not None)
             and (self.category_id is not None)
             and (self.timezone is not None)
+            and (self.prefer_emojis is not None)
         )
-
-    # TODO Add documentation
-    async def set_channel(self, channel_id: Optional[int] = None, cache: Optional[Cache] = None) -> None:
-        await self._set(cache, channel_id=channel_id)
-
-    # TODO Add documentation
-    async def reset_channel(self, cache: Optional[Cache] = None) -> None:
-        await self._remove(cache, "channel_id")
-
-    # TODO Add documentation
-    async def set_category(self, category_id: Optional[int] = None, cache: Optional[Cache] = None) -> None:
-        await self._set(cache, category_id=category_id)
-
-    # TODO Add documentation
-    async def reset_category(self, cache: Optional[Cache] = None) -> None:
-        await self._remove(cache, "category_id")
-
-    # TODO Add documentation
-    async def set_timezone(self, timezone: str, cache: Optional[Cache] = None) -> None:
-        await self._set(cache, timezone=timezone)
-
-    # TODO Add documentation
-    async def reset_timezone(self, cache: Optional[Cache] = None) -> None:
-        await self._remove(cache, "timezone")