CLI: Bedrock support and misc improvements

mcstatus/__main__.py

@@ -1,75 +1,107 @@
 from __future__ import annotations
 
+import sys
 import argparse
 import socket
+from typing import TYPE_CHECKING
 from json import dumps as json_dumps
 
-from mcstatus import JavaServer
+from mcstatus import JavaServer, BedrockServer
+from mcstatus.responses import JavaStatusResponse
 
+if TYPE_CHECKING:
+    SupportedServers = JavaServer | BedrockServer
 
-def ping(server: JavaServer) -> None:
-    print(f"{server.ping()}ms")
 
+def ping(server: SupportedServers) -> int:
+    # this method supports both Java and Bedrock.
+    # only Java supports the `ping` packet, and even then not always:
+    # https://github.com/py-mine/mcstatus/issues/850
+    print(f"{server.status().latency}")
+    return 0
 
-def status(server: JavaServer) -> None:
+
+def status(server: SupportedServers) -> int:
     response = server.status()
-    if response.players.sample is not None:
-        player_sample = str([f"{player.name} ({player.id})" for player in response.players.sample])
+
+    java_res = response if isinstance(response, JavaStatusResponse) else None
+
+    if not java_res:
+        player_sample = ""
+    elif java_res.players.sample is not None:
+        player_sample = str([f"{player.name} ({player.id})" for player in java_res.players.sample])
     else:
         player_sample = "No players online"
 
-    print(f"version: v{response.version.name} (protocol {response.version.protocol})")
-    print(f'motd: "{response.motd}"')
-    print(f"players: {response.players.online}/{response.players.max} {player_sample}")
+    if player_sample:
+        player_sample = " " + player_sample
 
+    print(f"version: {server.kind()} {response.version.name} (protocol {response.version.protocol})")
+    print(f"motd: {response.motd.to_ansi()}")
+    print(f"players: {response.players.online}/{response.players.max}{player_sample}")
+    print(f"ping: {response.latency:.2f} ms")
+    return 0
 
-def json(server: JavaServer) -> None:
+
+def json(server: SupportedServers) -> int:
     data = {}
     data["online"] = False
+    data["kind"] = server.kind()
     # Build data with responses and quit on exception
     try:
         status_res = server.status(tries=1)
+        java_res = status_res if isinstance(status_res, JavaStatusResponse) else None
         data["version"] = status_res.version.name
         data["protocol"] = status_res.version.protocol
         data["motd"] = status_res.motd.raw
         data["player_count"] = status_res.players.online
         data["player_max"] = status_res.players.max
         data["players"] = []
-        if status_res.players.sample is not None:
-            data["players"] = [{"name": player.name, "id": player.id} for player in status_res.players.sample]
+        if java_res and java_res.players.sample is not None:
+            data["players"] = [{"name": player.name, "id": player.id} for player in java_res.players.sample]
 
         data["ping"] = status_res.latency
         data["online"] = True
 
-        query_res = server.query(tries=1)  # type: ignore[call-arg] # tries is supported with retry decorator
-        data["host_ip"] = query_res.raw["hostip"]
-        data["host_port"] = query_res.raw["hostport"]
-        data["map"] = query_res.map
-        data["plugins"] = query_res.software.plugins
+        if isinstance(server, JavaServer):
+            query_res = server.query(tries=1)
+            data["host_ip"] = query_res.hostip
+            data["host_port"] = query_res.hostport
+            data["map"] = query_res.map
+            data["plugins"] = query_res.software.plugins
     except Exception:  # TODO: Check what this actually excepts
         pass
+
     print(json_dumps(data))
+    return 0
 
 
-def query(server: JavaServer) -> None:
+def query(server: SupportedServers) -> int:
+    if not isinstance(server, JavaServer):
+        print("The 'query' protocol is only supported by Java servers.", file=sys.stderr)
+        return 1
+
     try:
         response = server.query()
     except socket.timeout:
         print(
             "The server did not respond to the query protocol."
             "\nPlease ensure that the server has enable-query turned on,"
             " and that the necessary port (same as server-port unless query-port is set) is open in any firewall(s)."
-            "\nSee https://wiki.vg/Query for further information."
+            "\nSee https://wiki.vg/Query for further information.",
+            file=sys.stderr,
         )
-        return
-    print(f"host: {response.raw['hostip']}:{response.raw['hostport']}")
+        return 1
+
+    print(f"host: {response.hostip}:{response.hostport}")
     print(f"software: v{response.software.version} {response.software.brand}")
     print(f"plugins: {response.software.plugins}")
-    print(f'motd: "{response.motd}"')
+    print(f"motd: {response.motd.to_ansi()}")
     print(f"players: {response.players.online}/{response.players.max} {response.players.names}")
+    return 0
 
 
-def main() -> None:
+def main(argv: list[str]) -> int:
     parser = argparse.ArgumentParser(
         "mcstatus",
         description="""
@@ -80,8 +112,11 @@ def main() -> None:
     )
 
     parser.add_argument("address", help="The address of the server.")
+    parser.add_argument("--bedrock", help="Specifies that 'address' is a Bedrock server (default: Java).", action="store_true")
+
+    subparsers = parser.add_subparsers(title="commands", description="Command to run, defaults to 'status'.")
+    parser.set_defaults(func=status)
 
-    subparsers = parser.add_subparsers()
     subparsers.add_parser("ping", help="Ping server for latency.").set_defaults(func=ping)
     subparsers.add_parser(
         "status", help="Prints server status. Supported by all Minecraft servers that are version 1.7 or higher."
@@ -94,11 +129,17 @@ def main() -> None:
         help="Prints server status and query in json. Supported by all Minecraft servers that are version 1.7 or higher.",
     ).set_defaults(func=json)
 
-    args = parser.parse_args()
-    server = JavaServer.lookup(args.address)
+    args = parser.parse_args(argv)
+    lookup = JavaServer.lookup if not args.bedrock else BedrockServer.lookup
+    server = lookup(args.address)
 
-    args.func(server)
+    try:
+        return args.func(server)
+    except (socket.timeout, socket.gaierror, ValueError) as e:
+        # catch and hide traceback for expected user-facing errors
+        print(f"Error: {e}", file=sys.stderr)
+        return 1
 
 
 if __name__ == "__main__":
-    main()
+    sys.exit(main(sys.argv[1:]))

mcstatus/querier.py

@@ -132,6 +132,8 @@ def __init__(self, version: str, plugins: str):
     map: str
     players: Players
     software: Software
+    hostip: str
+    hostport: int
 
     def __init__(self, raw: dict[str, str], players: list[str]):
         try:
@@ -140,8 +142,10 @@ def __init__(self, raw: dict[str, str], players: list[str]):
             self.map = raw["map"]
             self.players = QueryResponse.Players(raw["numplayers"], raw["maxplayers"], players)
             self.software = QueryResponse.Software(raw["version"], raw["plugins"])
-        except KeyError:
-            raise ValueError("The provided data is not valid")
+            self.hostip = raw["hostip"]
+            self.hostport = int(raw["hostport"])
+        except KeyError as e:
+            raise ValueError("The provided data is not valid") from e
 
     @classmethod
     def from_connection(cls, response: Connection) -> Self:

mcstatus/server.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from abc import ABC
+from abc import ABC, abstractmethod
 from typing import TYPE_CHECKING
 
 from mcstatus.address import Address, async_minecraft_srv_address_lookup, minecraft_srv_address_lookup
@@ -53,12 +53,20 @@ def lookup(cls, address: str, timeout: float = 3) -> Self:
         addr = Address.parse_address(address, default_port=cls.DEFAULT_PORT)
         return cls(addr.host, addr.port, timeout=timeout)
 
+    @classmethod
+    @abstractmethod
+    def kind(cls) -> str: ...
+
 
 class JavaServer(MCServer):
     """Base class for a Minecraft Java Edition server."""
 
     DEFAULT_PORT = 25565
 
+    @classmethod
+    def kind(cls) -> str:
+        return "Java"
+
     @classmethod
     def lookup(cls, address: str, timeout: float = 3) -> Self:
         """Mimics minecraft's server address field.
@@ -188,6 +196,10 @@ class BedrockServer(MCServer):
 
     DEFAULT_PORT = 19132
 
+    @classmethod
+    def kind(cls) -> str:
+        return "Bedrock"
+
     @retry(tries=3)
     def status(self, **kwargs) -> BedrockStatusResponse:
         """Checks the status of a Minecraft Bedrock Edition server.