diff --git a/labgrid/driver/bareboxdriver.py b/labgrid/driver/bareboxdriver.py index 081012014..25881f600 100644 --- a/labgrid/driver/bareboxdriver.py +++ b/labgrid/driver/bareboxdriver.py @@ -19,7 +19,12 @@ @target_factory.reg_driver @attr.s class BareboxDriver(CommandMixin, Driver, CommandProtocol, LinuxBootProtocol): - """BareboxDriver - Driver to control barebox via the console""" + """BareboxDriver - Driver to control barebox via the console. + BareboxDriver binds on top of a ConsoleProtocol. + + Args: + prompt (str): The default Barebox Prompt + """ bindings = {"console": ConsoleProtocol, } prompt = attr.ib(default="", validator=attr.validators.instance_of(str)) @@ -32,20 +37,31 @@ def __attrs_post_init__(self): self._status = 0 def on_activate(self): + """Activate the BareboxDriver + + This function checks for a prompt and awaits it if not already active + """ self._check_prompt() if self._status == 0: self.await_prompt() def on_deactivate(self): + """Deactivate the BareboxDriver + + Simply sets the internal status to 0 + """ self._status = 0 @step(args=['cmd']) - def run(self, cmd, *, step): + def run(self, cmd: str, *, step): """ - Runs the specified cmd on the shell and returns the output. + Runs the specified command on the shell and returns the output. - Arguments: - cmd - cmd to run on the shell + Args: + cmd (str): command to run on the shell + + Returns: + Tuple[List[str],List[str], int]: if successful, None otherwise """ # FIXME: Handle pexpect Timeout marker = gen_marker() @@ -71,13 +87,16 @@ def run(self, cmd, *, step): else: return None - def run_check(self, cmd): + def run_check(self, cmd: str): """ - Runs the specified cmd on the shell and returns the output if successful, + Runs the specified command on the shell and returns the output if successful, raises ExecutionError otherwise. - Arguments: - cmd - cmd to run on the shell + Args: + cmd (str): command to run on the shell + + Returns: + List[str]: stdout of the executed command """ res = self.run(cmd) if res[2] != 0: @@ -85,14 +104,18 @@ def run_check(self, cmd): return res[0] def get_status(self): - """Returns the status of the barebox driver. - 0 means not connected/found, 1 means shell + """Retrieve status of the BareboxDriver + 0 means inactive, 1 means active. + + Returns: + int: status of the driver """ return self._status def _check_prompt(self): """ - Internal function to check if we have a valid prompt + Internal function to check if we have a valid prompt. + It sets the internal _status to 1 or 0 based on the prompt detection. """ self.console.sendline("") try: @@ -111,9 +134,16 @@ def await_prompt(self): self._check_prompt() def await_boot(self): + """Wait for the initial Linux version string to verify we succesfully + jumped into the kernel. + """ self.console.expect(r"Linux version \d") - def boot(self, name): + def boot(self, name: str): + """Boot the default or a specific boot entry + + Args: + name (str): name of the entry to boot""" if name: self.console.sendline("boot -v {}".format(name)) else: diff --git a/labgrid/driver/shelldriver.py b/labgrid/driver/shelldriver.py index 8a05ccd22..78ef09e67 100644 --- a/labgrid/driver/shelldriver.py +++ b/labgrid/driver/shelldriver.py @@ -21,7 +21,16 @@ @target_factory.reg_driver @attr.s class ShellDriver(CommandMixin, Driver, CommandProtocol): - """ShellDriver - Driver to execute commands on the shell""" + """ShellDriver - Driver to execute commands on the shell + ShellDriver binds on top of a ConsoleProtocol. + + Args: + prompt (regex): The Linux Prompt to detect + login_prompt (regex): The Login Prompt to detect + username (str): username to login with + password (str): password to login with + keyfile (str): keyfile to bind mount over users authorized keys + """ bindings = {"console": ConsoleProtocol, } prompt = attr.ib(validator=attr.validators.instance_of(str)) login_prompt = attr.ib(validator=attr.validators.instance_of(str)) diff --git a/labgrid/driver/ubootdriver.py b/labgrid/driver/ubootdriver.py index a0d02f12f..5e9c23c08 100644 --- a/labgrid/driver/ubootdriver.py +++ b/labgrid/driver/ubootdriver.py @@ -18,7 +18,14 @@ @target_factory.reg_driver @attr.s class UBootDriver(CommandMixin, Driver, CommandProtocol, LinuxBootProtocol): - """UBootDriver - Driver to control uboot via the console""" + """UBootDriver - Driver to control uboot via the console. + UBootDriver binds on top of a ConsoleProtocol. + + Args: + prompt (str): The default UBoot Prompt + password (str): optional password to unlock UBoot + init_commands (Tuple[str]): a tuple of commands to run after unlock + """ bindings = {"console": ConsoleProtocol, } prompt = attr.ib(default="", validator=attr.validators.instance_of(str)) password = attr.ib(default="", validator=attr.validators.instance_of(str)) @@ -33,19 +40,30 @@ def __attrs_post_init__(self): self._status = 0 def on_activate(self): + """Activate the UBootDriver + + This function checks for a prompt and awaits it if not already active + """ if self._status == 0: self.await_prompt() def on_deactivate(self): + """Deactivate the UBootDriver + + Simply sets the internal status to 0 + """ self._status = 0 @step(args=['cmd'], result=True) def run(self, cmd): """ - Runs the specified cmd on the shell and returns the output. + Runs the specified command on the shell and returns the output. + + Args: + cmd (str): command to run on the shell - Arguments: - cmd - cmd to run on the shell + Returns: + Tuple[List[str],List[str], int]: if successful, None otherwise """ # FIXME: Handle pexpect Timeout # TODO: Shell Escaping for the U-Boot Shell @@ -77,11 +95,14 @@ def run(self, cmd): @step(args=['cmd'], result=True) def run_check(self, cmd): """ - Runs the specified cmd on the shell and returns the output if successful, + Runs the specified command on the shell and returns the output if successful, raises ExecutionError otherwise. - Arguments: - cmd - cmd to run on the shell + Args: + cmd (str): command to run on the shell + + Returns: + List[str]: stdout of the executed command """ res = self.run(cmd) if res[2] != 0: @@ -89,14 +110,18 @@ def run_check(self, cmd): return res[0] def get_status(self): - """Returns the status of the uboot driver. - 0 means not connected/found, 1 means shell + """Retrieve status of the UBootDriver. + 0 means inactive, 1 means active. + + Returns: + int: status of the driver """ return self._status def _check_prompt(self): """ - Internal function to check if we have a valid prompt + Internal function to check if we have a valid prompt. + It sets the internal _status to 1 or 0 based on the prompt detection. """ marker = gen_marker() # hide marker from expect @@ -111,7 +136,9 @@ def _check_prompt(self): @step() def await_prompt(self): - """Await autoboot line and stop it to get to the prompt""" + """Await autoboot line and stop it to get to the prompt, optionally + enter the password. + """ self.console.expect(r"U-Boot 20\d+") index, _, _, _ = self.console.expect( [self.prompt, "stop autoboot", "enter Password:"] @@ -131,11 +158,17 @@ def await_prompt(self): @step() def await_boot(self): - """Wait for boot line of the linux kernel""" + """Wait for the initial Linux version string to verify we succesfully + jumped into the kernel. + """ self.console.expect(r"Linux version \d") @step(args=['name']) def boot(self, name): + """Boot the default or a specific boot entry + + Args: + name (str): name of the entry to boot""" if name: self.console.sendline("boot -v {}".format(name)) else: diff --git a/labgrid/resource/base.py b/labgrid/resource/base.py index 1c5756543..ea5e22176 100644 --- a/labgrid/resource/base.py +++ b/labgrid/resource/base.py @@ -5,10 +5,19 @@ @attr.s class SerialPort(Resource): + """The basic SerialPort describes port and speed + + Args: + port (str): port to connect to + speed (int): speed of the port, defaults to 115200""" port = attr.ib(default=None) speed = attr.ib(default=115200, validator=attr.validators.instance_of(int)) @attr.s class EthernetInterface(Resource): + """The basic EthernetInterface contains an interfacename + + Args: + ifname (str): name of the interface""" ifname = attr.ib(default=None) diff --git a/labgrid/resource/common.py b/labgrid/resource/common.py index 301d48739..2e94579a7 100644 --- a/labgrid/resource/common.py +++ b/labgrid/resource/common.py @@ -13,6 +13,7 @@ class Resource(BindingMixin): use. Life cycle: + - create - bind (n times) """ @@ -25,6 +26,15 @@ def command_prefix(self): @attr.s class NetworkResource(Resource): + """ + Represents a remote Resource available on another computer. + + This stores a command_prefix to describe how to connect to the remote + computer. + + Args: + host (str): remote host the resource is available on + """ host = attr.ib(validator=attr.validators.instance_of(str)) @property diff --git a/labgrid/resource/onewireport.py b/labgrid/resource/onewireport.py index ca5066c2b..f0ae874ca 100644 --- a/labgrid/resource/onewireport.py +++ b/labgrid/resource/onewireport.py @@ -9,8 +9,8 @@ class OneWirePIO(Resource): """This resource describes a Onewire PIO Port. - Arguments: - host - The hostname of the owserver e.g. localhost:4304 - path - Path to the port on the owserver e.g. 29.7D6913000000/PIO.0""" + Args: + host (str): hostname of the owserver e.g. localhost:4304 + path (str): path to the port on the owserver e.g. 29.7D6913000000/PIO.0""" host = attr.ib(validator=attr.validators.instance_of(str)) path = attr.ib(validator=attr.validators.instance_of(str)) diff --git a/labgrid/resource/power.py b/labgrid/resource/power.py index 7efe6e6d5..f7e2c3ac5 100644 --- a/labgrid/resource/power.py +++ b/labgrid/resource/power.py @@ -7,6 +7,13 @@ @target_factory.reg_resource @attr.s class NetworkPowerPort(Resource): + """The NetworkPowerPort describes a remotely switchable PowerPort + + Args: + model (str): model of the external power switch + host (str): host to connect to + index (str): index of the power port on the external switch + """ model = attr.ib(validator=attr.validators.instance_of(str)) host = attr.ib(validator=attr.validators.instance_of(str)) index = attr.ib(validator=attr.validators.instance_of(str), diff --git a/labgrid/resource/serialport.py b/labgrid/resource/serialport.py index 189a88893..42a069777 100644 --- a/labgrid/resource/serialport.py +++ b/labgrid/resource/serialport.py @@ -8,6 +8,7 @@ @target_factory.reg_resource @attr.s class RawSerialPort(SerialPort, Resource): + """RawSerialPort describes a serialport which is vailable on the local computer.""" def __attrs_post_init__(self): super().__attrs_post_init__() if self.port is None: @@ -17,5 +18,11 @@ def __attrs_post_init__(self): @target_factory.reg_resource @attr.s class NetworkSerialPort(NetworkResource): + """A NetworkSerialPort is a remotely accessable serialport, usually + accessed via rfc2217. + + Args: + port (str): connection string to the port e.g. 'rfc2217://:' + speed (int): speed of the port e.g. 9800""" port = attr.ib(validator=attr.validators.instance_of(int)) speed = attr.ib(default=115200, validator=attr.validators.instance_of(int))