API Reference#

This section outlines the API of hypixel.py.

Version Info#

hypixel.__version__#

A string representation of the version. E.g. '1.0.0rc1'. Based off of PEP 440.

Client#

Attributes
Methods
class hypixel.Client(keys=None, *, loop=None, **options)#

Class for interacting with both the Mojang and Hypixel APIs.

Parameters:

  • keys (Union[str, List[str]]) –

    The Hypixel API key(s) the client will use to access the API.

    Warning

    KeyRequired will be raised if a method is called that requires an API key and none were passed or added with add_key().

    Warning

    Please note that using multiple keys is disallowed by Hypixel: “You may not use methods such as multiple accounts to bypass the API limits.” Refer to (https://github.com/HypixelDev/PublicAPI/issues/229) and (https://api.hypixel.net/#section/Introduction/Rules) for more information. Hypixel.py does not encourage the use of multiple keys.

  • loop (asyncio.AbstractEventLoop) – The loop the client will use for asynchronous operations. Defaults to None in which case the event loop is created using asyncio.get_event_loop().

  • autoverify (bool) – Runs validate_keys() on client initialization. Defaults to False.

  • cache (bool) –

    Whether or not API calls are cached. If True, new requests won’t be made for the same calls to request methods if the response for the passed arguments is still stored. Defaults to False.

    Note

    Cached items will be accessible either until the size limit is reached (self.cache_size), or the cached data expires (self.cache_time).

    Note

    The cache uses an async, time-invalidating, least recently used implementation. This means it works on asynchronous functions, can invalidate items that have been in the cache for x amount of time, and can remove least recently used items if the size limit is reached.

    Limitations

    When a cached item is time-invalidated, it does not get removed from the cache and can inflate the cache size with multiple of the same item if they were called far enough apart from each other and self.cache_time is not None. Also, self.cache_time is based on the time from when it’s first added to the cache, and not refreshed on the last access to that cached item. This could also be considered a feature and is therefore a design decision.

  • cache_h (bool) – Whether or not to cache Hypixel API calls. Refer to self.cache for more information. Defaults to self.cache.

  • cache_m (bool) – Whether or not to cache Mojang API calls. Refer to self.cache for more information. Defaults to self.cache.

  • cache_size (int) – The amount of cached items that are stored before deleting the oldest items. If None (the default), then there is no limit.

  • cache_size_h (int) – Cache size for the Hypixel API. Refer to self.cache_size for more information. Defaults to self.cache_size.

  • cache_size_m (int) – Cache size for the Mojang API. Refer to self.cache_size for more information. Defaults to self.cache_size.

  • cache_time (int) –

    The amount of time (in seconds) cached items can be stored before getting invalidated. Defaults to 60.

    Note

    The timestamp of a cached item is stored when the function is called, not when it is returned. So, the time the API takes to get the request counts towards the time invalidation. That’s why it’s recommended to have a value of at least 10, but for the average use case it should be at least 60 to get any cache hits.

  • cache_time_h (int) – Cache time for the Hypixel API. Refer to self.cache_time for more information. Defaults to self.cache_time.

  • cache_time_m (int) – Cache time for the Mojang API. Refer to self.cache_time for more information. Defaults to self.cache_time.

  • rate_limit (bool) –

    Whether or not to handle rate limits. Defaults to True.

    Note

    For the Hypixel API, this will wait for the ‘Retry-After’ header’s amount of time either until a non-429 status is returned, or ‘Retry-After’ exceeds self.timeout.

    Note

    For the Mojang API, this will wait for ExponentialBackoff.delay() amount of time either until a non-429 status is returned, or the time from the last invocation exceeds self.timeout in which case TimeoutError is raised. The delay time is reset on every new Mojang method call.

  • rate_limit_h (bool) – Whether or not to handle Hypixel API rate limits. See self.rate_limit for more information. Defaults to self.rate_limit.

  • rate_limit_m (bool) – Whether or not to handle Mojang API rate limits. See self.rate_limit for more information. Defaults to self.rate_limit.

  • timeout (int) –

    The maximum amount of time (in seconds) to wait for a request. This includes both waiting for a request to return, and waiting for rate limit retry times if self.rate_limit is True. Defaults to 10.

    Warning

    None is a valid argument; however, it is advised against using because there’s no fallback without a timeout, and there are chances you might end up waiting a very long time.

    Warning

    If self.rate_limit is True (default), then for Mojang API requests, if a 429 response is received and the interval is greater than self.timeout, then it will raise a TimeoutError.

Raises:
property keys#

A list of Hypixel API key(s) that were passed or added to the client.

Can also be None.

Type:

List[str]

property hypixel_cache_info#

A named tuple that represents cache information for all Hypixel API related methods.

This is the same as functools.lru_cache.cache_info(). Fields are hits, misses, maxsize, and currsize. All of which are an int except maxsize which can also be None.

Type:

type

property mojang_cache_info#

A named tuple that represents cache information for all Mojang related methods.

This is the same as functools.lru_cache.cache_info(). Fields are hits, misses, maxsize, and currsize. All of which are an int except maxsize which can also be None.

Type:

type

await close()#

Safely closes the aiohttp session.

Note

This is here to handle the closing of the self.ClientSession by yourself if you are done using the Client. You can also use the Client with an asynchronous context manager (async with) if you want to handle session cleanup automatically.

Warning

Make sure this is awaited before the program ends if you aren’t using a context manager.

Warning

Calling a client method that requires an open aiohttp session after this is called will raise a ClosedSession exception.

await validate_keys()#

Validates the keys passed into the client.

This method requests data from Hypixel.

Note

This first checks for malformed UUIDs, and then requests key objects from the API to check if the keys are valid.

Note

An error is raised when the first invalid key is found, so this is not viable for testing all of your keys at once if more than one is invalid.

Raises:
add_key(key)#

Adds a key to keys and update internal attributes.

Parameters:

key (str) – The Hypixel API key to add to the Client.

remove_key(key)#

Removes a key from keys and update internal attributes.

Parameters:

key (str) – The Hypixel API key to remove from the Client.

clear_cache()#

Clear hypixel and mojang caches.

clear_mojang_cache()#

Clear mojang cache.

clear_hypixel_cache()#

Clear hypixel cache.

await get_uuid(name)#

Returns the uuid of a player from their username.

This method requests data from Mojang.

Parameters:

name (str) – The username of the player.

Raises:

  • ApiError – An unexpected error occurred with the Mojang API.

  • ClosedSession – self.ClientSession is closed.

  • InvalidPlayerId – The passed player name is not a string.

  • PlayerNotFound – The passed player name does not exist.

  • RateLimitError – The rate limit is exceeded and self.rate_limit_m is False.

  • TimeoutError – The request took longer than self.timeout, or the retry delay time is longer than self.timeout.

Returns:

The uuid of the player.

Return type:

str

await get_name(uuid)#

Returns the username of a player from their uuid.

This method requests data from Mojang.

Parameters:

uuid (str) – The uuid of the player.

Raises:

  • ApiError – An unexpected error occurred with the Mojang API.

  • ClosedSession – self.ClientSession is closed.

  • InvalidPlayerId – The passed player uuid is not a string.

  • PlayerNotFound – The passed player uuid does not exist.

  • RateLimitError – The rate limit is exceeded and self.rate_limit_m is False.

  • TimeoutError – The request took longer than self.timeout, or the retry delay time is longer than self.timeout.

Returns:

The name of the player.

Return type:

str

await player(id_)#

Returns player info.

This method requests data from Hypixel.

Note

If a username is passed instead of a uuid, then API errors can also apply to Mojang’s API since it will be called to get the uuid.

Parameters:

id_ (str) – The username or uuid of a player.

Raises:

  • ApiError – An unexpected error occurred with the Hypixel or Mojang API.

  • ClosedSession – self.ClientSession is closed.

  • InvalidApiKey – The API key used is invalid.

  • KeyRequired – The client does not have any keys.

  • PlayerNotFound – The passed player id does not exist in Mojang’s or Hypixel’s databases.

  • RateLimitError – The rate limit is exceeded and self.rate_limit_h is False.

  • TimeoutError – The request took longer than self.timeout, or the retry delay time is longer than self.timeout.

Returns:

A player model used to abstract data.

Return type:

Player

await player_count()#

Returns the number of players connected to Hypixel.

This method requests data from Hypixel.

Raises:

  • ApiError – An unexpected error occurred with the Hypixel API.

  • ClosedSession – self.ClientSession is closed.

  • InvalidApiKey – The API key used is invalid.

  • KeyRequired – The client does not have any keys.

  • RateLimitError – The rate limit is exceeded and self.rate_limit_h is False.

  • TimeoutError – The request took longer than self.timeout, or the retry delay time is longer than self.timeout.

Returns:

The number of players connected to Hypixel.

Return type:

int

await key(key)#

Returns key info.

This method requests data from Hypixel.

Parameters:

key (str) –

The Hypixel API key the model will be made for.

Note

Can be passed with or without dashes.

Raises:

  • ApiError – An unexpected error occurred with the Hypixel API.

  • ClosedSession – self.ClientSession is closed.

  • InvalidApiKey – The API key used is invalid.

  • RateLimitError – The rate limit is exceeded and self.rate_limit_h is False.

  • TimeoutError – The request took longer than self.timeout, or the retry delay time is longer than self.timeout.

Returns:

A key model used to abstract data.

Return type:

Key

await bans()#

Returns staff and watchdog ban info.

This method requests data from Hypixel.

Raises:

  • ApiError – An unexpected error occurred with the Hypixel API.

  • ClosedSession – self.ClientSession is closed.

  • InvalidApiKey – The API key used is invalid.

  • KeyRequired – The client does not have any keys.

  • RateLimitError – The rate limit is exceeded and self.rate_limit_h is False.

  • TimeoutError – The request took longer than self.timeout, or the retry delay time is longer than self.timeout.

Returns:

A ban model used to abstract data.

Return type:

Bans

await player_status(id_)#

Get the status of a player.

await guild_from_id(id_)#

Get a guild from the id.

await guild_from_player(id_)#

Get a guild from a player.

await guild_from_name(name)#

Get a guild from the name.

await leaderboards()#

Get the game leaderboards.

API Models#

API Models are dataclasses that are not meant to be manually constructed.

Danger

These are not intended to be created by users and should be treated as read-only.

Note

Although attributes are technically modifiable, it is not recommended to do so.

Bans#

Attributes
class hypixel.Bans#

Bans(raw: dict, staff_day: int, staff_total: int, watchdog_recent: int, watchdog_day: int, watchdog_total: int)

raw#
staff_day#
staff_total#
watchdog_recent#
watchdog_day#
watchdog_total#

Guild#

Attributes
class hypixel.Guild#

Guild model object.

id#
name#
exp#
created#
level#
legacy_rank = None#
members#
ranks#
winners = 0#
experience_kings = 0#
most_online_players = 0#
joinable = False#
tag = None#
tag_color = None#
description = None#
preferred_games#
publicly_listed = False#
game_exp#
Attributes
class hypixel.GuildMember#

GuildMember(uuid: ‘str’, rank: ‘GuildRank’, joined: ‘datetime’, exp_history: ‘Dict[datetime, int]’, quest_participation: ‘int’ = 0, name: ‘Optional[str]’ = None)

uuid#
rank#
joined#
exp_history#
quest_participation = 0#
name = None#
Attributes
class hypixel.GuildRank#

GuildRank(name: ‘str’, default: ‘bool’ = False, created: ‘Optional[datetime]’ = None, priority: ‘Optional[int]’ = None, tag: ‘Optional[str]’ = None)

name#
default = False#
created = None#
priority = None#
tag = None#

Key#

Attributes
class hypixel.Key#

Key(raw: dict, key: str, owner: str, limit: int, queries: int = 0, recent_queries: int = 0)

raw#
key#
owner#
limit#
queries = 0#
recent_queries = 0#

Leaderboards#

Attributes
class hypixel.Leaderboard#

Leaderboard(path: str, prefix: str, title: str, location: Tuple[int, int, int], leaders: list)

path#
prefix#
title#
location#
leaders#

Player#

Attributes
Methods
class hypixel.models.player.Player#

Player model object.

Tip

You can use the == operator to compare two Player classes.

raw#

The raw json response returned from the API.

Type:

dict

id#

Hypixel’s unique identifier.

Type:

str

uuid#

Mojang’s unique identifier.

Type:

str

first_login#

The first login time represented as a datetime in the UTC timezone.

Type:

datetime.datetime

name#

The username of the player with correct capitalization.

Note

If the player changed their username after last_login, then this attribute will be outdated.

Type:

str

last_login#

The last login time represented as a datetime in the UTC timezone.

Type:

datetime.datetime

last_logout#

The last logout time represented as a datetime in the UTC timezone.

Type:

datetime.datetime

achievements#

A list of achievement name strings.

Tip

You can use hypixel.Achievement.from_type() to get the achievement object from its type name string. You can also use build_achievements() to build a list of Achievement objects.

Type:

List[str]

network_exp#

The player’s current network experience points.

Type:

int

karma#

The player’s current karma.

Type:

int

achievement_points#

The player’s achievement points.

Type:

int

current_gadget#

The player’s current gadget equipped in lobbies.

Type:

str

channel#

The current text channel the player is in.

Note

Will be None if the player’s Online Status API setting is disabled.

Type:

Optional[str]

rank#

A string representation of the player’s rank if it exists; otherwise None.

Possible values are 'VIP', 'VIP+', 'MVP', 'MVP+', 'MVP++', 'YOUTUBE', 'PIG+++', 'MOJANG', 'GAME MASTER', 'ADMIN', and 'OWNER'.

Type:

Optional[str]

plus_color#

The player’s plus color if their rank has a plus in it; otherwise None.

Type:

Optional[Color]

level#

The player’s Hypixel level.

Type:

float

most_recent_game#

The player’s most recent game they played.

Note

Will be None if the player’s Recent Games API setting is disabled.

Type:

Optional[Game]

arcade#

A model for abstracting arcade data.

Type:

Arcade

bedwars#

A model for abstracting bedwars data.

Type:

Bedwars

blitz#

A model for abstracting blitz data.

Type:

Blitz

duels#

A model for abstracting duels data.

Type:

Duels

murder_mystery#

A model for abstracting murder mystery data.

Type:

MurderMystery

paintball#

A model for abstracting paintball data.

Type:

Paintball

parkour#

A model for abstracting parkour data.

Type:

Parkour

skywars#

A model for abstracting skywars data.

Type:

Skywars

socials#

A model for abstracting socials data.

Type:

Socials

tkr#

A model for abstracting tkr data.

Type:

TurboKartRacers

tnt_games#

A model for abstracting tnt games data.

Type:

TntGames

uhc#

A model for abstracting uhc data.

Type:

Uhc

wool_games#

A model for abstracting wool games data.

Type:

WoolGames

build_achievements()#

Converts the achievements in achievements to List[Achievement].

Warning

If the package hypixel.py-data is not installed, this will convert achievements to an empty list.

Attributes
class hypixel.models.player.Arcade#

Arcade(_data: dict, coins: int = 0)

coins = 0#
ctw#
hypixel_says#
mini_walls#
party_games#
Attributes
class hypixel.models.player.CaptureTheWool#

CaptureTheWool(captures: int = 0, kills_assists: int = 0)

captures = 0#
kills_assists = 0#
Attributes
class hypixel.models.player.HypixelSays#

HypixelSays(rounds: int = 0, wins: int = 0, top_score: int = 0)

rounds = 0#
wins = 0#
top_score = 0#
losses#
wlr#
Attributes
class hypixel.models.player.MiniWalls#

MiniWalls(kills: int = 0, deaths: int = 0, wins: int = 0, final_kills: int = 0, wither_kills: int = 0, wither_damage: int = 0, arrows_hit: int = 0, arrows_shot: int = 0)

kills = 0#
deaths = 0#
wins = 0#
final_kills = 0#
wither_kills = 0#
wither_damage = 0#
arrows_hit = 0#
arrows_shot = 0#
kdr#
Attributes
class hypixel.models.player.PartyGames#

PartyGames(wins: int = 0, wins_2: int = 0, wins_3: int = 0)

wins = 0#
wins_2 = 0#
wins_3 = 0#
total_wins#
Attributes
class hypixel.models.player.Bedwars#

Base model for bedwars stats.

Note

Overall stats only include core modes.

level#

Level.

Type:

int

coins#

Coins.

Type:

int

kills#

Normal kills.

Type:

int

deaths#

Normal deaths.

Type:

int

fall_deaths#

Deaths from fall damage.

Type:

int

void_deaths#

Deaths from the void.

Type:

int

wins#

Wins.

Type:

int

losses#

Losses.

Type:

int

games#

Total games played.

Note

This number is usually a bit higher than self.wins + self.losses for an unknown reason.

Type:

int

final_kills#

Final kills.

Type:

int

final_deaths#

Final deaths.

Type:

int

fall_final_deaths#

Final deaths from fall damage.

Type:

int

void_final_deaths#

Final deaths from the void.

Type:

int

beds_broken#

Beds broken.

Type:

int

beds_lost#

Beds lost.

Type:

int

winstreak#

Winstreak.

Note

If the player has winstreaks disabled in their API settings, then this will be None.

Type:

Optional[int]

exp#

Experience points.

Type:

int

kdr#

Kill death ratio; self.kills / self.deaths.

Type:

float

wlr#

Win loss ratio; self.wins / self.losses.

Type:

float

fkdr#

Final kill death ratio; self.final_kills / self.final_deaths.

Type:

float

bblr#

Bed break bed loss ratio; self.beds_broken / self.beds_lost.

Type:

float

solo#

A model for abstracting solo bedwars data.

Type:

BedwarsMode

doubles#

A model for abstracting doubles bedwars data.

Type:

BedwarsMode

threes#

A model for abstracting threes bedwars data.

Type:

BedwarsMode

fours#

A model for abstracting fours bedwars data.

Type:

BedwarsMode

teams#

A model for abstracting teams bedwars data.

Type:

BedwarsMode

Attributes
class hypixel.models.player.BedwarsMode#

Base model for bedwars mode stats.

kills#

Normal kills.

Type:

int

deaths#

Normal deaths.

Type:

int

fall_deaths#

Deaths from fall damage.

Type:

int

void_deaths#

Deaths from the void.

Type:

int

wins#

Wins.

Type:

int

losses#

Losses.

Type:

int

games#

Total games played.

Note

This number tends to be a bit higher than self.wins + self.losses for an unknown/unresearched reason.

Type:

int

final_kills#

Final kills.

Type:

int

final_deaths#

Final deaths.

Type:

int

fall_final_deaths#

Final deaths from fall damage.

Type:

int

void_final_deaths#

Final deaths from the void.

Type:

int

beds_broken#

Beds broken.

Type:

int

beds_lost#

Beds lost.

Type:

int

kdr#

Kill death ratio; self.kills / self.deaths.

Type:

float

wlr#

Win loss ratio; self.wins / self.losses.

Type:

float

fkdr#

Final kill death ratio; self.final_kills / self.final_deaths.

Type:

float

bblr#

Bed break bed loss ratio; self.beds_broken / self.beds_lost.

Type:

float

Attributes
class hypixel.models.player.Blitz#

Blitz(coins: int = 0, kills: int = 0, deaths: int = 0, wins: int = 0, wins_solo: int = 0, wins_team: int = 0, arrows_hit: int = 0, arrows_shot: int = 0, chests_opened: int = 0, games: int = 0)

coins = 0#
kills = 0#
deaths = 0#
wins = 0#
wins_solo = 0#
wins_team = 0#
arrows_hit = 0#
arrows_shot = 0#
chests_opened = 0#
games = 0#
kdr#
wlr#
ar#
Attributes
class hypixel.models.player.Duels#

Duels(_data: dict, coins: int = 0, kills: int = 0, deaths: int = 0, wins: int = 0, losses: int = 0, melee_hits: int = 0, melee_swings: int = 0, arrows_hit: int = 0, arrows_shot: int = 0)

coins = 0#
kills = 0#
deaths = 0#
wins = 0#
losses = 0#
melee_hits = 0#
melee_swings = 0#
arrows_hit = 0#
arrows_shot = 0#
wlr#
mr#
ar#
title#
blitz#
bow#
boxing#
bridge#
classic#
combo#
mega_walls#
no_debuff#
op#
parkour#
skywars#
sumo#
tnt_games#
uhc#
Attributes
class hypixel.models.player.DuelsMode#

DuelsMode(_data: dict, _mode: str, kills: int = 0, deaths: int = 0, wins: int = 0, losses: int = 0, melee_hits: int = 0, melee_swings: int = 0, arrows_hit: int = 0, arrows_shot: int = 0)

kills = 0#
deaths = 0#
wins = 0#
losses = 0#
melee_hits = 0#
melee_swings = 0#
arrows_hit = 0#
arrows_shot = 0#
wlr#
mr#
ar#
title#
Attributes
class hypixel.models.player.MurderMystery#

MurderMystery(_data: dict, coins: int = 0, games: int = 0, wins: int = 0, kills: int = 0, deaths: int = 0, bow_kills: int = 0, knife_kills: int = 0, thrown_knife_kills: int = 0, murderer_wins: int = 0, detective_wins: int = 0)

coins = 0#
games = 0#
wins = 0#
kills = 0#
deaths = 0#
bow_kills = 0#
knife_kills = 0#
thrown_knife_kills = 0#
murderer_wins = 0#
detective_wins = 0#
kdr#
assassins#
classic#
double_up#
hardcore#
showdown#
Attributes
class hypixel.models.player.MurderMysteryMode#

MurderMysteryMode(games: int = 0, wins: int = 0, kills: int = 0, deaths: int = 0, bow_kills: int = 0, knife_kills: int = 0, thrown_knife_kills: int = 0, removed: bool = False)

games = 0#
wins = 0#
kills = 0#
deaths = 0#
bow_kills = 0#
knife_kills = 0#
thrown_knife_kills = 0#
removed = False#
kdr#
Attributes
class hypixel.models.player.Paintball#

Paintball(coins: int = 0, wins: int = 0, kills: int = 0, deaths: int = 0, killstreaks: int = 0, shots_fired: int = 0)

coins = 0#
wins = 0#
kills = 0#
deaths = 0#
killstreaks = 0#
shots_fired = 0#
kdr#
skr#
Attributes
class hypixel.models.player.Parkour#

Parkour(_data: dict)

arcade#
bedwars#
blitz#
build_battle#
cops_and_crims#
duels#
main#
mega_walls#
murder_mystery#
skywars#
smash#
tnt#
uhc#
warlords#
Attributes
class hypixel.models.player.ParkourLobby#

ParkourLobby(completed: datetime.datetime, time: datetime.timedelta)

completed#
time#
Attributes
class hypixel.models.player.Skywars#

Skywars(_data: dict, coins: int = 0, kills: int = 0, deaths: int = 0, wins: int = 0, losses: int = 0, games: int = 0, arrows_hit: int = 0, arrows_shot: int = 0, winstreak: Union[int, NoneType] = None, souls: int = 0, exp: int = 0)

level#
coins = 0#
kills = 0#
deaths = 0#
wins = 0#
losses = 0#
games = 0#
arrows_hit = 0#
arrows_shot = 0#
winstreak = None#
souls = 0#
exp = 0#
kdr#
wlr#
ar#
ranked#
solo_normal#
solo_insane#
team_normal#
team_insane#
mega_normal#
mega_doubles#
Attributes
class hypixel.models.player.SkywarsMode#

SkywarsMode(kills: int = 0, deaths: int = 0, wins: int = 0, losses: int = 0)

kills = 0#
deaths = 0#
wins = 0#
losses = 0#
kdr#
wlr#
Attributes
class hypixel.models.player.Socials#

Socials(discord: Union[str, NoneType] = None, youtube: Union[str, NoneType] = None, twitter: Union[str, NoneType] = None, twitch: Union[str, NoneType] = None, instagram: Union[str, NoneType] = None, hypixel_forums: Union[str, NoneType] = None)

discord = None#
youtube = None#
twitter = None#
twitch = None#
instagram = None#
hypixel_forums = None#
Attributes
class hypixel.models.player.TurboKartRacers#

TurboKartRacers(coins: int = 0, laps: int = 0, gold: int = 0, silver: int = 0, bronze: int = 0, blue_torpedo_hits: int = 0, banana_hits: int = 0, bananas_received: int = 0, wins: int = 0)

coins = 0#
laps = 0#
gold = 0#
silver = 0#
bronze = 0#
blue_torpedo_hits = 0#
banana_hits = 0#
bananas_received = 0#
wins = 0#
br#
Attributes
class hypixel.models.player.TntGames#

TntGames(coins: int = 0)

coins = 0#
Attributes
class hypixel.models.player.Uhc#

Uhc(_data: dict, coins: int = 0, score: int = 0, parkour_1: bool = False, parkour_2: bool = False)

level#
coins = 0#
score = 0#
parkour_1 = False#
parkour_2 = False#
wins#
kills#
deaths#
heads_eaten#
ultimates_crafted#
solo#
team#
brawl#
kdr#
Attributes
class hypixel.models.player.UhcMode#

UhcMode(wins: int = 0, kills: int = 0, deaths: int = 0, heads_eaten: int = 0, ultimates_crafted: int = 0)

wins = 0#
kills = 0#
deaths = 0#
heads_eaten = 0#
ultimates_crafted = 0#
kdr#
Attributes
class hypixel.models.player.WoolGames#

WoolGames(_data: dict, level: int = 1, coins: int = 0, exp: int = 0)

level = 1#
coins = 0#
exp = 0#
wool_wars#
Attributes
class hypixel.models.player.WoolGamesMode#

WoolGamesMode(kills: int = 0, deaths: int = 0, assists: int = 0, wins: int = 0, games: int = 0, blocks_broken: int = 0, wool_placed: int = 0, selected_class: str = None)

kills = 0#
deaths = 0#
assists = 0#
wins = 0#
losses#
games = 0#
blocks_broken = 0#
wool_placed = 0#
selected_class = None#
kdr#
wlr#

Status#

Attributes
class hypixel.Status#

Status(raw: dict, online: bool = False, game: Union[hypixel.game.Game, NoneType] = None, mode: Union[str, NoneType] = None, map: Union[str, NoneType] = None)

raw#
online = False#
game = None#
mode = None#
map = None#

Data Classes#

These classes are data containers.

They hold metadata for what would otherwise be arbitrary strings returned by the API.

Achievement#

Attributes
Methods
class hypixel.Achievement#

Represents a Hypixel achievement.

type_name#

The type name used to reference the achievement in the Hypixel API.

Type:

str

points#

Amount of achievement points the achievement is worth.

Type:

int

name#

The name of the achievement.

Type:

str

description#

The description of the achievement.

Type:

str

global_unlocked#

The percentage of players who have unlocked the achievement.

Note

For achievements which legacy is True, this attribute will be None.

Type:

Optional[float]

game_unlocked#

The percentage of players who have unlocked the achievement that have played the game.

Note

Achievements that do not have a game associated with them will have this attribute as None.

Type:

Optional[float]

legacy#

Whether or not the achievement is legacy.

Type:

bool

classmethod from_type(type_name)#

Constructs an Achievement from its type name.

This method requires the hypixel.py-data package.

Warning

Some achievements that come from the Hypixel API will return None. This is because the API does not provide the data for some older achievements.

Parameters:

type_name (str) – The type name used in Hypixel API attributes.

Returns:

The constructed achievement, or None if the achievement could not be found.

Return type:

Optional[Achievement]

Color#

Attributes
Methods
class hypixel.Color#

Represents a Minecraft color.

type_name#

The name used to reference the color in the Hypixel API.

Type:

str

clean_name#

The color name in Title Case.

Type:

str

chat_code#

The Minecraft chat formatting code for the color.

Type:

str

hexadecimal#

The hexadecimal value of the color.

Type:

str

classmethod from_type(type_name)#

Constructs a Color from its type name.

Parameters:

type_name (str) – The type name used in Hypixel API attributes.

Returns:

The constructed color object, or None if the type name is invalid.

Return type:

Optional[Color]

Game#

Attributes
Methods
class hypixel.Game#

Represents a Hypixel game.

id#

The id of the game.

Note

Although there are ids ranging from 2-68, there aren’t 66 game types as some are skipped for whatever reason.

Type:

int

type_name#

The type name used in Hypixel API attributes.

Type:

str

database_name#

The key value used in the Hypixel API.

Type:

str

clean_name#

The game name in Title Case.

Type:

str

standard_name#

Sometimes shorter than self.clean_name.

Type:

str

legacy#

Whether or not the game is a legacy game.

Type:

bool

classmethod from_type(type_name)#

Constructs a Game from its type name.

Parameters:

type_name (str) – The type name used in Hypixel API attributes.

Returns:

The constructed game object, or None if the type name is invalid.

Return type:

Optional[Game]

classmethod from_id(id_)#

Constructs a Game from its id.

Parameters:

id (int) – The id number of the game.

Returns:

The constructed game object, or None if the id is invalid.

Return type:

Optional[Game]

Utilities#

Methods
class hypixel.ExponentialBackoff(timeout=2048)#

An implementation of the exponential backoff algorithm.

Provides a convenient interface to implement an exponential backoff for reconnecting or retrying transmissions.

Once instantiated, the delay method will return the next interval to wait for when retrying a connection or transmission. The maximum delay increases exponentially with each retry up to a maximum of 2^10 * base.

Raises:

TimeoutError – Raised when the difference of time from the last request is greater than the client’s timeout.

delay()#

Compute the next delay.

Returns the next delay to wait according to the exponential backoff algorithm. This is a value between 0 and base * 2^exp where exponent starts off at 1 and is incremented at every invocation of this method up to a maximum of 10.

If a period of more than base * 2^11 has passed since the last retry, the exponent is reset to 1.

Exceptions#

exception hypixel.HypixelException#

Base exception for hypixel.py

Theoretically, this can be used to catch all errors from this library.

exception hypixel.ArgumentError(message)#

Raised when a passed argument is faulty.

Inherits from HypixelException

Note

Could be from either an invalid type or if the argument passed does not yield an API response.

exception hypixel.InvalidPlayerId(player_id)#

Raised when a passed player id is not a string.

Inherits from ArgumentError

id#

The invalid player id.

Type:

str

exception hypixel.PlayerNotFound(player)#

Raised when a requested player does not exist.

Inherits from ArgumentError

player#

The player requested. Could be a uuid or a username.

Type:

str

exception hypixel.KeyNotFound(key)#

Raised when a requested key does not exist.

Inherits from ArgumentError

key#

The key requested.

Type:

str

exception hypixel.ApiError(response, api, message=None)#

Base exception for when an API request fails.

Inherits from HypixelException

api#

The API that caused the error.

Type:

str

response#

The client response object that was received.

Type:

aiohttp.ClientResponse

exception hypixel.TimeoutError(api)#

Raised when the client did not receive a response within the required time.

Inherits from ApiError

api#

The API that caused the error.

Type:

str

exception hypixel.RateLimitError(retry_after, api, response)#

Raised when the rate limit is reached.

Inherits from ApiError

Note

Will not be raised if Client.handle_rate_limits is True (default).

retry_after#

The time to wait until to retry a request.

Type:

datetime.datetime

exception hypixel.InvalidApiKey(key, message=None)#

Base exception for invalid API key exceptions.

Inherits from ArgumentError

Note

Will not be raised until a request is made unless the key is malformed or Client.validate_keys() is called.

Warning

For simplicity, if multiple API keys are invalid, only the first one will be included, even if Client.validate_keys() is called multiple times.

key#

The key that caused the error.

Type:

str

exception hypixel.MalformedApiKey(key)#

Raised when a passed API key is not in valid uuid format.

Inherits from InvalidApiKey and ValueError

key#

The key that caused the error. See InvalidApiKey for details.

Type:

str

exception hypixel.KeyRequired(path)#

Raised when an API key is required but none were passed.

Inherits from InvalidApiKey and TypeError

path#

The API endpoint the error was from.

Type:

str

exception hypixel.ClosedSession#

Raised when the Client tries to make an API call after Client.close() is called.

Inherits from HypixelException and RuntimeError

Note

If Client.cache is True and the response is stored in cache, ClosedSession won’t be raised and the function will return normally.

exception hypixel.LoopPolicyError#

Raised when the event loop policy is misconfigured.

Inherits from HypixelException and RuntimeError

exception hypixel.GuildNotFound(guild)#

Raised when a requested guild does not exist.

Inherits from ArgumentError

guild#

The guild requested. Could be a username, a player uuid, a guild name, or a guild uuid.

Type:

str

Exception Hierarchy#