Writing own handler

It is possible to extend the application by adding own custom commands. To do so it is required to implement class, which derives from ahriman.application.handlers.handler.Handler and put it to the ahriman.application.handlers package. The class later will be loaded automatically and included to each command run.

Let’s imagine, that the new class implements help-web, which prints server information to the stdout. To do so, we need to implement base ahriman.application.handlers.handler.Handler.run method which is entry point for all subcommands:

from ahriman.application.application import Application
from ahriman.application.handlers.handler import Handler


class HelpWeb(Handler):

   @classmethod
   def run(cls, args: argparse.Namespace, repository_id: RepositoryId, configuration: Configuration, *,
           report: bool) -> None:
     # load application instance
     # report is set to True to make sure that web client is loaded
     application = Application(repository_id, configuration, report=True)
     # extract web client
     client = application.repository.reporter

     # send request to the server
     response = client.make_request("GET", f"{client.address}/api/v1/info")
     result = response.json()
     print(result)

The main functionality of the class is already described, but command is still not available yet. To do so, it is required to set arguments property, which is the list of the functions, each of them which takes argument parser object, creates new subcommand and returns the modified parser, e.g.:

import argparse

from ahriman.application.handlers.handler import SubParserAction

...

    @staticmethod
    def set_parser(root: SubParserAction) -> argparse.ArgumentParser:
        parser = root.add_parser("help-web", help="get web server status",
                                 description="request server info and print it to stdout")

    arguments = set_parser

In addition, ahriman.application.handlers.handler.Handler.ALLOW_MULTI_ARCHITECTURE_RUN can be set to False in order to disable multiprocess run (e.g. in case if there are conflicting operations, like writing to stdout).

Save the file above as /usr/lib/python3.12/site-packages/ahriman/application/handlers/help_web.py (replace python3.12 with actual python version) and you are set.

For more examples and details, please check builtin handlers and classes documentations.