from pax25.applications.parsers import no_arguments

Command Router¶

The command router is built to allow for easy routing of commands. In most applications, the user has the option to enter one of several commands. The command router allows for specification of these commands, basic parsing, and execution of the commands.

When paired with the help system, it allows for easy programming of applications.

Initializing a Command Router¶

To build a command router, import the CommandRouter class and invoke it. You will probably want to do this in the setup class, saving it on self:

from pax25 import Application
from pax25.applications.router import CommandRouter


class MyApplication(Application):
    ...
    def setup(self):
        ...
        self.router = CommandRouter()

Adding commands¶

Once you have a command router, you can add commands to it. Adding commands to a router requires building a CommandSpec and using the .add method:

from pax25 import Application
from pax25.applications.router import CommandRouter, CommandSpec
from pax25.applications.utils import send_message


class MyApplication(Application):
    ...
    def setup(self):
        ...
        self.router = CommandRouter()
        # Create the command
        command = CommandSpec(
            command='Hello',
            function=self.say_hello,
            # See the article on the help system for more information on this feature.
            help="Greets the user.",
            aliases=('Hi', 'hola'),
        )
        # Add it to the router.
        self.router.add(command)

    def say_hello(self, connection, context):
        # This will say "Hi! You used the hello command!"
        send_message(connection, f"Hi! You used the {context.spec.command} command!")

Routing commands¶

Once commands are added to the router, you can send messages from the user to the command router, and it will execute the command. Commands can have their own parsers to interpret their arguments as needed.

from pax25 import Application
from pax25.applications.router import CommandRouter, CommandSpec
from pax25.applications.utils import send_message
from pax25.applications.parsers import no_arguments, ParseError

def positive_number_parser(args):
    """
    A simple parser that converts the arguments into a number.
    """
    try:
        number = int(args)
    except ValueError:
        raise ParseError("That's not a number!")
    if number <= 0:
        raise ParseError("The number must be a positive integer!")
    return number

class MyApplication(Application):
    ...

    def setup(self):
        ...
        self.router = CommandRouter()
        # Create the command
        hello_command = CommandSpec(
            command='Hello',
            function=self.say_hello,
            # See the article on the help system for more information on this feature.
            help="Greets the user.",
            aliases=('Hi', 'hola'),
            # Parsers for commands are pluggable. This one indicates that no
            # arguments are used. These functions take the raw arguments as a string,
            # and then their return value is set as the .args value on the
            # context.
            parser=no_arguments,
        )
        countdown_command = CommandSpec(
            command='countdown',
            function=self.countdown,
            help="Counts down from a number.",
            aliases=('blastoff',),
            # At the bottom of this example file, you'll find the implementation for
            # number_parser.
            parser=positive_number_parser,
        )
        # Add these to the router.
        self.router.add(hello_command)
        self.router.add(countdown_command)

    def say_hello(self, connection, context):
        # This will say "Hi! You used the hello command!"
        send_message(connection, f"Hi! You used the {context.spec.command} command!")

    def countdown(self, connection, context):
        # This will count down from the number supplied.
        # context.args is an integer here, since that's the return value of
        # positive_number_parser.
        current = context.args
        while current > 0:
            send_message(connection, f"{current}!")
            current -= 1
        send_message(connection, "Blast off!")

    def on_message(self, connection, message: str):
        # Will lookup the command (if it exists) and run it, or else send a useful error.
        self.router.route(connection, message)

`pax25.applications.router.CommandRouter` ¶

Router object that allows us to quickly route to command functions based on a command string sent by a user.