Various documentation changes

- Added documentation for all methods, even private
- Added url property to Killer class.

Author: Galarzaa90

tibiapy/character.py

@@ -555,6 +555,7 @@ def by_player(self):
         """:class:`bool`: Whether the kill involves other characters."""
         return any([k.player and self.name != k.name for k in self.killers])
 
+
 class Killer:
     """
     Represents a killer.
@@ -575,6 +576,7 @@ class Killer:
         The name of the summoned creature, if applicable.
     """
     __slots__ = ("name", "player", "summon")
+
     def __init__(self, name=None, player=False, summon=None):
         self.name = name
         self.player = player
@@ -595,6 +597,14 @@ def __repr__(self):
             attributes += ",%s=%r" % (attr, v)
         return "{0.__class__.__name__}({0.name!r}{1})".format(self, attributes)
 
+    @property
+    def url(self):
+        """
+        Optional[:class:`str`]: The URL of the character’s information page on Tibia.com, if applicable.
+        """
+        return Character.get_url(self.name) if self.player else None
+
+
 class OtherCharacter(abc.Character):
     """
     Represents other character's displayed in the Character's information page.

tibiapy/guild.py

@@ -121,14 +121,16 @@ def url(self):
     def _beautiful_soup(content):
         """
         Parses HTML content into a BeautifulSoup object.
+
         Parameters
         ----------
         content: :class:`str`
             The HTML content.
 
         Returns
         -------
-        :class:`bs4.BeautifulSoup`: The parsed content.
+        :class:`bs4.BeautifulSoup`
+            The parsed content.
         """
         return bs4.BeautifulSoup(content.replace('ISO-8859-1', 'utf-8'), 'lxml',
                                  parse_only=bs4.SoupStrainer("div", class_="BoxContent"))
@@ -177,12 +179,10 @@ def _parse_current_member(guild, previous_rank, values):
         ----------
         guild: :class:`dict`[str, Any]
             Dictionary where information will be stored.
-        previous_rank
-        values
-
-        Returns
-        -------
-
+        previous_rank: :class:`dict`[int, str]
+            The last rank present in the rows.
+        values: tuple[:class:`str`]
+            A list of row contents.
         """
         rank, name, vocation, level, joined, status = values
         rank = previous_rank[1] if rank == " " else rank
@@ -205,12 +205,32 @@ def _parse_current_member(guild, previous_rank, values):
 
     @staticmethod
     def _parse_guild_applications(guild, info_container):
+        """
+        Parses the guild's application info.
+
+        Parameters
+        ----------
+        guild: :class:`dict`[str, Any]
+            Dictionary where information will be stored.
+        info_container: :class:`bs4.Tag`
+            The parsed content of the information container.
+        """
         m = applications_regex.search(info_container.text)
         if m:
             guild["open_applications"] = m.group(1) == "opened"
 
     @staticmethod
     def _parse_guild_disband_info(guild, info_container):
+        """
+        Parses the guild's disband info, if available.
+
+        Parameters
+        ----------
+        guild: :class:`dict`[str, Any]
+            Dictionary where information will be stored.
+        info_container: :class:`bs4.Tag`
+            The parsed content of the information container.
+        """
         m = disband_regex.search(info_container.text)
         if m:
             guild["disband_condition"] = m.group(2)
@@ -221,6 +241,16 @@ def _parse_guild_disband_info(guild, info_container):
 
     @staticmethod
     def _parse_guild_guildhall(guild, info_container):
+        """
+        Parses the guild's guildhall info.
+
+        Parameters
+        ----------
+        guild: :class:`dict`[str, Any]
+            Dictionary where information will be stored.
+        info_container: :class:`bs4.Tag`
+            The parsed content of the information container.
+        """
         m = guildhall_regex.search(info_container.text)
         if m:
             guild["guildhall"] = {"name": m.group("name"), "paid_until": m.group("date").replace("\xa0", " ")}
@@ -229,6 +259,16 @@ def _parse_guild_guildhall(guild, info_container):
 
     @staticmethod
     def _parse_guild_homepage(guild, info_container):
+        """
+        Parses the guild's homepage info.
+
+        Parameters
+        ----------
+        guild: :class:`dict`[str, Any]
+            Dictionary where information will be stored.
+        info_container: :class:`bs4.Tag`
+            The parsed content of the information container.
+        """
         m = homepage_regex.search(info_container.text)
         if m:
             guild["homepage"] = m.group(1)
@@ -237,6 +277,16 @@ def _parse_guild_homepage(guild, info_container):
 
     @staticmethod
     def _parse_guild_info(guild, info_container):
+        """
+        Parses the guild's general information.
+
+        Parameters
+        ----------
+        guild: :class:`dict`[str, Any]
+            Dictionary where information will be stored.
+        info_container: :class:`bs4.Tag`
+            The parsed content of the information container.
+        """
         m = founded_regex.search(info_container.text)
         if m:
             description = m.group("desc").strip()
@@ -247,6 +297,21 @@ def _parse_guild_info(guild, info_container):
 
     @staticmethod
     def _parse_guild_list(content, active_only=False):
+        """
+        Parses the contents of a world's guild list page.
+
+        Parameters
+        ----------
+        content: :class:`str`
+            The HTML content of the page.
+        active_only: :class:`bool`
+            Whether to only show active guilds.
+
+        Returns
+        -------
+        List[:class:`dict`[str, Any]]
+            A list of guild dictionaries.
+        """
         parsed_content = Guild._beautiful_soup(content)
         selected_world = parsed_content.find('option', selected=True)
         try:
@@ -284,6 +349,21 @@ def _parse_guild_list(content, active_only=False):
 
     @staticmethod
     def _parse_guild_logo(guild, parsed_content):
+        """
+        Parses the guild's logo.
+
+        Parameters
+        ----------
+        guild: :class:`dict`[str, Any]
+            Dictionary where information will be stored.
+        parsed_content: :class:`bs4.Tag`
+            The parsed content of the page.
+
+        Returns
+        -------
+        :class:`bool`
+            Whether the logo was found or not.
+        """
         logo_img = parsed_content.find('img', {'height': '64'})
         if logo_img is None:
             return False
@@ -293,25 +373,55 @@ def _parse_guild_logo(guild, parsed_content):
 
     @staticmethod
     def _parse_guild_members(guild, parsed_content):
+        """
+        Parses the guild's member and invited list.
+
+        Parameters
+        ----------
+        guild: :class:`dict`[str, Any]
+            Dictionary where information will be stored.
+        parsed_content: :class:`bs4.Tag`
+            The parsed content of the guild's page
+        """
         member_rows = parsed_content.find_all("tr", {'bgcolor': ["#D4C0A1", "#F1E0C6"]})
         guild["members"] = []
         guild["invites"] = []
         previous_rank = {}
         for row in member_rows:
             columns = row.find_all('td')
-            values = (c.text.replace("\u00a0", " ") for c in columns)
+            values = tuple(c.text.replace("\u00a0", " ") for c in columns)
             if len(columns) == COLS_GUILD_MEMBER:
                 Guild._parse_current_member(guild, previous_rank, values)
             if len(columns) == COLS_INVITED_MEMBER:
                 Guild._parse_invited_member(guild, values)
 
     @staticmethod
     def _parse_guild_name(guild, parsed_content):
+        """
+        Parses the guild's name.
+
+        Parameters
+        ----------
+        guild: :class:`dict`[str, Any]
+            Dictionary where information will be stored.
+        parsed_content: :class:`bs4.Tag`
+            The parsed content of guild's page.
+        """
         header = parsed_content.find('h1')
         guild["name"] = header.text
 
     @staticmethod
     def _parse_invited_member(guild, values):
+        """
+        Parses the column texts of an invited row into a invited dictionary.
+
+        Parameters
+        ----------
+        guild: :class:`dict`[str, Any]
+            Dictionary where information will be stored.
+        values: tuple[:class:`str`]
+            A list of row contents.
+        """
         name, date = values
         if date != "Invitation Date":
             guild["invites"].append({
@@ -329,9 +439,9 @@ def list_from_content(content, active_only=False):
 
         Parameters
         ----------
-        content: str
+        content: :class:`str`
             The html content of the page.
-        active_only: bool
+        active_only: :class:`bool`
             Whether to only show active guilds or not.
 
         Returns
@@ -346,10 +456,9 @@ def list_from_content(content, active_only=False):
     def from_content(content) -> Optional['Guild']:
         """Creates an instance of the class from the html content of the guild's page.
 
-
         Parameters
         -----------
-        content: str
+        content: :class:`str`
             The HTML content of the page.
 
         Returns
@@ -378,12 +487,12 @@ def get_url(name):
 
         Parameters
         ------------
-        name: str
+        name: :class:`str`
             The name of the guild
 
         Returns
         --------
-        str
+        :class:`str`
             The URL to the guild's page"""
         return GUILD_URL + urllib.parse.quote(name.encode('iso-8859-1'))
 
@@ -393,12 +502,12 @@ def get_world_list_url(world):
 
         Parameters
         ----------
-        world: str
+        world: :class:`str`
             The name of the world
 
         Returns
         -------
-        str
+        :class:`str`
             The URL to the guild's page
         """
         return GUILD_LIST_URL + urllib.parse.quote(world.title().encode('iso-8859-1'))
@@ -410,11 +519,11 @@ def json_list_from_content(content, active_only=False, indent=None):
 
         Parameters
         ----------
-        content: str
+        content: :class:`str`
             The html content of the page.
-        active_only: bool
+        active_only: :class:`bool`
             Whether to only show active guilds or not.
-        indent: int
+        indent: :class:`int`
             The number of spaces to indent the output with.
 
         Returns
@@ -431,15 +540,16 @@ def parse_to_json(content, indent=None):
 
         Parameters
         -------------
-        content: str
+        content: :class:`str`
             The HTML content of the page.
-        indent: int
+        indent: :class:`int`
             The number of spaces to indent the output with.
 
         Returns
         ------------
         :class:`str`
-            A string in JSON format."""
+            A string in JSON format.
+        """
         char_dict = Guild._parse(content)
         return json.dumps(char_dict, indent=indent)
 
@@ -500,8 +610,8 @@ class GuildInvite(abc.Character):
         The name of the character
 
     date: :class:`datetime.date`
-        The day when the character was invited."""
-
+        The day when the character was invited.
+    """
     __slots__ = ("date", )
 
     def __init__(self, name=None, date=None):