hypixelez package

Submodules

• hypixelez.hypixel_api module
  • HypixelClient
    • HypixelClient.fetch_profile_info()
    • HypixelClient.get_profile_names_ids_by_id()
    • HypixelClient.get_uuid_by_name()
  • SkyblockProfileData
    • SkyblockProfileData.get_cata_class_level()
    • SkyblockProfileData.get_cata_class_xp()
    • SkyblockProfileData.get_cata_level()
    • SkyblockProfileData.get_cata_xp()
    • SkyblockProfileData.get_collection()
    • SkyblockProfileData.get_global_level()
    • SkyblockProfileData.get_global_xp()
    • SkyblockProfileData.get_skill_current_level_xp()
    • SkyblockProfileData.get_skill_level()
    • SkyblockProfileData.get_slayer_level()
    • SkyblockProfileData.get_slayer_stats()
    • SkyblockProfileData.get_slayer_stats_by_tier()
    • SkyblockProfileData.get_slayer_xp()
• hypixelez.logger module
  • get_logger()
  • setup_logging()

Module contents

class hypixelez.HypixelClient(api_key, debug=True, base_url='https://api.hypixel.net/v2/skyblock/profile')

Bases: object

HTTP client for the Hypixel SkyBlock API.

This client also supports resolving Minecraft usernames to UUIDs via Mojang API.

Parameters:

api_key (str)

fetch_profile_info(uuid, profile)

Fetch full SkyBlock profile data and wrap it in SkyblockProfileData.

Parameters:

• uuid (str) – Minecraft UUID.

• profile (str) – SkyBlock profile id.

Returns:

A SkyblockProfileData instance with the raw API response and UUID.

Raises:

• requests.RequestException – For network issues or non-2xx HTTP status.

• Exception – If Hypixel returns success=false (API-level error).

Notes

On API-level errors the code currently raises a generic Exception. Consider introducing a custom exception type for better UX and docs.

get_profile_names_ids_by_id(uuid)

Get available SkyBlock profiles for a player UUID.

Parameters:

uuid (str) – Minecraft UUID.

Returns:

A mapping {profile_name: profile_id}, where profile_name is the Hypixel “cute_name” (e.g. “Peach”), and profile_id is the profile id.

Raises:

requests.RequestException – If the underlying HTTP request fails.

Return type:

dict

Notes

This method currently assumes the response contains a "profiles" key.

get_uuid_by_name(name)

Resolve a Minecraft username to a UUID using Mojang API.

The result is cached in-memory for the lifetime of the client.

Parameters:

name (str) – Minecraft username.

Returns:

The UUID string if found; otherwise None. Returns None also in case of network errors.

Return type:

str | None

Notes

This method currently swallows requests exceptions and returns None instead of raising.

class hypixelez.SkyblockProfileData(raw_data, uuid)

Bases: object

Wrapper around Hypixel SkyBlock profile JSON with convenience getters.

Most getter methods are “safe”: if the requested data is missing, they return a default value (usually 0 or an empty list) and log a warning.

get_cata_class_level(class_name)

Get the dungeon class level.

Parameters:

class_name – Dungeon class id (e.g. “mage”, “berserk”, “archer”, “tank”, “healer”).

Returns:

Class level if present, otherwise 0.

Return type:

int

get_cata_class_xp(class_name)

Get dungeon class XP progress within the current class level.

Parameters:

class_name – Dungeon class id (e.g. “mage”, “berserk”, “archer”, “tank”, “healer”).

Returns:

Current class level XP progress if present, otherwise 0.

Return type:

int

get_cata_level()

Get the Catacombs level.

Returns:

Catacombs level if present, otherwise 0.

Return type:

int

get_cata_xp()

Get Catacombs XP progress within the current Catacombs level.

Returns:

Current Catacombs level XP progress if present, otherwise 0.

Return type:

int

get_collection(collection_name)

Get the amount collected for a specific collection.

Parameters:

collection_name (CollectionKey | str) – Collection key (e.g. “LOG”, “WHEAT”). Full list: CollectionKey.

Returns:

Collection amount if present, otherwise 0.

Return type:

int

get_global_level()

Get the global SkyBlock level.

Returns:

Global level if present, otherwise 0.

Return type:

int

Notes

The current implementation derives level as experience // 100.

get_global_xp()

Get XP progress within the current global SkyBlock level.

Returns:

Current global level XP progress if present, otherwise 0.

Return type:

int

Notes

The current implementation derives progress as experience % 100.

get_skill_current_level_xp(skill_name)

Get XP progress within the current level for a given skill.

Parameters:

skill_name – Skill XP key (e.g. “SKILL_CARPENTRY”).

Returns:

Current level XP progress if present, otherwise 0.

Return type:

int

get_skill_level(skill_name)

Get the current level for a given SkyBlock skill.

Parameters:

skill_name – Skill XP key (e.g. “SKILL_CARPENTRY”).

Returns:

Skill level if present, otherwise 0.

Return type:

int

get_slayer_level(slayer_name)

Get the slayer level derived from claimed levels.

Parameters:

slayer_name – Slayer id (e.g. “zombie”, “spider”, “wolf”, …).

Returns:

Highest claimed slayer level if present, otherwise 0.

Return type:

int

get_slayer_stats(slayer_name)

Get slayer boss kill statistics by tiers.

Parameters:

slayer_name – Slayer id (e.g. “zombie”, “spider”, “wolf”, …).

Returns:

A list of tier kill counts if present, otherwise an empty list.

Return type:

list

Notes

The current implementation iterates over keys inside the slayer dict and appends values for keys that contain "boss_kills_tier". If you need stable ordering (tier1..tierN), consider sorting keys.

get_slayer_stats_by_tier(slayer_name, tier)

Get slayer boss kill count for a specific tier.

Parameters:

• slayer_name – Slayer id (e.g. “zombie”, “spider”, “wolf”, …).

• tier – Tier number (1-indexed). For example, tier=1 means “tier I”.

Returns:

Kill count for the requested tier if present, otherwise 0.

Return type:

int

Notes

If tier is out of range, the implementation will fall back to 0.

get_slayer_xp(slayer_name)

Get total slayer XP for a specific slayer.

Parameters:

slayer_name – Slayer id (e.g. “zombie”, “spider”, “wolf”, …).

Returns:

Total slayer XP if present, otherwise 0.

Return type:

int