Extending osc with plugins

Note

New in osc 1.1.0

This is a simple tutorial. More details can be found in the osc.commandline.OscCommand reference.

Steps

1. First, we choose a location where to put the plugin

• The directory from where the osc.commands module gets loaded.
• /usr/lib/osc-plugins
• /usr/local/lib/osc-plugins
• ~/.local/lib/osc-plugins
• ~/.osc-plugins

2. Then we pick a file name

• The file should contain a single command and its name should correspond with the command name.
• The file name should be prefixed with parent command(s) (only if applicable).
• Example: Adding list subcommand to osc request -> request_list.py.

3. And then we write a class that inherits from osc.commandline.OscCommand and implements our command.

• The class name should also correspond with the command name incl. the parent prefix.
• Examples follow…

A simple command

simple.py

import osc.commandline


class SimpleCommand(osc.commandline.OscCommand):
    """
    A command that does nothing

    More description
    of what the command does.
    """

    # command name
    name = "simple"

    # options and positional arguments
    def init_arguments(self):
        self.add_argument(
            "--bool-option",
            action="store_true",
            help="...",
        )
        self.add_argument(
            "arguments",
            metavar="arg",
            nargs="+",
            help="...",
        )

    # code of the command
    def run(self, args):
        print(f"Bool option is {args.bool_option}")
        print(f"Positional arguments are {args.arguments}")

Command with subcommands

request.py

import osc.commandline


class RequestCommand(osc.commandline.OscCommand):
    """
    Manage requests
    """

    name = "request"
    aliases = ["rq"]

    # arguments specified here will get inherited to all subcommands automatically
    def init_arguments(self):
        self.add_argument(
            "-m",
            "--message",
            metavar="TEXT",
        )

request_list.py

import osc.commandline


class RequestListCommand(osc.commandline.OscCommand):
    """
    List requests
    """

    name = "list"
    parent = "RequestCommand"

    def run(self, args):
        print("Listing requests")

request_accept.py

import osc.commandline


class RequestAcceptCommand(osc.commandline.OscCommand):
    """
    Accept request
    """

    name = "accept"
    parent = "RequestCommand"

    def init_arguments(self):
        self.add_argument(
            "id",
            type=int,
        )

    def run(self, args):
        print(f"Accepting request '{args.id}'")