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(*, 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: tibiapy.client.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.

Returns

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)

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

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[tibiapy.guild.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.

Returns

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.

Returns

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.

Returns

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.

Returns

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.

Returns

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.

Returns

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

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, tibiapy.bazaar.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 tibiapy.bazaar.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 tibiapy.bazaar.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 tibiapy.bazaar.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 tibiapy.bazaar.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.

Returns

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 character contained in the page.

Return type

Character

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

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.

Returns

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: bs4.element.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_tibia_datetime(datetime_str) → Optional[datetime.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[datetime.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[datetime.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.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[datetime.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.try_enum(cls: Type[tibiapy.utils.T], val, default: Optional[tibiapy.utils.D] = None) → Union[tibiapy.utils.T, tibiapy.utils.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, bs4.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.