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)[source]¶

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_cm_post_archive(start_date, end_date, page=1)[source]¶

Fetches 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.

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)[source]¶

Fetches the event calendar.

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.

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.

async fetch_forum_community_boards()[source]¶

Fetches the forum’s community boards.

New in version 3.0.0.

Returns

The forum boards in the community section.

Return type

TibiaResponse of list of ListedBoard

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()[source]¶

Fetches the forum’s community boards.

New in version 3.0.0.

Returns

The forum boards in the community section.

Return type

TibiaResponse of list of ListedBoard

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()[source]¶

Fetches the forum’s world boards.

New in version 3.0.0.

Returns

The forum boards in the world section.

Return type

TibiaResponse of list of ListedBoard

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()[source]¶

Fetches the forum’s trade boards.

New in version 3.0.0.

Returns

The forum boards in the trade section.

Return type

TibiaResponse of list of ListedBoard

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)[source]¶

Fetches 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.

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)[source]¶

Fetches 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.

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)[source]¶

Fetches 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.

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)[source]¶

Fetches a forum announcement.

New in version 3.0.0.

Parameters

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

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()[source]¶

Fetches today’s boosted creature.

New in version 2.1.0.

Returns

The boosted creature of the day.

Return type

TibiaResponse of BoostedCreature

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)[source]¶

Fetches a character by its name from Tibia.com

Parameters

name (str) – The name of the character.

Returns

A response containig 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)[source]¶

Fetches a guild by its name from Tibia.com

Parameters

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

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)[source]¶

Fetches 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.

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)[source]¶

Fetches 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.

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, category=Category.EXPERIENCE, vocation=VocationFilter.ALL, page=1)[source]¶

Fetches a single highscores page from Tibia.com

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.

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.

async fetch_kill_statistics(world)[source]¶

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

Parameters

world (str) – The name of the world.

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_world(name)[source]¶

Fetches a world from Tibia.com

Parameters

name (str) – The name of the world.

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: tibiapy.enums.HouseStatus = None, order=HouseOrder.NAME)[source]¶

Fetches the house list of a world and type.

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.

Returns

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

Return type

TibiaResponse of list of ListedHouse

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)[source]¶

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

Parameters

world (str) – The name of the world.

Returns

A response containing the lists of guilds in the world.

Return type

TibiaResponse of list of ListedGuild

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()[source]¶

Fetches the world overview information from Tibia.com.

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(begin_date, end_date, categories=None, types=None)[source]¶

Fetches news from the archive meeting the search criteria.

Parameters

begin_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 ListedNews) – The allowed news types to show. if unused, all types will be searched.

Returns

The news meeting the search criteria.

Return type

TibiaResponse of list of ListedNews

Raises

ValueError: – If begin_date is more recent than end_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)[source]¶

Fetches all the published news in the last specified days.

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

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 ListedNews) – The allowed news types to show. if unused, all types will be searched.

Returns

The news posted in the last specified days.

Return type

TibiaResponse of list of ListedNews

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)[source]¶

Fetches a news entry by its id from Tibia.com

Parameters

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

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_tournament(tournament_cycle=0)[source]¶

Fetches 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.

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)[source]¶

Fetches 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.

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(*args, **kwds)[source]¶

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.

class tibiapy.AccountStatus(value)[source]¶

Possible account statuses.

FREE_ACCOUNT = 'Free Account'¶

PREMIUM_ACCOUNT = 'Premium Account'¶

class tibiapy.Category(value)[source]¶

The different highscores categories.

ACHIEVEMENTS = 1¶

AXE_FIGHTING = 2¶

CHARM_POINTS = 3¶

CLUB_FIGHTING = 4¶

DISTANCE_FIGHTING = 5¶

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)[source]¶

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)[source]¶

Renting statuses of a house.

RENTED = 'rented'¶

AUCTIONED = 'auctioned'¶

class tibiapy.HouseType(value)[source]¶

The types of house available.

HOUSE = 'house'¶

GUILDHALL = 'guildhall'¶

class tibiapy.NewsCategory(value)[source]¶

The different news categories.

CIPSOFT = 'cipsoft'¶

COMMUNITY = 'community'¶

DEVELOPMENT = 'development'¶

SUPPORT = 'support'¶

TECHNICAL_ISSUES = 'technical'¶

class tibiapy.NewsType(value)[source]¶

The different types of new entries.

NEWS_TICKER = 'News Ticker'¶

FEATURED_ARTICLE = 'Featured Article'¶

NEWS = 'News'¶

class tibiapy.PvpType(value)[source]¶

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)[source]¶

Possible character sexes.

MALE = 'male'¶

FEMALE = 'female'¶

class tibiapy.ThreadStatus(value)[source]¶

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()[source]¶

Generates 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)[source]¶

Gets 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)[source]¶

The possible types of tournament worlds.

REGUlAR = 'Regular'¶

RESTRICTED = 'Restricted Store'¶

class tibiapy.TournamentPhase(value)[source]¶

The possible tournament phases.

SIGN_UP = 'sign up'¶

RUNNING = 'running'¶

ENDED = 'ended'¶

class tibiapy.TransferType(value)[source]¶

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)[source]¶

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.VocationFilter(value)[source]¶

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)[source]¶

Gets 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.WorldLocation(value)[source]¶

The possible physical locations for servers.

EUROPE = 'Europe'¶

NORTH_AMERICA = 'North America'¶

SOUTH_AMERICA = 'South America'¶

Main Models¶

The following models all contain their respective from_content methods. They all have their respective section in Tibia.com

BoostedCreature¶

class tibiapy.BoostedCreature(name, image_url)[source]¶

Represents a boosted creature entry.

This creature changes every server save and applies to all Game Worlds. Boosted creatures yield twice the amount of experience points, carry more loot and respawn at a faster rate.

name¶

The name of the boosted creature.

Type: str

image_url¶

An URL containing the boosted creature’s image.

Type: str

classmethod from_content(content)[source]¶

Gets 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: BoostedCreature
Raises: InvalidContent – If content is not the HTML of a Tibia.com’s page.

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

Gets 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

Character¶

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

Represents a Tibia character.

name¶

The name of the character.

Type: str

deletion_date¶

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

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.

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.

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 visible.

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¶

Whether the character is scheduled for deletion or not.

Type: bool

property guild_name¶

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

Type: str

property guild_rank¶

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

Type: str

property guild_url¶

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

Type: str

property hidden¶

Whether this is a hidden character or not.

Type: bool

property married_to_url¶

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

Type: str

classmethod from_content(content)[source]¶

Creates 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)¶

Gets 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)¶

Gets 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

CMPostArchive¶

class tibiapy.CMPostArchive(**kwargs)[source]¶

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)[source]¶

Gets 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)[source]¶

Gets 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)[source]¶

Parses 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)¶

Gets 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

EventSchedule¶

class tibiapy.EventSchedule(month, year, **kwargs)[source]¶

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¶

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

Type: str

get_events_on(date)[source]¶

Gets 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)[source]¶

Gets 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)[source]¶

Creates 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)¶

Gets 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)[source]¶

Represent’s 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)[source]¶

Parses 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)¶

Gets 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)¶

Gets 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 Gets the URL to this announcement.

ForumBoard¶

class tibiapy.ForumBoard(**kwargs)[source]¶

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 total_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: :class:ìnt`

announcements¶

The list of announcements currently visible.

Type: list of ListedAnnouncement

threads¶

The list of threads currently visible.

Type: list of ListedThread

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)[source]¶

Gets 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)[source]¶

Parses 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()¶

Gets 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()¶

Gets 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()¶

Gets 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)¶

Gets 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()¶

Gets 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)¶

Gets 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)[source]¶

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

emoticon¶

The URL to the post’s emoticon.

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)¶

Gets 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)¶

Gets 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¶

Gets the URL to this specific post.

Type: str

ForumThread¶

class tibiapy.ForumThread(**kwargs)[source]¶

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)[source]¶

Gets 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)[source]¶

Creates 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)¶

Gets 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)¶

Gets 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)[source]¶

Represents a Tibia guild.

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¶

Ranks in their hierarchical order.

Type: list of str

classmethod from_content(content)[source]¶

Creates 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)¶

Gets 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)¶

Gets 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

classmethod get_world_list_url(world)¶

Gets 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)¶

Gets 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.

GuildWars¶

class tibiapy.GuildWars(name, current=None, history=None)[source]¶

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)[source]¶

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

Parameters: name (class:str) – The name of the guild.
Returns: The URL to the guild’s war page.
Return type: str

classmethod from_content(content)[source]¶

Gets 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)¶

Gets 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¶

class tibiapy.Highscores(world, category, **kwargs)[source]¶

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

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

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

classmethod from_content(content)[source]¶

Creates 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)[source]¶

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

Parameters

world (str) – The game world of the desired highscores. If no world is passed, ALL worlds are shown.
category (Category) – The desired highscores category.
vocation (VocationFiler) – The vocation filter to apply. By default all vocations will be shown.
page (int) – The page of highscores to show.

Returns

Return type

The URL to the Tibia.com highscores.

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

Gets 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)[source]¶

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)[source]¶

Parses 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_list_url(world, town, house_type: tibiapy.enums.HouseType = HouseType.HOUSE, status: tibiapy.enums.HouseStatus = None, order=HouseOrder.NAME)¶

Gets the URL to the house list on Tibia.com with the specified parameters.

Parameters

world (str) – The name of the world.
town (str) – The name of the town.
house_type (HouseType) – Whether to search for houses or guildhalls.
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.

Returns

The URL to the list matching the parameters.

Return type

str

classmethod get_url(house_id, world)¶

Gets 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)¶

Gets 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

KillStatistics¶

class tibiapy.KillStatistics(world, entries=None, total=None)[source]¶

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

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)[source]¶

Gets 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)[source]¶

Creates 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)¶

Gets 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

ListedAnnouncement¶

class tibiapy.ListedAnnouncement(**kwargs)[source]¶

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: class:int

announcement_author¶

The character that made the announcement.

Type: str

classmethod get_url(announcement_id)¶

Gets 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)¶

Gets 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 Gets the URL to this announcement.

ListedBoard¶

class tibiapy.ListedBoard(**kwargs)[source]¶

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: inst

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)[source]¶

Parses 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 ListedBoard
Raises: InvalidContent` – Content is not a board list in Tibia.com

classmethod get_community_boards_url()¶

Gets 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()¶

Gets 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()¶

Gets 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)¶

Gets 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()¶

Gets 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)¶

Gets 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

ListedGuild¶

class tibiapy.ListedGuild(name, world, logo_url=None, description=None, active=False)[source]¶

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 list_from_content(content)[source]¶

Gets 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: list of ListedGuild
Raises: InvalidContent – If content is not the HTML of a guild’s page.

classmethod get_url(name)¶

Gets 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)¶

Gets 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

classmethod get_world_list_url(world)¶

Gets 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)¶

Gets 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.

ListedHouse¶

class tibiapy.ListedHouse(name, world, houseid, **kwargs)[source]¶

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

classmethod list_from_content(content)[source]¶

Parses 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
Return type: list of ListedHouse
Raises: InvalidContent` – Content is not the house list from Tibia.com

classmethod get_list_url(world, town, house_type: tibiapy.enums.HouseType = HouseType.HOUSE, status: tibiapy.enums.HouseStatus = None, order=HouseOrder.NAME)¶

Gets the URL to the house list on Tibia.com with the specified parameters.

Parameters

world (str) – The name of the world.
town (str) – The name of the town.
house_type (HouseType) – Whether to search for houses or guildhalls.
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.

Returns

The URL to the list matching the parameters.

Return type

str

classmethod get_url(house_id, world)¶

Gets 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)¶

Gets 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

ListedNews¶

class tibiapy.ListedNews(news_id, title, news_type, category, date, **kwargs)[source]¶

Represents a news entry.

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 list_from_content(content)[source]¶

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

Parameters: content (str) – The HTML content of the page.
Returns: List of news in the search results.
Return type: list of ListedNews
Raises: InvalidContent – If content is not the HTML of a news search’s page.

classmethod get_list_url()¶

Gets 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)¶

Gets 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)¶

Gets 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

ListedThread¶

class tibiapy.ListedThread(**kwargs)[source]¶

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: class:int

thread_started¶

The character that started the thread.

Type: str

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 total_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)¶

Gets 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)¶

Gets 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 The URL to the thread in Tibia.com.

ListedTournament¶

class tibiapy.ListedTournament(title, start_date, end_date, **kwargs)[source]¶

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)¶

Gets 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)¶

Gets 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

ListedWorld¶

class tibiapy.ListedWorld(name, location=None, pvp_type=None, **kwargs)[source]¶

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_protected¶

Whether the server is currently protected with BattlEye or not.

Type: bool

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

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

classmethod get_list_url()[source]¶

Gets 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)[source]¶

Parses 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 ListedWorld
Raises: InvalidContent – If the provided content is not the HTML content of the worlds section in Tibia.com

classmethod get_url(name)¶

Gets 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)¶

Gets 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

News¶

class tibiapy.News(news_id, title, content, date, category, **kwargs)[source]¶

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)[source]¶

Gets 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()¶

Gets 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)¶

Gets 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)¶

Gets 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

Tournament¶

class tibiapy.Tournament(**kwargs)[source]¶

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 ListedTournament

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)[source]¶

Gets 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)[source]¶

Creates 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)¶

Gets 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)¶

Gets 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)[source]¶

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: ListedTournament

entries¶

The leaderboard entries.

Type: list of LeaderboardEntry

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¶

Gets the URL to the current leaderboard and page.

Type: str

classmethod get_url(world, tournament_cycle, page=1)[source]¶

Gets 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)[source]¶

Creates 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)¶

Gets 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

World¶

class tibiapy.World(name, location=None, pvp_type=None, **kwargs)[source]¶

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_protected¶

Whether the server is currently protected with BattlEye or not.

Type: bool

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

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 creation_year¶

Returns the year when the world was created.

Type: int

property creation_month¶

Returns the month when the world was created.

Type: ìnt

classmethod from_content(content)[source]¶

Parses 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)¶

Gets 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)¶

Gets 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

WorldOverview¶

class tibiapy.WorldOverview(**kwargs)[source]¶

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 ListedWorld

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 ListedWorld

classmethod get_url()[source]¶

Gets 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)[source]¶

Parses 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)¶

Gets 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¶

Auxiliary classes are used to hold certain data in a standardized way, in some cases, introducing additional methods and properties for their use.

AccountBadge¶

class tibiapy.AccountBadge(name, icon_url, description)[source]¶

Represents an account badge.

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)¶

Gets 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)[source]¶

Represents the account information of a character.

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)¶

Gets 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)[source]¶

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: :class:´bool´

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

Gets 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)[source]¶

Represents 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_list_url(world, town, house_type: tibiapy.enums.HouseType = HouseType.HOUSE, status: tibiapy.enums.HouseStatus = None, order=HouseOrder.NAME)¶

Gets the URL to the house list on Tibia.com with the specified parameters.

Parameters

world (str) – The name of the world.
town (str) – The name of the town.
house_type (HouseType) – Whether to search for houses or guildhalls.
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.

Returns

The URL to the list matching the parameters.

Return type

str

classmethod get_url(house_id, world)¶

Gets 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)¶

Gets 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

CMPost¶

class tibiapy.CMPost(**kwargs)[source]¶

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)¶

Gets 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)¶

Gets 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¶

Gets the URL to this specific post.

Type: str

EventEntry¶

class tibiapy.EventEntry(title, description, **kwargs)[source]¶

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

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

Gets 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

ForumAuthor¶

class tibiapy.ForumAuthor(name, **kwargs)[source]¶

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

classmethod get_url(name)¶

Gets 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)¶

Gets 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)[source]¶

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)¶

Gets 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

Death¶

class tibiapy.Death(name=None, level=0, **kwargs)[source]¶

Represents a death by a character

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)¶

Gets 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

GuildHouse¶

class tibiapy.GuildHouse(name, world=None, owner=None, paid_until_date=None)[source]¶

Represents a House owned by a guild.

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

owner¶

The owner of the guildhall.

Type: str

paid_until_date¶

The date the last paid rent is due.

Type: datetime.date

classmethod get_list_url(world, town, house_type: tibiapy.enums.HouseType = HouseType.HOUSE, status: tibiapy.enums.HouseStatus = None, order=HouseOrder.NAME)¶

Gets the URL to the house list on Tibia.com with the specified parameters.

Parameters

world (str) – The name of the world.
town (str) – The name of the town.
house_type (HouseType) – Whether to search for houses or guildhalls.
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.

Returns

The URL to the list matching the parameters.

Return type

str

classmethod get_url(house_id, world)¶

Gets 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)¶

Gets 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

GuildInvite¶

class tibiapy.GuildInvite(name=None, date=None)[source]¶

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)¶

Gets 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)¶

Gets 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

GuildMember¶

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

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)¶

Gets 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)¶

Gets 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

GuildMembership¶

class tibiapy.GuildMembership(name, rank, title=None)[source]¶

Represents 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.

Type: str

classmethod get_url(name)¶

Gets 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)¶

Gets 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

classmethod get_world_list_url(world)¶

Gets 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)¶

Gets 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.

GuildWarEntry¶

class tibiapy.GuildWarEntry(**kwargs)[source]¶

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)¶

Gets 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)[source]¶

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)¶

Gets 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)¶

Gets 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

Killer¶

class tibiapy.Killer(name, player=False, summon=None)[source]¶

Represents a killer.

A killer can be:

A creature.
A character.
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)¶

Gets 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)[source]¶

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

deleted¶

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

Type: bool

property author_url¶

The URL to the author’s character information page.

Type: str

classmethod get_url(post_id)¶

Gets 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)¶

Gets 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¶

Gets the URL to this specific post.

Type: str

LeaderboardEntry¶

class tibiapy.LeaderboardEntry(**kwargs)[source]¶

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)¶

Gets 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)¶

Gets 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)[source]¶

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)¶

Gets 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)¶

Gets 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

OnlineCharacter¶

class tibiapy.OnlineCharacter(name, world, level, vocation)[source]¶

Represents an online character.

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)¶

Gets 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)¶

Gets 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

OtherCharacter¶

class tibiapy.OtherCharacter(name, world, online=False, deleted=False, main=False, position=None)[source]¶

Represents other characters displayed in the Character’s information page.

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

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)¶

Gets 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)¶

Gets 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

RaceEntry¶

class tibiapy.RaceEntry(last_day_killed=0, last_day_players_killed=0, last_week_killed=0, last_week_players_killed=0)[source]¶

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)¶

Gets 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

RewardEntry¶

class tibiapy.RewardEntry(**kwargs)[source]¶

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)¶

Gets 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)[source]¶

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

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

Gets 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)[source]¶

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

New in version 2.5.0.

level_gain_loss¶

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

Type: int

charm_point_multiplier¶

The multiplier for every charm point.

Type: int

character_death¶

The points lost for dying.

Type: int

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

Gets 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[source]¶

Base class for all announcement classes.

Implement common properties and methods for announcements.

The following implement this class:

ForumAnnouncement
ListedAnnouncement

announcement_id¶

The ID of the announcement.

Type: int

property url¶: str Gets the URL to this announcement.

classmethod get_url(announcement_id)[source]¶

Gets 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[source]¶

Base class for all board classes.

Implements common properties and methods for boards.

The following implement this class:

ForumBoard
ListedBoard

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)[source]¶

Gets 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()[source]¶

Gets 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()[source]¶

Gets 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()[source]¶

Gets 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()[source]¶

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

Returns: The URL to the Support Boards.
Return type: str

class tibiapy.abc.BaseCharacter[source]¶

Base class for all character classes.

Implements common properties methods for characters.

The following implement this class:

Character
GuildInvite
GuildMember
HighscoresEntry
LeaderboardEntry
OnlineCharacter
OtherCharacter

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)[source]¶

Gets 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[source]¶

Base class for Guild classes.

The following implement this class:

Guild
GuildMembership
:class:’.ListedGuild’

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)[source]¶

Gets 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)[source]¶

Gets 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

classmethod get_world_list_url(world)[source]¶

Gets 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

class tibiapy.abc.BaseHouse[source]¶

Base class for all house classes

The following implement this class:

House
GuildHouse
CharacterHouse
ListedHouse

name¶

The name of the house.

Type: str

classmethod get_url(house_id, world)[source]¶

Gets 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

classmethod get_list_url(world, town, house_type: tibiapy.enums.HouseType = HouseType.HOUSE, status: tibiapy.enums.HouseStatus = None, order=HouseOrder.NAME)[source]¶

Gets the URL to the house list on Tibia.com with the specified parameters.

Parameters

world (str) – The name of the world.
town (str) – The name of the town.
house_type (HouseType) – Whether to search for houses or guildhalls.
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.

Returns

The URL to the list matching the parameters.

Return type

str

class tibiapy.abc.HouseWithId[source]¶

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[source]¶

Base class for all news classes

Implements the id attribute and common properties.

The following implement this class:

News
ListedNews

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)[source]¶

Gets 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()[source]¶

Gets 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[source]¶

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¶

Gets the URL to this specific post.

Type: str

classmethod get_url(post_id)[source]¶

Gets 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[source]¶

Base class for thread classes.

The following implement this class:

ListedThread
ForumThread

thread_id¶

The internal ID of the thread.

Type: int

property url¶: str The URL to the thread in Tibia.com.

classmethod get_url(thread_id, page=1)[source]¶

Gets 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[source]¶

Base class for tournament classes.

The following implement this class:

ListedTournament
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)[source]¶

Gets 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[source]¶

Base class for all World classes.

The following implement this class:

ListedWorld
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)[source]¶

Gets 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[source]¶

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)[source]¶

Gets 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[source]¶

Base exception for the tibiapy module.

All exceptions thrown by the module are inherited from this.

class tibiapy.InvalidContent(message, original=None)[source]¶

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)[source]¶

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

class tibiapy.Forbidden(message, original=None)[source]¶

A subclass of network error 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)[source]¶

Converts 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, *, anchor=None, **kwargs)[source]¶

Builds 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.
kwargs – Additional parameters to pass to the url as query parameters (e.g name, world, houseid, etc)

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_integer(number: str, default: Optional[int] = 0)[source]¶

Parses 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][source]¶

Parses 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.

Parameters: datetime_str (str) – The date and time as represented in Tibia.com
Returns: The represented datetime, in UTC.
Return type: datetime.datetime, optional

tibiapy.utils.parse_tibia_date(date_str) → Optional[datetime.date][source]¶

Parses 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.
Return type: datetime.date, optional

tibiapy.utils.parse_tibia_forum_datetime(datetime_str, utc_offset=1)[source]¶

Parses 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 datetime represented by the text, in UTC.

Return type

datetime

tibiapy.utils.parse_tibia_full_date(date_str) → Optional[datetime.date][source]¶

Parses 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.
Return type: datetime.date, optional

tibiapy.utils.parse_number_words(text_num)[source]¶

Parses 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][source]¶

Attempts 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, or None if conversion wasn’t possible.
Return type: datetime.datetime, optional

tibiapy.utils.try_date(obj) → Optional[datetime.date][source]¶

Attempts 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.
Return type: datetime.date, optional

tibiapy.utils.parse_tibiacom_content(content, *, html_class='BoxContent', tag='div', builder='lxml')[source]¶

Parses 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[T], val, default: D = None) → Union[T, D][source]¶

Attempts 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)[source]¶

Parses a string that may contain ‘k’ as thousand suffix.

Parameters: argument (str) – A numeric string.
Returns: The value represented by the string.
Return type: int

tibiapy.utils.split_list(items, separator=',', last_separator=' and ')[source]¶

Splits 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)[source]¶

Parses 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.