Extending osc with plugins
Note
New in osc 1.1.0
Warning
Plugins are currently NOT supported in virtualenv.
This is a simple tutorial.
More details can be found in the osc.commandline.OscCommand
reference.
Steps
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
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 toosc request
->request_list.py
.
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}'")