API Reference

This module implements a variety of classes used to hold the data parsed from Tibia.com.

These objects are generally obtained from their respective from_content methods. It is possible to create and edit these objects as desired, but it may lead to unexpected behaviour if not done properly.

Client

class tibiapy.Client(loop=None, session=None, *, proxy_url=None)

An asynchronous client that fetches information from Tibia.com.

The client uses a aiohttp.ClientSession to request the information. A single session is shared across all operations.

If desired, a custom ClientSession instance may be passed, instead of creating a new one.

New in version 2.0.0.

Changed in version 3.0.0: All methods return a TibiaResponse instance, containing additional information such as cache age.

loop

The event loop to use. The default one will be used if not defined.

Type:

asyncio.AbstractEventLoop

session

The client session that will be used for the requests. One will be created by default.

Type:

aiohttp.ClientSession

proxy_url

The URL of the SOCKS proxy to use for requests. Note that if a session is passed, the SOCKS proxy won’t be used and must be applied when creating the session.

Type:

str

async fetch_current_auctions(page=1, filters=None, *, test=False)

Fetch the current auctions in the bazaar.

New in version 3.3.0.

Parameters:

• page (int) – The desired page to display.

• filters (AuctionFilters) – The filtering criteria to use.

Returns:

The current auctions.

Return type:

TibiaResponse of CharacterBazaar

Raises:

• Forbidden – If a 403 Forbidden error was returned. This usually means that Tibia.com is rate-limiting the client because of too many requests.

• NetworkError – If there’s any connection errors during the request.

• ValueError – If the page number is not 1 or greater.

async fetch_auction_history(page=1, filters=None, *, test=False)

Fetch the auction history of the bazaar.

New in version 3.3.0.

Parameters:

• page (int) – The page to display.

• filters (AuctionFilters) – The filtering criteria to use.

• test (bool) – Whether to request the test website instead.

Returns:

The character bazaar containing the auction history.

Return type:

TibiaResponse of CharacterBazaar

Raises:

• Forbidden – If a 403 Forbidden error was returned. This usually means that Tibia.com is rate-limiting the client because of too many requests.

• NetworkError – If there’s any connection errors during the request.

• ValueError – If the page number is not 1 or greater.

async fetch_auction(auction_id, *, fetch_items=False, fetch_mounts=False, fetch_outfits=False, skip_details=False, test=False)

Fetch an auction by its ID.

New in version 3.3.0.

Parameters:

• auction_id (int) – The ID of the auction.

• fetch_items (bool) – Whether to fetch all of the character’s items. By default only the first page is fetched.

• fetch_mounts (bool) – Whether to fetch all of the character’s mounts. By default only the first page is fetched.

• fetch_outfits (bool) – Whether to fetch all of the character’s outfits. By default only the first page is fetched.

• skip_details (bool, optional) –

  Whether to skip parsing the entire auction and only parse the information shown in lists. False by default.

  This allows fetching basic information like name, level, vocation, world, bid and status, shaving off some parsing time.

• test (bool) – Whether to request the test website instead.

Returns:

The auction matching the ID if found.

Return type:

TibiaResponse of Auction

Raises:

• Forbidden – If a 403 Forbidden error was returned. This usually means that Tibia.com is rate-limiting the client because of too many requests.

• NetworkError – If there’s any connection errors during the request.

• ValueError – If the auction id is not 1 or greater.

async fetch_cm_post_archive(start_date, end_date, page=1, *, test=False)

Fetch the CM post archive.

New in version 3.0.0.

Parameters:

• start_date – The start date to display.

• end_date – The end date to display.

• page (int) – The desired page to display.

• test (bool) – Whether to request the test website instead.

Returns:

The CM Post Archive.

Return type:

TibiaResponse of CMPostArchive

Raises:

• Forbidden – If a 403 Forbidden error was returned. This usually means that Tibia.com is rate-limiting the client because of too many requests.

• NetworkError – If there’s any connection errors during the request.

• ValueError – If the start_date is more recent than the end date or page number is not 1 or greater.

async fetch_event_schedule(month=None, year=None, *, test=False)

Fetch the event calendar. By default, it gets the events for the current month.

New in version 3.0.0.

Parameters:

• month (int) – The month of the events to display.

• year (int) – The year of the events to display.

• test (bool) – Whether to request the test website instead.

Returns:

The event calendar.

Return type:

TibiaResponse of EventSchedule

Raises:

• Forbidden – If a 403 Forbidden error was returned. This usually means that Tibia.com is rate-limiting the client because of too many requests.

• NetworkError – If there’s any connection errors during the request.

• ValueError – If only one of year or month are defined.

async fetch_forum_community_boards(*, test=False)

Fetch the forum’s community boards.

New in version 3.0.0.

Parameters:

test (bool) – Whether to request the test website instead.

Returns:

The forum boards in the community section.

Return type:

TibiaResponse of list of BoardEntry

Raises:

• Forbidden – If a 403 Forbidden error was returned. This usually means that Tibia.com is rate-limiting the client because of too many requests.

• NetworkError – If there’s any connection errors during the request.

async fetch_forum_support_boards(*, test=False)

Fetch the forum’s community boards.

New in version 3.0.0.

Parameters:

test (bool) – Whether to request the test website instead.

Returns:

The forum boards in the community section.

Return type:

TibiaResponse of list of BoardEntry

Raises:

• Forbidden – If a 403 Forbidden error was returned. This usually means that Tibia.com is rate-limiting the client because of too many requests.

• NetworkError – If there’s any connection errors during the request.

async fetch_forum_world_boards(*, test=False)

Fetch the forum’s world boards.

New in version 3.0.0.

Parameters:

test (bool) – Whether to request the test website instead.

Returns:

The forum boards in the world section.

Return type:

TibiaResponse of list of BoardEntry

Raises:

• Forbidden – If a 403 Forbidden error was returned. This usually means that Tibia.com is rate-limiting the client because of too many requests.

• NetworkError – If there’s any connection errors during the request.

async fetch_forum_trade_boards(*, test=False)

Fetch the forum’s trade boards.

New in version 3.0.0.

Parameters:

test (bool) – Whether to request the test website instead.

Returns:

The forum boards in the trade section.

Return type:

TibiaResponse of list of BoardEntry

Raises:

• Forbidden – If a 403 Forbidden error was returned. This usually means that Tibia.com is rate-limiting the client because of too many requests.

• NetworkError – If there’s any connection errors during the request.

async fetch_forum_board(board_id, page=1, age=30, *, test=False)

Fetch a forum board with a given id.

New in version 3.0.0.

Parameters:

• board_id (int) – The id of the board.

• page (int) – The page number to show.

• age (int) –

  The maximum age in days of the threads to display.

  To show threads of all ages, use -1.

• test (bool) – Whether to request the test website instead.

Returns:

A response containing the forum, if found.

Return type:

TibiaResponse of ForumBoard

Raises:

• Forbidden – If a 403 Forbidden error was returned. This usually means that Tibia.com is rate-limiting the client because of too many requests.

• NetworkError – If there’s any connection errors during the request.

async fetch_forum_thread(thread_id, page=1, *, test=False)

Fetch a forum thread with a given id.

New in version 3.0.0.

Parameters:

• thread_id (int) – The id of the thread.

• page (int) – The desired page to display, by default 1.

• test (bool) – Whether to request the test website instead.

Returns:

A response containing the forum, if found.

Return type:

TibiaResponse of ForumThread

Raises:

• Forbidden – If a 403 Forbidden error was returned. This usually means that Tibia.com is rate-limiting the client because of too many requests.

• NetworkError – If there’s any connection errors during the request.

async fetch_forum_post(post_id, *, test=False)

Fetch a forum post with a given id.

The thread that contains the post will be returned, containing the desired post in ForumThread.anchored_post.

The displayed page will be the page where the post is located.

New in version 3.1.0.

Parameters:

• post_id (int) – The id of the post.

• test (bool) – Whether to request the test website instead.

Returns:

A response containing the forum, if found.

Return type:

TibiaResponse of ForumThread

Raises:

• Forbidden – If a 403 Forbidden error was returned. This usually means that Tibia.com is rate-limiting the client because of too many requests.

• NetworkError – If there’s any connection errors during the request.

async fetch_forum_announcement(announcement_id, *, test=False)

Fetch a forum announcement.

New in version 3.0.0.

Parameters:

• announcement_id (int) – The id of the desired announcement.

• test (bool) – Whether to request the test website instead.

Returns:

The forum announcement, if found.

Return type:

TibiaResponse of ForumAnnouncement

Raises:

• Forbidden – If a 403 Forbidden error was returned. This usually means that Tibia.com is rate-limiting the client because of too many requests.

• NetworkError – If there’s any connection errors during the request.

async fetch_boosted_creature_and_boss(*, test=False)

Fetch today’s boosted creature and boss.

New in version 5.3.0.

Parameters:

test (bool) – Whether to request the test website instead.

Returns:

The boosted creature and boss of the day.

Return type:

TibiaResponse of BoostedCreatures

Raises:

• Forbidden – If a 403 Forbidden error was returned. This usually means that Tibia.com is rate-limiting the client because of too many requests.

• NetworkError – If there’s any connection errors during the request.

async fetch_boosted_boss(*, test=False)

Fetch today’s boosted boss.

New in version 5.3.0.

Parameters:

test (bool) – Whether to request the test website instead.

Returns:

The boosted boss of the day.

Return type:

TibiaResponse of BossEntry

Raises:

• Forbidden – If a 403 Forbidden error was returned. This usually means that Tibia.com is rate-limiting the client because of too many requests.

• NetworkError – If there’s any connection errors during the request.

async fetch_library_bosses(*, test=False)

Fetch the bosses from the library section.

New in version 4.0.0.

Parameters:

test (bool) – Whether to request the test website instead.

Returns:

The creature’s section in Tibia.com

Return type:

TibiaResponse of BoostableBosses

Raises:

• Forbidden – If a 403 Forbidden error was returned. This usually means that Tibia.com is rate-limiting the client because of too many requests.

• NetworkError – If there’s any connection errors during the request.

async fetch_boosted_creature(*, test=False)

Fetch today’s boosted creature.

New in version 2.1.0.

Changed in version 4.0.0: The return type of the data returned was changed to Creature, previous type was removed.

Parameters:

test (bool) – Whether to request the test website instead.

Returns:

The boosted creature of the day.

Return type:

TibiaResponse of CreatureEntry

Raises:

• Forbidden – If a 403 Forbidden error was returned. This usually means that Tibia.com is rate-limiting the client because of too many requests.

• NetworkError – If there’s any connection errors during the request.

async fetch_library_creatures(*, test=False)

Fetch the creatures from the library section.

New in version 4.0.0.

Parameters:

test (bool) – Whether to request the test website instead.

Returns:

The creature’s section in Tibia.com

Return type:

TibiaResponse of CreaturesSection

Raises:

• Forbidden – If a 403 Forbidden error was returned. This usually means that Tibia.com is rate-limiting the client because of too many requests.

• NetworkError – If there’s any connection errors during the request.

async fetch_creature(identifier, *, test=False)

Fetch a creature’s information from the Tibia.com library.

New in version 4.0.0.

Parameters:

• identifier (str) – The internal name of the race.

• test (bool) – Whether to request the test website instead.

Returns:

The creature’s section in Tibia.com

Return type:

TibiaResponse of Creature

Raises:

• Forbidden – If a 403 Forbidden error was returned. This usually means that Tibia.com is rate-limiting the client because of too many requests.

• NetworkError – If there’s any connection errors during the request.

async fetch_character(name, *, test=False)

Fetch a character by its name from Tibia.com.

Parameters:

• name (str) – The name of the character.

• test (bool) – Whether to request the test website instead.

Returns:

A response containing the character, if found.

Return type:

TibiaResponse of Character

Raises:

• Forbidden – If a 403 Forbidden error was returned. This usually means that Tibia.com is rate-limiting the client because of too many requests.

• NetworkError – If there’s any connection errors during the request.

async fetch_guild(name, *, test=False)

Fetch a guild by its name from Tibia.com.

Parameters:

• name (str) – The name of the guild. The case must match exactly.

• test (bool) – Whether to request the test website instead.

Returns:

A response containing the found guild, if any.

Return type:

TibiaResponse of Guild

Raises:

• Forbidden – If a 403 Forbidden error was returned. This usually means that Tibia.com is rate-limiting the client because of too many requests.

• NetworkError – If there’s any connection errors during the request.

async fetch_guild_wars(name, *, test=False)

Fetch a guild’s wars by its name from Tibia.com.

New in version 3.0.0.

Parameters:

• name (str) – The name of the guild. The case must match exactly.

• test (bool) – Whether to request the test website instead.

Returns:

A response containing the found guild’s wars.

If the guild doesn’t exist, the displayed data will show a guild with no wars instead of indicating the guild doesn’t exist.

Return type:

TibiaResponse of GuildWars

Raises:

• Forbidden – If a 403 Forbidden error was returned. This usually means that Tibia.com is rate-limiting the client because of too many requests.

• NetworkError – If there’s any connection errors during the request.

async fetch_house(house_id, world, *, test=False)

Fetch a house in a specific world by its id.

Parameters:

• house_id (int) – The house’s internal id.

• world (str) – The name of the world to look for.

• test (bool) – Whether to request the test website instead.

Returns:

The house if found, None otherwise.

Return type:

TibiaResponse of House

Raises:

• Forbidden – If a 403 Forbidden error was returned. This usually means that Tibia.com is rate-limiting the client because of too many requests.

• NetworkError – If there’s any connection errors during the request.

async fetch_highscores_page(world=None, category=Category.EXPERIENCE, vocation=VocationFilter.ALL, page=1, battleye_type=None, pvp_types=None, *, test=False)

Fetch a single highscores page from Tibia.com.

Notes

It is not possible to use BattlEye or PvPType filters when requesting a specific world.

Parameters:

• world (str) – The world to search the highscores in.

• category (Category) – The highscores category to search, by default Experience.

• vocation (VocationFilter) – The vocation filter to use. No filter used by default.

• page (int) – The page to fetch, by default the first page is fetched.

• battleye_type (BattlEyeFilter) – The type of BattlEye protection to display results from.

• pvp_types (list of PvpTypeFilter) – The list of PvP types to filter the results for.

• test (bool) – Whether to request the test website instead.

Returns:

The highscores information or None if not found.

Return type:

TibiaResponse of Highscores

Raises:

• Forbidden – If a 403 Forbidden error was returned. This usually means that Tibia.com is rate-limiting the client because of too many requests.

• NetworkError – If there’s any connection errors during the request.

• ValueError – If an invalid filter combination is passed.

async fetch_kill_statistics(world, *, test=False)

Fetch the kill statistics of a world from Tibia.com.

Parameters:

• world (str) – The name of the world.

• test (bool) – Whether to request the test website instead.

Returns:

The kill statistics of the world if found.

Return type:

TibiaResponse of KillStatistics

Raises:

• Forbidden – If a 403 Forbidden error was returned. This usually means that Tibia.com is rate-limiting the client because of too many requests.

• NetworkError – If there’s any connection errors during the request.

async fetch_leaderboard(world, rotation=None, page=1, *, test=False)

Fetch the leaderboards for a specific world and rotation.

New in version 5.0.0.

Parameters:

• world (str) – The name of the world.

• rotation (int) – The ID of the rotation. By default it will get the current rotation.

• page (int) – The page to get.

• test (bool) – Whether to request the test website instead.

Returns:

The leaderboards of the world if found.

Return type:

TibiaResponse of Leaderboard

Raises:

• Forbidden – If a 403 Forbidden error was returned. This usually means that Tibia.com is rate-limiting the client because of too many requests.

• NetworkError – If there’s any connection errors during the request.

async fetch_world(name, *, test=False)

Fetch a world from Tibia.com.

Parameters:

• name (str) – The name of the world.

• test (bool) – Whether to request the test website instead.

Returns:

A response containig the he world’s information if found, None otherwise.

Return type:

TibiaResponse of World

Raises:

• Forbidden – If a 403 Forbidden error was returned. This usually means that Tibia.com is rate-limiting the client because of too many requests.

• NetworkError – If there’s any connection errors during the request.

async fetch_world_houses(world, town, house_type=HouseType.HOUSE, status=None, order=None, *, test=False)

Fetch the house list of a world and type.

Changed in version 5.0.0: The data attribute of the response contains an instance of HousesSection instead.

Parameters:

• world (str) – The name of the world.

• town (str) – The name of the town.

• house_type (HouseType) – The type of building. House by default.

• status (HouseStatus, optional) – The house status to filter results. By default, no filters will be applied.

• order (HouseOrder, optional) – The ordering to use for the results. By default, they are sorted by name.

• test (bool) – Whether to request the test website instead.

Returns:

A response containing the lists of houses meeting the criteria if found.

Return type:

TibiaResponse of HousesSection

Raises:

• Forbidden – If a 403 Forbidden error was returned. This usually means that Tibia.com is rate-limiting the client because of too many requests.

• NetworkError – If there’s any connection errors during the request.

async fetch_world_guilds(world: str, *, test=False)

Fetch the list of guilds in a world from Tibia.com.

If a world that does not exist is passed, the world attribute of the result will be None. If the world attribute is set, but the list is empty, it just means the world has no guilds.

Changed in version 5.0.0: The data attribute of the response contains an instance of GuildsSection instead.

Parameters:

• world (str) – The name of the world.

• test (bool) – Whether to request the test website instead.

Returns:

A response containing the guilds section for the specified world.

Return type:

TibiaResponse of GuildsSection

Raises:

• Forbidden – If a 403 Forbidden error was returned. This usually means that Tibia.com is rate-limiting the client because of too many requests.

• NetworkError – If there’s any connection errors during the request.

async fetch_world_list(*, test=False)

Fetch the world overview information from Tibia.com.

Parameters:

test (bool) – Whether to request the test website instead.

Returns:

A response containing the world overview information.

Return type:

TibiaResponse of WorldOverview

Raises:

• Forbidden – If a 403 Forbidden error was returned. This usually means that Tibia.com is rate-limiting the client because of too many requests.

• NetworkError – If there’s any connection errors during the request.

async fetch_news_archive(start_date, end_date, categories=None, types=None, *, test=False)

Fetch news from the archive meeting the search criteria.

Changed in version 5.0.0: The data attribute of the response contains an instance of NewsArchive instead.

Parameters:

• start_date (datetime.date) – The beginning date to search dates in.

• end_date (datetime.date) – The end date to search dates in.

• categories (list of NewsCategory) – The allowed categories to show. If left blank, all categories will be searched.

• types (list of NewsType) – The allowed news types to show. if unused, all types will be searched.

• test (bool) – Whether to request the test website instead.

Returns:

The news meeting the search criteria.

Return type:

TibiaResponse of NewsArchive

Raises:

• ValueError: – If begin_date is more recent than to_date.

• Forbidden – If a 403 Forbidden error was returned. This usually means that Tibia.com is rate-limiting the client because of too many requests.

• NetworkError – If there’s any connection errors during the request.

async fetch_recent_news(days=30, categories=None, types=None, *, test=False)

Fetch all the published news in the last specified days.

This is a shortcut for fetch_news_archive(), to handle dates more easily.

Changed in version 5.0.0: The data attribute of the response contains an instance of NewsArchive instead.

Parameters:

• days (int) – The number of days to search, by default 30.

• categories (list of NewsCategory) – The allowed categories to show. If left blank, all categories will be searched.

• types (list of NewsType) – The allowed news types to show. if unused, all types will be searched.

• test (bool) – Whether to request the test website instead.

Returns:

The news posted in the last specified days.

Return type:

TibiaResponse of NewsArchive

Raises:

• Forbidden – If a 403 Forbidden error was returned. This usually means that Tibia.com is rate-limiting the client because of too many requests.

• NetworkError – If there’s any connection errors during the request.

async fetch_news(news_id, *, test=False)

Fetch a news entry by its id from Tibia.com.

Parameters:

• news_id (int) – The id of the news entry.

• test (bool) – Whether to request the test website instead.

Returns:

The news entry if found, None otherwise.

Return type:

TibiaResponse of News

Raises:

• Forbidden – If a 403 Forbidden error was returned. This usually means that Tibia.com is rate-limiting the client because of too many requests.

• NetworkError – If there’s any connection errors during the request.

async fetch_spells(*, vocation=None, group=None, spell_type=None, premium=None, sort=None, test=False)

Fetch the spells section.

Parameters:

• vocation (VocationSpellFilter, optional) – The vocation to filter in spells for.

• group (SpellGroup, optional) – The spell’s primary cooldown group.

• spell_type (SpellType, optional) – The type of spells to show.

• premium (bool, optional) – The type of premium requirement to filter. None means any premium requirement.

• sort (SpellSorting, optional) – The field to sort spells by.

Returns:

The spells section with the results.

Return type:

TibiaResponse of SpellsSection

Raises:

• Forbidden – If a 403 Forbidden error was returned. This usually means that Tibia.com is rate-limiting the client because of too many requests.

• NetworkError – If there’s any connection errors during the request.

async fetch_spell(identifier, *, test=False)

Fetch a spell by its identifier.

Parameters:

• identifier (str) – The spell’s identifier. This is usually the name of the spell in lowercase and with no spaces.

• test (bool) – Whether to request the test website instead.

Returns:

The spell if found, None otherwise.

Return type:

TibiaResponse of Spell

Raises:

• Forbidden – If a 403 Forbidden error was returned. This usually means that Tibia.com is rate-limiting the client because of too many requests.

• NetworkError – If there’s any connection errors during the request.

async fetch_tournament(tournament_cycle=0, *, test=False)

Fetch a tournament from Tibia.com.

New in version 2.5.0.

Parameters:

• tournament_cycle (int) – The cycle of the tournament. if unspecified, it will get the currently running tournament.

• test (bool) – Whether to request the test website instead.

Returns:

The tournament if found, None otherwise.

Return type:

TibiaResponse of Tournament

Raises:

• Forbidden – If a 403 Forbidden error was returned. This usually means that Tibia.com is rate-limiting the client because of too many requests.

• NetworkError – If there’s any connection errors during the request.

async fetch_tournament_leaderboard(tournament_cycle, world, page=1, *, test=False)

Fetch a tournament leaderboard from Tibia.com.

New in version 2.5.0.

Parameters:

• tournament_cycle (int) – The cycle of the tournament. if unspecified, it will get the currently running tournament.

• world (str) – The name of the world to get the leaderboards for.

• page (int) – The desired leaderboards page, by default 1 is used.

• test (bool) – Whether to request the test website instead.

Returns:

The tournament’s leaderboard if found, None otherwise.

Return type:

TibiaResponse of TournamentLeaderboard

Raises:

• Forbidden – If a 403 Forbidden error was returned. This usually means that Tibia.com is rate-limiting the client because of too many requests.

• NetworkError – If there’s any connection errors during the request.

class tibiapy.TibiaResponse(raw_response, data: T, parsing_time=None)

Represents a response from Tibia.com.

timestamp

The date and time when the page was fetched, in UTC.

Type:

datetime.datetime

cached

Whether the response is cached or it is a fresh response.

Type:

bool

age

The age of the cache in seconds.

Type:

int

fetching_time

The time in seconds it took for Tibia.com to respond.

Type:

float

parsing_time

The time in seconds it took for the response to be parsed into data.

Type:

float

data

The data contained in the response.

Type:

T

property time_left

The time left for the cache of this response to expire.

Type:

datetime.timedelta

property seconds_left

The time left in seconds for this response’s cache to expire.

Type:

int

Enumerations

Enumerations are provided for various values in order to avoid depending on strings.

Many of these enumerations correspond to available options in forms in Tibia.com

class tibiapy.AccountStatus(value)

Possible account statuses.

FREE_ACCOUNT = 'Free Account'

PREMIUM_ACCOUNT = 'Premium Account'

class tibiapy.AuctionOrder(value)

The possible ordering directions for auctions.

The field or value used for the ordering is defined by AuctionOrderBy.

HIGHEST_LATEST = 0

Order by the highest or latest value.

LOWEST_EARLIEST = 1

Order by the lowest or earliest value.

class tibiapy.AuctionOrderBy(value)

The possible values to order the auctions by.

BID = 100

The currently displayed bid for the auction.

END_DATE = 101

The end date of the auction.

LEVEL = 102

The experience level of the auctioned character.

START_DATE = 103

The start date of the auction.

AXE_FIGHTING = 10

CLUB_FIGHTING = 9

DISTANCE_FIGHTING = 7

FISHING = 13

FIST_FIGHTING = 11

MAGIC_LEVEL = 1

SHIELDING = 6

SWORD_FIGHTING = 8

class tibiapy.AuctionSearchType(value)

The possible search types.

ITEM_DEFAULT = 0

Searches everything that includes the words on the search string.

ITEM_WILDCARD = 1

Searches everything that includes the search string

CHARACTER_NAME = 2

Searches a character’s name.

class tibiapy.AuctionStatus(value)

The possible values an auction might have.

IN_PROGRESS = 'in progress'

The auction is currently active.

Notes

This status doesn’t exist in Tibia.com explicitly. It is given to all ongoing auctions.

CURRENTLY_PROCESSED = 'currently processed'

The auction ended with a winner, but payment hasn’t been received yet.

PENDING_TRANSFER = 'will be transferred at the next server save'

The auction was finished and was paid, but the character hasn’t been transferred to the new owner yet.

CANCELLED = 'cancelled'

The auction was cancelled as no payment was received in time.

FINISHED = 'finished'

The auction either finished with no bids or the character was transferred to the new owner already.

class tibiapy.BattlEyeType(value)

The possible BattlEye statuses a world can have.

New in version 4.0.0.

UNPROTECTED = 0

Worlds without any BattlEye protection.

PROTECTED = 1

Worlds protected after the world was created, represented by a yellow symbol.

INITIALLY_PROTECTED = 2

Worlds protected from the beginning, represented by a green symbol.

YELLOW = 1

Alias for protected worlds.

GREEN = 2

Alias for initially protected worlds.

class tibiapy.BattlEyeHighscoresFilter(value)

The possible BattlEye filters that can be used for highscores.

ANY_WORLD = -1

Show all worlds.

INITIALLY_PROTECTED = 2

Worlds protected from the beginning, represented by a green symbol.

PROTECTED = 1

Worlds protected after the world was created, represented by a yellow symbol.

UNPROTECTED = 0

Worlds without any BattlEye protection.

YELLOW = 1

Alias for protected worlds.

New in version 4.0.0.

GREEN = 2

Alias for initially protected worlds.

New in version 4.0.0.

class tibiapy.BattlEyeTypeFilter(value)

The possible BattlEye filters that can be used for auctions.

INITIALLY_PROTECTED = 1

Worlds protected from the beginning, represented by a green symbol.

PROTECTED = 2

Worlds protected after the world was created, represented by a yellow symbol.

NOT_PROTECTED = 3

Worlds without any BattlEye protection.

YELLOW = 2

Alias for protected worlds.

New in version 4.0.0.

GREEN = 1

Alias for initially protected worlds.

New in version 4.0.0.

class tibiapy.BazaarType(value)

The possible bazaar types.

CURRENT = 'Current Auctions'

HISTORY = 'Auction History'

class tibiapy.BidType(value)

The possible bid types for an auction.

MINIMUM = 'Minimum Bid'

The minimum bid set by the auction author, meaning the auction hasn’t received any bids or it finished without bids.

CURRENT = 'Current Bid'

The current maximum bid, meaning the auction has received at least one bid.

WINNING = 'Winning Bid'

The bid that won the auction.

class tibiapy.Category(value)

The different highscores categories.

ACHIEVEMENTS = 1

AXE_FIGHTING = 2

CHARM_POINTS = 3

CLUB_FIGHTING = 4

DISTANCE_FIGHTING = 5

DROME_SCORE = 14

EXPERIENCE = 6

FISHING = 7

FIST_FIGHTING = 8

GOSHNARS_TAINT = 9

LOYALTY_POINTS = 10

MAGIC_LEVEL = 11

SHIELDING = 12

SWORD_FIGHTING = 13

class tibiapy.HouseOrder(value)

The possible ordering methods for house lists in Tibia.com

NAME = 'name'

SIZE = 'size'

RENT = 'rent'

BID = 'bid'

AUCTION_END = 'end'

class tibiapy.HouseStatus(value)

Renting statuses of a house.

RENTED = 'rented'

AUCTIONED = 'auctioned'

class tibiapy.HouseType(value)

The types of house available.

HOUSE = 'house'

GUILDHALL = 'guildhall'

property plural

The plural for the house type.

Type:

str

class tibiapy.NewsCategory(value)

The different news categories.

CIPSOFT = 'cipsoft'

COMMUNITY = 'community'

DEVELOPMENT = 'development'

SUPPORT = 'support'

TECHNICAL_ISSUES = 'technical'

property filter_name

class tibiapy.NewsType(value)

The different types of new entries.

NEWS_TICKER = 'News Ticker'

FEATURED_ARTICLE = 'Featured Article'

NEWS = 'News'

property filter_name

class tibiapy.PvpTypeFilter(value)

The possible PVP filters that can be used for auctions.

OPEN_PVP = 0

OPTIONAL_PVP = 1

HARDCORE_PVP = 2

RETRO_OPEN_PVP = 3

RETRO_HARDCORE_PVP = 4

class tibiapy.PvpType(value)

The possible PvP types a World can have.

OPEN_PVP = 'Open PvP'

OPTIONAL_PVP = 'Optional PvP'

RETRO_OPEN_PVP = 'Retro Open PvP'

RETRO_HARDCORE_PVP = 'Retro Hardcore PvP'

HARDCORE_PVP = 'Hardcore PvP'

class tibiapy.Sex(value)

Possible character sexes.

MALE = 'male'

FEMALE = 'female'

class tibiapy.SkillFilter(value)

The different skill filters for auctions.

AXE_FIGHTING = 10

CLUB_FIGHTING = 9

DISTANCE_FIGHTING = 7

FISHING = 13

FIST_FIGHTING = 11

MAGIC_LEVEL = 1

SHIELDING = 6

SWORD_FIGHTING = 8

class tibiapy.SpellGroup(value)

The possible cooldown groups.

Note that secondary groups are not enumerated.

ATTACK = 'Attack'

HEALING = 'Healing'

SUPPORT = 'Support'

class tibiapy.SpellSorting(value)

The different sorting options for the spells section.

NAME = 'name'

GROUP = 'group'

TYPE = 'type'

EXP_LEVEL = 'level'

MANA = 'mana'

PRICE = 'price'

PREMIUM = 'premium'

class tibiapy.SpellType(value)

The possible spell types.

INSTANT = 'Instant'

RUNE = 'Rune'

class tibiapy.ThreadStatus(value)

The possible status a thread can have.

Threads can have a combination of multiple status. The numeric values are arbitrary.

NONE = 0

HOT = 1

Thread has more than 16 replies.

NEW = 2

Thread has new posts since last visit.

CLOSED = 4

Thread is closed.

STICKY = 8

Thread is stickied.

get_icon_name()

Generate an icon name, following the same ordering used in Tibia.com.

Returns:

The name of the icon used in Tibia.com

Return type:

str

classmethod from_icon(icon)

Get the flag combination, based from the icon’s name present in the thread status.

Parameters:

icon (str) – The icon’s filename.

Returns:

The combination of thread status founds.

Return type:

ThreadStatus

class tibiapy.TournamentWorldType(value)

The possible types of tournament worlds.

REGULAR = 'Regular'

RESTRICTED = 'Restricted Store'

class tibiapy.TournamentPhase(value)

The possible tournament phases.

SIGN_UP = 'sign up'

RUNNING = 'running'

ENDED = 'ended'

class tibiapy.TransferType(value)

The possible special transfer restrictions a world may have.

REGULAR = 'regular'

No special transfer restrictions

BLOCKED = 'blocked'

Can’t transfer to this world, but can transfer out of this world.

LOCKED = 'locked'

Can transfer to this world, but can’t transfer out of this world.

class tibiapy.Vocation(value)

The possible vocation types.

NONE = 'None'

DRUID = 'Druid'

KNIGHT = 'Knight'

PALADIN = 'Paladin'

SORCERER = 'Sorcerer'

ELDER_DRUID = 'Elder Druid'

ELITE_KNIGHT = 'Elite Knight'

ROYAL_PALADIN = 'Royal Paladin'

MASTER_SORCERER = 'Master Sorcerer'

class tibiapy.VocationAuctionFilter(value)

The possible vocation filters for auctions.

NONE = 1

DRUID = 2

KNIGHT = 3

PALADIN = 4

SORCERER = 5

class tibiapy.VocationFilter(value)

The vocation filters available for Highscores.

The numeric values are what the highscores form accepts.

ALL = 0

NONE = 1

KNIGHTS = 2

PALADINS = 3

SORCERERS = 4

DRUIDS = 5

classmethod from_name(name, all_fallback=True)

Get a vocation filter from a vocation’s name.

Parameters:

• name (str) – The name of the vocation.

• all_fallback (bool) – Whether to return ALL if no match is found. Otherwise, None will be returned.

Returns:

The matching vocation filter.

Return type:

VocationFilter, optional

class tibiapy.VocationSpellFilter(value)

The possible vocation types to filter out spells.

DRUID = 'Druid'

KNIGHT = 'Knight'

PALADIN = 'Paladin'

SORCERER = 'Sorcerer'

class tibiapy.WorldLocation(value)

The possible physical locations for servers.

EUROPE = 'Europe'

NORTH_AMERICA = 'North America'

SOUTH_AMERICA = 'South America'

Characters

The Character section consists of the Character class and its auxiliary classes used to hold its data.

The entry points for this are:

• Character.from_content() - Parsing a character’s content.

• Client.fetch_character() - Fetching and parsing a character’s content.

Character

class tibiapy.Character(name=None, world=None, vocation=None, level=0, sex=None, **kwargs)

A full character from Tibia.com, obtained from its character page.

name

The name of the character.

Type:

str

traded

If the character was traded in the last 6 months.

Type:

bool

deletion_date

The date when the character will be deleted if it is scheduled for deletion. Will be None otherwise.

Type:

datetime.datetime, optional

former_names

Previous names of the character.

Type:

list of str

title

The character’s selected title, if any.

Type:

str, optional

unlocked_titles

The number of titles the character has unlocked.

Type:

int

sex

The character’s sex.

Type:

Sex

vocation

The character’s vocation.

Type:

Vocation

level

The character’s level.

Type:

int

achievement_points

The total of achievement points the character has.

Type:

int

world

The character’s current world.

Type:

str

former_world

The previous world the character was in, in the last 6 months.

Type:

str, optional

residence

The current hometown of the character.

Type:

str

married_to

The name of the character’s spouse. It will be None if not married.

Type:

str, optional

houses

The houses currently owned by the character.

Type:

list of CharacterHouse

guild_membership

The guild the character is a member of. It will be None if the character is not in a guild.

Type:

GuildMembership, optional

last_login

The last time the character logged in. It will be None if the character has never logged in.

Type:

datetime.datetime, optional

position

The position of the character (e.g. CipSoft Member), if any.

Type:

str, optional

comment

The displayed comment.

Type:

str, optional

account_status

Whether the character’s account is Premium or Free.

Type:

AccountStatus

account_badges

The displayed account badges.

Type:

list of AccountBadge

achievements

The achievements chosen to be displayed.

Type:

list of Achievement

deaths

The character’s recent deaths.

Type:

list of Death

deaths_truncated

Whether the character’s deaths are truncated or not.

In some cases, there are more deaths in the last 30 days than what can be displayed.

Type:

bool

account_information

The character’s account information. If the character is hidden, this will be None.

Type:

AccountInformation, optional

other_characters

Other characters in the same account.

It will be empty if the character is hidden, otherwise, it will contain at least the character itself.

Type:

list of OtherCharacter

property deleted: bool

Whether the character is scheduled for deletion or not.

Type:

bool

property guild_name: Optional[str]

The name of the guild the character belongs to, or None.

Type:

str, optional

property guild_rank: Optional[str]

The character’s rank in the guild they belong to, or None.

Type:

str, optional

property guild_url: Optional[str]

The character’s rank in the guild they belong to, or None.

Type:

str, optional

property hidden: bool

Whether this is a hidden character or not.

Type:

bool

property married_to_url: Optional[str]

The URL to the husband/spouse information page on Tibia.com, if applicable.

Type:

str, optional

classmethod from_content(content)

Create an instance of the class from the html content of the character’s page.

Parameters:

content (str) – The HTML content of the page.

Returns:

The character contained in the page, or None if the character doesn’t exist

Return type:

Character

Raises:

InvalidContent – If content is not the HTML of a character’s page.

classmethod get_url(name)

Get the Tibia.com URL for a given character name.

Parameters:

name (str) – The name of the character.

Returns:

The URL to the character’s page.

Return type:

str

to_json(*, indent=None, sort_keys=False)

Get the object’s JSON representation.

Parameters:

• indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.

• sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.

Returns:

JSON representation of the object.

Return type:

str

property url

The URL of the character’s information page on Tibia.com.

Type:

str

Auxiliary Classes

AccountBadge

class tibiapy.AccountBadge(name, icon_url, description)

A displayed account badge in the character’s information.

name

The name of the badge.

Type:

str

icon_url

The URL to the badge’s icon.

Type:

str

description

The description of the badge.

Type:

str

to_json(*, indent=None, sort_keys=False)

Get the object’s JSON representation.

Parameters:

• indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.

• sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.

Returns:

JSON representation of the object.

Return type:

str

AccountInformation

class tibiapy.AccountInformation(created, loyalty_title=None, position=None)

Contains the information of a character’s account.

This is only visible if the character is not marked as hidden.

created

The date when the account was created.

Type:

datetime.datetime

position

The special position of this account, if any.

Type:

str, optional

loyalty_title

The loyalty title of the account, if any.

Type:

str, optional

to_json(*, indent=None, sort_keys=False)

Get the object’s JSON representation.

Parameters:

• indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.

• sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.

Returns:

JSON representation of the object.

Return type:

str

Achievement

class tibiapy.Achievement(name, grade, secret=False)

Represents an achievement listed on a character’s page.

name

The name of the achievement.

Type:

str

grade

The grade of the achievement, also known as stars.

Type:

int

secret

Whether the achievement is secret or not.

Type:

bool

to_json(*, indent=None, sort_keys=False)

Get the object’s JSON representation.

Parameters:

• indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.

• sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.

Returns:

JSON representation of the object.

Return type:

str

CharacterHouse

class tibiapy.CharacterHouse(_id, name, world=None, town=None, owner=None, paid_until_date=None)

A house owned by a character.

id

The internal ID of the house. This is used on the website to identify houses.

Type:

int

name

The name of the house.

Type:

str

world

The name of the world the house belongs to.

Type:

str

status

The current status of the house.

Type:

HouseStatus

type

The type of the house.

Type:

HouseType

town

The town where the city is located in.

Type:

str

owner

The owner of the house.

Type:

str

paid_until_date

The date the last paid rent is due.

Type:

datetime.date

classmethod get_url(house_id, world)

Get the Tibia.com URL for a house with the given id and world.

Parameters:

• house_id (int) – The internal id of the house.

• world (str) – The world of the house.

Return type:

The URL to the house in Tibia.com

to_json(*, indent=None, sort_keys=False)

Get the object’s JSON representation.

Parameters:

• indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.

• sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.

Returns:

JSON representation of the object.

Return type:

str

property url

The URL to the Tibia.com page of the house.

Type:

str

Death

class tibiapy.Death(name=None, level=0, **kwargs)

A character’s death.

name

The name of the character this death belongs to.

Type:

str

level

The level at which the death occurred.

Type:

int

killers

A list of all the killers involved.

Type:

list of Killer

assists

A list of characters that were involved, without dealing damage.

Type:

list of Killer

time

The time at which the death occurred.

Type:

datetime.datetime

property by_player

Whether the kill involves other characters.

Type:

bool

property killer

The first killer in the list.

This is usually the killer that gave the killing blow.

Type:

Killer

to_json(*, indent=None, sort_keys=False)

Get the object’s JSON representation.

Parameters:

• indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.

• sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.

Returns:

JSON representation of the object.

Return type:

str

GuildMembership

class tibiapy.GuildMembership(name, rank, title=None)

The guild information of a character.

name

The name of the guild.

Type:

str

rank

The name of the rank the member has.

Type:

str

title

The title of the member in the guild. This is only available for characters in the forums section.

Type:

str, optional

classmethod get_url(name)

Get the Tibia.com URL for a given guild name.

Parameters:

name (str) – The name of the guild.

Returns:

The URL to the guild’s page.

Return type:

str

classmethod get_url_wars(name)

Get the Tibia.com URL for the guild wars of a guild with a given name.

New in version 3.0.0.

Parameters:

name (str) – The name of the guild.

Returns:

The URL to the guild’s wars page.

Return type:

str

to_json(*, indent=None, sort_keys=False)

Get the object’s JSON representation.

Parameters:

• indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.

• sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.

Returns:

JSON representation of the object.

Return type:

str

property url

The URL to the guild’s information page on Tibia.com.

Type:

str

property url_wars

str The URL to the guild’s wars page on Tibia.com.

New in version 3.0.0.

Killer

class tibiapy.Killer(name, player=False, summon=None, traded=False)

Represents a killer.

A killer can be:

1. A creature.

2. A character.

3. A creature summoned by a character.

name

The name of the killer. In the case of summons, the name belongs to the owner.

Type:

str

player

Whether the killer is a player or not.

Type:

bool

summon

The name of the summoned creature, if applicable.

Type:

str, optional

traded

If the killer was traded after this death happened.

Type:

str, optional

property url

The URL of the character’s information page on Tibia.com, if applicable.

Type:

str, optional

to_json(*, indent=None, sort_keys=False)

Get the object’s JSON representation.

Parameters:

• indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.

• sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.

Returns:

JSON representation of the object.

Return type:

str

OtherCharacter

class tibiapy.OtherCharacter(name, world, online=False, deleted=False, main=False, position=None, traded=False)

A character listed in the characters section of a character’s page.

These are only shown if the character is not hidden, and only characters that are not hidden are shown here.

name

The name of the character.

Type:

str

world

The name of the world.

Type:

str

online

Whether the character is online or not.

Type:

bool

deleted

Whether the character is scheduled for deletion or not.

Type:

bool

traded

Whether the character has been traded recently or not.

Type:

bool

main

Whether this is the main character or not.

Type:

bool

position

The character’s official position, if any.

Type:

str

classmethod get_url(name)

Get the Tibia.com URL for a given character name.

Parameters:

name (str) – The name of the character.

Returns:

The URL to the character’s page.

Return type:

str

to_json(*, indent=None, sort_keys=False)

Get the object’s JSON representation.

Parameters:

• indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.

• sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.

Returns:

JSON representation of the object.

Return type:

str

property url

The URL of the character’s information page on Tibia.com.

Type:

str

Worlds

Models related to Tibia.com’s World section. The WorldOverview class contains the list of all worlds, while the World class contains the details of a single world.

WorldOverview

class tibiapy.WorldOverview(**kwargs)

Container class for the World Overview section.

record_count

The overall player online record.

Type:

int

record_date

The date when the record was achieved.

Type:

datetime.datetime

worlds

List of worlds, with limited info.

Type:

list of WorldEntry

property total_online

Total players online across all worlds.

Type:

int

property tournament_worlds

List of tournament worlds.

Note that tournament worlds are not listed when there are no active or upcoming tournaments.

Type:

list of GuildMember

property regular_worlds

List of worlds that are not tournament worlds.

Type:

list of WorldEntry

classmethod get_url()

Get the URL to the World Overview page in Tibia.com.

Returns:

The URL to the World Overview’s page.

Return type:

str

classmethod from_content(content)

Parse the content of the World Overview section from Tibia.com into an object of this class.

Parameters:

content (str) – The HTML content of the World Overview page in Tibia.com

Returns:

An instance of this class containing all the information.

Return type:

WorldOverview

Raises:

InvalidContent – If the provided content is not the HTML content of the worlds section in Tibia.com

to_json(*, indent=None, sort_keys=False)

Get the object’s JSON representation.

Parameters:

• indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.

• sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.

Returns:

JSON representation of the object.

Return type:

str

WorldEntry

class tibiapy.WorldEntry(name, location=None, pvp_type=None, **kwargs)

Represents a game server listed in the World Overview section.

name

The name of the world.

Type:

str

status

The current status of the world.

Type:

str

online_count

The number of currently online players in the world.

Type:

int

location

The physical location of the game servers.

Type:

WorldLocation

pvp_type

The type of PvP in the world.

Type:

PvpType

transfer_type

The type of transfer restrictions this world has.

Type:

TransferType

battleye_date

The date when BattlEye was added to this world. If this is None and the world is protected, it means the world was protected from the beginning.

Type:

datetime.date

battleye_type

The type of BattlEye protection this world has.

New in version 4.0.0.

Type:

BattlEyeType

experimental

Whether the world is experimental or not.

Type:

bool

premium_only

Whether only premium account players are allowed to play in this server.

Type:

bool

tournament_world_type

The type of tournament world. None if this is not a tournament world.

Type:

TournamentWorldType

property battleye_protected

Whether the server is currently protected with BattlEye or not.

Changed in version 4.0.0: Now a calculated property instead of a field.

Type:

bool

classmethod get_list_url()

Get the URL to the World Overview page in Tibia.com.

Returns:

The URL to the World Overview’s page.

Return type:

str

classmethod list_from_content(content)

Parse the content of the World Overview section from Tibia.com and returns only the list of worlds.

Parameters:

content (str) – The HTML content of the World Overview page in Tibia.com

Returns:

A list of the worlds and their current information.

Return type:

list of WorldEntry

Raises:

InvalidContent – If the provided content is not the HTML content of the worlds section in Tibia.com

classmethod get_url(name)

Get the URL to the World’s information page on Tibia.com.

Parameters:

name (str) – The name of the world.

Returns:

The URL to the world’s information page.

Return type:

str

to_json(*, indent=None, sort_keys=False)

Get the object’s JSON representation.

Parameters:

• indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.

• sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.

Returns:

JSON representation of the object.

Return type:

str

property url

URL to the world’s information page on Tibia.com.

Type:

str

World

class tibiapy.World(name, location=None, pvp_type=None, **kwargs)

Represents a Tibia game server.

name

The name of the world.

Type:

str

status

The current status of the world.

Type:

str

online_count

The number of currently online players in the world.

Type:

int

record_count

The server’s online players record.

Type:

int

record_date

The date when the online record was achieved.

Type:

datetime.datetime

location

The physical location of the game servers.

Type:

WorldLocation

pvp_type

The type of PvP in the world.

Type:

PvpType

creation_date

The month and year the world was created. In YYYY-MM format.

Type:

str

transfer_type

The type of transfer restrictions this world has.

Type:

TransferType

world_quest_titles

List of world quest titles the server has achieved.

Type:

list of str

battleye_date

The date when BattlEye was added to this world. If this is None and the world is protected, it means the world was protected from the beginning.

Type:

datetime.date

battleye_type

The type of BattlEye protection this world has.

New in version 4.0.0.

Type:

BattlEyeType

experimental

Whether the world is experimental or not.

Type:

bool

tournament_world_type

The type of tournament world. None if this is not a tournament world.

Type:

TournamentWorldType

online_players

A list of characters currently online in the server.

Type:

list of OnlineCharacter.

premium_only

Whether only premium account players are allowed to play in this server.

Type:

bool

property battleye_protected

Whether the server is currently protected with BattlEye or not.

Changed in version 4.0.0: Now a calculated property instead of a field.

Type:

bool

property creation_year

Returns the year when the world was created.

Type:

int

property creation_month

Returns the month when the world was created.

Type:

int

classmethod from_content(content)

Parse a Tibia.com response into a World.

Parameters:

content (str) – The raw HTML from the server’s information page.

Returns:

The World described in the page, or None.

Return type:

World

Raises:

InvalidContent – If the provided content is not the HTML content of the world section in Tibia.com

classmethod get_url(name)

Get the URL to the World’s information page on Tibia.com.

Parameters:

name (str) – The name of the world.

Returns:

The URL to the world’s information page.

Return type:

str

to_json(*, indent=None, sort_keys=False)

Get the object’s JSON representation.

Parameters:

• indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.

• sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.

Returns:

JSON representation of the object.

Return type:

str

property url

URL to the world’s information page on Tibia.com.

Type:

str

OnlineCharacter

class tibiapy.OnlineCharacter(name, world, level, vocation)

An online character in the world’s page.

name

The name of the character.

Type:

str

world

The name of the world.

Type:

str

vocation

The vocation of the character.

Type:

Vocation

level

The level of the character.

Type:

int

classmethod get_url(name)

Get the Tibia.com URL for a given character name.

Parameters:

name (str) – The name of the character.

Returns:

The URL to the character’s page.

Return type:

str

to_json(*, indent=None, sort_keys=False)

Get the object’s JSON representation.

Parameters:

• indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.

• sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.

Returns:

JSON representation of the object.

Return type:

str

property url

The URL of the character’s information page on Tibia.com.

Type:

str

Guilds

Models related to Tibia.com’s Guilds section. The main model is Guild, while GuildEntry is the previewed information in the guild list of the GuildsSection.

GuildsSection

class tibiapy.GuildsSection(world, entries=None, available_worlds=None)

The guilds section in Tibia.com.

New in version 5.0.0.

world

The name of the world. If None, the section belongs to a world that doesn’t exist.

Type:

str

entries

The list of guilds in the world.

Type:

list of GuildEntry

available_worlds

The list of worlds available for selection.

Type:

list of str

property active_guilds

Get a list of the guilds that are active.

Type:

list of GuildEntry

property in_formation_guilds

Get a list of the guilds that are in course of formation.

Type:

list of GuildEntry

property url

Get the URL to this guild section.

Type:

str

classmethod from_content(content)

Get a list of guilds from the HTML content of the world guilds’ page.

Parameters:

content (str) – The HTML content of the page.

Returns:

List of guilds in the current world. None if it’s the list of a world that doesn’t exist.

Return type:

GuildsSection

Raises:

InvalidContent – If content is not the HTML of a guild’s page.

classmethod get_url(world)

Get the Tibia.com URL for the guild section of a specific world.

Parameters:

world (str) – The name of the world.

Returns:

The URL to the guild’s page

Return type:

str

to_json(*, indent=None, sort_keys=False)

Get the object’s JSON representation.

Parameters:

• indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.

• sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.

Returns:

JSON representation of the object.

Return type:

str

Guild

class tibiapy.Guild(name=None, world=None, **kwargs)

A Tibia guild, viewed from its guild’s page.

name

The name of the guild.

Type:

str

logo_url

The URL to the guild’s logo.

Type:

str

description

The description of the guild.

Type:

str, optional

world

The world this guild belongs to.

Type:

str

founded

The day the guild was founded.

Type:

datetime.date

active

Whether the guild is active or still in formation.

Type:

bool

guildhall

The guild’s guildhall if any.

Type:

GuildHouse, optional

open_applications

Whether applications are open or not.

Type:

bool

active_war

Whether the guild is currently in an active war or not.

New in version 3.0.0.

Type:

bool

disband_date

The date when the guild will be disbanded if the condition hasn’t been meet.

Type:

datetime.datetime, optional

disband_condition

The reason why the guild will get disbanded.

Type:

str, optional

homepage

The guild’s homepage, if any.

Type:

str, optional

members

List of guild members.

Type:

list of GuildMember

invites

List of invited characters.

Type:

list of GuildInvite

property member_count

The number of members in the guild.

Type:

int

property online_count

The number of online members in the guild.

Type:

int

property online_members

List of currently online members.

Type:

list of GuildMember

property ranks: List[str]

Ranks in their hierarchical order.

Type:

list of str

property members_by_rank: Dict[str, List[GuildMember]]

Get a mapping of members, grouped by their guild rank.

Type:

dict

classmethod from_content(content)

Create an instance of the class from the HTML content of the guild’s page.

Parameters:

content (str) – The HTML content of the page.

Returns:

The guild contained in the page or None if it doesn’t exist.

Return type:

Guild

Raises:

InvalidContent – If content is not the HTML of a guild’s page.

classmethod get_url(name)

Get the Tibia.com URL for a given guild name.

Parameters:

name (str) – The name of the guild.

Returns:

The URL to the guild’s page.

Return type:

str

classmethod get_url_wars(name)

Get the Tibia.com URL for the guild wars of a guild with a given name.

New in version 3.0.0.

Parameters:

name (str) – The name of the guild.

Returns:

The URL to the guild’s wars page.

Return type:

str

to_json(*, indent=None, sort_keys=False)

Get the object’s JSON representation.

Parameters:

• indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.

• sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.

Returns:

JSON representation of the object.

Return type:

str

property url

The URL to the guild’s information page on Tibia.com.

Type:

str

property url_wars

str The URL to the guild’s wars page on Tibia.com.

New in version 3.0.0.

GuildEntry

class tibiapy.GuildEntry(name, world, logo_url=None, description=None, active=False)

Represents a Tibia guild in the guild list of a world.

name

The name of the guild.

Type:

str

logo_url

The URL to the guild’s logo.

Type:

str

description

The description of the guild.

Type:

str, optional

world

The world this guild belongs to.

Type:

str

active

Whether the guild is active or still in formation.

Type:

bool

classmethod get_url(name)

Get the Tibia.com URL for a given guild name.

Parameters:

name (str) – The name of the guild.

Returns:

The URL to the guild’s page.

Return type:

str

classmethod get_url_wars(name)

Get the Tibia.com URL for the guild wars of a guild with a given name.

New in version 3.0.0.

Parameters:

name (str) – The name of the guild.

Returns:

The URL to the guild’s wars page.

Return type:

str

to_json(*, indent=None, sort_keys=False)

Get the object’s JSON representation.

Parameters:

• indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.

• sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.

Returns:

JSON representation of the object.

Return type:

str

property url

The URL to the guild’s information page on Tibia.com.

Type:

str

property url_wars

str The URL to the guild’s wars page on Tibia.com.

New in version 3.0.0.

Auxiliary Classes

GuildInvite

class tibiapy.GuildInvite(name=None, date=None)

Represents an invited character.

name

The name of the character

Type:

str

date

The day when the character was invited.

Type:

datetime.date

classmethod get_url(name)

Get the Tibia.com URL for a given character name.

Parameters:

name (str) – The name of the character.

Returns:

The URL to the character’s page.

Return type:

str

to_json(*, indent=None, sort_keys=False)

Get the object’s JSON representation.

Parameters:

• indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.

• sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.

Returns:

JSON representation of the object.

Return type:

str

property url

The URL of the character’s information page on Tibia.com.

Type:

str

GuildHouse

class tibiapy.GuildHouse(name, world=None, owner=None, paid_until_date=None)

A guildhall owned by a guild.

By limitation of Tibia.com, the ID of the guildhall is not available.

name

The name of the house.

Type:

str

world

The name of the world the house belongs to.

Type:

str

status

The current status of the house.

This is kept for compatibility with house objects and will always be HouseStatus.RENTED.

Type:

HouseStatus

type

The type of the house.

This is kept for compatibility with house objects and will always be HouseType.GUILDHALL.

Type:

HouseType

owner

The owner of the guildhall.

Type:

str

paid_until_date

The date the last paid rent is due.

Type:

datetime.date

classmethod get_url(house_id, world)

Get the Tibia.com URL for a house with the given id and world.

Parameters:

• house_id (int) – The internal id of the house.

• world (str) – The world of the house.

Return type:

The URL to the house in Tibia.com

to_json(*, indent=None, sort_keys=False)

Get the object’s JSON representation.

Parameters:

• indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.

• sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.

Returns:

JSON representation of the object.

Return type:

str

GuildMember

class tibiapy.GuildMember(name=None, rank=None, title=None, level=0, vocation=None, **kwargs)

Represents a guild member.

rank

The rank the member belongs to

Type:

str

name

The name of the guild member.

Type:

str

title

The member’s title.

Type:

str, optional

level

The member’s level.

Type:

int

vocation

The member’s vocation.

Type:

Vocation

joined

The day the member joined the guild.

Type:

datetime.date

online

Whether the member is online or not.

Type:

bool

classmethod get_url(name)

Get the Tibia.com URL for a given character name.

Parameters:

name (str) – The name of the character.

Returns:

The URL to the character’s page.

Return type:

str

to_json(*, indent=None, sort_keys=False)

Get the object’s JSON representation.

Parameters:

• indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.

• sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.

Returns:

JSON representation of the object.

Return type:

str

property url

The URL of the character’s information page on Tibia.com.

Type:

str

GuildWars

class tibiapy.GuildWars(name, current=None, history=None)

Represents a guild’s wars.

New in version 3.0.0.

name

The name of the guild.

Type:

str

current

The current war the guild is involved in.

Type:

GuildWarEntry

history

The previous wars the guild has been involved in.

Type:

list of GuildWarEntry

property url

The URL of this guild’s war page on Tibia.com.

Type:

str

classmethod get_url(name)

Get the URL to the guild’s war page of a guild with the given name.

Parameters:

name (str) – The name of the guild.

Returns:

The URL to the guild’s war page.

Return type:

str

classmethod from_content(content)

Get a guild’s war information from Tibia.com’s content.

Parameters:

content (str) – The HTML content of a guild’s war section in Tibia.com

Returns:

The guild’s war information.

Return type:

GuildWars

to_json(*, indent=None, sort_keys=False)

Get the object’s JSON representation.

Parameters:

• indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.

• sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.

Returns:

JSON representation of the object.

Return type:

str

GuildWarEntry

class tibiapy.GuildWarEntry(**kwargs)

Represents a guild war entry.

New in version 3.0.0.

guild_name

The name of the guild.

Type:

str

guild_score

The number of kills the guild has scored.

Type:

int

guild_fee

The number of gold coins the guild will pay if they lose the war.

Type:

int

opponent_name

The name of the opposing guild. If the guild no longer exist, this will be None.

Type:

str

opponent_score

The number of kills the opposing guild has scored.

Type:

int

opponent_fee

The number of gold coins the opposing guild will pay if they lose the war.

Type:

int

start_date

The date when the war started.

When a war is in progress, the start date is not visible.

Type:

datetime.date

score_limit

The number of kills needed to win the war.

Type:

int

duration

The set duration of the war.

When a war is in progress, the duration is not visible.

Type:

datetime.timedelta

end_date

The deadline for the war to finish if the score is not reached for wars in progress, or the date when the war ended.

Type:

datetime.date

winner

The name of the guild that won.

Note that if the winning guild is disbanded, this may be None.

Type:

str

surrender

Whether the losing guild surrendered or not.

Type:

bool

property guild_url

The URL to the guild’s information page on Tibia.com.

Type:

str

property opponent_guild_url

The URL to the opposing guild’s information page on Tibia.com.

Type:

str

to_json(*, indent=None, sort_keys=False)

Get the object’s JSON representation.

Parameters:

• indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.

• sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.

Returns:

JSON representation of the object.

Return type:

str

Highscores

Models related to Tibia.com’s Highscores section.

Highscores

class tibiapy.Highscores(world, category=Category.EXPERIENCE, **kwargs)

Represents the highscores of a world.

New in version 1.1.0.

world

The world the highscores belong to. If this is None, the highscores shown are for all worlds.

Type:

str

category

The selected category to displays the highscores of.

Type:

Category

vocation

The selected vocation to filter out values.

Type:

VocationFilter

battleye_filter

The selected BattlEye filter. If None, all worlds will be displayed.

Only applies for global highscores. Only characters from worlds with the matching BattlEye protection will be shown.

Type:

BattlEyeHighscoresFilter

pvp_types_filter

The selected PvP types filter. If None, all world will be displayed.

Only applies for global highscores. Only characters from worlds with the matching PvP type will be shown.

Type:

list of PvpTypeFilter

page

The page number being displayed.

Type:

int

total_pages

The total number of pages.

Type:

int

results_count

The total amount of highscores entries in this category. These may be shown in another page.

Type:

int

last_updated

How long ago were this results updated. The resolution is 1 minute.

Type:

datetime.timedelta

entries

The highscores entries found.

Type:

list of HighscoresEntry

available_worlds

The worlds available for selection.

Type:

list of str

property from_rank

The starting rank of the provided entries.

Type:

int

property to_rank

The last rank of the provided entries.

Type:

int

property url

The URL to the highscores page on Tibia.com containing the results.

Type:

str

property previous_page_url

The URL to the previous page of the current highscores, if there’s any.

Type:

str

property next_page_url

The URL to the next page of the current highscores, if there’s any.

Type:

str

get_page_url(page)

Get the URL to a specific page for the current highscores.

Parameters:

page (int) – The page to get the URL for.

Returns:

The URL to the page of the current highscores.

Return type:

str

Raises:

ValueError – The provided page is less or equals than zero.

classmethod from_content(content)

Create an instance of the class from the html content of a highscores page.

Notes

Tibia.com only shows up to 50 entries per page, so in order to obtain the full highscores, all pages must be obtained individually and merged into one.

Parameters:

content (str) – The HTML content of the page.

Returns:

The highscores results contained in the page.

Return type:

Highscores

Raises:

InvalidContent – If content is not the HTML of a highscore’s page.

classmethod get_url(world=None, category=Category.EXPERIENCE, vocation=VocationFilter.ALL, page=1, battleye_type=None, pvp_types=None)

Get the Tibia.com URL of the highscores for the given parameters.

Parameters:

• world (str, optional) – The game world of the desired highscores. If no world is passed, ALL worlds are shown.

• category (Category) – The desired highscores category.

• vocation (VocationFilter) – The vocation filter to apply. By default all vocations will be shown.

• page (int) – The page of highscores to show.

• battleye_type (BattlEyeHighscoresFilter, optional) – The battleEye filters to use.

• pvp_types (list of PvpTypeFilter, optional) – The list of PvP types to filter the results for.

Return type:

The URL to the Tibia.com highscores.

to_json(*, indent=None, sort_keys=False)

Get the object’s JSON representation.

Parameters:

• indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.

• sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.

Returns:

JSON representation of the object.

Return type:

str

HighscoresEntry

class tibiapy.HighscoresEntry(rank, name, vocation, world, level, value)

Represents a entry for the highscores.

name

The name of the character.

Type:

str

rank

The character’s rank in the respective highscores.

Type:

int

vocation

The character’s vocation.

Type:

Vocation

world

The character’s world.

Type:

str

level

The character’s level.

Type:

int

value

The character’s value for the highscores.

Type:

int

classmethod get_url(name)

Get the Tibia.com URL for a given character name.

Parameters:

name (str) – The name of the character.

Returns:

The URL to the character’s page.

Return type:

str

to_json(*, indent=None, sort_keys=False)

Get the object’s JSON representation.

Parameters:

• indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.

• sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.

Returns:

JSON representation of the object.

Return type:

str

property url

The URL of the character’s information page on Tibia.com.

Type:

str

LoyaltyHighscoresEntry

class tibiapy.LoyaltyHighscoresEntry(rank, name, vocation, world, level, value, title)

Represents a entry for the highscores loyalty points category.

This is a subclass of HighscoresEntry, adding an extra field for title.

name

The name of the character.

Type:

str

rank

The character’s rank in the respective highscores.

Type:

int

vocation

The character’s vocation.

Type:

Vocation

world

The character’s world.

Type:

str

level

The character’s level.

Type:

int

value

The character’s loyalty points.

Type:

int

title

The character’s loyalty title.

Type:

str

classmethod get_url(name)

Get the Tibia.com URL for a given character name.

Parameters:

name (str) – The name of the character.

Returns:

The URL to the character’s page.

Return type:

str

to_json(*, indent=None, sort_keys=False)

Get the object’s JSON representation.

Parameters:

• indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.

• sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.

Returns:

JSON representation of the object.

Return type:

str

property url

The URL of the character’s information page on Tibia.com.

Type:

str

Houses

Models related to Tibia.com’s Houses section.

HousesSection

class tibiapy.HousesSection(**kwargs)

Represents the house section.

New in version 5.0.0.

world

The selected world to show houses for.

Type:

str

town

The town to show houses for.

Type:

str

status

The status to show. If None, any status is shown.

Type:

HouseStatus

house_type

The type of houses to show.

Type:

HouseType

order

The ordering to use for the results.

Type:

HouseOrder

entries

The houses matching the filters.

Type:

list of HouseEntry

available_worlds

The list of available worlds to choose from.

Type:

list of str

available_towns

The list of available towns to choose from.

Type:

list of str

property url

Get the URL to the houses section with the current parameters.

Type:

str

classmethod get_url(world, town, house_type, status=None, order=None)

Get the URL to the house list on Tibia.com with the specified filters.

Parameters:

• world (str) – The world to search in.

• town (str) – The town to show results for.

• house_type (HouseType) – The type of houses to show.

• status (HouseStatus) – The status of the houses to show.

• order (HouseOrder) – The sorting parameter to use for the results.

Returns:

The URL to the list matching the parameters.

Return type:

str

classmethod from_content(content)

Parse the content of a house list from Tibia.com into a list of houses.

Parameters:

content (str) – The raw HTML response from the house list.

Returns:

The houses found in the page.

Return type:

HouseSection

Raises:

InvalidContent` – Content is not the house list from Tibia.com

to_json(*, indent=None, sort_keys=False)

Get the object’s JSON representation.

Parameters:

• indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.

• sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.

Returns:

JSON representation of the object.

Return type:

str

House

class tibiapy.House(name, world=None, **kwargs)

Represents a house in a specific world.

id

The internal ID of the house. This is used on the website to identify houses.

Type:

int

name

The name of the house.

Type:

str

world

The name of the world the house belongs to.

Type:

str

status

The current status of the house.

Type:

HouseStatus

type

The type of the house.

Type:

HouseType

image_url

The URL to the house’s minimap image.

Type:

str

beds

The number of beds the house has.

Type:

int

size

The number of SQM the house has.

Type:

int

rent

The monthly cost paid for the house, in gold coins.

Type:

int

owner

The current owner of the house, if any.

Type:

str

owner_sex

The sex of the owner of the house, if applicable.

Type:

Sex

paid_until

The date the last paid rent is due.

Type:

datetime.datetime, optional

transfer_date

The date when the owner will move out of the house, if applicable.

Type:

datetime.datetime, optional

transferee

The character who will receive the house when the owner moves, if applicable.

Type:

str, optional

transfer_price

The price that will be paid from the transferee to the owner for the house transfer.

Type:

int

transfer_accepted

Whether the house transfer has already been accepted or not.

Type:

bool

highest_bid

The currently highest bid on the house if it is being auctioned.

Type:

int

highest_bidder

The character that holds the highest bid.

Type:

str, optional

auction_end

The date when the auction will end.

Type:

datetime.datetime, optional

property owner_url

The URL to the Tibia.com page of the house’s owner, if applicable.

Type:

str

property transferee_url

The URL to the Tibia.com page of the character receiving the house, if applicable.

Type:

str

property highest_bidder_url

The URL to the Tibia.com page of the character with the highest bid, if applicable.

Type:

str

classmethod from_content(content)

Parse a Tibia.com response into a House object.

Parameters:

content (str) – HTML content of the page.

Returns:

The house contained in the page, or None if the house doesn’t exist.

Return type:

House

Raises:

InvalidContent – If the content is not the house section on Tibia.com

classmethod get_url(house_id, world)

Get the Tibia.com URL for a house with the given id and world.

Parameters:

• house_id (int) – The internal id of the house.

• world (str) – The world of the house.

Return type:

The URL to the house in Tibia.com

to_json(*, indent=None, sort_keys=False)

Get the object’s JSON representation.

Parameters:

• indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.

• sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.

Returns:

JSON representation of the object.

Return type:

str

property url

The URL to the Tibia.com page of the house.

Type:

str

HouseEntry

class tibiapy.HouseEntry(name, world, houseid, **kwargs)

Represents a house from the house list in Tibia.com.

id

The internal ID of the house. This is used on the website to identify houses.

Type:

int

name

The name of the house.

Type:

str

world

The name of the world the house belongs to.

Type:

str

status

The current status of the house.

Type:

HouseStatus

type

The type of house.

Type:

HouseType

town

The town where the house is located.

Type:

str

size

The size of the house in SQM.

Type:

int

rent

The monthly cost of the house, in gold coins.

Type:

int

time_left

The number of days or hours left until the bid ends, if it has started. This is not an exact measure, it is rounded to hours or days.

Type:

datetime.timedelta, optional

highest_bid

The highest bid so far, if the auction has started.

Type:

int, optional.

classmethod get_url(house_id, world)

Get the Tibia.com URL for a house with the given id and world.

Parameters:

• house_id (int) – The internal id of the house.

• world (str) – The world of the house.

Return type:

The URL to the house in Tibia.com

to_json(*, indent=None, sort_keys=False)

Get the object’s JSON representation.

Parameters:

• indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.

• sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.

Returns:

JSON representation of the object.

Return type:

str

property url

The URL to the Tibia.com page of the house.

Type:

str

Leaderboard

Models related to Tibia.com’s Leaderboard section.

Leaderboard

class tibiapy.Leaderboard(world, rotation, **kwargs)

Represents the Tibiadrome leaderboards.

New in version 5.0.0.

world

The world this leaderboards are for.

Type:

str

available_worlds

The worlds available for selection.

Type:

list of str

rotation

The rotation this leaderboards’ entries are for.

Type:

LeaderboardRotation

available_rotations

The available rotations for selection.

Type:

list of LeaderboardRotation

entries

The list of entries in this leaderboard.

Type:

list of LeaderboardEntry

last_update

How long ago was the currently displayed data updated. Only available for the current rotation.

Type:

datetime.timedelta

page

The page number being displayed.

Type:

int

total_pages

The total number of pages.

Type:

int

results_count

The total amount of entries in this rotation. These may be shown in another page.

Type:

int

property url

The URL to the current leaderboard.

Type:

str

property previous_page_url

The URL to the previous page of the current leaderboard results, if there’s any.

Type:

str

property next_page_url

The URL to the next page of the current leaderboard results, if there’s any.

Type:

str

get_page_url(page)

Get the URL of the leaderboard at a specific page, with the current date parameters.

Parameters:

page (int) – The desired page.

Returns:

The URL to the desired page.

Return type:

str

Raises:

ValueError – If the specified page is zer or less.

classmethod get_url(world, rotation_id=None, page=1)

Get the URL to the leaderboards of a world.

Parameters:

• world (str) – The desired world.

• rotation_id (int) – The ID of the desired rotation. If undefined, the current rotation is shown.

• page (int) – The desired page. By default, the first page is returned.

Returns:

The URL to the leaderboard with the desired parameters.

Return type:

str

Raises:

ValueError – If the specified page is zer or less.

classmethod from_content(content)

Parse the content of the leaderboards page.

Parameters:

content (str) – The HTML content of the leaderboards page.

Returns:

The ledaerboard if found.

Return type:

Leaderboard

to_json(*, indent=None, sort_keys=False)

Get the object’s JSON representation.

Parameters:

• indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.

• sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.

Returns:

JSON representation of the object.

Return type:

str

Auxiliary Classes

LeaderboardRotation

class tibiapy.LeaderboardRotation(rotation_id, end_date, current=False)

A leaderboard rotation.

New in version 5.0.0.

Parameters:

• rotation_id (int) – The internal ID of the rotation.

• current (bool) – Whether this is the currently running rotation or not.

• end_date (datetime.datetime) – The date and time when this rotation ends.

to_json(*, indent=None, sort_keys=False)

Get the object’s JSON representation.

Parameters:

• indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.

• sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.

Returns:

JSON representation of the object.

Return type:

str

LeaderboardEntry

class tibiapy.LeaderboardEntry(rank, name, drome_level)

Represents a single leadeboard entry.

Parameters:

• rank (int) – The rank of this entry.

• name (str) – The name of the character.

• drome_level (int) – The Tibia Drome level of this entry.

classmethod get_url(name)

Get the Tibia.com URL for a given character name.

Parameters:

name (str) – The name of the character.

Returns:

The URL to the character’s page.

Return type:

str

to_json(*, indent=None, sort_keys=False)

Get the object’s JSON representation.

Parameters:

• indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.

• sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.

Returns:

JSON representation of the object.

Return type:

str

property url

The URL of the character’s information page on Tibia.com.

Type:

str

Tournaments

Models related to Tibia.com’s Tournaments section.

Tournament

class tibiapy.Tournament(**kwargs)

Represents a tournament’s information.

New in version 2.5.0.

title

The title of the tournament.

Type:

str

cycle

An internal number used to get direct access to a specific tournament in the archive.

This will only be present when viewing an archived tournament, otherwise it will default to 0.

Type:

int

phase

The current phase of the tournament.

Type:

TournamentPhase

start_date

The start date of the tournament.

Type:

datetime.datetime

end_date

The end date of the tournament.

Type:

datetime.datetime

worlds

The worlds where this tournament is active on.

Type:

list of str

rule_set

The specific rules for this tournament.

Type:

RuleSet

score_set

The ways to gain points in the tournament.

Type:

ScoreSet

reward_set

The list of rewards awarded for the specified ranges.

Type:

list of RewardEntry

archived_tournaments

The list of other archived tournaments. This is only present when viewing an archived tournament.

Type:

list of TournamentEntry

property rewards_range

The range of ranks that might receive rewards.

Type:

tuple

property duration

The total duration of the tournament.

Type:

datetime.timedelta

rewards_for_rank(rank)

Get the rewards for a given rank, if any.

Parameters:

rank (int) – The rank to check.

Returns:

The rewards for the given rank or None if there are no rewards.

Return type:

RewardEntry, optional

classmethod from_content(content)

Create an instance of the class from the html content of the tournament’s page.

Parameters:

content (str) – The HTML content of the page.

Returns:

The tournament contained in the page, or None if the tournament doesn’t exist.

Return type:

Tournament

Raises:

InvalidContent – If content is not the HTML of a tournament’s page.

classmethod get_url(tournament_cycle)

Get the URL to a tournament’s information page.

If its cycle is provided, otherwise it shows the current tournament.

Parameters:

tournament_cycle (int) – The tournament’s cycle.

Returns:

The URL to the specified tournament.

Return type:

str

to_json(*, indent=None, sort_keys=False)

Get the object’s JSON representation.

Parameters:

• indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.

• sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.

Returns:

JSON representation of the object.

Return type:

str

property url

The URL to the tournament’s information page.

Type:

str

TournamentLeaderboard

class tibiapy.TournamentLeaderboard(**kwargs)

Represents a tournament’s leaderboards.

New in version 2.5.0.

world

The world this leaderboard belongs to.

Type:

str

tournament

The tournament this leaderboard belongs to.

Type:

TournamentEntry

entries

The leaderboard entries.

Type:

list of TournamentLeaderboardEntry

results_count

The total number of leaderboard entries. These might be in a different page.

Type:

int

property from_rank

The starting rank of the provided entries.

Type:

int

property to_rank

The last rank of the provided entries.

Type:

int

property page

The page number the shown results correspond to on Tibia.com.

Type:

int

property total_pages

The total of pages in the leaderboard.

Type:

int

property url

Get the URL to the current leaderboard and page.

Type:

str

classmethod get_url(world, tournament_cycle, page=1)

Get the URL to the leaderboards of a specific world, tournament and page.

Parameters:

• world (str) – The world to get the leaderboards for.

• tournament_cycle (int) – The cycle of the tournament to get the leaderboards for.

• page (int) – The leader board’s page to view. By default 1.

Return type:

The URL to the specified leaderboard.

classmethod from_content(content)

Create an instance of the class from the html content of the tournament’s leaderboards page.

Parameters:

content (str) – The HTML content of the page.

Returns:

The tournament contained in the page, or None if the tournament leaderboard doesn’t exist.

Return type:

TournamentLeaderboard

Raises:

InvalidContent – If content is not the HTML of a tournament’s leaderboard page.

to_json(*, indent=None, sort_keys=False)

Get the object’s JSON representation.

Parameters:

• indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.

• sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.

Returns:

JSON representation of the object.

Return type:

str

Auxiliary Classes

TournamentEntry

class tibiapy.TournamentEntry(title, start_date, end_date, **kwargs)

Represents an tournament in the archived tournaments list.

start_date and end_date might be None when a tournament that is currently running is on the list (e.g. on the leaderboards tournament selection section).

New in version 2.5.0.

title

The title of the tournament.

Type:

str

cycle

An internal number used to get direct access to a specific tournament in the archive.

Type:

int

start_date

The start date of the tournament.

Type:

datetime.date

end_date

The end date of the tournament.

Type:

datetime.date

property duration

The total duration of the tournament.

Type:

datetime.timedelta

classmethod get_url(tournament_cycle)

Get the URL to a tournament’s information page.

If its cycle is provided, otherwise it shows the current tournament.

Parameters:

tournament_cycle (int) – The tournament’s cycle.

Returns:

The URL to the specified tournament.

Return type:

str

to_json(*, indent=None, sort_keys=False)

Get the object’s JSON representation.

Parameters:

• indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.

• sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.

Returns:

JSON representation of the object.

Return type:

str

property url

The URL to the tournament’s information page.

Type:

str

TournamentLeaderboardEntry

class tibiapy.TournamentLeaderboardEntry(**kwargs)

Represents a single tournament leaderboard’s entry.

New in version 2.5.0.

name

The character’s name.

Type:

str

rank

The entry’s rank.

Type:

int

change

The entry’s change in rank since the last server save.

Type:

int

vocation

The character’s vocation. This will always show the base vocation, without promotions.

Type:

Vocation

score

The entry’s score.

Type:

int

classmethod get_url(name)

Get the Tibia.com URL for a given character name.

Parameters:

name (str) – The name of the character.

Returns:

The URL to the character’s page.

Return type:

str

to_json(*, indent=None, sort_keys=False)

Get the object’s JSON representation.

Parameters:

• indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.

• sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.

Returns:

JSON representation of the object.

Return type:

str

property url

The URL of the character’s information page on Tibia.com.

Type:

str

RewardEntry

class tibiapy.RewardEntry(**kwargs)

Represents the rewards for a specific rank range.

initial_rank

The highest rank that gets this reward.

Type:

int

last_rank

The lowest rank that gets this reward.

Type:

int

tibia_coins

The amount of tibia coins awarded.

Type:

:class`int`

tournament_coins

The amount of tournament coins awarded.

Type:

int

tournament_ticket_voucher

The amount of tournament ticker vouchers awarded.

Type:

int

cup

The type of cup awarded.

Type:

str

deed

The type of deed awarded.

Type:

str

other_rewards

Other rewards given for this rank.

Type:

str

to_json(*, indent=None, sort_keys=False)

Get the object’s JSON representation.

Parameters:

• indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.

• sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.

Returns:

JSON representation of the object.

Return type:

str

RuleSet

class tibiapy.RuleSet(**kwargs)

Contains the tournament rule set.

pvp_type

The PvP type of the tournament.

Type:

PvPType

daily_tournament_playtime

The maximum amount of time participants can play each day.

Type:

datetime.timedelta

total_tournament_playtime

The total amount of time participants can play in the tournament.

Type:

datetime.timedelta

playtime_reduced_only_in_combat

Whether playtime will only be reduced while in combat or not.

Type:

bool

death_penalty_modifier

The modifier for the death penalty.

Type:

float

xp_multiplier

The multiplier for experience gained.

Type:

float

skill_multiplier

The multiplier for skill gained.

Type:

float

spawn_rate_multiplier

The multiplier for the spawn rate.

Type:

float

loot_probability

The multiplier for the loot rate.

Type:

float

rent_percentage

The percentage of rent prices relative to the regular price.

Type:

int

house_auction_durations

The duration of house auctions.

Type:

int

shared_xp_bonus

Whether there is a bonus for sharing experience or not.

Type:

bool

to_json(*, indent=None, sort_keys=False)

Get the object’s JSON representation.

Parameters:

• indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.

• sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.

Returns:

JSON representation of the object.

Return type:

str

ScoreSet

class tibiapy.ScoreSet(**kwargs)

Represents the ways to earn or lose points in the tournament.

New in version 2.5.0.

creature_kills

Points received for participating in creature kills.

Type:

dict

level_gain_loss

The points gained for leveling up or lost for losing a level.

Type:

int

skill_gain_loss

The points gained for leveling up or lost for losing a skill level.

Type:

int

charm_point_multiplier

The multiplier for every charm point.

Type:

int

character_death

The points lost for dying.

Type:

int

area_discovery

Points that will be added to the score for discovering an area entirely.

Type:

int

to_json(*, indent=None, sort_keys=False)

Get the object’s JSON representation.

Parameters:

• indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.

• sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.

Returns:

JSON representation of the object.

Return type:

str

Forums

Models related to Tibia.com’s Forum section.

CMPostArchive

class tibiapy.CMPostArchive(**kwargs)

Represents the CM Post Archive.

The CM Post Archive is a collection of posts made in the forum by community managers.

New in version 3.0.0.

start_date

The start date of the displayed posts.

Type:

datetime.date

end_date

The end date of the displayed posts.

Type:

datetime.date

page

The currently displayed page.

Type:

int

total_pages

The number of pages available.

Type:

int

results_count

The total number of results available in the selected date range.

Type:

int

posts

The list of posts for the selected range.

Type:

list of CMPost

property url

The URL of the CM Post Archive with the current parameters.

Type:

str

property previous_page_url

The URL to the previous page of the current CM Post Archive results, if there’s any.

Type:

str

property next_page_url

The URL to the next page of the current CM Post Archive results, if there’s any.

Type:

str

get_page_url(page)

Get the URL of the CM Post Archive at a specific page, with the current date parameters.

Parameters:

page (int) – The desired page.

Returns:

The URL to the desired page.

Return type:

str

classmethod get_url(start_date, end_date, page=1)

Get the URL to the CM Post Archive for the given date range.

Parameters:

• start_date – The start date to display.

• end_date – The end date to display.

• page (int) – The desired page to display.

Returns:

The URL to the CM Post Archive

Return type:

str

Raises:

• TypeError: – Either of the dates is not an instance of datetime.date

• ValueError: – If start_date is more recent than end_date.

classmethod from_content(content)

Parse the content of the CM Post Archive page from Tibia.com.

Parameters:

content (str) – The HTML content of the CM Post Archive in Tibia.com

Returns:

The CM Post archive found in the page.

Return type:

CMPostArchive

Raises:

InvalidContent – If content is not the HTML content of the CM Post Archive in Tibia.com

to_json(*, indent=None, sort_keys=False)

Get the object’s JSON representation.

Parameters:

• indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.

• sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.

Returns:

JSON representation of the object.

Return type:

str

ForumAnnouncement

class tibiapy.ForumAnnouncement(**kwargs)

Represents a forum announcement.

These are a special kind of thread that are shown at the top of boards. They cannot be replied to and they show no view counts.

New in version 3.0.0.

announcement_id

The id of the announcement.

Type:

int

board

The board this thread belongs to.

Type:

str

section

The board section this thread belongs to.

Type:

str

board_id

The internal id of the board the post is in.

Type:

int

section_id

The internal id of the section the post is in.

Type:

int

author

The author of the announcement.

Type:

ForumAuthor

title

The title of the announcement.

Type:

str

content

The HTML content of the announcement.

Type:

str

start_date

The starting date of the announcement.

Type:

datetime.datetime

end_date

The end date of the announcement.

Type:

datetime.datetime

classmethod from_content(content, announcement_id=0)

Parse the content of an announcement’s page from Tibia.com.

Parameters:

• content (str) – The HTML content of an announcement in Tibia.com

• announcement_id (int) – The id of the announcement. Since there is no way to obtain the id from the page, the id may be passed to assing.

Returns:

The announcement contained in the page or None if not found.

Return type:

ForumAnnouncement

Raises:

InvalidContent – If content is not the HTML content of an announcement page in Tibia.com

classmethod get_url(announcement_id)

Get the URL to an announcement with a given ID.

Parameters:

announcement_id (int) – The ID of the announcement

Returns:

The URL of the announcement.

Return type:

str

to_json(*, indent=None, sort_keys=False)

Get the object’s JSON representation.

Parameters:

• indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.

• sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.

Returns:

JSON representation of the object.

Return type:

str

property url

str Get the URL to this announcement.

ForumBoard

class tibiapy.ForumBoard(**kwargs)

Represents a forum’s board.

New in version 3.0.0.

name

The name of the board.

Type:

str

section

The section of the board.

Type:

str

current_page

The current page being viewed.

Type:

int

pages

The number of pages the board has for the current display range.

Type:

int

age

The maximum age of the displayed threads, in days.

-1 means all threads will be shown.

Type:

ìnt

announcements

The list of announcements currently visible.

Type:

list of AnnouncementEntry

threads

The list of threads currently visible.

Type:

list of ThreadEntry

property url

The URL of this board.

Type:

str

property previous_page_url

The URL to the previous page of the board, if there’s any.

Type:

str

property next_page_url

The URL to the next page of the board, if there’s any.

Type:

str

get_page_url(page)

Get the URL to a given page of the board.

Parameters:

page (int) – The desired page.

Returns:

The URL to the desired page.

Return type:

str

classmethod from_content(content)

Parse the board’s HTML content from Tibia.com.

Parameters:

content (str) – The HTML content of the board.

Returns:

The forum board contained.

Return type:

ForumBoard

Raises:

InvalidContent` – Content is not a board in Tibia.com

classmethod get_community_boards_url()

Get the URL to the Community Boards section in Tibia.com.

Returns:

The URL to the Community Boards.

Return type:

str

classmethod get_support_boards_url()

Get the URL to the Support Boards section in Tibia.com.

Returns:

The URL to the Support Boards.

Return type:

str

classmethod get_trade_boards_url()

Get the URL to the Trade Boards section in Tibia.com.

Returns:

The URL to the Trade Boards.

Return type:

str

classmethod get_url(board_id, page=1, age=30)

Get the Tibia.com URL to a board with a given id.

Parameters:

• board_id (int) – The ID of the board.

• page (int) – The page to go to.

• age (int) – The age in days of the threads to display.

Returns:

The URL to the board.

Return type:

str

classmethod get_world_boards_url()

Get the URL to the World Boards section in Tibia.com.

Returns:

The URL to the World Boards.

Return type:

str

to_json(*, indent=None, sort_keys=False)

Get the object’s JSON representation.

Parameters:

• indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.

• sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.

Returns:

JSON representation of the object.

Return type:

str

ForumPost

class tibiapy.ForumPost(**kwargs)

Represents a forum post.

New in version 3.0.0.

author

The author of the post.

Type:

ForumAuthor

emoticon

The emoticon selected for the post.

Type:

ForumEmoticon

title

The title of the post.

Type:

str, optional

content

The content of the post.

Type:

str

signature

The signature of the post.

Type:

str

post_id

The id of the post.

Type:

int

posted_date

The date when the post was made.

Type:

datetime.datetime

edited_date

The date when the post was last edited, if applicable.

Type:

datetime.datetime, optional

edited_by

The character that edited the post.

This is usually the same author, but in some occasions staff members edit the posts of others.

Type:

str, optional

classmethod get_url(post_id)

Get the URL to a specific post.

Parameters:

post_id (int) – The ID of the desired post.

Returns:

The URL to the post.

Return type:

str

to_json(*, indent=None, sort_keys=False)

Get the object’s JSON representation.

Parameters:

• indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.

• sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.

Returns:

JSON representation of the object.

Return type:

str

property url

Get the URL to this specific post.

Type:

str

ForumThread

class tibiapy.ForumThread(**kwargs)

Represents a forum thread.

New in version 3.0.0.

title

The title of the thread.

Type:

str

thread_id

The thread’s number.

Type:

int

board

The board this thread belongs to.

Type:

str

section

The board section this thread belongs to.

Type:

str

previous_topic_number

The number of the previous topic.

Type:

int

next_topic_number

The number of the next topic.

Type:

int

pages

The number of total_pages this thread has.

Type:

int

current_page

The page being viewed.

Type:

int

posts

The list of posts the thread has.

Type:

list of ForumPost

golden_frame

Whether the thread has a golden frame or not.

In the Proposals board,a golden frame means the thread has a reply by a staff member.

Type:

bool

anchored_post

The post where the page is anchored to, if any.

When a post is fetched directly, the thread that contains it is displayed, anchored to the specific post.

Type:

ForumPost

property url

The URL of this thread and current page.

Type:

str

property previous_page_url

The URL to the previous page of the thread, if there’s any.

Type:

str

property next_page_url

The URL to the next page of the thread, if there’s any.

Type:

str

property previous_thread_url

The URL to the previous topic of the board, if there’s any.

Type:

str

property next_thread_url

The URL to the next topic of the board, if there’s any.

Type:

str

get_page_url(page)

Get the URL to a given page of the board.

Parameters:

page (int) – The desired page.

Returns:

The URL to the desired page.

Return type:

str

classmethod from_content(content)

Create an instance of the class from the html content of the thread’s page.

Parameters:

content (str) – The HTML content of the page.

Returns:

The thread contained in the page, or None if the thread doesn’t exist

Return type:

ForumThread

Raises:

InvalidContent – If content is not the HTML of a thread’s page.

classmethod get_url(thread_id, page=1)

Get the URL to a thread with a given id.

Parameters:

• thread_id (int) – The id of the desired thread.

• page (int) – The desired page, by default 1.

Returns:

The URL to the thread.

Return type:

str

to_json(*, indent=None, sort_keys=False)

Get the object’s JSON representation.

Parameters:

• indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.

• sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.

Returns:

JSON representation of the object.

Return type:

str

AnnouncementEntry

class tibiapy.AnnouncementEntry(**kwargs)

Represents an announcement in the forum boards.

New in version 3.0.0.

title

The title of the announcement.

Type:

str

announcement_id

The internal id of the announcement.

Type:

int

announcement_author

The character that made the announcement.

Type:

str

classmethod get_url(announcement_id)

Get the URL to an announcement with a given ID.

Parameters:

announcement_id (int) – The ID of the announcement

Returns:

The URL of the announcement.

Return type:

str

to_json(*, indent=None, sort_keys=False)

Get the object’s JSON representation.

Parameters:

• indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.

• sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.

Returns:

JSON representation of the object.

Return type:

str

property url

str Get the URL to this announcement.

BoardEntry

class tibiapy.BoardEntry(**kwargs)

Represents a board in the list of boards.

This is the board information available when viewing a section (e.g. World, Trade, Community)

New in version 3.0.0.

name

The name of the board.

Type:

str

board_id

The board’s internal id.

Type:

int

description

The description of the board.

Type:

str

posts

The number of posts in this board.

Type:

int

threads

The number of threads in this board.

Type:

int

last_post

The information of the last post made in this board.

Type:

LastPost

classmethod list_from_content(content)

Parse the content of a board list Tibia.com into a list of boards.

Parameters:

content (str) – The raw HTML response from the board list.

Return type:

list of BoardEntry

Raises:

InvalidContent` – Content is not a board list in Tibia.com

classmethod get_community_boards_url()

Get the URL to the Community Boards section in Tibia.com.

Returns:

The URL to the Community Boards.

Return type:

str

classmethod get_support_boards_url()

Get the URL to the Support Boards section in Tibia.com.

Returns:

The URL to the Support Boards.

Return type:

str

classmethod get_trade_boards_url()

Get the URL to the Trade Boards section in Tibia.com.

Returns:

The URL to the Trade Boards.

Return type:

str

classmethod get_url(board_id, page=1, age=30)

Get the Tibia.com URL to a board with a given id.

Parameters:

• board_id (int) – The ID of the board.

• page (int) – The page to go to.

• age (int) – The age in days of the threads to display.

Returns:

The URL to the board.

Return type:

str

classmethod get_world_boards_url()

Get the URL to the World Boards section in Tibia.com.

Returns:

The URL to the World Boards.

Return type:

str

to_json(*, indent=None, sort_keys=False)

Get the object’s JSON representation.

Parameters:

• indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.

• sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.

Returns:

JSON representation of the object.

Return type:

str

property url

The URL of this board.

Type:

str

ThreadEntry

class tibiapy.ThreadEntry(**kwargs)

Represents a thread in a forum board.

New in version 3.0.0.

title

The title of the thread.

Type:

str

thread_id

The internal id of the thread.

Type:

int

thread_starter

The character that started the thread.

Type:

str

thread_starter_traded

Whether the thread starter was recently traded or not. .. versionadded:: 5.0.0

Type:

bool

replies

The number of replies.

Type:

int

views

The number of views.

Type:

int

last_post

The information of the last post made in this board.

Type:

LastPost

status

The status of the thread.

Type:

ThreadStatus

status_icon

The URL of the icon displayed as status.

Type:

str

emoticon

The emoticon used for the thread.

Type:

ForumEmoticon

pages

The number of pages the thread has.

Type:

int

golden_frame

Whether the thread has a gold frame or not.

In the Proposals board, the gold frame indicates that a staff member has replied in the thread.

Type:

bool

classmethod get_url(thread_id, page=1)

Get the URL to a thread with a given id.

Parameters:

• thread_id (int) – The id of the desired thread.

• page (int) – The desired page, by default 1.

Returns:

The URL to the thread.

Return type:

str

to_json(*, indent=None, sort_keys=False)

Get the object’s JSON representation.

Parameters:

• indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.

• sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.

Returns:

JSON representation of the object.

Return type:

str

property url

The URL to the thread in Tibia.com.

Type:

str

Auxiliary Classes

CMPost

class tibiapy.CMPost(**kwargs)

Represents a CM Post entry.

New in version 3.0.0.

post_id

The ID of the post.

Type:

int

date

The date when the post was made.

Type:

datetime.date

board

The name of the board where the post was made.

Type:

str

thread_title

The title of the thread where the post is.

Type:

str

classmethod get_url(post_id)

Get the URL to a specific post.

Parameters:

post_id (int) – The ID of the desired post.

Returns:

The URL to the post.

Return type:

str

to_json(*, indent=None, sort_keys=False)

Get the object’s JSON representation.

Parameters:

• indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.

• sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.

Returns:

JSON representation of the object.

Return type:

str

property url

Get the URL to this specific post.

Type:

str

ForumAuthor

class tibiapy.ForumAuthor(name, **kwargs)

Represents a post’s author.

New in version 3.0.0.

name

The name of the character, author of the post.

Type:

str

level

The level of the character.

Type:

int

world

The world the character belongs to.

Type:

str

position

The character’s position, if any.

Type:

str

title

The character’s selected title, if any.

Type:

str

vocation

The vocation of the character.

Type:

Vocation

guild

The guild the author belongs to, if any.

Type:

GuildMembership

posts

The number of posts this character has made.

Type:

int

deleted

Whether the author is deleted or not.

Type:

bool

traded

Whether the author is traded or not.

New in version 4.0.0.

Type:

bool

classmethod get_url(name)

Get the Tibia.com URL for a given character name.

Parameters:

name (str) – The name of the character.

Returns:

The URL to the character’s page.

Return type:

str

to_json(*, indent=None, sort_keys=False)

Get the object’s JSON representation.

Parameters:

• indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.

• sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.

Returns:

JSON representation of the object.

Return type:

str

property url

The URL of the character’s information page on Tibia.com.

Type:

str

ForumEmoticon

class tibiapy.ForumEmoticon(name, url)

Represents a forum’s emoticon.

New in version 3.0.0.

name

The emoticon’s name.

Type:

str

url

The URL to the emoticon`s image.

Type:

str

to_json(*, indent=None, sort_keys=False)

Get the object’s JSON representation.

Parameters:

• indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.

• sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.

Returns:

JSON representation of the object.

Return type:

str

LastPost

class tibiapy.LastPost(author, post_id, date, *, deleted=False, traded=False)

Represents a forum thread.

New in version 3.0.0.

author

The name of the character that made the last post.

Type:

str

post_id

The internal id of the post.

Type:

int

date

The date when the last post was made.

Type:

datetime.datetime

deleted

Whether the last post’s author is a character that is already deleted.

Type:

bool

traded

Whether the last post’s author was recently traded. .. versionadded:: 5.0.0

Type:

bool

property author_url

The URL to the author’s character information page.

Type:

str

classmethod get_url(post_id)

Get the URL to a specific post.

Parameters:

post_id (int) – The ID of the desired post.

Returns:

The URL to the post.

Return type:

str

to_json(*, indent=None, sort_keys=False)

Get the object’s JSON representation.

Parameters:

• indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.

• sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.

Returns:

JSON representation of the object.

Return type:

str

property url

Get the URL to this specific post.

Type:

str

News

Models related to Tibia.com’s News section. This also contains the Event Calendar

NewsArchive

class tibiapy.NewsArchive(**kwargs)

Represents the news archive.

New in version 5.0.0.

start_date

The start date to show news for.

Type:

datetime.date

end_date

The end date to show news for.

Type:

datetime.date

types

The type of news to show.

Type:

list of NewsType

categories

The categories to show.

Type:

list of NewsCategory.

entries

The news matching the provided parameters.

Type:

list of NewsEntry

classmethod get_form_data(start_date, end_date, categories=None, types=None)

Get the form data attributes to search news with specific parameters.

Parameters:

• start_date (datetime.date) – The beginning date to search dates in.

• end_date (datetime.date) – The end date to search dates in.

• categories (list of NewsCategory) – The allowed categories to show. If left blank, all categories will be searched.

• types (list of NewsType) – The allowed news types to show. if unused, all types will be searched.

Returns:

A dictionary with the required form data to search news in the archive.

Return type:

dict

classmethod get_url()

Get the URL to Tibia.com’s news archive page.

Notes

It is not possible to perform a search using query parameters. News searches can only be performed using POST requests sending the parameters as form-data.

Returns:

The URL to the news archive page on Tibia.com.

Return type:

str

classmethod from_content(content)

Get a list of news from the HTML content of the news search page.

Parameters:

content (str) – The HTML content of the page.

Returns:

The news archive with the news found.

Return type:

NewsArchive

Raises:

InvalidContent – If content is not the HTML of a news search’s page.

to_json(*, indent=None, sort_keys=False)

Get the object’s JSON representation.

Parameters:

• indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.

• sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.

Returns:

JSON representation of the object.

Return type:

str

News

class tibiapy.News(news_id, title, content, date, category, **kwargs)

Represents a news entry.

id

The internal ID of the news entry.

Type:

int

title

The title of the news entry.

Type:

str

category

The category this belongs to.

Type:

NewsCategory

category_icon

The URL of the icon corresponding to the category.

Type:

str

date

The date when the news were published.

Type:

datetime.date

content

The raw html content of the entry.

Type:

str, optional

thread_id

The thread id of the designated discussion thread for this entry.

Type:

int, optional

property thread_url

The URL to the thread discussing this news entry, if any.

Type:

str

classmethod from_content(content, news_id=0)

Get a news entry by its HTML content from Tibia.com.

Notes

Since there’s no way to obtain the entry’s Id from the page contents, it will always be 0. A news_id can be passed to set the news_id of the resulting object.

Parameters:

• content (str) – The HTML content of the page.

• news_id (int, optional) – The news_id belonging to the content being parsed.

Returns:

The news article found in the page.

Return type:

News

Raises:

InvalidContent – If content is not the HTML of a news’ page.

classmethod get_list_url()

Get the URL to Tibia.com’s news archive page.

Notes

It is not possible to perform a search using query parameters. News searches can only be performed using POST requests sending the parameters as form-data.

Returns:

The URL to the news archive page on Tibia.com.

Return type:

str

classmethod get_url(news_id)

Get the Tibia.com URL for a news entry by its id.

Parameters:

news_id (int) – The id of the news entry.

Returns:

The URL to the news’ page

Return type:

str

to_json(*, indent=None, sort_keys=False)

Get the object’s JSON representation.

Parameters:

• indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.

• sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.

Returns:

JSON representation of the object.

Return type:

str

property url

The URL to the Tibia.com page of the news entry.

Type:

str

NewsEntry

class tibiapy.NewsEntry(news_id, title, news_type, category, date, **kwargs)

A news entry from the news archive.

id

The internal ID of the news entry.

Type:

int

title

The title of the news entry. News tickers have a fragment of their content as a title.

Type:

str

category

The category this belongs to.

Type:

NewsCategory

category_icon

The URL of the icon corresponding to the category.

Type:

str

date

The date when the news were published.

Type:

datetime.date

type

The type of news of this list entry.

Type:

NewsType

classmethod get_list_url()

Get the URL to Tibia.com’s news archive page.

Notes

It is not possible to perform a search using query parameters. News searches can only be performed using POST requests sending the parameters as form-data.

Returns:

The URL to the news archive page on Tibia.com.

Return type:

str

classmethod get_url(news_id)

Get the Tibia.com URL for a news entry by its id.

Parameters:

news_id (int) – The id of the news entry.

Returns:

The URL to the news’ page

Return type:

str

to_json(*, indent=None, sort_keys=False)

Get the object’s JSON representation.

Parameters:

• indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.

• sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.

Returns:

JSON representation of the object.

Return type:

str

property url

The URL to the Tibia.com page of the news entry.

Type:

str

EventSchedule

class tibiapy.EventSchedule(month, year, **kwargs)

Represents the event’s calendar in Tibia.com.

month

The month being displayed.

Note that some days from the previous and next month may be included too.

Type:

int

year

The year being displayed.

Type:

int

events

A list of events that happen during this month.

It might include some events from the previous and next months as well.

Type:

list of EventEntry

property url

Get the URL to the event calendar with the current parameters.

Type:

str

get_events_on(date)

Get a list of events that are active during the specified desired_date.

Parameters:

date (datetime.date) – The date to check.

Returns:

The events that are active during the desired_date, if any.

Return type:

list of EventEntry

Notes

Dates outside the calendar’s month and year may yield unexpected results.

classmethod get_url(month=None, year=None)

Get the URL to the Event Schedule or Event Calendar on Tibia.com.

Notes

If no parameters are passed, it will show the calendar for the current month and year.

Tibia.com limits the dates that the calendar displays, passing a month and year far from the current ones may result in the response being for the current month and year instead.

Parameters:

• month (int, optional) – The desired month.

• year (int, optional) – The desired year.

Returns:

The URL to the calendar with the given parameters.

Return type:

str

classmethod from_content(content)

Create an instance of the class from the html content of the event’s calendar.

Parameters:

content (str) – The HTML content of the page.

Returns:

The event calendar contained in the page

Return type:

EventSchedule

Raises:

InvalidContent – If content is not the HTML of the event’s schedule page.

to_json(*, indent=None, sort_keys=False)

Get the object’s JSON representation.

Parameters:

• indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.

• sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.

Returns:

JSON representation of the object.

Return type:

str

EventEntry

class tibiapy.EventEntry(title, description, **kwargs)

Represents an event’s entry in the calendar.

title

The title of the event.

Type:

str

description

The description of the event.

Type:

str

start_date

The day the event starts.

If the event is continuing from the previous month, this will be None.

Type:

datetime.date

end_date

The day the event ends.

If the event is continuing on the next month, this will be None.

Type:

datetime.date

property duration

The number of days this event will be active for.

Type:

int

to_json(*, indent=None, sort_keys=False)

Get the object’s JSON representation.

Parameters:

• indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.

• sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.

Returns:

JSON representation of the object.

Return type:

str

Bazaar

Models related to Tibia.com’s Bazaar section.

CharacterBazaar

class tibiapy.CharacterBazaar(**kwargs)

Represents the char bazaar.

page

The page being currently viewed.

Type:

int

total_pages

The total number of pages available.

Type:

int

results_count

The number of auctions listed.

Type:

int

entries

The auctions displayed.

Type:

list of AuctionEntry

type

The type of auctions being displayed, either current or auction history.

Type:

BazaarType

filters

The currently set filtering options.

Type:

AuctionFilters

property url

Get the URL to the bazaar.

Type:

str

classmethod get_current_auctions_url(page=1, filters=None)

Get the URL to the list of current auctions in Tibia.com.

Parameters:

• page (int) – The page to show the URL for.

• filters (AuctionFilters) – The filtering criteria to use.

Returns:

The URL to the current auctions section in Tibia.com

Return type:

str

classmethod get_auctions_history_url(page=1, filters=None)

Get the URL to the auction history in Tibia.com.

Parameters:

• page (int) – The page to show the URL for.

• filters (AuctionFilters) – The filtering criteria to use.

Returns:

The URL to the auction history section in Tibia.com

Return type:

str

classmethod from_content(content)

Get the bazaar’s information and list of auctions from Tibia.com.

Parameters:

content (str) – The HTML content of the bazaar section at Tibia.com.

Returns:

The character bazaar with the entries found.

Return type:

CharacterBazaar

to_json(*, indent=None, sort_keys=False)

Get the object’s JSON representation.

Parameters:

• indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.

• sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.

Returns:

JSON representation of the object.

Return type:

str

AuctionEntry

class tibiapy.AuctionEntry(**kwargs)

Represents an auction in the list, containing the summary.

auction_id

The internal id of the auction.

Type:

int

name

The name of the character.

Type:

str

level

The level of the character.

Type:

int

world

The world the character is in.

Type:

str

vocation

The vocation of the character.

Type:

Vocation

sex

The sex of the character.

Type:

Sex

outfit

The current outfit selected by the user.

Type:

OutfitImage

displayed_items

The items selected to be displayed.

Type:

list of DisplayItem

sales_arguments

The sale arguments selected for the auction.

Type:

list of SalesArgument

auction_start

The date when the auction started.

Type:

datetime.datetime

auction_end

The date when the auction ends.

Type:

datetime.datetime

bid

The current bid in Tibia Coins.

Type:

int

bid_type

The type of the auction’s bid.

Type:

BidType

status

The current status of the auction.

Type:

AuctionStatus

property character_url

The URL of the character’s information page on Tibia.com.

Type:

str

property url

The URL to this auction’s detail page on Tibia.com.

Type:

str

classmethod get_url(auction_id)

Get the URL to the Tibia.com detail page of an auction with a given id.

Parameters:

auction_id (int) – The ID of the auction.

Returns:

The URL to the auction’s detail page.

Return type:

str

to_json(*, indent=None, sort_keys=False)

Get the object’s JSON representation.

Parameters:

• indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.

• sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.

Returns:

JSON representation of the object.

Return type:

str

Auction

class tibiapy.Auction(**kwargs)

The details of an auction.

auction_id

The internal id of the auction.

Type:

int

name

The name of the character.

Type:

str

level

The level of the character.

Type:

int

world

The world the character is in.

Type:

str

vocation

The vocation of the character.

Type:

Vocation

sex

The sex of the character.

Type:

Sex

outfit

The current outfit selected by the user.

Type:

OutfitImage

displayed_items

The items selected to be displayed.

Type:

list of DisplayItem

sales_arguments

The sale arguments selected for the auction.

Type:

list of SalesArgument

auction_start

The date when the auction started.

Type:

datetime.datetime

auction_end

The date when the auction ends.

Type:

datetime.datetime

bid

The current bid in Tibia Coins.

Type:

int

bid_type

The type of the auction’s bid.

Type:

BidType

status

The current status of the auction.

Type:

AuctionStatus

hit_points

The hit points of the character.

Type:

int

mana

The mana points of the character.

Type:

int

capacity

The character’s capacity in ounces.

Type:

int

speed

The character’s speed.

Type:

int

blessings_count

The number of blessings the character has.

Type:

int

outfits_count

The number of outfits the character has.

Type:

int

titles_count

The number of titles the character has.

Type:

int

skills

The current skills of the character.

Type:

list of SkillEntry

creation_date

The date when the character was created.

Type:

datetime.datetime

experience

The total experience of the character.

Type:

int

gold

The total amount of gold the character has.

Type:

int

achievement_points

The number of achievement points of the character.

Type:

int

regular_world_transfer_available_date

The date after regular world transfers will be available to purchase and use. None indicates it is available immediately.

Type:

datetime.datetmie

charm_expansion

Whether the character has a charm expansion or not.

Type:

bool

available_charm_points

The amount of charm points the character has available to spend.

Type:

int

spent_charm_points

The total charm points the character has spent.

Type:

int

prey_wildcards

The number of Prey Wildcards the character has.

Type:

int

daly_reward_streak

The current daily reward streak.

Type:

int

permanent_hunting_task_slots

The number of hunting task slots.

Type:

int

permanent_prey_slots

The number of prey slots.

Type:

int

hirelings

The number of hirelings the character has.

Type:

int

hireling_jobs

The number of hireling jobs the character has.

Type:

int

hireling_outfits

The number of hireling outfits the character has.

Type:

int

exalted_dust

The amount of exalted dust the character has.

Type:

int

exalted_dust_limit

The dust limit of the character.

Type:

int

items

The items the character has across inventory, depot and item stash.

Type:

ItemSummary

store_items

The store items the character has.

Type:

ItemSummary

mounts

The mounts the character has unlocked.

Type:

Mounts

store_mounts

The mounts the character has purchased from the store.

Type:

Mounts

outfits

The outfits the character has unlocked.

Type:

Outfits

store_outfits

The outfits the character has purchased from the store.

Type:

Outfits

familiars

The familiars the character has purchased or unlocked.

Type:

Familiars

blessings

The blessings the character has.

Type:

list of BlessingEntry

imbuements

The imbuements the character has unlocked access to.

Type:

list of str

charms

The charms the character has unlocked.

Type:

list of CharmEntry

completed_cyclopedia_map_areas

The cyclopedia map areas that the character has fully discovered.

Type:

list of str

completed_quest_lines

The quest lines the character has fully completed.

Type:

list of str

titles

The titles the character has unlocked.

Type:

list of str

achievements

The achievements the character has unlocked.

Type:

list of AchievementEntry

bestiary_progress

The bestiary progress of the character.

Type:

list of BestiaryEntry

property completed_bestiary_entries

Get a list of completed bestiary entries.

Type:

list of BestiaryEntry

property regular_world_transfer_available

Whether regular world transfers are available immediately for this character.

Type:

bool

property skills_map: Dict[str, SkillEntry]

A mapping of skills by their name.

Type:

dict of str, SkillEntry

classmethod from_content(content, auction_id=0, skip_details=False)

Parse an auction detail page from Tibia.com and extracts its data.

Parameters:

• content (str) – The HTML content of the auction detail page in Tibia.com

• auction_id (int, optional) –

  The ID of the auction.

  It is not possible to extract the ID from the page’s content, so it may be passed to assign it manually.

• skip_details (bool, optional) –

  Whether to skip parsing the entire auction and only parse the information shown in lists. False by default.

  This allows fetching basic information like name, level, vocation, world, bid and status, shaving off some parsing time.

Returns:

The auction details if found, None otherwise.

Return type:

Auction

Raises:

InvalidContent – If the content does not belong to a auction detail’s page.

property character_url

The URL of the character’s information page on Tibia.com.

Type:

str

classmethod get_url(auction_id)

Get the URL to the Tibia.com detail page of an auction with a given id.

Parameters:

auction_id (int) – The ID of the auction.

Returns:

The URL to the auction’s detail page.

Return type:

str

to_json(*, indent=None, sort_keys=False)

Get the object’s JSON representation.

Parameters:

• indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.

• sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.

Returns:

JSON representation of the object.

Return type:

str

property url

The URL to this auction’s detail page on Tibia.com.

Type:

str

Auxiliary Classes

AchievementEntry

class tibiapy.AchievementEntry(name, secret=False)

An unlocked achievement by the character.

name

The name of the achievement.

Type:

str

secret

Whether the achievement is secret or not.

Type:

bool

to_json(*, indent=None, sort_keys=False)

Get the object’s JSON representation.

Parameters:

• indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.

• sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.

Returns:

JSON representation of the object.

Return type:

str

AuctionFilters

class tibiapy.AuctionFilters(**kwargs)

The auction filters available in the auctions section.

All attributes are optional.

world

The character’s world to show characters for.

Type:

str

pvp_type

The PvP type of the character’s worlds to show.

Type:

PvpTypeFilter

battleye

The type of BattlEye protection of the character’s worlds to show.

Type:

BattlEyeTypeFilter

vocation

The character vocation to show results for.

Type:

VocationAuctionFilter

min_level

The minimum level to display.

Type:

int

max_level

The maximum level to display.

Type:

int

skill

The skill to filter by its level range.

Type:

SkillFilter

min_skill_level

The minimum skill level of the selected skill to display.

Type:

int

max_skill_level

The maximum skill level of the selected skill to display.

Type:

int

search_string

The search term to filter out auctions.

Type:

str

search_type

The type of search to use. Defines the behaviour of search_string.

Type:

AuctionSearchType

available_worlds

The list of available worlds to select to filter.

Type:

list of str

property query_params

The query parameters representing this filter.

Type:

dict

to_json(*, indent=None, sort_keys=False)

Get the object’s JSON representation.

Parameters:

• indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.

• sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.

Returns:

JSON representation of the object.

Return type:

str

BestiaryEntry

class tibiapy.BestiaryEntry(name, kills, step)

The bestiary progress for a specific creature.

name

The name of the creature.

Type:

str

kills

The number of kills of this creature the player has done.

Type:

int

step

The current step to unlock this creature the character is in, where 4 is fully unlocked.

Type:

int

property completed

Whether the entry is completed or not.

Type:

bool

to_json(*, indent=None, sort_keys=False)

Get the object’s JSON representation.

Parameters:

• indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.

• sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.

Returns:

JSON representation of the object.

Return type:

str

BlessingEntry

class tibiapy.BlessingEntry(name, amount=0)

A character’s blessings.

name

The name of the blessing.

Type:

str

amount

The amount of blessing charges the character has.

Type:

int

to_json(*, indent=None, sort_keys=False)

Get the object’s JSON representation.

Parameters:

• indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.

• sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.

Returns:

JSON representation of the object.

Return type:

str

CharmsEntry

class tibiapy.CharmEntry(name, cost=0)

An unlocked charm by the character.

name

The name of the charm.

Type:

str

cost

The cost of the charm in charm points.

Type:

int

to_json(*, indent=None, sort_keys=False)

Get the object’s JSON representation.

Parameters:

• indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.

• sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.

Returns:

JSON representation of the object.

Return type:

str

DisplayFamiliar

class tibiapy.DisplayFamiliar(**kwargs)

Represents a familiar owned or unlocked by the character.

image_url

The URL to the image.

Type:

str

name

The familiar’s name.

Type:

str

familiar_id

The internal ID of the familiar.

Type:

int

to_json(*, indent=None, sort_keys=False)

Get the object’s JSON representation.

Parameters:

• indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.

• sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.

Returns:

JSON representation of the object.

Return type:

str

DisplayItem

class tibiapy.DisplayItem(**kwargs)

Represents an item displayed on an auction, or the character’s items in the auction detail.

image_url

The URL to the item’s image.

Type:

str

name

The item’s name.

Type:

str

description

The item’s description, if any.

Type:

str

count

The item’s count.

Type:

int

item_id

The item’s client id.

Type:

int

to_json(*, indent=None, sort_keys=False)

Get the object’s JSON representation.

Parameters:

• indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.

• sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.

Returns:

JSON representation of the object.

Return type:

str

DisplayMount

class tibiapy.DisplayMount(**kwargs)

Represents a mount owned or unlocked by the character.

image_url

The URL to the image.

Type:

str

name

The mount’s name.

Type:

str

mount_id

The internal ID of the mount.

Type:

int

to_json(*, indent=None, sort_keys=False)

Get the object’s JSON representation.

Parameters:

• indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.

• sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.

Returns:

JSON representation of the object.

Return type:

str

DisplayOutfit

class tibiapy.DisplayOutfit(**kwargs)

Represents an outfit owned or unlocked by the character.

image_url

The URL to the image.

Type:

str

name

The outfit’s name.

Type:

str

outfit_id

The internal ID of the outfit.

Type:

int

addons

The unlocked or owned addons for this outfit.

Type:

int

to_json(*, indent=None, sort_keys=False)

Get the object’s JSON representation.

Parameters:

• indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.

• sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.

Returns:

JSON representation of the object.

Return type:

str

Familiars

class tibiapy.Familiars(**kwargs)

The familiars the character has unlocked or purchased.

page

The current page being displayed.

Type:

int

total_pages

The total number of pages.

Type:

int

results

The total number of results.

Type:

int

entries

The familiars the character has unlocked or purchased.

Type:

list of DisplayFamiliar

fully_fetched

Whether the summary was fetched completely, including all other pages.

Type:

bool

entry_class

alias of DisplayFamiliar

get_by_id(entry_id)

Get an outfit by its familiar id.

Parameters:

entry_id (int) – The ID of the outfit.

Returns:

The outfit matching the id.

Return type:

DisplayOutfit

get_by_name(name)

Get an entry by its name.

Parameters:

name (str) – The name of the entry, case insensitive.

Returns:

The entry matching the name.

Return type:

object

search(value)

Search an entry by its name.

Parameters:

value (str) – The value to look for.

Returns:

A list of entries with names containing the search term.

Return type:

list

to_json(*, indent=None, sort_keys=False)

Get the object’s JSON representation.

Parameters:

• indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.

• sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.

Returns:

JSON representation of the object.

Return type:

str

ItemSummary

class tibiapy.ItemSummary(**kwargs)

Items in a character’s inventory and depot.

page

The current page being displayed.

Type:

int

total_pages

The total number of pages.

Type:

int

results

The total number of results.

Type:

int

entries

The character’s items.

Type:

list of DisplayItem

fully_fetched

Whether the summary was fetched completely, including all other pages.

Type:

bool

entry_class

alias of DisplayItem

get_by_id(entry_id)

Get an item by its item id.

Parameters:

entry_id (int) – The ID of the item.

Returns:

The item matching the id.

Return type:

DisplayItem

get_by_name(name)

Get an entry by its name.

Parameters:

name (str) – The name of the entry, case insensitive.

Returns:

The entry matching the name.

Return type:

object

search(value)

Search an entry by its name.

Parameters:

value (str) – The value to look for.

Returns:

A list of entries with names containing the search term.

Return type:

list

to_json(*, indent=None, sort_keys=False)

Get the object’s JSON representation.

Parameters:

• indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.

• sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.

Returns:

JSON representation of the object.

Return type:

str

Mounts

class tibiapy.Mounts(**kwargs)

The mounts a character has unlocked or purchased.

page

The current page being displayed.

Type:

int

total_pages

The total number of pages.

Type:

int

results

The total number of results.

Type:

int

entries

The character’s mounts.

Type:

list of DisplayMount

fully_fetched

Whether the summary was fetched completely, including all other pages.

Type:

bool

entry_class

alias of DisplayMount

get_by_id(entry_id)

Get a mount by its mount id.

Parameters:

entry_id (int) – The ID of the mount.

Returns:

The mount matching the id.

Return type:

DisplayMount

get_by_name(name)

Get an entry by its name.

Parameters:

name (str) – The name of the entry, case insensitive.

Returns:

The entry matching the name.

Return type:

object

search(value)

Search an entry by its name.

Parameters:

value (str) – The value to look for.

Returns:

A list of entries with names containing the search term.

Return type:

list

to_json(*, indent=None, sort_keys=False)

Get the object’s JSON representation.

Parameters:

• indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.

• sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.

Returns:

JSON representation of the object.

Return type:

str

OutfitImage

class tibiapy.OutfitImage(**kwargs)

The image of the outfit currently being worn by the character.

image_url

The URL of the image.

Type:

str

outfit_id

The ID of the outfit.

Type:

int

addons

The addons displayed in the outfit.

Type:

int

to_json(*, indent=None, sort_keys=False)

Get the object’s JSON representation.

Parameters:

• indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.

• sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.

Returns:

JSON representation of the object.

Return type:

str

Outfits

class tibiapy.Outfits(**kwargs)

The outfits the character has unlocked or purchased.

page

The current page being displayed.

Type:

int

total_pages

The total number of pages.

Type:

int

results

The total number of results.

Type:

int

entries

The outfits the character has unlocked or purchased.

Type:

list of DisplayOutfit

fully_fetched

Whether the summary was fetched completely, including all other pages.

Type:

bool

entry_class

alias of DisplayOutfit

get_by_id(entry_id)

Get an outfit by its outfit id.

Parameters:

entry_id (int) – The ID of the outfit.

Returns:

The outfit matching the id.

Return type:

DisplayOutfit

get_by_name(name)

Get an entry by its name.

Parameters:

name (str) – The name of the entry, case insensitive.

Returns:

The entry matching the name.

Return type:

object

search(value)

Search an entry by its name.

Parameters:

value (str) – The value to look for.

Returns:

A list of entries with names containing the search term.

Return type:

list

to_json(*, indent=None, sort_keys=False)

Get the object’s JSON representation.

Parameters:

• indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.

• sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.

Returns:

JSON representation of the object.

Return type:

str

SalesArgument

class tibiapy.SalesArgument(**kwargs)

Represents a sales argument.

Sales arguments can be selected when creating an auction, and allow the user to highlight certain character features in the auction listing.

category_image

The URL to the category icon.

Type:

str

content

The content of the sales argument.

Type:

str

to_json(*, indent=None, sort_keys=False)

Get the object’s JSON representation.

Parameters:

• indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.

• sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.

Returns:

JSON representation of the object.

Return type:

str

SkillEntry

class tibiapy.SkillEntry(**kwargs)

Represents the character’s skills.

name

The name of the skill.

Type:

name

level

The current level.

Type:

int

progress

The percentage of progress for the next level.

Type:

float

to_json(*, indent=None, sort_keys=False)

Get the object’s JSON representation.

Parameters:

• indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.

• sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.

Returns:

JSON representation of the object.

Return type:

str

Kill Statistics

KillStatistics

class tibiapy.KillStatistics(world, entries=None, total=None, available_worlds=None)

Represents the kill statistics of a world.

world

The world the statistics belong to.

Type:

str

entries

A dictionary of kills entries of every race, where the key is the name of the race.

Type:

dict

total

The kill statistics totals.

Type:

RaceEntry

available_worlds

The list of worlds available for selection.

Type:

list of str

property url

The URL to the kill statistics page on Tibia.com containing the results.

Type:

str

property players

The kill statistics for players.

Type:

RaceEntry

classmethod get_url(world)

Get the Tibia.com URL of the kill statistics of a world.

Parameters:

world (str) – The game world of the desired kill statistics.

Return type:

The URL to the Tibia.com kill statistics for this world.

classmethod from_content(content)

Create an instance of the class from the HTML content of the kill statistics’ page.

Parameters:

content (str) – The HTML content of the page.

Returns:

The kill statistics contained in the page or None if it doesn’t exist.

Return type:

KillStatistics

Raises:

InvalidContent – If content is not the HTML of a kill statistics’ page.

to_json(*, indent=None, sort_keys=False)

Get the object’s JSON representation.

Parameters:

• indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.

• sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.

Returns:

JSON representation of the object.

Return type:

str

RaceEntry

class tibiapy.RaceEntry(last_day_killed=0, last_day_players_killed=0, last_week_killed=0, last_week_players_killed=0)

Represents the statistics of a race.

last_day_killed

Number of creatures of this race killed in the last day.

Type:

int

last_day_players_killed

Number of players killed by this race in the last day.

Type:

int

last_week_killed

Number of creatures of this race killed in the last week.

Type:

int

last_week_players_killed

Number of players killed by this race in the last week.

Type:

int

to_json(*, indent=None, sort_keys=False)

Get the object’s JSON representation.

Parameters:

• indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.

• sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.

Returns:

JSON representation of the object.

Return type:

str

Library

CreaturesSection

class tibiapy.CreaturesSection(boosted_creature, creatures)

Represents the creature’s section in the Tibia.com library.

boosted_creature

The current boosted creature.

Type:

CreatureEntry

creatures

The list of creatures in the library.

Type:

list of CreatureEntry

classmethod get_url()

Get the URL to the Tibia.com library section.

Returns:

The URL to the Tibia.com library section.

Return type:

str

classmethod boosted_creature_from_header(content)

Get the boosted creature from any Tibia.com page.

Parameters:

content (str) – The HTML content of a Tibia.com page.

Returns:

The boosted creature of the day.

Return type:

CreatureEntry

Raises:

InvalidContent – If content is not the HTML of a Tibia.com’s page.

classmethod from_content(content)

Create an instance of the class from the html content of the creature library’s page.

Parameters:

content (str) – The HTML content of the page.

Returns:

The creatures section from Tibia.com.

Return type:

CreaturesSection

Raises:

InvalidContent – If content is not the HTML of a creature library’s page.

to_json(*, indent=None, sort_keys=False)

Get the object’s JSON representation.

Parameters:

• indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.

• sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.

Returns:

JSON representation of the object.

Return type:

str

Creature

class tibiapy.Creature(name, identifier, **kwargs)

Represents a creature’s details on the Tibia.com library.

name

The name of the creature, in plural form.

Type:

str

identifier

The race’s internal name. Used for links and images.

Type:

str

description

A description of the creature.

Type:

str

hitpoints

The number of hitpoints the creature has.

Type:

int

experience

The number of experience points given for killing this creature.

Type:

int

immune_to

The elements this creature is immune to.

Type:

list of str

weak_against

The elements this creature is weak against.

Type:

list of str

strong_against

The elements this creature is strong against.

Type:

list of str

loot

Some of the items this creature drops.

Type:

str

mana_cost

The mana neccessary to summon or convince this creature.

Type:

int, optional

summonable

Whether this creature can be summoned or not.

Type:

bool

convinceable

Whether this creature can be convinced or not.

Type:

bool

classmethod from_content(content)

Create an instance of the class from the html content of the creature library’s page.

Parameters:

content (str) – The HTML content of the page.

Returns:

The character contained in the page.

Return type:

Creature

classmethod get_url(identifier)

Get the URL to the creature’s detail page on Tibia.com.

Parameters:

identifier (str) – The race’s internal name.

Returns:

The URL to the detail page.

Return type:

str

property image_url

The URL to this creature’s image.

Type:

str

to_json(*, indent=None, sort_keys=False)

Get the object’s JSON representation.

Parameters:

• indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.

• sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.

Returns:

JSON representation of the object.

Return type:

str

property url

The URL to this creature’s details.

Type:

str

CreatureEntry

class tibiapy.CreatureEntry(name, identifier=None)

Represents a creature in the Library section.

name

The name of the creature, usually in plural, except for the boosted creature.

Type:

str

identifier

The internal name of the creature’s race. Used for links and images.

Type:

str

property url

The URL to this creature’s details.

Type:

str

property image_url

The URL to this creature’s image.

Type:

str

classmethod get_url(identifier)

Get the URL to the creature’s detail page on Tibia.com.

Parameters:

identifier (str) – The race’s internal name.

Returns:

The URL to the detail page.

Return type:

str

to_json(*, indent=None, sort_keys=False)

Get the object’s JSON representation.

Parameters:

• indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.

• sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.

Returns:

JSON representation of the object.

Return type:

str

BoostableBosses

class tibiapy.BoostableBosses(boosted_boss, bosses)

Represents the boostable bosses section in the Tibia.com library

boosted_boss

The current boosted boss.

Type:

BossEntry

bosses

The list of boostable bosses.

Type:

list of BossEntry

classmethod get_url()

Get the URL to the Tibia.com boostable bosses.

Returns:

The URL to the Tibia.com library section.

Return type:

str

classmethod from_content(content)

Create an instance of the class from the html content of the boostable bosses library’s page.

Parameters:

content (str) – The HTML content of the page.

Returns:

The Boostable Bosses section.

Return type:

BoostableBosses

Raises:

InvalidContent – If content is not the HTML of a creature library’s page.

classmethod boosted_boss_from_header(content)

Get the boosted boss from any Tibia.com page.

Parameters:

content (str) – The HTML content of a Tibia.com page.

Returns:

The boosted boss of the day.

Return type:

BossEntry

Raises:

InvalidContent – If content is not the HTML of a Tibia.com’s page.

to_json(*, indent=None, sort_keys=False)

Get the object’s JSON representation.

Parameters:

• indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.

• sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.

Returns:

JSON representation of the object.

Return type:

str

BoostedCreatures

class tibiapy.BoostedCreatures(creature, boss)

Contains both boosted creature and boosted boss.

creature

The boosted creature of the day.

Type:

CreatureEntry

boss

The boosted boss of the day.

Type:

BossEntry

classmethod from_header(content: str)

Parses both boosted creature and boss from the content of any section in Tibia.com

Parameters:

content (str) – The HTML content of the page.

Returns:

The boosted creature an boss.

Return type:

BoostedCreatures

Raises:

InvalidContent – If content is not the HTML of a Tibia.com page.

to_json(*, indent=None, sort_keys=False)

Get the object’s JSON representation.

Parameters:

• indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.

• sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.

Returns:

JSON representation of the object.

Return type:

str

BossEntry

class tibiapy.BossEntry(name, identifier=None)

Represents a boss in the boostable bosses section in the Tibia.com library.

name

The name of the boss..

Type:

str

identifier

The internal name of the boss. Used for images.

Type:

str

property image_url

The URL to this boss’s image.

Type:

str

to_json(*, indent=None, sort_keys=False)

Get the object’s JSON representation.

Parameters:

• indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.

• sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.

Returns:

JSON representation of the object.

Return type:

str

SpellsSection

class tibiapy.SpellsSection(**kwargs)

The spells section in Tibia.com.

New in version 5.0.0.

vocation

The selected vocation filter. If None, spells for any vocation will be shown.

Type:

VocationSpellFilter

group

The selected spell group to display. If None, spells for any group will be shown.

Type:

SpellGroup

spell_type

The selected spell type to display. If None, spells for any type will be shown.

Type:

SpellType

premium

The premium status to filter in. True to show only premium spells, False to show free account spells and None will show any spells.

Type:

bool

sort_by

The sorting order of the displayed spells.

Type:

SpellSorting

entries

The spells matching the selected filters.

Type:

SpellEntry

classmethod from_content(content)

Parse the content of the spells section.

Parameters:

content (str) – The HTML content of the page.

Returns:

The spells contained and the filtering information.

Return type:

SpellsSection

Raises:

InvalidContent – If content is not the HTML of the spells section.

classmethod get_url(*, vocation=None, group=None, spell_type=None, premium=None, sort=None)

Get the URL to the spells section with the desired filtering parameters.

Parameters:

• vocation (VocationSpellFilter, optional) – The vocation to filter in spells for.

• group (SpellGroup, optional) – The spell’s primary cooldown group.

• spell_type (SpellType, optional) – The type of spells to show.

• premium (bool, optional) – The type of premium requirement to filter. None means any premium requirement.

• sort (SpellSorting, optional) – The field to sort spells by.

Returns:

The URL to the spells section with the provided filtering parameters.

Return type:

str

to_json(*, indent=None, sort_keys=False)

Get the object’s JSON representation.

Parameters:

• indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.

• sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.

Returns:

JSON representation of the object.

Return type:

str

Spell

class tibiapy.Spell(identifier, name, words, **kwargs)

A spell listed on the spells section.

New in version 5.0.0.

name

The name of the spell.

Type:

str

words

The words to cast the spell.

Type:

str

group

The cooldown group of the spell.

Type:

SpellGroup

spell_type

The type of the spell

Type:

SpellType

exp_level

The required level to cast the spell.

Type:

int

mana

The mana required to use the spell. If None, the mana cost is variable.

Type:

int, optional.

price

The price in gold coins to learn the spell.

Type:

int

premium

Whether the spell requires a premium account to learn and use it.

Type:

bool

description

A description of the spells effect and history.

Type:

str

vocations

The vocations that can use this spell.

Type:

list of str

cooldown

The individual cooldown of this spell in seconds.

Type:

int

cooldown_group

The group cooldown of this spell in seconds.

Type:

int, optional

group_secondary

The secondary cooldown group of this spell, if any.

Type:

str, optional

cooldown_group_secondary

The secondary cooldown of this spell in seconds.

Type:

int, optional

soul_points

The number of soul points consumed by this spell. It will be None if not applicable.

Type:

int, optional

amount

The amount of objects created by this spell. It will be None if not applicable.

Type:

int, optional

magic_type

The type of magic of this spell. Influenced by specialized magic level attributes.

Type:

str, optional

cities

The cities where this spell can be learned.

Type:

list of str

rune

Information of the rune created by this spell, if applicable.

Type:

Rune, optinal

classmethod from_content(content)

Parse the content of a spells page.

Parameters:

content (str) – The HTML content of the page.

Returns:

The spell data. If the spell doesn’t exist, this will be None.

Return type:

Spell

Raises:

InvalidContent – If content is not the HTML of the spells section.

classmethod get_url(identifier)

Get the URL to a spell in the Tibia.com spells section.

Parameters:

identifier (str) – The identifier of the spell.

Returns:

The URL to the spell.

Return type:

str

property image_url

The URL to this spell’s image.

Type:

str

to_json(*, indent=None, sort_keys=False)

Get the object’s JSON representation.

Parameters:

• indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.

• sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.

Returns:

JSON representation of the object.

Return type:

str

property url

The URL to the spell.

Type:

str

SpellEntry

class tibiapy.SpellEntry(identifier, name, words, **kwargs)

A spell listed on the spells section.

New in version 5.0.0.

identifier

The internal identifier of the spell. This is used as a key for links and images.

Type:

str

name

The name of the spell.

Type:

str

words

The words to cast the spell.

Type:

str

group

The cooldown group of the spell.

Type:

SpellGroup

spell_type

The type of the spell

Type:

SpellType

exp_level

The required level to cast the spell.

Type:

int

mana

The mana required to use the spell. If None, the mana cost is variable.

Type:

int, optional.

price

The price in gold coins to learn the spell.

Type:

int

premium

Whether the spell requires a premium account to learn and use it.

Type:

bool

property url

The URL to the spell.

Type:

str

property image_url

The URL to this spell’s image.

Type:

str

classmethod get_url(identifier)

Get the URL to a spell in the Tibia.com spells section.

Parameters:

identifier (str) – The identifier of the spell.

Returns:

The URL to the spell.

Return type:

str

to_json(*, indent=None, sort_keys=False)

Get the object’s JSON representation.

Parameters:

• indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.

• sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.

Returns:

JSON representation of the object.

Return type:

str

Base Classes

The following classes are not meant to be used or instantiated, but are documented here for informational purposes.

They implement methods and properties that can be inherited by other classes to implement their functionality.

class tibiapy.abc.BaseAnnouncement

Base class for all announcement classes.

Implement common properties and methods for announcements.

The following implement this class:

• ForumAnnouncement

• AnnouncementEntry

announcement_id

The ID of the announcement.

Type:

int

property url

str Get the URL to this announcement.

classmethod get_url(announcement_id)

Get the URL to an announcement with a given ID.

Parameters:

announcement_id (int) – The ID of the announcement

Returns:

The URL of the announcement.

Return type:

str

class tibiapy.abc.BaseBoard

Base class for all board classes.

Implements common properties and methods for boards.

The following implement this class:

• ForumBoard

• BoardEntry

board_id

The ID of the board.

Type:

int

property url

The URL of this board.

Type:

str

classmethod get_url(board_id, page=1, age=30)

Get the Tibia.com URL to a board with a given id.

Parameters:

• board_id (int) – The ID of the board.

• page (int) – The page to go to.

• age (int) – The age in days of the threads to display.

Returns:

The URL to the board.

Return type:

str

classmethod get_world_boards_url()

Get the URL to the World Boards section in Tibia.com.

Returns:

The URL to the World Boards.

Return type:

str

classmethod get_trade_boards_url()

Get the URL to the Trade Boards section in Tibia.com.

Returns:

The URL to the Trade Boards.

Return type:

str

classmethod get_community_boards_url()

Get the URL to the Community Boards section in Tibia.com.

Returns:

The URL to the Community Boards.

Return type:

str

classmethod get_support_boards_url()

Get the URL to the Support Boards section in Tibia.com.

Returns:

The URL to the Support Boards.

Return type:

str

class tibiapy.abc.BaseCharacter

Base class for all character classes.

Implements common properties methods for characters.

The following implement this class:

• Character

• GuildInvite

• GuildMember

• HighscoresEntry

• TournamentLeaderboardEntry

• OnlineCharacter

• OtherCharacter

• AuctionEntry

• Auction

name

The name of the character.

Type:

str

property url

The URL of the character’s information page on Tibia.com.

Type:

str

classmethod get_url(name)

Get the Tibia.com URL for a given character name.

Parameters:

name (str) – The name of the character.

Returns:

The URL to the character’s page.

Return type:

str

class tibiapy.abc.BaseGuild

Base class for Guild classes.

The following implement this class:

• Guild

• GuildMembership

• GuildEntry

name

The name of the guild.

Type:

str

property url

The URL to the guild’s information page on Tibia.com.

Type:

str

property url_wars

str The URL to the guild’s wars page on Tibia.com.

New in version 3.0.0.

classmethod get_url(name)

Get the Tibia.com URL for a given guild name.

Parameters:

name (str) – The name of the guild.

Returns:

The URL to the guild’s page.

Return type:

str

classmethod get_url_wars(name)

Get the Tibia.com URL for the guild wars of a guild with a given name.

New in version 3.0.0.

Parameters:

name (str) – The name of the guild.

Returns:

The URL to the guild’s wars page.

Return type:

str

class tibiapy.abc.BaseHouse

Base class for all house classes.

The following implement this class:

• House

• GuildHouse

• CharacterHouse

• HouseEntry

name

The name of the house.

Type:

str

classmethod get_url(house_id, world)

Get the Tibia.com URL for a house with the given id and world.

Parameters:

• house_id (int) – The internal id of the house.

• world (str) – The world of the house.

Return type:

The URL to the house in Tibia.com

class tibiapy.abc.HouseWithId

Implements the id attribute and dependant functions and properties.

Subclasses mut also implement BaseHouse

property url

The URL to the Tibia.com page of the house.

Type:

str

class tibiapy.abc.BaseNews

Base class for all news classes.

Implements the id attribute and common properties.

The following implement this class:

• News

• NewsEntry

id

The internal ID of the news entry.

Type:

int

property url

The URL to the Tibia.com page of the news entry.

Type:

str

classmethod get_url(news_id)

Get the Tibia.com URL for a news entry by its id.

Parameters:

news_id (int) – The id of the news entry.

Returns:

The URL to the news’ page

Return type:

str

classmethod get_list_url()

Get the URL to Tibia.com’s news archive page.

Notes

It is not possible to perform a search using query parameters. News searches can only be performed using POST requests sending the parameters as form-data.

Returns:

The URL to the news archive page on Tibia.com.

Return type:

str

class tibiapy.abc.BasePost

Base classs for post classes.

The following implement this class:

• CMPost

• ForumPost

• LastPost

post_id

The internal ID of the post.

Type:

int

property url

Get the URL to this specific post.

Type:

str

classmethod get_url(post_id)

Get the URL to a specific post.

Parameters:

post_id (int) – The ID of the desired post.

Returns:

The URL to the post.

Return type:

str

class tibiapy.abc.BaseThread

Base class for thread classes.

The following implement this class:

• ThreadEntry

• ForumThread

thread_id

The internal ID of the thread.

Type:

int

property url

The URL to the thread in Tibia.com.

Type:

str

classmethod get_url(thread_id, page=1)

Get the URL to a thread with a given id.

Parameters:

• thread_id (int) – The id of the desired thread.

• page (int) – The desired page, by default 1.

Returns:

The URL to the thread.

Return type:

str

class tibiapy.abc.BaseTournament

Base class for tournament classes.

The following implement this class:

• TournamentEntry

• Tournament

title

The tournament’s title.

Type:

str

cycle

The tournament’s cycle.

Type:

int

property url

The URL to the tournament’s information page.

Type:

str

classmethod get_url(tournament_cycle)

Get the URL to a tournament’s information page.

If its cycle is provided, otherwise it shows the current tournament.

Parameters:

tournament_cycle (int) – The tournament’s cycle.

Returns:

The URL to the specified tournament.

Return type:

str

class tibiapy.abc.BaseWorld

Base class for all World classes.

The following implement this class:

• WorldEntry

• World

name

The name of the world.

Type:

str

property url

URL to the world’s information page on Tibia.com.

Type:

str

classmethod get_url(name)

Get the URL to the World’s information page on Tibia.com.

Parameters:

name (str) – The name of the world.

Returns:

The URL to the world’s information page.

Return type:

str

class tibiapy.abc.Serializable

Contains methods to make a class convertible to JSON.

Only attributes defined in __slots__ will be serialized.

Note

There’s no way to convert JSON strings back to their original object.

Attempting to do so may result in data loss.

to_json(*, indent=None, sort_keys=False)

Get the object’s JSON representation.

Parameters:

• indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.

• sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.

Returns:

JSON representation of the object.

Return type:

str

Exceptions

class tibiapy.TibiapyException

Base exception for the tibiapy module.

All exceptions thrown by the module are inherited from this.

class tibiapy.InvalidContent(message, original=None)

Exception thrown when the provided content is unrelated for the calling function.

This usually means that the content provided belongs to a different website or section of the website. This serves as a way to differentiate those cases from a parsing that returned no results (e.g. Character not found)

In some cases this can mean that Tibia.com’s format has changed and the library needs updating.

original

The original exception that caused this exception.

Type:

Exception

class tibiapy.NetworkError(message, original=None, fetching_time=0)

Exception thrown when there was a network error trying to fetch a resource from the web.

original

The original exception that caused this exception.

Type:

Exception

fetching_time

The time between the request and the response.

Type:

float

class tibiapy.SiteMaintenanceError(message, original=None, fetching_time=0)

A subclass of NetworkError thrown when Tibia.com is down for maintenance.

When Tibia.com is under maintenance, all sections of the website redirect to maintenance.tibia.com.

class tibiapy.Forbidden(message, original=None, fetching_time=0)

A subclass of NetworkError thrown when Tibia.com returns a 403 status code.

Tibia.com returns a 403 status code when it detects that too many requests are being done. This has its own subclass to let the user decide to treat this differently than other network errors.

Utility functions

These are functions used thorough the module that may not be intended for public use.

tibiapy.utils.convert_line_breaks(element)

Convert the <br> tags in a HTML elements to actual line breaks.

Parameters:

element (bs4.Tag) – A BeautifulSoup object.

tibiapy.utils.get_tibia_url(section, subtopic=None, *args, anchor=None, test=False, **kwargs)

Build a URL to Tibia.com with the given parameters.

Parameters:

• section (str) – The desired section (e.g. community, abouttibia, manual, library)

• subtopic (str, optional) – The desired subtopic (e.g. characters, guilds, houses, etc)

• anchor (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)

• test (bool) – Whether to use the test website or not.

Returns:

The generated Tibia.com URL.

Return type:

str

Examples

>>> get_tibia_url("community", "houses", page="view", houseid=55302, world="Gladera")
https://www.tibia.com/community/?subtopic=houses&page=view&houseid=55302&world=Gladera

You can also build a dictionary and pass it like:

>>> params = {'world': "Gladera"}
>>> get_tibia_url("community", "worlds", **params)
https://www.tibia.com/community/?subtopic=worlds&world=Gladera

tibiapy.utils.parse_form_data(form: Tag, include_options=True)

Parse the currently selected values in a form.

This should correspond to all the data the form would send if submitted.

Parameters:

• form (bs4.Tag) – A form tag.

• include_options (bool) – Whether to also include listings of all the possible options. These will be nested inside the __options__ parameter of the resulting dictionary.

Returns:

A dictionary containing all the data.

Return type:

dict

tibiapy.utils.parse_integer(number: str, default: Optional[int] = 0)

Parse a string representing an integer, ignoring commas or periods.

Parameters:

• number (str) – A string representing a number.

• default (int) – The default value to use if the string is not numeric. By default, 0 is used.

Returns:

The represented integer, or the default value if invalid.

Return type:

int

tibiapy.utils.parse_link_info(link_tag)

Parse the information of a link tag.

It will parse the link’s content, target URL as well as the query parameters where applicable.

Parameters:

link_tag (bs4.Tag) – The link tag object.

Returns:

A dictionary containing the link’s data.

Return type:

dict

Examples

>>> # <a href="https://www.tibia.com/community/?subtopic=houses&page=view&houseid=55302&world=Gladera">House</>
>>> parse_link_info(link_tag)
{
    "text": "House",
    "url": "https://www.tibia.com/community/?subtopic=houses&page=view&houseid=55302&world=Gladera"
    "query": {
        "subtopic": "houses",
        "page": "view",
        "houseid": "55302",
        "world": "Gladera"
    }
}

When parsing links that have multiple query parameters, they are displayed as a list. Empty parameters are omitted.

>>> # <a href="https://example.com/?world=&beprotection=-1&worldtypes[]=0&worldtypes[]=3">Link</a>
>>> parse_link_info(link_tag)
{
    "text": "Link",
    "url": "https://example.com/?world=&beprotection=-1&worldtypes[]=0&worldtypes[]=3"
    "query": {
        "beprotection": "-1",
        "worldtypes": ["0", "3"]
    }
}

tibiapy.utils.parse_tibia_datetime(datetime_str) → Optional[datetime]

Parse date and time from the format used in Tibia.com.

Accepted format:

• MMM DD YYYY, HH:mm:ss ZZZ, e.g. Dec 10 2018, 21:53:37 CET.

• MMM DD YYYY, HH:mm ZZZ, e.g. Dec 10 2018, 21:53 CET.

Parameters:

datetime_str (str) – The date and time as represented in Tibia.com

Returns:

The represented datetime, in UTC (timezone aware).

Return type:

datetime.datetime, optional

tibiapy.utils.parse_tibia_date(date_str) → Optional[date]

Parse a date from the format used in Tibia.com.

Accepted format:

• MMM DD YYYY, e.g. Jul 23 2015

Parameters:

date_str (str) – The date as represented in Tibia.com

Returns:

The represented date, in UTC (timezone aware).

Return type:

datetime.date, optional

tibiapy.utils.parse_tibia_forum_datetime(datetime_str, utc_offset=1)

Parse a date in the format used in the Tibia.com forums.

Accepted format:

• DD.MM.YY HH:mm:ss, e.g. 23.07.2015 21:30:30

Parameters:

• datetime_str (str) – The string containing the date and time.

• utc_offset (int) –

  The UTC offset to apply to the parsed datetime.

  Since the timestamps contain no timezone information, it can be passed as an additional parameter.

  By default CET (+1) is considered.

Returns:

The represented datetime, in UTC (timezone aware).

Return type:

datetime

tibiapy.utils.parse_tibia_full_date(date_str) → Optional[date]

Parse a date in the fuller format used in Tibia.com.

Accepted format:

• MMMM DD, YYYY, e.g. July 23, 2015

Parameters:

date_str (str) – The date as represented in Tibia.com

Returns:

The represented date, in UTC (timezone aware).

Return type:

datetime.date, optional

tibiapy.utils.parse_number_words(text_num)

Parse the word representation of a number to a integer.

Parameters:

text_num (str) – The text representation of a number.

Returns:

The number represented by the string.

Return type:

int

tibiapy.utils.try_datetime(obj) → Optional[datetime]

Attempt to convert an object into a datetime.

If the date format is known, it’s recommended to use the corresponding function This is meant to be used in constructors.

Parameters:

obj (str, dict, datetime.datetime) – The object to convert.

Returns:

The represented datetime, in UTC (timezone aware), or None if conversion wasn’t possible.

Return type:

datetime.datetime, optional

tibiapy.utils.try_date(obj) → Optional[date]

Attempt to convert an object into a date.

If the date format is known, it’s recommended to use the corresponding function This is meant to be used in constructors.

Parameters:

obj (str, datetime.datetime, datetime.date) – The object to convert.

Returns:

The represented date, in UTC (timezone aware).

Return type:

datetime.date, optional

tibiapy.utils.parse_tibiacom_content(content, *, html_class='BoxContent', tag='div', builder='lxml')

Parse HTML content from Tibia.com into a BeautifulSoup object.

Parameters:

• content (str) – The raw HTML content from Tibia.com

• html_class (str) – The HTML class of the parsed element. The default value is BoxContent.

• tag (str) – The HTML tag select. The default value is div.

• builder (str) – The builder to use. The default value is lxml.

Returns:

The parsed content.

Return type:

bs4.BeautifulSoup, optional

tibiapy.utils.parse_tibiacom_tables(parsed_content) → Dict[str, Tag]

Parse tables from Tibia.com into a mapping by the tables title.

This is used for the table style used in Tibia.com, where a table is wrapped in a container with a title.

Parameters:

parsed_content (bs4.BeautifulSoup) – The content to find the tables in.

Returns:

A dictionary mapping the container titles and the contained table.

Return type:

dict

tibiapy.utils.try_enum(cls: Type[T], val, default: Optional[D] = None) → Union[T, D]

Attempt to convert a value into their enum value.

Parameters:

• cls (Enum) – The enum to convert to.

• val – The value to try to convert to Enum

• default (optional) – The value to return if no enum value is found.

Returns:

The enum value if found, otherwise None.

Return type:

obj

tibiapy.utils.parse_tibia_money(argument)

Parse a string that may contain ‘k’ as thousand suffix.

Parameters:

argument (str) – A numeric string using k as a prefix for thousands.

Returns:

The value represented by the string.

Return type:

int

tibiapy.utils.split_list(items, separator=',', last_separator=' and ')

Split a string listing elements into an actual list.

Parameters:

• items (str) – A string listing elements.

• separator (str) – The separator between each item. A comma by default.

• last_separator (str) – The separator used for the last item. ‘ and ‘ by default.

Returns:

A list containing each one of the items.

Return type:

list of str

tibiapy.utils.parse_popup(popup_content) → Tuple[str, BeautifulSoup]

Parse the information popups used through Tibia.com.

Parameters:

popup_content (str) – The raw content of the javascript function that creates the popup.

Returns:

• str – The popup’s title.

• bs4.BeautifulSoup – The parsed HTML content of the popup.

tibiapy.utils.parse_pagination(pagination_block) → Tuple[int, int, int]

Parse a pagination section in Tibia.com and extracts its information.

Parameters:

pagination_block (bs4.Tag) – The HTML containing the pagination information.

Returns:

• page (int) – The current page.

• total_pages (int) – The total number of pages.

• results_count (int) – The total number of results.