[ruff] Add flake8-annotations rules

Author: Galarzaa90

pyproject.toml

@@ -202,6 +202,8 @@ select = [
     "PERF",
     # Ruff-specific rules
     "RUF",
+    # flake8-annotations
+    "ANN",
 
 ]
 ignore = [
@@ -218,7 +220,15 @@ ignore = [
     # Mutable class attributes should be annotated with `typing.ClassVar`
     "RUF012",
     # PEP 484 prohibits implicit `Optional`
-    "RUF013"
+    "RUF013",
+    # Missing type annotation for {name} in method
+    "ANN101",
+    # Missing type annotation for {name} in classmethod
+    "ANN102",
+    # Missing return type annotation for private function {name}
+    "ANN202",
+    # Missing return type annotation for special method {name}
+    "ANN204",
 ]
 
 

tibiapy/builders/highscores.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from typing import List, TYPE_CHECKING
+from typing import List, Set, TYPE_CHECKING
 
 from tibiapy.models import Highscores
 
@@ -42,7 +42,7 @@ def battleye_filter(self, battleye_filter: HighscoresBattlEyeType) -> Self:
         self._battleye_filter = battleye_filter
         return self
 
-    def pvp_types_filter(self, pvp_types_filter: PvpTypeFilter) -> Self:
+    def pvp_types_filter(self, pvp_types_filter: Set[PvpTypeFilter]) -> Self:
         self._pvp_types_filter = pvp_types_filter
         return self
 

tibiapy/parsers/character.py

@@ -209,7 +209,7 @@ def _parse_house_column(cls, builder: CharacterBuilder, column: bs4.Tag):
         house_link = parse_link_info(house_link_tag)
         builder.add_house(
             CharacterHouse(
-                id=house_link["query"]["houseid"],
+                id=int(house_link["query"]["houseid"]),
                 name=house_link["text"],
                 town=house_link["query"]["town"],
                 paid_until=paid_until_date,

tibiapy/parsers/highscores.py

@@ -4,7 +4,9 @@
 import datetime
 import re
 from collections import OrderedDict
-from typing import Optional, TYPE_CHECKING
+from typing import Dict, Optional, TYPE_CHECKING
+
+import bs4
 
 from tibiapy.builders.highscores import HighscoresBuilder
 from tibiapy.enums import HighscoresBattlEyeType, HighscoresCategory, HighscoresProfession, PvpTypeFilter
@@ -34,7 +36,7 @@ def from_content(cls, content: str) -> Optional[Highscores]:
 
         Notes
         -----
-        Tibia.com only shows up to 50 entries per page, so in order to obtain the full highscores, all pages must be
+        Tibia.com only shows up to 50 entries per page, so to obtain the full highscores, all pages must be
         obtained individually and merged into one.
 
         Parameters
@@ -73,7 +75,7 @@ def from_content(cls, content: str) -> Optional[Highscores]:
 
     # region Private methods
     @classmethod
-    def _parse_entries_table(cls, builder: HighscoresBuilder, table):
+    def _parse_entries_table(cls, builder: HighscoresBuilder, table: bs4.Tag) -> None:
         """Parse the table containing the highscore entries.
 
         Parameters
@@ -100,7 +102,7 @@ def _parse_entries_table(cls, builder: HighscoresBuilder, table):
             cls._parse_entry(builder, cols_raw)
 
     @classmethod
-    def _parse_filters_table(cls, builder, form):
+    def _parse_filters_table(cls, builder: HighscoresBuilder, form: bs4.Tag) -> None:
         """Parse the filters table found in a highscores page.
 
         Parameters
@@ -120,7 +122,7 @@ def _parse_filters_table(cls, builder, form):
         builder.available_worlds([v for v in data.available_options["world"].values() if v])
 
     @classmethod
-    def _parse_tables(cls, parsed_content):
+    def _parse_tables(cls, parsed_content: bs4.BeautifulSoup) -> Dict[str, bs4.Tag]:
         """Parse the information tables found in a highscores page.
 
         Parameters
@@ -145,7 +147,7 @@ def _parse_tables(cls, parsed_content):
         return output
 
     @classmethod
-    def _parse_entry(cls, builder, cols):
+    def _parse_entry(cls, builder: HighscoresBuilder, cols: bs4.ResultSet) -> None:
         """Parse an entry's row and adds the result to py:attr:`entries`.
 
         Parameters

tibiapy/urls.py

@@ -3,7 +3,7 @@
 
 import datetime
 import urllib.parse
-from typing import Optional, Set, TYPE_CHECKING
+from typing import Optional, Set, TYPE_CHECKING, Tuple, Union
 
 if TYPE_CHECKING:
     from tibiapy.enums import (BazaarType, HighscoresBattlEyeType, HighscoresCategory, HighscoresProfession, HouseOrder,
@@ -12,22 +12,29 @@
     from tibiapy.models import AuctionFilters
 
 
-def get_tibia_url(section, subtopic=None, *args, anchor=None, test=False, **kwargs):
+def get_tibia_url(
+        section: str,
+        subtopic: str = None,
+        *args: Tuple[str, Union[str, int]],
+        anchor: str = None,
+        test: bool = False,
+        **kwargs: Union[str, int],
+) -> str:
     """Build a URL to Tibia.com with the given parameters.
 
     Parameters
     ----------
     section: :class:`str`
-        The desired section (e.g. community, abouttibia, manual, library)
+        The desired section (e.g., community, abouttibia, manual, library)
     subtopic: :class:`str`, optional
-        The desired subtopic (e.g. characters, guilds, houses, etc)
+        The desired subtopic (e.g., characters, guilds, houses, etc.)
     anchor: :class:`str`
         A link anchor to add to the link.
     args:
         A list of key-value pairs to add as query parameters.
         This allows passing multiple parameters with the same name.
     kwargs:
-        Additional parameters to pass to the url as query parameters (e.g name, world, houseid, etc)
+        Additional parameters to pass to the url as query parameters (e.g., name, world, houseid, etc.)
     test: :class:`bool`
         Whether to use the test website or not.
 
@@ -58,7 +65,7 @@ def get_tibia_url(section, subtopic=None, *args, anchor=None, test=False, **kwar
             if value is None:
                 continue
 
-            params[key] = value
+            params[key] = str(value)
 
     url += urllib.parse.urlencode(params)
     if args:
@@ -104,7 +111,7 @@ def get_character_url(name: str) -> str:
 
 
 def get_world_guilds_url(world: str) -> str:
-    """Get the URL to guild list of a specific world.
+    """Get the URL to the guild list of a specific world.
 
     Parameters
     ----------
@@ -146,7 +153,7 @@ def get_guild_wars_url(name: str) -> str:
     Returns
     -------
     :class:`str`
-        The URL to the guild's wars page.
+        The URL to the guild's wars' page.
     """
     return get_tibia_url("community", "guilds", page="guildwars", action="view", GuildName=name)
 
@@ -260,7 +267,7 @@ def get_forum_section_url_by_name(section_name: str) -> str:
     return get_tibia_url("forum", section_name)
 
 
-def get_world_boards_url():
+def get_world_boards_url() -> str:
     """Get the URL to the World Boards section in Tibia.com.
 
     Returns
@@ -271,7 +278,7 @@ def get_world_boards_url():
     return get_tibia_url("forum", "worldboards")
 
 
-def get_trade_boards_url():
+def get_trade_boards_url() -> str:
     """Get the URL to the Trade Boards section in Tibia.com.
 
     Returns
@@ -282,7 +289,7 @@ def get_trade_boards_url():
     return get_tibia_url("forum", "tradeboards")
 
 
-def get_community_boards_url():
+def get_community_boards_url() -> str:
     """Get the URL to the Community Boards section in Tibia.com.
 
     Returns
@@ -293,7 +300,7 @@ def get_community_boards_url():
     return get_tibia_url("forum", "communityboards")
 
 
-def get_support_boards_url():
+def get_support_boards_url() -> str:
     """Get the URL to the Support Boards section in Tibia.com.
 
     Returns
@@ -360,7 +367,7 @@ def get_forum_thread_url(thread_id: int, page: int = 1) -> str:
     return get_tibia_url("forum", None, action="thread", threadid=thread_id, pagenumber=page)
 
 
-def get_forum_post_url(post_id):
+def get_forum_post_url(post_id: int) -> str:
     """Get the URL to a specific post.
 
     Parameters
@@ -380,7 +387,7 @@ def get_highscores_url(
         world: str = None,
         category: HighscoresCategory = None,
         vocation: HighscoresProfession = None,
-        page=1,
+        page: int = 1,
         battleye_type: HighscoresBattlEyeType = None,
         pvp_types: Set[PvpTypeFilter] = None,
 ) -> str:
@@ -485,7 +492,7 @@ def get_houses_section_url(world: str, town: str, house_type: HouseType, status:
     return get_tibia_url("community", "houses", **{k: v for k, v in params.items() if v is not None})
 
 
-def get_auction_url(auction_id: int):
+def get_auction_url(auction_id: int) -> str:
     """Get the URL to the Tibia.com detail page of an auction with a given id.
 
     Parameters
@@ -501,7 +508,7 @@ def get_auction_url(auction_id: int):
     return get_tibia_url("charactertrade", "currentcharactertrades", page="details", auctionid=auction_id)
 
 
-def get_bazaar_url(type: BazaarType, page: int = 1, filters: AuctionFilters = None):
+def get_bazaar_url(type: BazaarType, page: int = 1, filters: AuctionFilters = None) -> str:
     """Get the URL to the list of current auctions in Tibia.com.
 
     Parameters
@@ -522,7 +529,7 @@ def get_bazaar_url(type: BazaarType, page: int = 1, filters: AuctionFilters = No
     return get_tibia_url("charactertrade", type.subtopic, currentpage=page, **query_params)
 
 
-def get_cm_post_archive_url(from_date: datetime.date, to_date: datetime.date, page=1):
+def get_cm_post_archive_url(from_date: datetime.date, to_date: datetime.date, page: int = 1) -> str:
     """Get the URL to the CM Post Archive for the given date range.
 
     Parameters
@@ -629,7 +636,7 @@ def get_boostable_bosses_url() -> str:
     return get_tibia_url("library", "boostablebosses")
 
 
-def _to_yes_no(value: Optional[bool]):
+def _to_yes_no(value: Optional[bool]) -> Optional[str]:
     if value is None:
         return None
 
@@ -642,7 +649,7 @@ def get_spells_section_url(
         spell_type: SpellType = None,
         is_premium: bool = None,
         sort: SpellSorting = None,
-):
+) -> str:
     """Get the URL to the spells section with the desired filtering parameters.
 
     Parameters

tibiapy/utils.py

@@ -5,7 +5,7 @@
 import re
 import urllib.parse
 from collections import defaultdict
-from typing import Any, Callable, Dict, Iterable, List, Optional, Tuple, Type, TypeVar, Union
+from typing import Any, Callable, Dict, Iterable, List, Optional, Tuple, Type, TypeVar, TypedDict, Union
 
 import bs4
 from pydantic import BaseModel
@@ -54,7 +54,7 @@ def clean_text(tag: Union[bs4.PageElement, str]) -> str:
     return text.replace("\xa0", " ").strip()
 
 
-def convert_line_breaks(element: bs4.Tag):
+def convert_line_breaks(element: bs4.Tag) -> None:
     """Convert the <br> tags in a HTML elements to actual line breaks.
 
     Parameters
@@ -133,7 +133,7 @@ def parse_form_data(form: bs4.Tag) -> FormData:
     return form_data
 
 
-def parse_integer(number: str, default: Optional[int] = 0):
+def parse_integer(number: str, default: Optional[int] = 0) -> int:
     """Parse a string representing an integer, ignoring commas or periods.
 
     Parameters
@@ -159,7 +159,15 @@ def parse_integer(number: str, default: Optional[int] = 0):
         return default
 
 
-def parse_link_info(link_tag: bs4.Tag):
+class LinkInfo(TypedDict):
+    """Represent the dictionary containing link information."""
+
+    text: str
+    url: str
+    query: Dict[str, Union[List[str], str]]
+
+
+def parse_link_info(link_tag: bs4.Tag) -> LinkInfo:
     """Parse the information of a link tag.
 
     It will parse the link's content, target URL as well as the query parameters where applicable.
@@ -509,7 +517,7 @@ def parse_tibiacom_tables(parsed_content: bs4.BeautifulSoup) -> Dict[str, bs4.Ta
     return tables
 
 
-def try_enum(cls: Type[T], val: Any, default: D = None) -> Union[T, D]:
+def try_enum(cls: Type[T], val: Any, default: D = None) -> Union[T, D]:  # noqa: ANN401
     """Attempt to convert a value into their enum value.
 
     Parameters