Skip to content

CLI

Command line user interface for the node component

Attributes

cli module-attribute

cli = NodeCLI()

Classes

DatasetArgumentParser

DatasetArgumentParser(subparser, parser=None)

Bases: CLIArgumentParser

Initializes CLI options for dataset actions

Source code in fedbiomed/common/cli.py
def __init__(self, subparser: argparse.ArgumentParser, parser=None):
    self._subparser = subparser
    # Parser that is going to be add using subparser
    self._parser = None

    self._main_parser = parser

Methods:

add
add(args)

Adds datasets

Source code in fedbiomed/node/cli.py
def add(self, args):
    """Adds datasets"""

    if args.mnist != "":
        if args.mnist is None:
            mnist_path = os.path.join(self._context.config.root, NODE_DATA_FOLDER)
        else:
            mnist_path = args.mnist
        return add_database(
            self._context.dataset_manager, interactive=False, path=mnist_path
        )

    if args.file:
        return self._add_dataset_from_file(path=args.file)

    # All operation is handled by CLI utils add_database
    return add_database(
        self._context.dataset_manager,
        initialdir=os.path.join(self._context.config.root, NODE_DATA_FOLDER),
    )
delete
delete(args)

Deletes datasets

Source code in fedbiomed/node/cli.py
def delete(self, args):
    """Deletes datasets"""

    if args.all:
        return delete_all_database(self._context.dataset_manager)

    if args.mnist:
        return delete_database(self._context.dataset_manager, interactive=False)

    return delete_database(self._context.dataset_manager)
initialize
initialize()

Initializes dataset options for the node CLI

Source code in fedbiomed/node/cli.py
def initialize(self):
    """Initializes dataset options for the node CLI"""

    self._parser = self._subparser.add_parser("dataset", help="Dataset operations")
    self._parser.set_defaults(func=self.default)

    # Creates subparser of dataset option
    dataset_subparsers = self._parser.add_subparsers()

    # Add option
    add = dataset_subparsers.add_parser("add", help="Adds dataset")
    add.set_defaults(func=self.add)

    # List option
    list_ = dataset_subparsers.add_parser(
        "list", help="List datasets that are deployed in the node."
    )

    # Delete option
    delete = dataset_subparsers.add_parser(
        "delete", help="Deletes dataset that are deployed in the node."
    )

    add.add_argument(
        "--mnist",
        "-m",
        metavar="MNIST_DATA_PATH",
        help="Deploys MNIST dataset by downloading form default source to given path.",
        nargs="?",
        type=str,
        required=False,
        default="",
    )
    self._mnist_path = add

    add.add_argument(
        "--file",
        "-fl",
        required=False,
        metavar="File that describes the dataset",
        help="File path the dataset file description. This option adds dataset by given file which has"
        "custom format that describes the dataset.",
    )

    delete.add_argument(
        "--all",
        "-a",
        required=False,
        action="store_true",
        help="Removes entire dataset database.",
    )

    delete.add_argument(
        "--mnist",
        "-m",
        required=False,
        action="store_true",
        help="Removes MNIST dataset.",
    )

    list_.set_defaults(func=self.list)
    delete.set_defaults(func=self.delete)
list
list(unused_args)

List datasets

Parameters:

Name Type Description Default
unused_args

Empty arguments since list command no positional args.

required
Source code in fedbiomed/node/cli.py
def list(self, unused_args):
    """List datasets

    Args:
      unused_args: Empty arguments since `list` command no positional args.
    """
    print("Listing your data available")
    data = self._context.dataset_manager.list_my_datasets(verbose=True)
    if len(data) == 0:
        print("No data has been set up.")

GUIControl

GUIControl(subparser, parser=None)

Bases: CLIArgumentParser

Source code in fedbiomed/common/cli.py
def __init__(self, subparser: argparse.ArgumentParser, parser=None):
    self._subparser = subparser
    # Parser that is going to be add using subparser
    self._parser = None

    self._main_parser = parser

Methods:

forward
forward(args, extra_args)

Launches Fed-BioMed Node GUI

Parameters:

Name Type Description Default
args Namespace

parser argument's namespace

required
Source code in fedbiomed/node/cli.py
def forward(self, args: argparse.Namespace, extra_args):
    """Launches Fed-BioMed Node GUI

    Args:
        args: parser argument's namespace
    """

    fedbiomed_root = os.path.abspath(args.path)

    if args.data_folder == "":
        data_folder = os.path.join(self._context.config.root, NODE_DATA_FOLDER)
    else:
        data_folder = os.path.abspath(args.data_folder)
    if not os.path.isdir(data_folder):
        raise FedbiomedError(f"path {data_folder} is not a folder. Aborting")
    os.environ.update(
        {
            "DATA_PATH": data_folder,
            "FBM_NODE_COMPONENT_ROOT": fedbiomed_root,
        }
    )
    current_env = os.environ.copy()

    if args.key_file and args.cert_file:
        certificate = ["--keyfile", args.key_file, "--certfile", args.cert_file]
    else:
        certificate = []

    fedbiomed_gui = importlib.import_module("fedbiomed_gui")
    server_app = Path(fedbiomed_gui.__file__).parent  # type: ignore[arg-type]
    print("path to server", server_app)

    # The server serves the bundle built from `ui`, so changes to its sources
    # show only once it is rebuilt, the way `hatch_build.py` builds it
    if args.recreate:
        ui_folder = server_app / "ui"
        if not (ui_folder / "package.json").is_file():
            raise FedbiomedError(
                f"Cannot rebuild the GUI: its sources are not in {ui_folder}."
            )

        yarn = shutil.which("yarn")
        if yarn is None:
            raise FedbiomedError("NodeJS `yarn` is required to rebuild the GUI.")

        try:
            subprocess.run([yarn, "install"], cwd=ui_folder, check=True)
            subprocess.run([yarn, "build"], cwd=ui_folder, check=True)
        except subprocess.CalledProcessError as exp:
            raise FedbiomedError(
                f"Rebuilding the GUI failed: `yarn {exp.cmd[1]}` exited with "
                f"code {exp.returncode}."
            ) from exp

    host_port = ["--host", args.host, "--port", args.port]
    if args.development:
        command = [
            "FLASK_ENV=development",
            f"FLASK_APP={os.path.join(server_app, 'server', 'wsgi.py')}",
            "flask",
            "run",
            *host_port,
            *certificate,
        ]
    else:
        command = [
            "gunicorn",
            "--workers",
            "1",
            # str(os.cpu_count()),
            *certificate,
            "-b",
            f"{args.host}:{args.port}",
            "--access-logfile",
            "-",
            "fedbiomed_gui.server.wsgi:app",
        ]

    try:
        with subprocess.Popen(
            " ".join(command), env=current_env, shell=True
        ) as proc:
            try:
                proc.wait()
            except KeyboardInterrupt:
                proc.wait()
    except Exception as e:
        print(e)
initialize
initialize()

Initializes GUI commands

Source code in fedbiomed/node/cli.py
def initialize(self):
    """Initializes GUI commands"""
    self._parser = self._subparser.add_parser(
        "gui",  # add_help=False,
        help="Action to manage Node user interface",
    )

    gui_subparsers = self._parser.add_subparsers(title="start GUI")
    start = gui_subparsers.add_parser(
        "start", help="Launch the server (defaults on localhost:8484)"
    )

    start.set_defaults(func=self.forward)

    start.add_argument(
        "--data-folder",
        "-df",
        type=str,
        nargs="?",
        default="",  # data folder in root directory
        required=False,
    )

    start.add_argument(
        "--cert-file",
        "-cf",
        type=str,
        nargs="?",
        required=False,
        help="Name of the certificate to use in order to enable HTTPS. "
        "If cert file doesn't exist script will raise an error.",
    )

    start.add_argument(
        "--key-file",
        "-kf",
        type=str,
        nargs="?",
        required=False,
        help="Name of the private key for the SSL certificate. "
        "If the key file doesn't exist, the script will raise an error.",
    )

    start.add_argument(
        "--port",
        "-p",
        type=str,
        nargs="?",
        default="8484",
        required=False,
        help="HTTP port that GUI will be served. Default is `8484`",
    )

    start.add_argument(
        "--host",
        "-ho",
        type=str,
        default="localhost",
        nargs="?",
        required=False,
        help="HTTP port that GUI will be served. Default is `127.0.0.1` (localhost)",
    )

    start.add_argument(
        "--debug",
        "-dbg",
        action="store_true",
        required=False,
        help="Debug mode for the GUI. Default is `False`",
    )

    start.add_argument(
        "--recreate",
        "-rc",
        action="store_true",
        required=False,
        help="Rebuilds the user interface from its sources (`yarn install`, "
        "`yarn build`) before starting the GUI",
    )

    start.add_argument(
        "--development",
        "-dev",
        action="store_true",
        required=False,
        help="If it is set, GUI will start in development mode.",
    )

NodeCLI

NodeCLI()

Bases: CommonCLI

The fedbiomed node command line application.

Defines and parses what a user can type, then hands over to the matching action. Decides which action runs and, through --path, on which node; what the action then acts on is the NodeContext it passes to every subparser.

Source code in fedbiomed/node/cli.py
def __init__(self):
    super().__init__()

    self._parser.prog = "fedbiomed node"
    self.description = f"{__intro__} \nA CLI app for fedbiomed node component."
    # Parent parser for parameters that are common for Node CLI actions
    self.initialize()

Attributes

description instance-attribute
description = f'{__intro__} 
A CLI app for fedbiomed node component.'

Methods:

initialize
initialize()

Initializes node module

Source code in fedbiomed/node/cli.py
def initialize(self):
    """Initializes node module"""

    class ComponentDirectoryActionNode(ComponentDirectoryAction):
        _this = self
        _component = ComponentType.NODE

        def set_component(self, component_dir: str | None = None) -> None:
            """Create node instance"""
            if component_dir:
                component_dir = os.path.abspath(component_dir)
                os.environ["FBM_NODE_COMPONENT_ROOT"] = component_dir
            else:
                print(
                    "Component is not specified: Using 'fbm-node' in current working directory..."
                )
                component_dir = os.path.join(os.getcwd(), "fbm-node")
                os.environ["FBM_NODE_COMPONENT_ROOT"] = component_dir
            config = node_component.initiate(root=component_dir)
            self._this.config = config
            context = NodeContext(config)
            # Set context object to make it accessible
            ComponentDirectoryActionNode._this._context = context
            os.environ[f"FEDBIOMED_ACTIVE_{self._component.name}_ID"] = config.get(
                "default", "id"
            )

            # Set context in all subparsers
            for (
                _,
                parser,
            ) in ComponentDirectoryActionNode._this._arg_parsers.items():
                parser._context = context

    super().initialize()

    self._path_action = self._parser.add_argument(
        "--path",
        "-p",
        nargs="?",
        action=ComponentDirectoryActionNode,
        default="fbm-node",
        help="The path were component is located. It can be absolute or "
        "relative to the path where CLI is executed.",
    )
initialize_certificate_parser
initialize_certificate_parser()

Adds certificate check, which only a node has.

What readiness means differs by component: a node pins the one researcher certificate it registers, where a researcher trusts the several it holds.

Source code in fedbiomed/node/cli.py
def initialize_certificate_parser(self):
    """Adds `certificate check`, which only a node has.

    What readiness means differs by component: a node pins the one researcher
    certificate it registers, where a researcher trusts the several it holds.
    """
    super().initialize_certificate_parser()

    check = self._certificate_sub_parsers.add_parser(
        "check",
        help="Reports what stops this node connecting under mutual "
        "authentication, and what it tolerates but an operator should fix. "
        "Exits 1 when the node would not start.",
    )
    check.set_defaults(func=self._check_certificate)

NodeControl

NodeControl(subparser, parser=None)

Bases: CLIArgumentParser

CLI argument parser for starting the node

Source code in fedbiomed/common/cli.py
def __init__(self, subparser: argparse.ArgumentParser, parser=None):
    self._subparser = subparser
    # Parser that is going to be add using subparser
    self._parser = None

    self._main_parser = parser

Methods:

initialize
initialize()

Initializes missing control argument parser

Source code in fedbiomed/node/cli.py
def initialize(self):
    """Initializes missing control argument parser"""
    start = self._subparser.add_parser("start", help="Starts the node")
    start.set_defaults(func=self.start)

    start.add_argument(
        "--gpu",
        action="store_true",
        help="Activate GPU usage if the flag is present",
    )

    start.add_argument(
        "--gpu-num",
        "-gn",
        type=int,
        nargs="?",
        required=False,
        default=1,
        help="Number of GPU that is going to be used",
    )

    start.add_argument(
        "--gpu-only",
        "-go",
        action="store_true",
        help="Node performs training only using GPU resources."
        "This flag automatically activate GPU.",
    )

    start.add_argument(
        "--debug",
        "-D",
        action="store_true",
        required=False,
        help="Activate debug mode for the Node. Default is `False`",
    )

    start.add_argument(
        "--background",
        "-b",
        action="store_true",
        required=False,
        help="Start the node in the background. Default is `False`",
    )

    start.add_argument(
        "--force",
        action="store_true",
        help=(
            "Start a new node process even when the process-state database "
            "reports that the node is already running."
        ),
    )

    stop = self._subparser.add_parser("stop", help="Stops the node")
    stop.set_defaults(func=self.stop)

    restart = self._subparser.add_parser(
        "restart",
        help="Restarts the node. Takes the same arguments as `start` command for restarting the node.",
    )
    restart.set_defaults(func=self.restart)

    restart.add_argument(
        "--gpu",
        action="store_true",
        default=None,
        help="Activate GPU usage if the flag is present",
    )

    restart.add_argument(
        "--gpu-num",
        "-gn",
        type=int,
        nargs="?",
        required=False,
        default=None,
        help="Number of GPU that is going to be used",
    )

    restart.add_argument(
        "--gpu-only",
        "-go",
        action="store_true",
        default=None,
        help="Node performs training only using GPU resources."
        "This flag automatically activate GPU.",
    )

    restart.add_argument(
        "--debug",
        "-D",
        action="store_true",
        required=False,
        default=None,
        help="Activate debug mode for the Node. Default is `False`",
    )

    restart.add_argument(
        "--background",
        "-b",
        action="store_true",
        required=False,
        default=None,
        help="Start the node in the background. Default is `False`",
    )

    status = self._subparser.add_parser("status", help="Shows the node status")
    status.set_defaults(func=self.status)

    status.add_argument(
        "--history",
        action="store_true",
        required=False,
        help="Also lists the connection state changes the node recorded recently.",
    )
restart
restart(args)

Restarts the node

Source code in fedbiomed/node/cli.py
def restart(self, args):
    """Restarts the node"""
    node_args = {}
    if args.gpu is not None:
        node_args["gpu"] = args.gpu
    if args.gpu_num is not None:
        node_args["gpu_num"] = args.gpu_num
    if args.gpu_only is not None:
        node_args["gpu_only"] = args.gpu_only
        if args.gpu_only:
            node_args["gpu"] = True
    if args.debug is not None:
        node_args["debug"] = args.debug

    node_process_manager = NodeProcessManager(self._context.config)
    node_process_manager.restart(
        node_args=node_args,
        background=args.background,
        actor={"source": "cli"},
        reason="cli_restart_command",
    )
start
start(args)

Starts the node

Source code in fedbiomed/node/cli.py
def start(self, args):
    """Starts the node"""
    intro()

    node_args = {
        "gpu": (args.gpu is True) or (args.gpu_only is True),
        "gpu_num": args.gpu_num,
        "gpu_only": True if args.gpu_only else False,
        "debug": True if args.debug else False,
    }

    node_process_manager = NodeProcessManager(self._context.config)
    background = True if args.background else False
    try:
        if background:
            logger.info("Starting the node in the background...")
            logger.info(
                "Use `fedbiomed node status` command to check the node status."
            )
            logger.info(
                "You can use the `fedbiomed node stop` command to stop the node."
            )
            logger.info(
                "Or you can use the `fedbiomed node restart` command to directly restart the node with new parameters."
            )
        else:
            logger.info("Starting the node in the foreground...")
            logger.info("Use Ctrl+C to stop the node.")
        node_process_manager.start(
            node_args=node_args,
            background=background,
            actor={"source": "cli"},
            force=args.force,
        )
    except KeyboardInterrupt:
        node_process_manager.stop(
            actor={"source": "cli"},
            reason="keyboard_interrupt",
        )
        sys.exit(0)
status
status(args)

Shows the node status, and the connection it last recorded.

The node writes its connection state as it observes its channel, so what is reported here is only current while the node runs.

Source code in fedbiomed/node/cli.py
def status(self, args):
    """Shows the node status, and the connection it last recorded.

    The node writes its connection state as it observes its channel, so what
    is reported here is only current while the node runs.
    """
    node_process_manager = NodeProcessManager(self._context.config)
    status = node_process_manager.get_status()
    _print_table("Node process", [["State", _colored_state(status)]])
    print()

    connection_state = NodeConnectionStateManager(
        self._context.config
    ).get_connection_state()
    if connection_state is None:
        print("Connection to researcher: none recorded yet")
    else:
        _print_table("Connection to researcher", _connection_rows(connection_state))
        if status is not NodeState.RUNNING:
            print(
                "The node is not running, so this is the state it "
                "was in when it stopped."
            )

    if not args.history:
        return

    history = NodeConnectionStateManager(
        self._context.config
    ).get_connection_history()
    if not history:
        print("\nNo connection state change recorded.")
        return

    print("\nRecent connection state changes, newest first:")
    for entry in history:
        print(
            f"  {entry.updated_at or '-'}  {entry.state}"
            + (f"  {entry.operation}" if entry.operation else "")
            + (f"  {entry.reason}" if entry.reason else "")
        )
stop
stop()

Stops the node

Source code in fedbiomed/node/cli.py
def stop(self):
    """Stops the node"""
    node_process_manager = NodeProcessManager(self._context.config)
    node_process_manager.stop(
        actor={"source": "cli"},
        reason="cli_stop_command",
    )

TrainingPlanArgumentParser

TrainingPlanArgumentParser(subparser, parser=None)

Bases: CLIArgumentParser

Argument parser for training-plan operations

Source code in fedbiomed/common/cli.py
def __init__(self, subparser: argparse.ArgumentParser, parser=None):
    self._subparser = subparser
    # Parser that is going to be add using subparser
    self._parser = None

    self._main_parser = parser

Methods:

approve
approve(args)

Approves training plan

Source code in fedbiomed/node/cli.py
def approve(self, args):
    """Approves training plan"""
    approve_training_plan(self._context.tp_security_manager, id=args.id)
delete
delete(args)

Deletes training plan

Source code in fedbiomed/node/cli.py
def delete(self, args):
    """Deletes training plan"""
    delete_training_plan(self._context.tp_security_manager, id=args.id)
initialize
initialize()
Source code in fedbiomed/node/cli.py
def initialize(self):
    self._parser = self._subparser.add_parser(
        "training-plan",
        help="CLI operations for TrainingPlans register/list/delete/approve/reject etc.",
    )

    training_plan_suparsers = self._parser.add_subparsers()
    self._parser.set_defaults(func=self.default)

    common_reject_approve = argparse.ArgumentParser(add_help=False)
    common_reject_approve.add_argument(
        "--id",
        type=str,
        nargs="?",
        required=False,
        help="ID of the training plan that will be processed.",
    )

    update = training_plan_suparsers.add_parser(
        "update", help="Updates training plan"
    )
    update.set_defaults(func=self.update)

    register = training_plan_suparsers.add_parser(
        "register",
        help="Registers training plans manually by selected file through interactive browser.",
    )
    register.set_defaults(func=self.register)

    list = training_plan_suparsers.add_parser(
        "list", help="Lists all saved/registered training plans with their status."
    )
    list.set_defaults(func=self.list)

    delete = training_plan_suparsers.add_parser(
        "delete",
        parents=[common_reject_approve],
        help="Deletes interactively selected training plan from the database.",
    )
    delete.set_defaults(func=self.delete)

    approve = training_plan_suparsers.add_parser(
        "approve",
        parents=[common_reject_approve],
        help="Approves interactively selected training plans.",
    )
    approve.set_defaults(func=self.approve)

    reject = training_plan_suparsers.add_parser(
        "reject",
        parents=[common_reject_approve],
        help="Rejects interactively selected training plans.",
    )

    reject.add_argument(
        "--notes",
        type=str,
        nargs="?",
        required=False,
        default="No notes provided.",
        help="Note to explain why training plan is rejected.",
    )
    reject.set_defaults(func=self.reject)

    view = training_plan_suparsers.add_parser(
        "view", help="View interactively selected training plans."
    )
    view.set_defaults(func=self.view)
list
list()

Lists training plans

Source code in fedbiomed/node/cli.py
def list(self):
    """Lists training plans"""
    self._context.tp_security_manager.list_training_plans(verbose=True)
register
register()

Registers training plan

Source code in fedbiomed/node/cli.py
def register(self):
    """Registers training plan"""
    register_training_plan(self._context.tp_security_manager)
reject
reject(args)

Approves training plan

Source code in fedbiomed/node/cli.py
def reject(self, args):
    """Approves training plan"""
    reject_training_plan(
        self._context.tp_security_manager, id=args.id, notes=args.notes
    )
update
update()

Updates training plan

Source code in fedbiomed/node/cli.py
def update(self):
    """Updates training plan"""
    update_training_plan(self._context.tp_security_manager)
view
view()

Views training plan

Source code in fedbiomed/node/cli.py
def view(self):
    """Views training plan"""
    view_training_plan(self._context.tp_security_manager)

Functions:

intro

intro()

Prints intro for the CLI

Source code in fedbiomed/node/cli.py
def intro():
    """Prints intro for the CLI"""

    print(__intro__)
    print("\t- 🆔 Your node ID:", os.environ["FEDBIOMED_ACTIVE_NODE_ID"], "\n")