cleanup Merge 'pulls/326281544/67', added comments

joycontrol/controller_state.py

@@ -171,13 +171,13 @@ class ButtonState:
 
     def get_available_buttons(self):
         """
-        :returns set of valid buttons
+        :returns: set of valid buttons
         """
         return set(self._available_buttons)
 
     def __iter__(self):
         """
-        :returns iterator over the button bytes
+        :returns: iterator over the button bytes
         """
         yield self._byte_1
         yield self._byte_2
@@ -187,7 +187,12 @@ class ButtonState:
         self._byte_1 = self._byte_2 = self._byte_3 = 0
 
 
-async def button_down(controller_state, *buttons):
+async def button_press(controller_state, *buttons):
+    """
+    Set given buttons in the controller state to the pressed down state and wait till send.
+    :param controller_state:
+    :param buttons: Buttons to press down (see ButtonState.get_available_buttons)
+    """
     if not buttons:
         raise ValueError('No Buttons were given.')
 
@@ -195,13 +200,18 @@ async def button_down(controller_state, *buttons):
 
     for button in buttons:
         # push button
-        button_state.set_button(button)
+        button_state.set_button(button, pushed=True)
 
-    # send report
+    # wait until report is send
     await controller_state.send()
 
 
-async def button_up(controller_state, *buttons):
+async def button_release(controller_state, *buttons):
+    """
+    Set given buttons in the controller state to the unpressed state and wait till send.
+    :param controller_state:
+    :param buttons: Buttons to set to unpressed (see ButtonState.get_available_buttons)
+    """
     if not buttons:
         raise ValueError('No Buttons were given.')
 
@@ -211,14 +221,20 @@ async def button_up(controller_state, *buttons):
         # release button
         button_state.set_button(button, pushed=False)
 
-    # send report
+    # wait until report is send
     await controller_state.send()
 
 
 async def button_push(controller_state, *buttons, sec=0.1):
-    await button_down(controller_state, *buttons)
+    """
+    Shortly push the given buttons. Wait until the controller state is send.
+    :param controller_state:
+    :param buttons: Buttons to push (see ButtonState.get_available_buttons)
+    :param sec: Seconds to wait before releasing the button, default: 0.1
+    """
+    await button_press(controller_state, *buttons)
     await asyncio.sleep(sec)
-    await button_up(controller_state, *buttons)
+    await button_release(controller_state, *buttons)
 
 
 class _StickCalibration:

run_controller_cli.py

@@ -10,7 +10,7 @@ from aioconsole import ainput
 from joycontrol import logging_default as log, utils
 from joycontrol.command_line_interface import ControllerCLI
 from joycontrol.controller import Controller
-from joycontrol.controller_state import ControllerState, button_push, button_down, button_up
+from joycontrol.controller_state import ControllerState, button_push, button_press, button_release
 from joycontrol.memory import FlashMemory
 from joycontrol.protocol import controller_protocol_factory
 from joycontrol.server import create_hid_server
@@ -149,8 +149,21 @@ async def set_nfc(controller_state, file_path):
         controller_state.set_nfc(content)
 
 
+def ensure_valid_button(controller_state, *buttons):
+    """
+    Raise ValueError if any of the given buttons os not part of the controller state.
+    :param controller_state:
+    :param buttons: Any number of buttons to check (see ButtonState.get_available_buttons)
+    """
+    for button in buttons:
+        if button not in controller_state.button_state.get_available_buttons():
+            raise ValueError(f'Button {button} does not exist on {controller_state.get_controller()}')
+
+
 async def mash_button(controller_state, button, interval):
-    await ensure_valid_button(controller_state, button)
+    # wait until controller is fully connected
+    await controller_state.connect()
+    ensure_valid_button(controller_state, button)
 
     user_input = asyncio.ensure_future(
         ainput(prompt=f'Pressing the {button} button every {interval} seconds... Press <enter> to stop.')
@@ -164,24 +177,6 @@ async def mash_button(controller_state, button, interval):
     await user_input
 
 
-async def hold_button(controller_state, button):
-    await ensure_valid_button(controller_state, button)
-    await button_down(controller_state, button)
-
-
-async def release_button(controller_state, button):
-    await ensure_valid_button(controller_state, button)
-    await button_up(controller_state, button)
-
-
-async def ensure_valid_button(controller_state, button):
-    # waits until controller is fully connected
-    await controller_state.connect()
-
-    if button not in controller_state.button_state.get_available_buttons():
-        raise ValueError(f'Button {button} does not exist on {controller_state.get_controller()}')
-
-
 async def _main(args):
     # parse the spi flash
     if args.spi_flash:
@@ -237,15 +232,22 @@ async def _main(args):
         # Hold a button command
         async def hold(*args):
             """
-            hold - Press and hold a specified button
+            hold - Press and hold specified buttons
 
             Usage:
                 hold <button>
+
+            Example:
+                hold a b
             """
             if not args:
                 raise ValueError('"hold" command requires a button!')
 
-            await hold_button(controller_state, args[0])
+            ensure_valid_button(controller_state, *args)
+
+            # wait until controller is fully connected
+            await controller_state.connect()
+            await button_press(controller_state, *args)
 
         # add the script from above
         cli.add_command('hold', hold)
@@ -253,15 +255,22 @@ async def _main(args):
         # Release a button command
         async def release(*args):
             """
-            release - Release a held button
+            release - Release specified buttons
 
             Usage:
                 release <button>
+
+            Example:
+                release a b
             """
             if not args:
                 raise ValueError('"release" command requires a button!')
 
-            await release_button(controller_state, args[0])
+            ensure_valid_button(controller_state, *args)
+
+            # wait until controller is fully connected
+            await controller_state.connect()
+            await button_release(controller_state, *args)
 
         # add the script from above
         cli.add_command('release', release)
@@ -289,7 +298,6 @@ async def _main(args):
         cli.add_command('nfc', nfc)
         cli.add_command('amiibo', ControllerCLI.deprecated('Command is deprecated - use "nfc" instead!'))
 
-
         if args.nfc is not None:
             await nfc(args.nfc)