commandline: New class-based commands

This is based on a prototype we've worked on together
with Laurin Fäller <laurin.faeller@suse.com>.

doc/api/osc.commandline.rst

@@ -2,7 +2,16 @@ commandline
 ===========
 
 
-The `osc.commandline` module provides argument parsing functionality to osc plugins.
+The ``osc.commandline`` module provides functionality for creating osc command-line plugins.
+
+
+.. autoclass:: osc.commandline.OscCommand
+   :inherited-members:
+   :members:
+
+
+.. autoclass:: osc.commandline.OscMainCommand
+   :members: main
 
 
 .. automodule:: osc.commandline

doc/index.rst

@@ -20,6 +20,7 @@ API:
    :maxdepth: 2
 
    api/modules
+   plugins/index
 
 
 

doc/plugins/index.rst

@@ -0,0 +1,54 @@
+Extending osc with plugins
+==========================
+
+
+.. note::
+    New in osc 1.1.0
+
+
+This is a simple tutorial.
+More details can be found in the :py:class:`osc.commandline.OscCommand` reference.
+
+
+Steps
+-----
+1. First, we choose a location where to put the plugin
+
+  .. include:: plugin_locations.rst
+
+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 :py:class:`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``
+
+    .. literalinclude:: simple.py
+
+
+Command with subcommands
+------------------------
+
+``request.py``
+
+    .. literalinclude:: request.py
+
+``request_list.py``
+
+    .. literalinclude:: request_list.py
+
+``request_accept.py``
+
+    .. literalinclude:: request_accept.py

doc/plugins/plugin_locations.rst

@@ -0,0 +1,5 @@
+ - 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

doc/plugins/request.py

@@ -0,0 +1,18 @@
+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",
+        )

doc/plugins/request_accept.py

@@ -0,0 +1,19 @@
+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}'")

doc/plugins/request_list.py

@@ -0,0 +1,13 @@
+import osc.commandline
+
+
+class RequestListCommand(osc.commandline.OscCommand):
+    """
+    List requests
+    """
+
+    name = "list"
+    parent = "RequestCommand"
+
+    def run(self, args):
+        print("Listing requests")

doc/plugins/simple.py

@@ -0,0 +1,32 @@
+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}")