rename commands submodule to subcommands.

add Maprestart.with_configure()

README.md

@@ -10,6 +10,9 @@
 ## Table of Contents
 
 - [Installation](#installation)
+- [Configuration](#configuration)
+- [Use](#use)
+- [Shell Completion](#shell-completion)
 - [License](#license)
 
 ## Installation
@@ -60,7 +63,7 @@ export Q3RCON_CLI_PASSWORD="<rcon password>"
 Usage: q3rcon-cli [OPTIONS] COMMAND
 
 ┏━ Subcommands ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
-┃ fastrestart  Executes a fast restart of the server                                               ┃
+┃ fastrestart  Executes a fast restart of the map                                                  ┃
 ┃ gametype     Get or set the current gametype of the server                                       ┃
 ┃ hostname     Get or set the current hostname of the server                                       ┃
 ┃ map          Get the current map or change to a new one                                          ┃
@@ -83,6 +86,14 @@ Usage: q3rcon-cli [OPTIONS] COMMAND
 ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
 ```
 
+## Shell Completion
+
+Shell completion scripts are available for *bash*, *zsh*, and *fish*.
+
+```console
+q3rcon-cli --install-autocomplete
+```
+
 ## Special Thanks
 
 - [lapetus-11](https://github.com/Iapetus-11) for writing the [aio-q3-rcon](https://github.com/Iapetus-11/aio-q3-rcon) package.

src/q3rcon_cli/__about__.py

@@ -1,4 +1,4 @@
 # SPDX-FileCopyrightText: 2026-present onyx-and-iris <code@onyxandiris.online>
 #
 # SPDX-License-Identifier: MIT
-__version__ = '0.3.1'
+__version__ = '0.4.0'

src/q3rcon_cli/cli.py

@@ -1,33 +1,12 @@
 import clypi
 from aioq3rcon import Client, IncorrectPasswordError
 from clypi import Command, Spinner, arg
+from clypi import parsers as cp
 from typing_extensions import override
 
-from . import console
+from . import config, console
 from .__about__ import __version__
-from .commands import (
-    Fastrestart,
-    Gametype,
-    Hostname,
-    Map,
-    Mapname,
-    Maprestart,
-    Maprotate,
-    Plugins,
-    Status,
-)
-
-Subcommands = (
-    Fastrestart
-    | Gametype
-    | Hostname
-    | Map
-    | Mapname
-    | Maprestart
-    | Maprotate
-    | Plugins
-    | Status
-)
+from .subcommands import Status, Subcommands
 
 
 class Q3rconCli(Command):
@@ -38,6 +17,7 @@ class Q3rconCli(Command):
         help='The host to connect to',
         env='Q3RCON_CLI_HOST',
         group='Connection',
+        parser=cp.Str(min=1),
     )
     port: int = arg(
         28960,
@@ -45,6 +25,7 @@ class Q3rconCli(Command):
         help='The port to connect to',
         env='Q3RCON_CLI_PORT',
         group='Connection',
+        parser=cp.Int(min=1, max=65535),
     )
     password: str = arg(
         '',
@@ -52,6 +33,7 @@ class Q3rconCli(Command):
         help='The password for authentication',
         env='Q3RCON_CLI_PASSWORD',
         group='Connection',
+        parser=cp.Str(min=8),
     )
     interactive: bool = arg(
         False,
@@ -64,6 +46,23 @@ class Q3rconCli(Command):
         help='Show the version and exit',
     )
 
+    @override
+    async def pre_run_hook(self):
+        if self.subcommand is not None and self.interactive:
+            console.err.print(
+                'Cannot use subcommands in interactive mode.',
+                style='yellow',
+            )
+            self.print_help()
+            raise SystemExit(1)
+
+        if self.subcommand:
+            (
+                self.subcommand.timeout,
+                self.subcommand.fragment_read_timeout,
+                self.subcommand.interpret,
+            ) = config.get(self.subcommand.prog().split()[0].lower())
+
     @override
     async def run(self):
         if self.version:
@@ -72,8 +71,13 @@ class Q3rconCli(Command):
 
         if self.interactive:
             await self.run_interactive()
-        else:
+            return
+
+        if self.subcommand is None:
             await Status(self.host, self.port, self.password).run()
+            return
+
+        self.print_help()
 
     async def run_interactive(self):
         print(
@@ -81,23 +85,12 @@ class Q3rconCli(Command):
             clypi.style("'Q'", fg='yellow'),
             clypi.style('to quit.', fg='blue'),
         )
-
-        DEFAULT_TIMEOUT = 2
-        DEFAULT_FRAGMENT_READ_TIMEOUT = 0.25
         while command := input(clypi.style('cmd: ', fg='green')):
             if command.lower() == 'q':
                 break
 
-            CMD_CONFIG = {
-                'status': (2, 1, False),
-                'fast_restart': (3, 1, True),
-                'map_restart': (3, 1, True),
-                'map': (3, 1, True),
-                'map_rotate': (3, 1, True),
-            }
-            timeout, fragment_read_timeout, interpret = CMD_CONFIG.get(
-                command.split()[0].lower(),
-                (DEFAULT_TIMEOUT, DEFAULT_FRAGMENT_READ_TIMEOUT, False),
+            timeout, fragment_read_timeout, interpret = config.get(
+                command.split()[0].lower()
             )
 
             async with Spinner(f"Sending command: '{command}'", suffix='...'):
@@ -117,8 +110,7 @@ class Q3rconCli(Command):
                             f"Timeout waiting for response for command: '{command}'"
                         )
 
-            if response:
-                console.out.print_response(response)
+            console.out.print_response(response)
 
 
 def main():

src/q3rcon_cli/commands/maprestart.py

@@ -1,23 +0,0 @@
-from aioq3rcon import Client
-from clypi import Command, Spinner, arg
-from typing_extensions import override
-
-from q3rcon_cli import console
-
-
-class Maprestart(Command):
-    """Restarts the current map."""
-
-    host: str = arg(inherited=True)
-    port: int = arg(inherited=True)
-    password: str = arg(inherited=True)
-
-    @override
-    async def run(self):
-        async with Spinner('Restarting map', suffix='...'):
-            async with Client(
-                self.host, self.port, self.password, timeout=3, fragment_read_timeout=1
-            ) as client:
-                response = await client.send_command('map_restart', interpret=True)
-
-        console.out.print_response(response)

src/q3rcon_cli/config.py

@@ -0,0 +1,35 @@
+from collections import UserDict
+
+
+class Config(UserDict):
+    DEFAULT_TIMEOUT: int = 2
+    DEFAULT_FRAGMENT_READ_TIMEOUT: float = 0.25
+
+    def __init__(self):
+        self.data = {
+            'status': (2, 0.25, False),
+            'fast_restart': (3, 1, True),
+            'map_restart': (3, 1, True),
+            'map': (3, 1, True),
+            'map_rotate': (3, 1, True),
+        }
+
+    def __getitem__(self, key):
+        return self.data.get(
+            key, (self.DEFAULT_TIMEOUT, self.DEFAULT_FRAGMENT_READ_TIMEOUT, False)
+        )
+
+
+_config = Config()
+
+
+def get(key: str):
+    match key:
+        case 'fast_restart' | 'fastrestart':
+            return _config['fast_restart']
+        case 'map_restart' | 'maprestart':
+            return _config['map_restart']
+        case 'map_rotate' | 'maprotate':
+            return _config['map_rotate']
+        case _:
+            return _config[key]

src/q3rcon_cli/console.py

@@ -50,9 +50,8 @@ class OutConsole(Console):
         return OutConsole.COLOUR_CODE_REGEX.sub('', s)
 
     def print_response(self, response: str):
-        response = self._remove_colour_codes(response).removeprefix('print\n')
-
-        cprint(response, fg=self.style)
+        if response := self._remove_colour_codes(response).removeprefix('print\n'):
+            cprint(response, fg=self.style)
 
     def print_status(self, response: str):
         _slots = []

src/q3rcon_cli/subcommands/__init__.py

@@ -8,14 +8,14 @@ from .maprotate import Maprotate
 from .plugins import Plugins
 from .status import Status
 
-__all__ = [
-    'Status',
-    'Mapname',
-    'Maprotate',
-    'Fastrestart',
-    'Gametype',
-    'Hostname',
-    'Map',
-    'Plugins',
-    'Maprestart',
-]
+Subcommands = (
+    Fastrestart
+    | Gametype
+    | Hostname
+    | Map
+    | Mapname
+    | Maprestart
+    | Maprotate
+    | Plugins
+    | Status
+)

src/q3rcon_cli/subcommands/fastrestart.py

@@ -6,7 +6,7 @@ from q3rcon_cli import console
 
 
 class Fastrestart(Command):
-    """Executes a fast restart of the server."""
+    """Executes a fast restart of the map."""
 
     host: str = arg(inherited=True)
     port: int = arg(inherited=True)
@@ -15,7 +15,15 @@ class Fastrestart(Command):
     @override
     async def run(self):
         async with Spinner('Executing fast restart', suffix='...'):
-            async with Client(self.host, self.port, self.password) as client:
-                response = await client.send_command('fast_restart', interpret=True)
+            async with Client(
+                self.host,
+                self.port,
+                self.password,
+                timeout=self.timeout,
+                fragment_read_timeout=self.fragment_read_timeout,
+            ) as client:
+                response = await client.send_command(
+                    'fast_restart', interpret=self.interpret
+                )
 
         console.out.print_response(response)

src/q3rcon_cli/subcommands/gametype.py

@@ -4,6 +4,8 @@ from typing_extensions import override
 
 from q3rcon_cli import console
 
+from .maprestart import Maprestart
+
 
 class Gametype(Command):
     """Get or set the current gametype of the server."""
@@ -35,11 +37,7 @@ class Gametype(Command):
                 await client.send_command(f'g_gametype {self.new_gametype}')
 
         if self.force:
-            async with Spinner('Forcing gametype change', suffix='...'):
-                async with Client(self.host, self.port, self.password) as client:
-                    client.timeout = 3
-                    client.fragment_read_timeout = 1
-                    await client.send_command('map_restart')
+            await Maprestart.with_configure(self.host, self.port, self.password).run()
 
         console.out.print(
             f'Gametype changed successfully to {self.new_gametype}.', style='green'

src/q3rcon_cli/subcommands/map.py

@@ -27,9 +27,16 @@ class Map(Command):
 
         async with Spinner('Changing map', suffix='...'):
             async with Client(
-                self.host, self.port, self.password, fragment_read_timeout=1
+                self.host,
+                self.port,
+                self.password,
+                timeout=self.timeout,
+                fragment_read_timeout=self.fragment_read_timeout,
             ) as client:
-                await client.send_command(f'map mp_{self.new_map.removeprefix("mp_")}')
+                await client.send_command(
+                    f'map mp_{self.new_map.removeprefix("mp_")}',
+                    interpret=self.interpret,
+                )
 
         console.out.print(
             f'Map changed to {self.new_map.removeprefix("mp_")}', style='green'

src/q3rcon_cli/subcommands/maprestart.py

@@ -0,0 +1,45 @@
+from aioq3rcon import Client
+from clypi import Command, Spinner, arg
+from typing_extensions import override
+
+from q3rcon_cli import config, console
+
+
+class Maprestart(Command):
+    """Restarts the current map."""
+
+    host: str = arg(inherited=True)
+    port: int = arg(inherited=True)
+    password: str = arg(inherited=True)
+
+    @classmethod
+    def with_configure(cls, host, port, password):
+        """Configures the command with the appropriate configuration and runs it.
+
+
+        This classmethod is used if we invoke the maprestart command from another command (e.g. gametype),
+        since the pre_run_hook is not called in that case.
+        """
+        instance = cls(host, port, password)
+        (
+            instance.timeout,
+            instance.fragment_read_timeout,
+            instance.interpret,
+        ) = config.get(instance.prog().split()[0].lower())
+        return instance
+
+    @override
+    async def run(self):
+        async with Spinner('Restarting map', suffix='...'):
+            async with Client(
+                self.host,
+                self.port,
+                self.password,
+                timeout=self.timeout,
+                fragment_read_timeout=self.fragment_read_timeout,
+            ) as client:
+                response = await client.send_command(
+                    'map_restart', interpret=self.interpret
+                )
+
+        console.out.print_response(response)

src/q3rcon_cli/subcommands/maprotate.py

@@ -19,9 +19,11 @@ class Maprotate(Command):
                 self.host,
                 self.port,
                 self.password,
-                timeout=3,
-                fragment_read_timeout=1,
+                timeout=self.timeout,
+                fragment_read_timeout=self.fragment_read_timeout,
             ) as client:
-                response = await client.send_command('map_rotate', interpret=True)
+                response = await client.send_command(
+                    'map_rotate', interpret=self.interpret
+                )
 
         console.out.print_response(response)

src/q3rcon_cli/subcommands/status.py

@@ -15,9 +15,7 @@ class Status(Command):
     @override
     async def run(self):
         async with Spinner('Fetching status', suffix='...'):
-            async with Client(
-                self.host, self.port, self.password, fragment_read_timeout=1
-            ) as client:
+            async with Client(self.host, self.port, self.password) as client:
                 response = await client.send_command('status')
 
         console.out.print_status(response)