PyPixel
An asynchronous wrapper for the Hypixel API.
Attention
As of version 0.1.8, attributes will no longer be missing and should instead have a value of None
.
If there are still attributes missing, please open an issue on our GitHub.
Tutorial
The following is a tutorial for using PyPixel.
Installation
To install the module, simply use pip:
# Linux/macOS
python3 -m pip install -U pypixel-api
# Windows
py -3 -m pip install -U pypixel-api
Or, if you wish, you can install the development version off of GitHub:
# Linux/macOS
python3 -m pip install -U git+https://github.com/plun1331/PyPixel
# Windows
py -3 -m pip install -U git+https://github.com/plun1331/PyPixel
Obtaining an API Key
To use the module, you must first generate an API key.
Open Minecraft: Java Edition and connect to
mc.hypixel.net
Run the command
/api new
. This will give you your API Key.
Warning
/api new
will invalidate your existing API key, if you have one.
Warning
Your API key should remain private. If it is abused, it may get deleted and you may get banned from the Hypixel Network.
Creating a Script
Now, actually using the module.
First we must import the module.
import PyPixel
Now, to use the module’s features, we can initialize the Hypixel
class.
import PyPixel
hypixel = PyPixel.Hypixel(api_key="API Key")
Where "API Key"
is the API key that you got in the previous section.
This is the simplest example of using the module, if you would like more you can find examples here.
Examples
The following are examples of using PyPixel
Getting a Player
# Import the Module
import PyPixel
# Importing asyncio so we can call coroutines
import asyncio
# Initialize the Hypixel class
hypixel = PyPixel.Hypixel(api_key="API Key")
async def main():
# Get tha player's UUID
uuid = await hypixel.get_uuid('awsomo28')
# Get the player
player = await hypixel.get_player(uuid)
# Prints the player's rank
print(player.rank)
# run the above coroutine
loop = asyncio.get_event_loop()
loop.run_until_complete(main())
Getting a Player’s SkyBlock Profiles
# Import the Module
import PyPixel
# Importing asyncio so we can call coroutines
import asyncio
# Initialize the Hypixel class
hypixel = PyPixel.Hypixel(api_key="API Key")
async def main():
# Get the player's UUId
uuid = await hypixel.get_uuid('Jacktheguy')
# Get their profiles from the API.
profiles = await hypixel.get_profiles(uuid)
# Print their profile's names
print([str(profile) for profile in profiles]])
# run the above coroutine
loop = asyncio.get_event_loop()
loop.run_until_complete(main())
Using PyPixel.utils
# import the utils module
import PyPixel.utils
# print out the level you get for 777 xp
print(PyPixel.utils.HypixelUtils.playerLevel(777))
Adding Examples
If you wish to add another example, just make a pull request, I really don’t mind.
API Reference
The following section outlines the API for PyPixel.
- class AchievementData(data, cached)
New in version 0.1.9.
Represents Hypixel achievement data.
- Parameters
- raw
The raw data from the API.
- cached
Whether or not the data was retrieved from the cache.
- last_updated
The date and time the achievements were last updated.
- games
A list of AchievementGame.
- class AchievementGame(name, data)
New in version 0.1.9.
Represents a game with achievements.
- name
The game’s name.
- total_points
The total amount of achievement points you can earn in the game.
- class Achievement(data)
New in version 0.1.9.
Represents a Hypixel achievement.
- Parameters
data (dict) – The achievement’s data.
- name
The achievement’s name.
- description
The achievement’s description.
- class OneTime(data)
New in version 0.1.9.
Represents a one-time achievement.
This inherits from Achievement.
- Parameters
data (dict) – The achievement’s data.
- points
The amount of achievement points the achievement is worth.
- percent_unlocked_game
The percent of players who played the game the achievement belongs to that have it.
- percent_unlocked_global
The percent of players across the network that have the achievement.
- class Tiered(data)
New in version 0.1.9.
Represents a tiered achievement.
This inherits from Achievement.
- Parameters
data (dict) – The achievement’s data.
- tiers
A list of AchievementTier.
- class AchievementTier(data)
New in version 0.1.9.
Represents an achievement tier in a tiered achievement.
- Parameters
data (dict) – The tier’s data.
- tier
The Tier’s tier (if that makes sense).
- points
The amount of points the tier is worth.
- amount
The amount of
x
you have to get for this tier.
- class Auction(data, cached, hypixel)
New in version 0.2.0.
Represents an auction on the Skyblock Auction House.
- Parameters
- raw
The auction’s raw data from the API.
- cached
Whether or not the data is from the cache.
- id
The auction’s ID.
- auctioneer
The auctioneer’s UUID.
- auctioneer_profile
The auctioneer’s SkyBlock profile ID.
- auctioneer_coop_members
The members of the auctioneer’s coop.
- started
The date and time that the auction started.
- end
The date and time that the auction ends at.
- item
The name of the item being auctioned.
- lore
The lore of the item being auctioned.
- stripped_lore
The item’s lore, but stripped of formatting.
- extra
Some extra data on the item being auctioned.
- category
The category the item is in.
- tier
The item’s tier.
- starting_bid
The starting bid for the auction. If the auction is a BIN auction, this is the price of the item.
- nbt_data
The NBT data for the item.
- claimed
Whether or not the auction has been claimed.
- claimed_bidders
The bidders that have claimed their coins/items from the auction.
- highest_bid
The highest bid on the item. If nobody has bid, this will be 0. For BIN auctions, this will always be 0.
- bin
Whether or not the auction is a BIN auction.
- bids
A list of bids on the item. For BIN auctions, this will always be an empty list.
- get_auctioneer()
This function is a coroutine.
Gets the auctioneer’s player object.
- Raises
PlayerNotFound – The player couldn’t be found for some reason.
- Returns
The player from the API.
- Return type
- class AuctionPage(data, cached, hypixel)
New in version 0.2.0.
Represents a page of Skyblock auctions from the Hypixel API.
- Parameters
- raw
The raw data from the API.
- page
The page number.
- total_pages
The total number of pages.
- total_auctions
The total number of auctions.
- last_updated
The date and time that the page was last updated.
- class Cache(clear_cache_after)
Changed in version 0.2.0.
A class used for caching data returned from the api
- Parameters
clear_cache_after (int) – How long data should stay cached for.
- class Guild(data, cached, hypixel)
Represents a Hypixel guild.
- Parameters
- get_member(member)
This function is a coroutine.
Gets a Player object from a GuildMember
- Parameters
member (GuildMember) – The member you want a player object from.
- Returns
The retrieved player.
- Return type
- class GuildMember(memberdata)
Represents a Hypixel guild member.
- Parameters
memberdata (dict) – A dict containing the member’s data.
- uuid
The player’s UUID.
- rank
The player’s guild rank.
- joined
The date the player joined.
- quest_participation
The player’s quest participation.
- xp_history
The player’s guild XP history.
- class GuildRank(rankdata)
Represents a Hypixel guild rank.
- Parameters
rankdata (dict) – A dict containing the rank’s data.
- name
The rank’s name.
- default
A boolean indicating if the rank is the default rank.
- tag
The rank’s tag.
- created
The date/time the rank was created.
- priority
The rank’s priority in the guild’s rank heirarchy.
- class Hypixel(*, api_key, base_url, clear_cache_after, user_agent)
The main class that will be used for requesting information from the Hypixel API.
Changed in version 0.2.0: Removed the
validate
kwarg and added auser_agent
kwarg.Added the
get_auctions
method.Updated
_send
.- Parameters
api_key (str) – Your Hypixel API key.
base_url (Optional[str]) – The base URL for the Hypixel API. Defaults to
https://api.hypixel.net/
.clear_cache_after (Optional[int]) – How often the cache should clear in seconds.
user_agent (Optional[str]) – The user agent to use for requests. This is formatted with your Python version and aiohttp version.
- get_player(uuid)
This function is a coroutine.
Gets a player from the Hypixel API using the
/player
endpoint.- Parameters
uuid (str) – The UUID you are requesting player data for.
- Raises
PlayerNotFound – The player couldn’t be found.
- Returns
The player from the API.
- Return type
- get_guild(arg, by)
This function is a coroutine.
Gets a guild from the Hypixel API using the
/guild
endpoint.- Parameters
arg (str) – The guild ID or name, or a player UUID.
by (Literal['id', 'name', 'player']) – The type of ‘arg’ you provided.
- Raises
TypeError – Invalid ‘by’ parameter.
GuildNotFound – The guild was not found.
- Returns
The guild from the API.
- Return type
- get_profiles(uuid)
This function is a coroutine.
Gets a player’s SkyBlock profiles from the Hypixel API using the
/skyblock/profiles
endpoint.- Parameters
uuid (str) – The player’s UUID.
- Raises
PlayerNotFound – The player’s profiles could not be found.
- Returns
A list containing the player’s profiles.
- Return type
List[SkyBlockProfile]
- get_auctions(page)
This function is a coroutine.
New in version 0.2.0.
Gets a page of auctions from the Hypixel API.
Note
This does not use your API Key.
- Parameters
page (int) – The page to request.
- Returns
The page of auctions.
- Return type
- get_key(key=None)
New in version 0.1.8.
This function is a coroutine.
Gets information on an API Key using the
/key
endpoint.- Parameters
key (Optional[str]) – The API key you want information for. Defaults to the API key you provided on initialization of the class.
- Raises
KeyNotFound – The key provided does not exist.
- Returns
The data on the API Key
- Return type
- get_achievements()
New in version 0.1.9.
This function is a coroutine.
Gets every achievement on the Hypixel Network using the
/resources/achievements
endpoint.Note
This does not use your API Key.
- Raises
PyPixelError – The request failed for some reason.
- Returns
An object containing every achievement.
- Return type
- get_name(uuid)
This function is a coroutine.
Gets a player’s name from their UUID. This does not use the Hypixel API.
- Parameters
uuid (str) – The player’s UUID.
- Raises
PlayerNotFound – The UUID is invalid.
- Returns
The player’s name.
- Return type
- get_uuid(name)
This function is a coroutine.
Get’s a player’s UUID from their name.
- Parameters
name (str) – The player’s name.
- Raises
PlayerNotFound – The name is invalid.
- Returns
The player’s UUID.
- Return type
- _send(url, *, headers, authenticate)
This function is a coroutine.
Changed in version 0.2.0: Added a
header
kwarg, as well as theauthenticate
kwarg.This will also add the
User-Agent
header to requests.Sends a request to the specified url.
- Parameters
url (str) – The URL the request will be sent to.
headers (Optional[dict]) – The request headers. Defaults to an empty dict.
authenticate (Optional[bool]) – Whether or not to provide an
Api-Key
header with your API Key. If not provided, will provide theApi-Key
header based on the url the request is being sent to.
- Raises
APIError – The API returned a
500
range status code.NotFound – The API returned a
404
status code.ClientError – The API returned a
400
range status code.
- Returns
The json data from the API, and a boolean value indicating whether or not the data was retrieved from the cache.
- Return type
- APIKey(key_data, cached, hypixel):
New in version 0.1.8.
Represents an API Key.
- Parameters
key_data (dict) – The raw key data from the API.
cached (bool) – The raw key data from the API.
hypixel (Hypixel) – The raw key data from the API.
- cached
Indicates whether or not the data was retrieved from the cache.
- key
The API Key
- owner
The key’s owner.
- request_past_minute
The amount of requests made with the key in the past minute.
- total_requests
The total amount of requests made with the key.
- class Player(data, cached, hypixel)
Represents a Hypixel player.
- class PlayerStats(data)
Base class for a player’s statistics.
- Parameters
data (dict) – The raw player data from the API.
- skywars
The player’s SkyWars statistics.
- class Firework(firework)
Represents a firework. Interesting, right?
- Parameters
firework (dict) – The raw firework data.
- class SkyWarsStats(playerstats)
Base class for a player’s SkyWars stats.
- Parameters
playerstats (dict) – The raw player stats data from the API.
- class Overall(stats)
The player’s overall SkyWars stats.
- Parameters
stats (dict) – The raw SkyWars stats data from the API.
- class Solo(stats)
The player’s solo SkyWars stats.
- Parameters
stats (dict) – The raw SkyWars stats data from the API.
- class Teams(stats)
The player’s teams SkyWars stats.
- Parameters
stats (dict) – The raw SkyWars stats data from the API.
- class Mega(stats)
The player’s mega SkyWars stats.
- Parameters
stats (dict) – The raw SkyWars stats data from the API.
- class Ranked(stats)
The player’s ranked SkyWars stats.
- Parameters
stats (dict) – The raw SkyWars stats data from the API.
- class SkyBlockProfile(profiledata, cached, hypixel)
Represents a SkyBlock profile.
- class Profilemember(uuid, memberdata, hypixel)
Represents a member in a SkyBlock profile.
- Parameters
- get_player()
This function is a coroutine.
Gets the member’s player object.
- Raises
PlayerNotFound – The player couldn’t be found for some reason.
- Returns
The player from the API.
- Return type
- class SkyBlockStats(stats)
Represents a player’s SkyBlock Statistics.
- Parameters
stats (dict) – The player’s stats from their memberdata retrieved from the API.
- class SkyBlockObjective(objective_name, objective_data)
Represents a SkyBlock Objective.
- Parameters
- name
The name of the objective.
- status
The objective’s status.
- progress
The objective’s progress.
- completed_at
The objective’s completion date/time. Can also be
None
if not completed.
- class SkyBlockQuest(quest_name, quest_data)
Represents a SkyBlock quest.
- name
The name of the quest.
- status
The quest’s status.
- activated_at
The quest’s activation date/time.
- completed_at
The quest’s completion date/time. Can also be
None
if not completed.
- class SkyBlockSlayer(slayer, slayer_data)
Represents a SkyBlock slayer.
- slayer
The name of the slayer.
- claimed_levels
The player’s claimed levels for a slayer.
- xp
The player’s slayer xp.
- level
The player’s slayer level.
- class SkyBlockPet(pet_data)
Represents a SkyBlock pet.
- Parameters
pet_data (dict) – The pet’s data.
- uuid
The pet’s UUID, I guess.
- type
The pet’s type.
- xp
The pet’s XP.
- active
A boolean indicating whether or not the pet is active.
- tier
The pet’s tier
- held_item
The item the pet is holding.
- candy_used
The candy used on the pet.
- skin
The pet’s skin.
Exceptions
Changed in version 0.1.8: These exceptions are now actually used.
Oh also the parameters changed.
- exception PyPixelError(*args)
Base exception class for PyPixel.
- exception HTTPException
Base exception class for when the API returns an http error code.
- exception APIError
Exception that’s thrown when the API returns a 500 range status code.
- exception ClientError
Exception that’s thrown when the API returns a 400 range status code.
- exception NotFound
Exception thats thrown when the API returns a 404 status code.
- exception PlayerNotFound(reason)
Exception thats thrown when a player couldn’t be found.
- exception GuildNotFound(reason)
Exception thats thrown when a guild couldn’t be found.
- exception KeyNotFound(reason, url, data)
New in version 0.1.8.
Exception thats thrown when an API Key couldn’t be found.
Utils API Reference
The following section outlines the API for PyPixel.utils.
- class HypixelUtils
General utilities relating to Hypixel.
- static parseNBT(raw_data)
Parses NBT data from the API.
- static getRank(data)
Gets a player’s rank from their raw API data.
- Parameters
data (dict) – The player’s raw API data.
- Returns
The player’s rank.
- Return type
Literal[‘Default’, ‘VIP’, ‘VIP+’, ‘MVP’, ‘MVP+’, ‘MVP++’, ‘YouTube’, ‘Helper’, ‘Moderator’, ‘Admin’]
- static guildlevel(xp)
Gets a guild’s level from the guild’s xp.
- static playerLevel(xp)
Gets a player’s network level from their network experience, using the equation
(((2 * xp) + 30625) ^ (1 / 2) / 50) - 2.5
.
- static skywarsLevel(xp)
Gets a player’s SkyWars level from their SkyWars experience.
- static getGameName(game)
New in version 0.1.9.
Gets the name of a Hypixel gamemode from its ID or it’s name in the API.
- class SkyBlockUtils
Utilities relating to Hypixel SkyBlock.
- static getItem(item, *, reverse)
Gets an item name from an item ID.
- static getMinionSlots(crafted)
Gets the number of crafted minion slots a player has.
- static zombieSlayer(xp)
Gets the level for the Zombie slayer from the slayer experience.
- static spiderSlayer(xp)
Gets the level for the Spider slayer from the slayer experience.
- static wolfSlayer(xp)
Gets the level for the Wolf slayer from the slayer experience.
- static slayerLevels(data)
Retrieves a SkyBlock player’s Slayer levels from their profile data.
- static getSkillLevel(xp)
Converts skill XP to a skill level.
- static getRunecraftLevel(xp)
Converts runecrafting skill XP to a skill level.
This is seperate from getSkillLevel because runecrafting has different experience requirements.
- static farmingCollection(data)
Gets a player’s SkyBlock Farming collection from their member data.
- static miningCollection(data)
Gets a player’s SkyBlock Mining collection from their member data.
- static combatCollection(data)
Gets a player’s SkyBlock Combat collection from their member data.
- static foragingCollection(data)
Gets a player’s SkyBlock Foraging collection from their member data.
- static fishingCollection(data)
Gets a player’s SkyBlock Fishing collection from their member data.
- static getCollectionData(data, req_xp, collection, c)
Modifies a collection’s collection data.
- class Items
A class containing all the Hypixel SkyBlock Item IDs.
FAQ
Where is the FAQ?
Nowhere, nobody has asked any questions.
Changelog
0.2.0
Removed API Key validation.
Added support for the
/skyblock/auctions
endpoint.Added
stripFormatting
toHypixelUtils
to strip Minecraft text formatting from strings.The wrapper now sends an
Api-Key
header to authenticate with the API instead of thekey
path param.The wrapper will also send a
User-Agent
header to the APIs that it uses.The cache no longer uses Threading.
0.1.9
Added support for the
/resources/achievements
endpoint.Added a kwarg to bypass API key validation.
Added this changelog to the documentation.
Added a new method,
getGameName(game)
Added a new file in utils that contains game names/IDs
0.1.8
The module will now return
None
instead of having the value simply be missing.
0.1.7
Added documentation: https://pypixel.rtfd.io/
0.1.6
Add some methods
0.1.5
Released to PyPI
0.1.4
Added a changelog
Introduced SkyBlock Profiles
Added 3 new fuctions to
.Hypixel
(.get_name(uuid)
,.get_uuid(name)
, and .get_profiles(uuid))Deleted
Other.py
in favor of a submodule,utils
Moved the
send_request()
method to.Hypixel
and renamed it_send()
Added a new requirement,
NBT
(Used for parsing NBT data).Added some exception classes.
Started subclassing
object
for no paticular reason.
Getting Started
Is this your first time using PyPixel? This is the place to get started!