From 39b482e0ebfabf6c69ddf1b5d3c23dc168c444b6 Mon Sep 17 00:00:00 2001 From: Stefan Tatschner Date: Tue, 25 Oct 2022 09:19:53 +0200 Subject: [PATCH] docs: Add example for a simple script plugin --- docs/plugins.md | 38 ++++++++++++++++++++++++++++++++------ 1 file changed, 32 insertions(+), 6 deletions(-) diff --git a/docs/plugins.md b/docs/plugins.md index e8e226dab..a8f8e2505 100644 --- a/docs/plugins.md +++ b/docs/plugins.md @@ -17,15 +17,41 @@ These entry points are known by `gallia`: : List of callables which get called during the initialization phase of the `ArgumentParser`; can be used to add new categories to the CLI. `gallia_transports` -: List of subclasses of {class}`gallia.transports.BaseTransport` add a new URI scheme for the `--target` flag. +: List of subclasses of {class}`gallia.transports.base.BaseTransport` add a new URI scheme for the `--target` flag. `gallia_uds_ecus` -: List of subclasses of {class}`gallia.services.uds.ECU` which add new choices for the `--oem` flag. +: List of subclasses of {class}`gallia.services.uds.ecu.ECU` which add new choices for the `--oem` flag. -## CLI Categories +## Example -TODO +Below is an example that adds a new command to the CLI (using {class}`gallia.command.Script`). +Let's assume the following code snippet lives in the python module `hello.py` within the `hello_gallia` package. -## Commands +``` python +from argparse import Namespace -TODO +from gallia.command import Script + + +class HelloWorld(Script): + """A hello world script showing gallia's plugin API.""" + + COMMAND = "hello" + SHORT_HELP = "say hello to the world" + + + def main(self, args: Namespace) -> None: + print("Hello World") + + +commands = [HelloWorld] +``` + +In `pyproject.toml` using `poetry` the following entry_point needs to be specified: + +``` toml +[tool.poetry.plugins."gallia_cli_commands"] +"hello_world_commands" = "hello_gallia.hello:commands" +``` + +After issueing `poetry install`, the script can be called with `gallia script hello`.