75 lines
2.3 KiB
Python
75 lines
2.3 KiB
Python
# Copyright 2018 Open Source Foundries Limited.
|
|
#
|
|
# SPDX-License-Identifier: Apache-2.0
|
|
|
|
'''West's commands subpackage.
|
|
|
|
All commands should be implemented within modules in this package.
|
|
'''
|
|
|
|
from abc import ABC, abstractmethod
|
|
|
|
__all__ = ['CommandContextError', 'WestCommand']
|
|
|
|
|
|
class CommandContextError(RuntimeError):
|
|
'''Indicates that a context-dependent command could not be run.'''
|
|
|
|
|
|
class WestCommand(ABC):
|
|
'''Abstract superclass for a west command.
|
|
|
|
All top-level commands supported by west implement this interface.'''
|
|
|
|
def __init__(self, name, description, accepts_unknown_args=False):
|
|
'''Create a command instance.
|
|
|
|
`name`: the command's name, as entered by the user.
|
|
`description`: one-line command description to show to the user.
|
|
|
|
`accepts_unknown_args`: if true, the command can handle
|
|
arbitrary unknown command line arguments in its run()
|
|
method. Otherwise, passing unknown arguments will cause
|
|
UnknownArgumentsError to be raised.
|
|
'''
|
|
self.name = name
|
|
self.description = description
|
|
self._accept_unknown = accepts_unknown_args
|
|
|
|
def run(self, args, unknown):
|
|
'''Run the command.
|
|
|
|
`args`: known arguments parsed via `register_arguments()`
|
|
`unknown`: unknown arguments present on the command line
|
|
'''
|
|
if unknown and not self._accept_unknown:
|
|
self.parser.error('unexpected arguments: {}'.format(unknown))
|
|
self.do_run(args, unknown)
|
|
|
|
def add_parser(self, parser_adder):
|
|
'''Registers a parser for this command, and returns it.
|
|
'''
|
|
self.parser = self.do_add_parser(parser_adder)
|
|
return self.parser
|
|
|
|
#
|
|
# Mandatory subclass hooks
|
|
#
|
|
|
|
@abstractmethod
|
|
def do_add_parser(self, parser_adder):
|
|
'''Subclass method for registering command line arguments.
|
|
|
|
`parser_adder` is an argparse argument subparsers adder.'''
|
|
|
|
@abstractmethod
|
|
def do_run(self, args, unknown):
|
|
'''Subclasses must implement; called when the command is run.
|
|
|
|
`args` is the namespace of parsed known arguments.
|
|
|
|
If `accepts_unknown_args` was False when constructing this
|
|
object, `unknown` will be empty. Otherwise, it is an iterable
|
|
containing all unknown arguments present on the command line.
|
|
'''
|