diff --git a/classes/pycord_event.py b/classes/pycord_event.py index 19c99d4..b272a4c 100644 --- a/classes/pycord_event.py +++ b/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. diff --git a/classes/pycord_event_stage.py b/classes/pycord_event_stage.py index a3820cd..95ee2a9 100644 --- a/classes/pycord_event_stage.py +++ b/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 - cache (:obj:`Cache`, optional): Cache engine to get the cache from + stage_id (str | ObjectId): ID of the event stage to look up. + 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, - ): - await self._remove(cache, *args) + ) -> None: + """Remove attribute(s) on the object, replace them with a default value and save the updated entry into the database. + + 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. diff --git a/classes/pycord_guild.py b/classes/pycord_guild.py index 611d17d..87b3854 100644 --- a/classes/pycord_guild.py +++ b/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 - allow_creation (:obj:`bool`, optional): Create new guild record if none found in the database - cache (:obj:`Cache`, optional): Cache engine to get the cache from + guild_id (int): ID of the guild to look up. + allow_creation (:obj:`bool`, optional): Create a new record if none found in the database. + 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, - ): - await self._remove(cache, *args) + ) -> None: + """Remove attribute(s) on the object, replace them with a default value and save the updated entry into the database. + + 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")