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.

Enumerations

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

class tibiapy.HouseType

The types of house available.

HOUSE = 'house'

GUILDHALL = 'guildhall'

class tibiapy.AccountStatus

Possible account statuses.

FREE_ACCOUNT = 'Free Account'

PREMIUM_ACCOUNT = 'Premium Account'

class tibiapy.HouseStatus

Renting statuses of a house.

RENTED = 'rented'

AUCTIONED = 'auctioned'

class tibiapy.PvpType

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

Possible character sexes.

MALE = 'male'

FEMALE = 'female'

class tibiapy.TransferType

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

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

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

Character

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

Represents a Tibia character.

name

str – The name of the character.

deletion_date

datetime.datetime, optional – The date when the character will be deleted if it is scheduled for deletion.

former_names

list of str – Previous names of the character.

sex

Sex – The character’s sex.

vocation

Vocation – The character’s vocation.

level

int – The character’s level.

achievement_points

int – The total of achievement points the character has.

world

str – The character’s current world.

former_world

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

residence

str – The current hometown of the character.

married_to

str, optional – The name of the character’s spouse.

house

CharacterHouse, optional – The house currently owned by the character.

guild_membership

GuildMembership, optional – The guild the character is a member of.

last_login

datetime.datetime, optional – The last time the character logged in. It will be None if the character has never logged in.

position

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

comment

str, optional – The displayed comment.

account_status

AccountStatus – Whether the character’s account is Premium or Free.

achievements

list of Achievement – The achievements chosen to be displayed.

deaths

list of Death – The character’s recent deaths.

account_information

AccountInformation, optional – The character’s account information, if visible.

other_characters

list of OtherCharacter – Other characters in the same account. It will be empty if the character is hidden, otherwise, it will contain at least the character itself.

deleted

bool – Whether the character is scheduled for deletion or not.

guild_name

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

guild_rank

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

guild_url

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

hidden

bool – Whether this is a hidden character or not.

married_to_url

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

classmethod from_content(content)

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 from_tibiadata(content)

Builds a character object from a TibiaData character response.

Parameters:content (str) – The JSON content of the response. Returns:The character contained in the page, or None if the character doesn’t exist Return type:Character Raises:InvalidContent – If content is not a JSON string of the Character response.

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

classmethod get_url_tibiadata(name)

Gets the TibiaData.com URL for a given character name.

Parameters:name (str) – The name of the character. Returns:The URL to the character’s page on TibiaData.com. 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

url

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

url_tibiadata

str – The URL of the character’s information on TibiaData.com.

Guild

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

Represents a Tibia guild.

name

str – The name of the guild.

logo_url

str – The URL to the guild’s logo.

description

str, optional – The description of the guild.

world

str – The world this guild belongs to.

founded

datetime.date – The day the guild was founded.

active

bool – Whether the guild is active or still in formation.

guildhall

GuildHouse, optional – The guild’s guildhall if any.

open_applications

bool – Whether applications are open or not.

disband_date

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

disband_condition

str, optional – The reason why the guild will get disbanded.

homepage

str, optional – The guild’s homepage, if any.

members

list of GuildMember – List of guild members.

invites

list of GuildInvite – List of invited characters.

member_count

int – The number of members in the guild.

online_count

int – The number of online members in the guild.

online_members

list of GuildMember – List of currently online members.

ranks

list of str – Ranks in their hierarchical order.

classmethod from_content(content)

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 from_tibiadata(content)

Builds a guild object from a TibiaData character response.

Parameters:content (str) – The json string from the TibiaData response. Returns:The guild contained in the description or None. Return type:Guild Raises:InvalidContent – If content is not a JSON response 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_tibiadata(name)

Gets the TibiaData.com URL for a given guild name.

Parameters:name (str) – The name of the guild. Returns:The URL to the guild’s page on TibiaData.com. 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

url

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

url_tibiadata

str – The URL to the guild on TibiaData.com.

House

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

Represents a house in a specific world.

id

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

name

str – The name of the house.

world

str – The name of the world the house belongs to.

status

HouseStatus – The current status of the house.

type

HouseType – The type of the house.

image_url

str – The URL to the house’s minimap image.

beds

int – The number of beds the house has.

size

int – The number of SQM the house has.

rent

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

owner

str – The current owner of the house, if any.

owner_sex

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

paid_until

datetime.datetime, optional – The date the last paid rent is due.

transfer_date

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

transferee

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

transfer_price

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

transfer_accepted

bool – Whether the house transfer has already been accepted or not.

highest_bid

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

highest_bidder

str, optional – The character that holds the highest bid.

auction_end

datetime.datetime, optional – The date when the auction will end.

owner_url

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

transferee_url

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

highest_bidder_url

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

classmethod from_content(content)

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 from_tibiadata(content)

Parses a TibiaData response into a House object.

Parameters:content (str) – The JSON content of the TibiaData response. Returns:The house contained in the response, if found. Return type:House Raises:InvalidContent – If the content is not a house JSON response from TibiaData

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

classmethod get_url_tibiadata(house_id, world)

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

url

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

url_tibiadata

str – The URL to the TibiaData.com page of the house.

ListedGuild

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

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

name

str – The name of the guild.

logo_url

str – The URL to the guild’s logo.

description

str, optional – The description of the guild.

world

str – The world this guild belongs to.

active

bool – Whether the guild is active or still in formation.

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

classmethod get_world_list_url_tibiadata(world)

Gets the TibiaData.com URL for the guild list of a specific world.

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

classmethod list_from_content(content)

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 list_from_tibiadata(content)

Builds a character object from a TibiaData character response.

Parameters:content (str) – A string containing the JSON response from TibiaData. Returns:The list of guilds contained. Return type:list of ListedGuild Raises:InvalidContent – If content is not a JSON response of TibiaData’s guild list.

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_tibiadata(name)

Gets the TibiaData.com URL for a given guild name.

Parameters:name (str) – The name of the guild. Returns:The URL to the guild’s page on TibiaData.com. 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

url

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

url_tibiadata

str – The URL to the guild on TibiaData.com.

ListedHouse

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

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

id

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

name

str – The name of the house.

world

str – The name of the world the house belongs to.

status

HouseStatus – The current status of the house.

type

HouseType – The type of house.

town

str – The town where the house is located.

size

int – The size of the house in SQM.

rent

int – The monthly cost of the house, in gold coins.

time_left

datetime.timedelta, optional – 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.

highest_bid

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

classmethod list_from_content(content)

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 list_from_tibiadata(content)

Parses the content of a house list from TibiaData.com into a list of houses

Parameters:content (str) – The raw JSON response from TibiaData Returns: Return type:list of ListedHouse Raises:InvalidContent` – Content is not the house list from TibiaData.com

classmethod get_list_url(world, town, house_type: tibiapy.enums.HouseType = <HouseType.HOUSE: 'house'>)

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.

Returns:

The URL to the list matching the parameters.

Return type:

str

classmethod get_list_url_tibiadata(world, town, house_type: tibiapy.enums.HouseType = <HouseType.HOUSE: 'house'>)

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.

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

classmethod get_url_tibiadata(house_id, world)

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

url

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

url_tibiadata

str – The URL to the TibiaData.com page of the house.

ListedWorld

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

Represents a game server listed in the World Overview section.

name

str – The name of the world.

status

str – The current status of the world.

online_count

int – The number of currently online players in the world.

location

WorldLocation – The physical location of the game servers.

pvp_type

PvpType – The type of PvP in the world.

transfer_type

TransferType – The type of transfer restrictions this world has.

battleye_protected

bool – Whether the server is currently protected with BattlEye or not.

battleye_date

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

experimental

bool – Whether the world is experimental or not.

premium_only

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

classmethod get_list_url()

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

Returns:The URL to the World Overview’s page. Return type:str

classmethod get_list_url_tibiadata()

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)

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 list_from_tibiadata(content)

Parses the content of the World Overview section from TibiaData.com.

Notes

Due to TibiaData limitations, the listed worlds lack some information. The following attributes are unavailable:

• status is always Online.
• battleye_protected is always False
• battleye_date is always None.

Parameters:content (str) – The JSON response of the worlds section in TibiaData.com Returns:A list of the worlds and their current information. Return type:list of ListedWorld Raises:InvalidContent – If the provided content is the json content of the world section in TibiaData.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

classmethod get_url_tibiadata(name)

Gets the URL to the World’s information page on TibiaData.com.

Parameters:name (str) – The name of the world. Returns:The URL to the world’s information page on TibiaData.com. 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

url

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

url_tibiadata

str – URL to the world’s information page on TibiaData.com.

World

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

Represents a Tibia game server.

name

str – The name of the world.

status

str – The current status of the world.

online_count

int – The number of currently online players in the world.

record_count

int – The server’s online players record.

record_date

datetime.datetime – The date when the online record was achieved.

location

WorldLocation – The physical location of the game servers.

pvp_type

PvpType – The type of PvP in the world.

creation_date

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

transfer_type

TransferType – The type of transfer restrictions this world has.

world_quest_titles

list of str – List of world quest titles the server has achieved.

battleye_protected

bool – Whether the server is currently protected with BattlEye or not.

battleye_date

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

experimental

bool – Whether the world is experimental or not.

online_players

list of OnlineCharacter. – A list of characters currently online in the server.

premium_only

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

creation_year

int – Returns the year when the world was created.

creation_month

ìnt – Returns the month when the world was created.

classmethod from_content(content)

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 from_tibiadata(content)

Parses a TibiaData.com response into a World

Parameters:content (str) – The raw JSON content from TibiaData Returns:The World described in the page, or None. Return type:World Raises:InvalidContent – If the provided content is not a TibiaData world response.

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

classmethod get_url_tibiadata(name)

Gets the URL to the World’s information page on TibiaData.com.

Parameters:name (str) – The name of the world. Returns:The URL to the world’s information page on TibiaData.com. 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

url

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

url_tibiadata

str – URL to the world’s information page on TibiaData.com.

WorldOverview

class tibiapy.WorldOverview(**kwargs)

Container class for the World Overview section.

record_count

int – The overall player online record.

record_date

datetime.datetime – The date when the record was achieved.

worlds

list of ListedWorld – List of worlds, with limited info.

total_online

int – Total players online across all worlds.

classmethod get_url()

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

Returns:The URL to the World Overview’s page. Return type:str

classmethod get_url_tibiadata()

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)

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

classmethod from_tibiadata(content)

Parses the content of the World Overview section from TibiaData.com into an object of this class.

Notes

Due to TibiaData limitations, record_count and record_date are unavailable object.

Additionally, the listed worlds in worlds lack some information when obtained from TibiaData. The following attributes are unavailable:

• ListedWorld.status is always Online.
• ListedWorld.battleye_protected is always False
• ListedWorld.battleye_date is always None.

Parameters:content (str) – The JSON response of the worlds section in TibiaData.com Returns:An instance of this class containing only the available worlds. Return type:WorldOverview Raises:InvalidContent – If the provided content is the json content of the world section in TibiaData.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.

AccountInformation

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

Represents the account information of a character.

created

datetime.datetime – The date when the account was created.

position

str, optional – The special position of this account, if any.

loyalty_title

str, optional – The loyalty title of the account, if any.

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)

Represents an achievement listed on a character’s page.

name

str – The name of the achievement.

grade

int – The grade of the achievement, also known as stars.

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)

Represents a House owned by a character.

id

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

name

str – The name of the house.

world

str – The name of the world the house belongs to.

status

HouseStatus – The current status of the house.

type

HouseType – The type of the house.

town

str – The town where the city is located in.

owner

str – The owner of the house.

paid_until_date

datetime.date – The date the last paid rent is due.

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

classmethod get_url_tibiadata(house_id, world)

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

url

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

url_tibiadata

str – The URL to the TibiaData.com page of the house.

Death

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

Represents a death by a character

name

str – The name of the character this death belongs to.

level

int – The level at which the death occurred.

killers

list of Killer – A list of all the killers involved.

assists

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

time

datetime.datetime – The time at which the death occurred.

by_player

bool – Whether the kill involves other characters.

killer

Killer – The first killer in the list.

This is usually the killer that gave the killing blow.

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)

Represents a House owned by a guild.

name

str – The name of the house.

world

str – The name of the world the house belongs to.

status

HouseStatus – The current status of the house.

type

HouseType – The type of the house.

owner

str – The owner of the guildhall.

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

classmethod get_url_tibiadata(house_id, world)

Gets the TibiaData.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 TibiaData.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)

Represents an invited character

name

str – The name of the character

date

datetime.date – The day when the character was invited.

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

classmethod get_url_tibiadata(name)

Gets the TibiaData.com URL for a given character name.

Parameters:name (str) – The name of the character. Returns:The URL to the character’s page on TibiaData.com. 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

url

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

url_tibiadata

str – The URL of the character’s information on TibiaData.com.

GuildMember

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

Represents a guild member.

rank

str – The rank the member belongs to

name

str – The name of the guild member.

title

str, optional – The member’s title.

level

int – The member’s level.

vocation

Vocation – The member’s vocation.

joined

datetime.date – The day the member joined the guild.

online

bool – Whether the member is online or not.

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

classmethod get_url_tibiadata(name)

Gets the TibiaData.com URL for a given character name.

Parameters:name (str) – The name of the character. Returns:The URL to the character’s page on TibiaData.com. 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

url

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

url_tibiadata

str – The URL of the character’s information on TibiaData.com.

GuildMembership

class tibiapy.GuildMembership(name, rank)

Represents the guild information of a character.

name

str – The name of the guild.

rank

str – The name of the rank the member has.

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_tibiadata(name)

Gets the TibiaData.com URL for a given guild name.

Parameters:name (str) – The name of the guild. Returns:The URL to the guild’s page on TibiaData.com. 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

url

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

url_tibiadata

str – The URL to the guild on TibiaData.com.

Killer

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

Represents a killer.

A killer can be:

1. A creature.
2. A character.
3. A creature summoned by a character.

name

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

player

bool – Whether the killer is a player or not.

summon

str, optional – The name of the summoned creature, if applicable.

url

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

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

OnlineCharacter

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

Represents an online character.

name

str – The name of the character.

world

str – The name of the world.

vocation

Vocation – The vocation of the character.

level

int – The level of the character.

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

classmethod get_url_tibiadata(name)

Gets the TibiaData.com URL for a given character name.

Parameters:name (str) – The name of the character. Returns:The URL to the character’s page on TibiaData.com. 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

url

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

url_tibiadata

str – The URL of the character’s information on TibiaData.com.

OtherCharacter

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

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

name

str – The name of the character.

world

str – The name of the world.

online

bool – Whether the character is online or not.

deleted

bool – Whether the character is scheduled for deletion or not.

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

classmethod get_url_tibiadata(name)

Gets the TibiaData.com URL for a given character name.

Parameters:name (str) – The name of the character. Returns:The URL to the character’s page on TibiaData.com. 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

url

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

url_tibiadata

str – The URL of the character’s information on TibiaData.com.

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

Base class for all character classes.

Implements common properties methods for characters.

The following implement this class:

• Character
• GuildInvite
• GuildMember
• OnlineCharacter
• OtherCharacter

name

str – The name of the character.

url

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

url_tibiadata

str – The URL of the character’s information on TibiaData.com.

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

classmethod get_url_tibiadata(name)

Gets the TibiaData.com URL for a given character name.

Parameters:name (str) – The name of the character. Returns:The URL to the character’s page on TibiaData.com. 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

class tibiapy.abc.BaseGuild

Base class for Guild classes.

The following implement this class:

• Guild
• GuildMembership

name

str – The name of the guild.

url

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

url_tibiadata

str – The URL to the guild on TibiaData.com.

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_tibiadata(name)

Gets the TibiaData.com URL for a given guild name.

Parameters:name (str) – The name of the guild. Returns:The URL to the guild’s page on TibiaData.com. 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

class tibiapy.abc.BaseHouse

Base class for all house classes

The following implement this class:

• abc.BaseHouseWithId
• GuildHouse

name

str – The name of the house.

world

str – The name of the world the house belongs to.

status

HouseStatus – The current status of the house.

type

HouseType – The type of the house.

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

classmethod get_url_tibiadata(house_id, world)

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

class tibiapy.abc.BaseHouseWithId

A derivative of BaseHouse

Implements the id attribute and dependant functions and properties.

The following implement this class:

• House
• CharacterHouse

id

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

name

str – The name of the house.

world

str – The name of the world the house belongs to.

status

HouseStatus – The current status of the house.

type

HouseType – The type of the house.

url

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

url_tibiadata

str – The URL to the TibiaData.com page of the house.

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

classmethod get_url_tibiadata(house_id, world)

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

class tibiapy.abc.BaseWorld

Base class for all World classes.

The following implement this class:

• ListedWorld
• World

name

str – The name of the world.

status

str – The current status of the world.

online_count

int – The number of currently online players in the world.

location

WorldLocation – The physical location of the game servers.

pvp_type

PvpType – The type of PvP in the world.

transfer_type

TransferType – The type of transfer restrictions this world has.

battleye_protected

bool – Whether the server is currently protected with BattlEye or not.

battleye_date

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

experimental

bool – Whether the world is experimental or not.

premium_only

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

url

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

url_tibiadata

str – URL to the world’s information page on TibiaData.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

classmethod get_url_tibiadata(name)

Gets the URL to the World’s information page on TibiaData.com.

Parameters:name (str) – The name of the world. Returns:The URL to the world’s information page on TibiaData.com. 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

class tibiapy.abc.Serializable

Contains methods to make a class convertible to JSON.

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)

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

Base exception for the tibiapy module.

All exceptions thrown by the module are inherited from this.

class tibiapy.InvalidContent

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.

Utility functions

tibiapy.utils.parse_tibia_datetime(datetime_str) → Optional[datetime.datetime]

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]

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_full_date(date_str) → Optional[datetime.date]

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

tibiapy.utils.parse_tibiadata_datetime(date_dict) → Optional[datetime.datetime]

Parses time objects from the TibiaData API.

Time objects are made of a dictionary with three keys:

date: contains a string representation of the time timezone: a string representation of the timezone the date time is based on timezone_type: the type of representation used in the timezone key

Parameters:date_dict (dict) – Dictionary representing the time object. Returns:The represented datetime, in UTC. Return type:datetime.date, optional

tibiapy.utils.parse_tibiadata_date(date_str) → Optional[datetime.date]

Parses a date from the format used in TibiaData.

Parameters:date_str (str) – The date as represented in Tibia.com Returns:The represended date. Return type:datetime.date, optional

tibiapy.utils.try_datetime(obj) → Optional[datetime.datetime]

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

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

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

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]

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:

any