Installation

To use minecraftstatus, install it using pip

1(.venv) $ pip install minecraftstatus

or install it from the github repo using git with the following command

1(.venv) $ pip install -U git+https://github.com/Infernum1/minecraftstatus

Examples

An example of the get_server feature

 1 import asyncio
 2 import minecraftstatus
 3
 4 client = minecraftstatus.MCStatus()
 5
 6
 7 async def main(ip_address: str):
 8     server = await client.get_server(ip_address)
 9     print(server.motd)
10     print(server.max_players)
11     print(server.max_players)
12     print(server.version_info)  # and many more attributes!
13
14
15 if __name__ == "__main__":
16     asyncio.run(main("mc.hypixel.net"))

or the get_server_card feature

 1 import asyncio
 2 import minecraftstatus
 3
 4 client = minecraftstatus.MCStatus()
 5
 6
 7 async def main(ip_address: str):
 8     image = await client.get_server_card(ip_address, custom_server_name="An Awesome Minecraft Server")
 9     print(await image.getvalue())
10
11
12 if __name__ == "__main__":
13     asyncio.run(main("mc.hypixel.net"))

Take a look at all the examples on the github

Documentation

async minecraftstatus.client.MCStatus.achievement(self, achievement: str)

This is a method of the MCStatus class :param achievement: name of the achievement to display. :type achievement: str :raises BadTextFormation: text passed is not between 1-30 characters :return: an io.BytesIO object co-relating the achievement image.

How an achievement ‘card’ would look like:

_images/example_achievement.png
async minecraftstatus.client.MCStatus.splash_text(self, text: str)

This is a method of the MCStatus class :param text: text to display in the splash. :type text: str :raises BadTextFormation: text passed is not between 1-30 characters :return: an io.BytesIO object co-relating the splash text image.

How a splash text ‘card’ would look like:

_images/example_splash_text.png
async minecraftstatus.client.MCStatus.get_server_card(self, ip_address: str, custom_server_name: str = '')

This is a method of the MCStatus class

Parameters

  • ip_address (str) – IP address of the server

  • custom_server_name (str) – A custom server name to be displayed on the server card

Raises

BadTextFormation – text passed is not between 1-30 characters

Returns

an io.BytesIO object co-relating the server card image.

How a server ‘card’ would look like:

_images/example_server_card.png
exception minecraftstatus.BadTextFormation

Bases: Exception

Exception raised when the characters passed are not between 1 and 30 for some endpoints.

Note: the error is minecraftstatus.errors.BadTextFormation. Due to an issue, it’s incorrectly shown in the documentation above.

class minecraftstatus.MCStatus

Bases: minecraftstatus.http.HTTPClient

The main MCStatus class.

async get_server(ip_address: str)
Parameters

ip_address (str) – IP address of the server

Raises

ServerNotFound – server not found or is offline

Returns

a ServerStatus class instance

exception minecraftstatus.ServerNotFound(address: str)

Bases: Exception

Exception raised when a server is not found or is offline. Has the following attribute:

Note: the error is minecraftstatus.errors.ServerNotFound. Due to an issue, it’s incorrectly shown in the documentation above.

address
Type

(str)the address of the server passed.

class minecraftstatus.ServerStatus(resp)

Bases: object

property clean_motd: str

The clean message of the day (MOTD) of the server. (without the color codes)

Returns: str or None

property favicon: _io.BytesIO

The server favicon Returns: io.BytesIO object or None

property game_map: str

The game map of the server. Returns: str or None

property gamemode: str

The game mode of the server. Returns: str or None

property host: str

The host name of the server. (same as the IP address)

Returns: str

property is_online: bool

Checks if the server is online.

Returns: bool: True if the server is online, False otherwise.

property latency: int

The latency of the server.

Returns: int: latency in milliseconds, -1 if the server is offline.

property max_players: int

The maximum players a server can accommodate.

Returns: int or None

property motd: str

The message of the day (MOTD) of the server. (along with the colour codes)

Returns: str or None

property online_player_count: int

The online player count of the server.

Returns: int or None

property online_players: list

A list of dicts of the online players of the server and their UUID/XUID.

Returns: list[dict[str, str]]

property port: int

The port the server is running on. (usually 25565)

Returns: int or None

property version_info: dict

The descriptive version info of the server.

Returns: dict[Any, Any]