0.4.3 (#144)

* ⬆️ Bump argx to 0.2.2

* 🎨 Expose parse_args() to cli plugins

* 🔖 0.4.3

docs/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Change Log
 
+## 0.4.3
+
+- ⬆️ Bump `argx` to 0.2.2
+- 🎨 Expose `parse_args()` to cli plugins
+
 ## 0.4.2
 
 - ⬆️ Bump `argx` to 0.2

docs/cli.md

@@ -3,22 +3,19 @@
 To run it:
 
 ```shell
-❯ pipen
+❯ pipen --help
+Usage: pipen [-h] {version,profile,plugins,help} ...
 
-DESCRIPTION:
-  CLI Tool for pipen v0.1.4
+CLI Tool for pipen v0.4.2
 
-USAGE:
-  pipen [OPTIONS] COMMAND [OPTIONS]
+Optional Arguments:
+  -h, --help            show help message and exit
 
-OPTIONAL OPTIONS:
-  -h, --help                      - Print help information for the CLI tool.
-
-COMMANDS:
-  version                         - Print versions of pipen and its dependencies
-  profile                         - List available profiles.
-  plugins                         - List installed plugins
-  help                            - Print help for commands
+Subcommands:
+    version             Print versions of pipen and its dependencies
+    profile             List available profiles.
+    plugins             List installed plugins
+    help                Print help for commands
 ```
 
 ## Writing a plugin to extend the cli
@@ -29,11 +26,18 @@ A CLI plugin has to be a subclass of `pipen.cli.CLIPlugin`.
 
 A CLI plugin has to define a `name` property, which also is the sub-command of the plugin.
 
-Then a `params` property is also needed to define the commands and arguments of this plugin. To see how to define a `Params` object, see `pyparam`'s [documentation][5].
+There are a couple of methods of `pipen.cli.CLIPlugin` to extend for a plugin:
+
+- `__init__(self, parser, subparser)`: initialize the plugin
+  It takes the main parser and the subparser of the sub-command as arguments. You can add arguments to the parser or subparser here.
+  Check [argx][1] for more information about how to define arguments.
 
-You may also define a method `parse_args()` to parse CLI arguments by yourself. By default, it just calls `Params.parse()` to parse the arguments.
+- `parse_args(self)`: parse the arguments
+  It takes no arguments. It should parse the arguments and return the parsed arguments (Namespace), which are used to execute the command.
+  By default, `self.parser.parse_args()` is called to parse the arguments.
 
-Finally, define `exec_command()`, which takes the parsed arguments as argument, to execute the command as you wish.
+- `exec_command(self, args)`: execute the command
+  It takes the parsed arguments as argument. It should execute the command as you wish.
 
 ### loading CLI plugins
 
@@ -62,8 +66,7 @@ This subcommand is used to list the plugins for `pipen` itself, templates, sched
 
 This command prints the versions of `pipen` and its dependencies.
 
-[1]: https://github.com/pwwang/pyparam
+[1]: https://github.com/pwwang/argx
 [2]: ../plugin
 [3]: ../templating
 [4]: ../scheduler
-[5]: https://pwwang.github.io/pyparam

docs/plugin.md

@@ -76,7 +76,6 @@ See [`simplug`][1] for more details.
 
     The first plugin (based on priority) have this hook return `False` will cancel the submission
 
-
 - `on_job_submitted(proc, job)` (async)
 
     When a job is submitted in the scheduler system.
@@ -99,12 +98,10 @@ See [`simplug`][1] for more details.
 
     When a job completes successfully
 
-
 - `on_job_failed(proc, job)` (async)
 
     When a job is done but failed (i.e. return_code == 1).
 
-
 ## Loading plugins
 
 You can specify the plugins to be loaded by specifying the names or the plugin itself in `plugins` configuration. With names, the plugins will be loaded from [entry points][2].
@@ -140,13 +137,14 @@ You can also use the entry point to register your plugin using the group name `p
 For `setup.py`, you will need:
 ```python
 setup(
-	# ...
-	entry_points={"pipen": ["pipen_verbose = pipen_verbose"]},
-	# ...
+    # ...
+    entry_points={"pipen": ["pipen_verbose = pipen_verbose"]},
+    # ...
 )
 ```
 
 For `pyproject.toml`:
+
 ```toml
 [tool.poetry.plugins.pipen]
 pipen_verbose = "pipen_verbose"
@@ -168,7 +166,7 @@ logger = get_logger("verbose", "info")
 
 The above code will produce some logging on the console like this:
 
-```
+```shell
 11-04 12:00:19 I main    ╭═══════════════════════════ Process ═══════════════════════════╮
 11-04 12:00:19 I main    ║ Undescribed.                                                  ║
 11-04 12:00:19 I main    ╰═══════════════════════════════════════════════════════════════╯
@@ -178,6 +176,10 @@ The above code will produce some logging on the console like this:
 11-04 12:00:19 I verbose Process: [0/9] out.b: pipeline-0-output/Process/0/a.txt
 ```
 
+## CLI plugins
+
+See [CLI][11] for more details.
+
 ## Plugin gallery
 
 - [`pipen-verbose`][3]: Add verbosal information in logs for pipen.
@@ -189,8 +191,6 @@ The above code will produce some logging on the console like this:
 - [`pipen-cli-init`][9]: A pipen CLI plugin to create a pipen project (pipeline)
 - [`pipen-cli-run`][10]: A pipen cli plugin to run a process or a pipeline
 
-
-
 [1]: https://github.com/pwwang/simplug
 [2]: https://packaging.python.org/specifications/entry-points/
 [3]: https://github.com/pwwang/pipen-verbose
@@ -201,3 +201,4 @@ The above code will produce some logging on the console like this:
 [8]: https://github.com/pwwang/pipen-filters
 [9]: https://github.com/pwwang/pipen-cli-init
 [10]: https://github.com/pwwang/pipen-cli-run
+[11]: ../cli

pipen/cli/_hooks.py

@@ -30,8 +30,9 @@ def __init__(
     def name(self) -> str:
         """The name/command of this plugin"""
 
-    def define_args(self, parser: ArgumentParser):
+    def parse_args(self) -> Namespace:
         """Define arguments for the command"""
+        return self.parser.parse_args()
 
     @abstractmethod
     def exec_command(self, args: Namespace) -> None:

pipen/cli/_main.py

@@ -44,5 +44,6 @@ def main() -> None:
         )
         plugins[plg.name] = plg(parser, subparser)
 
-    parsed = parser.parse_args()
-    plugins[parsed.COMMAND].exec_command(parsed)
+    known_parsed, _ = parser.parse_known_args()
+    parsed = plugins[known_parsed.COMMAND].parse_args()
+    plugins[known_parsed.COMMAND].exec_command(parsed)

pipen/version.py

@@ -1,3 +1,3 @@
 """Provide version of pipen"""
 
-__version__ = "0.4.2"
+__version__ = "0.4.3"