Release version 3.0.0 (#15)

* Added constants to `ButtonInput` for parameter `action`.

Closes #11

* Updated the documentation to version 3.0.0

Resolves #12

* Tested and finalised version 3.0.0

Author: EGJ-Moorington

button_handler.py

@@ -41,7 +41,7 @@ def ticks_ms() -> int:
 except ImportError:
     pass
 
-__version__ = "2.0.0"
+__version__ = "3.0.0"
 __repo__ = "https://github.com/EGJ-Moorington/CircuitPython_Button_Handler.git"
 
 _TICKS_PERIOD = 1 << 29
@@ -73,22 +73,22 @@ def __init__(
     ) -> None:
         """
         :param bool enable_multi_press: Sets :attr:`.enable_multi_press`
-            (whether to track multi presses).
+            (whether to track multi-presses).
         :param float multi_press_interval: Sets :attr:`.multi_press_interval`
-            (the time frame within which two presses should occur to count as a multi press).
+            (the time frame within which two presses should occur to count as a multi-press).
         :param float long_press_threshold: Sets :attr:`.long_press_threshold`
             (the minimum length of a press to count as a long press).
         :param int max_multi_press: Sets :attr:`.max_multi_press`
-            (the maximum amount of presses a multi press can have).
+            (the maximum amount of presses a multi-press can have).
 
         .. attribute:: enable_multi_press
             :type: bool
             :value: enable_multi_press = True
 
             Whether to account for the possibility of another short press
-            following a short press and counting as a multi press.
+            following a short press and counting as a multi-press.
             If set to false, :meth:`ButtonHandler.update`
-            returns ``SHORT_PRESS`` immediately after a short press.
+            returns a short press :class:`ButtonInput` object immediately after a short press.
 
         .. attribute:: long_press_threshold
             :type: float
@@ -101,16 +101,16 @@ def __init__(
             :type: int
             :value: max_multi_press = 2
 
-            The maximum amount of button presses that a multi press can be.
-            :meth:`ButtonHandler.update` returns the appropiate ``_MULTI_PRESS`` immediaetly after
-            the button has been pressed this many times.
+            The maximum amount of button presses that a multi-press can be.
+            :meth:`ButtonHandler.update` returns the appropiate multi-press :class:`ButtonInput`
+            object immediaetly after the button has been pressed this many times.
 
         .. attribute:: multi_press_interval
             :type: float
             :value: multi_press_interval = 175
 
             The time frame from a button release within which
-            another release should occur to count as a multi press.
+            another release should occur to count as a multi-press.
         """
         self.enable_multi_press = enable_multi_press
         self.long_press_threshold = long_press_threshold
@@ -137,8 +137,9 @@ def __init__(
             :value: config.enable_multi_press = True
 
             Whether to account for the possibility of another short press
-            following a short press and counting that as a multi press. If set to false,
-            :meth:`ButtonHandler.update` returns ``SHORT_PRESS`` immediately after a short press.
+            following a short press and counting that as a multi-press. If set to false,
+            :meth:`ButtonHandler.update` returns a short press :class:`ButtonInput`
+            object immediately after a short press.
 
         .. attribute:: long_press_threshold
             :type: float
@@ -151,16 +152,16 @@ def __init__(
             :type: int
             :value: config.max_multi_press = 2
 
-            The maximum amount of button presses that a multi press can be.
-            :meth:`ButtonHandler.update` returns the appropiate ``_MULTI_PRESS`` immediaetly after
-            the button has been pressed this many times.
+            The maximum amount of button presses that a multi-press can be.
+            :meth:`ButtonHandler.update` returns the appropiate multi-press :class:`ButtonInput`
+            object immediaetly after the button has been pressed this many times.
 
         .. attribute:: multi_press_interval
             :type: float
             :value: config.multi_press_interval = 175
 
             The time frame from a button release within which
-            another release should occur to count as a multi press.
+            another release should occur to count as a multi-press.
 
         .. caution:: Attributes with a *leading underscore (_)* are meant for **internal use only**,
             and accessing them may cause **unexpected behaviour**. Please consider accessing
@@ -192,15 +193,15 @@ def __init__(
             :value: None
 
             The time (in miliseconds, tracked by :meth:`supervisor.ticks_ms`) that has passed since
-            the start of the previous press of a multi press. It is set to :type:`None`
+            the start of the previous press of a multi-press. It is set to :type:`None`
             after the time specified by :attr:`.multi_press_interval` has passed.
 
         .. attribute:: _press_count
             :type: int
             :value: 0
 
             The amount of times the button has been pressed since the last
-            multi press ended. It is set to 0 if the time set
+            multi-press ended. It is set to 0 if the time set
             by :attr:`.multi_press_interval` passes after a short press.
 
         .. attribute:: _press_start_time
@@ -257,12 +258,12 @@ def _check_multi_press_timeout(self, current_time: int) -> Union[int, None]:
         .. caution:: Methods with a *leading underscore (_)* are meant for **internal use only**,
             and calling them may cause **unexpected behaviour**. Please refrain from using them.
 
-        Check whether a multi press has ended.
-        If it has, return the amount of times the button was pressed in that multi press.
+        Check whether a multi-press has ended.
+        If it has, return the amount of times the button was pressed in that multi-press.
 
         :param int current_time: The current time, provided by :meth:`supervisor.ticks_ms`.
-        :return: The amount of times the button was pressed in a multi press,
-            if a multi press has ended.
+        :return: The amount of times the button was pressed in a multi-press,
+            if a multi-press has ended.
         :rtype: int or None
         """
         if (
@@ -301,9 +302,14 @@ def _is_held(self, current_time: int) -> bool:
 class ButtonInput:
     """Defines a button's input's characteristics."""
 
+    SHORT_PRESS = 1
+    DOUBLE_PRESS = 2
+    HOLD = "H"
+    LONG_PRESS = "L"
+
     def __init__(
         self,
-        action: Union[Literal["SHORT_PRESS", "LONG_PRESS", "HOLD", "DOUBLE_PRESS"], str],
+        action: Union[int, str],
         button_number: int = 0,
         callback: Callable[[], None] = lambda: None,
         timestamp: int = 0,
@@ -317,7 +323,13 @@ def __init__(
         :param int timestamp: Sets :attr:`timestamp` (the time at which the input was performed).
 
         .. type:: InputAction
-            :canonical: Literal["SHORT_PRESS", "LONG_PRESS", "HOLD", "DOUBLE_PRESS"] | str
+            :canonical: int | str
+
+            Represents the action the :class:`ButtonInput` object represents.
+            Using a constant defined by :class:`ButtonInput` when available is recommended.
+            To represent a multi-press, use the number of presses in that multi-press.
+            Available constants are :const:`SHORT_PRESS`, :const:`DOUBLE_PRESS`,
+            :const:`HOLD` and :const:`LONG_PRESS`.
 
         .. attribute:: button_number
             :type: int
@@ -339,6 +351,37 @@ def __init__(
             The timestamp (in milliseconds, provided by :meth:`supervisor.ticks_ms`)
             at which the input was performed.
 
+        .. warning:: Variables written in *upper case with underscores* are constants and
+            should not be modified. Doing so may cause **unexpected behaviour**.
+
+        .. data:: SHORT_PRESS
+            :type: int
+            :value: 1
+
+            Represents a short press to pass as an argument to
+            parameter `action` in :class:`ButtonInput`.
+
+        .. data:: DOUBLE_PRESS
+            :type: int
+            :value: 2
+
+            Represents a double press to pass as an argument to
+            parameter `action` in :class:`ButtonInput`.
+
+        .. data:: HOLD
+            :type: str
+            :value: "H"
+
+            Represents a hold action to pass as an argument to
+            parameter `action` in :class:`ButtonInput`.
+
+        .. data:: LONG_PRESS
+            :type: str
+            :value: "L"
+
+            Represents a long press to pass as an argument to
+            parameter `action` in :class:`ButtonInput`.
+
         .. caution:: Attributes with a *leading underscore (_)* are meant for
             **internal use only**, and accessing them may cause **unexpected behaviour**.
             Please consider accessing a *property* (if available) instead.
@@ -361,31 +404,23 @@ def action(self):
 
         :type: InputAction
         :param InputAction action: The action associated with the input.
-        :raise ValueError: if action is not a valid action. Valid actions are ``LONG_PRESS``,
-            ``HOLD``, ``SHORT_PRESS`` (exactly the same as ``1_MULTI_PRESS``),
-            ``DOUBLE_PRESS`` (exactly the same as ``2_MULTI_PRESS``) and
-            ``x_MULTI_PRESS`` where x is an :type:`int` bigger than 0.
+        :raise ValueError: if *action* is not a valid action. Valid actions are
+            :const:`SHORT_PRESS`, :const:`DOUBLE_PRESS`, :const:`HOLD`, :const:`LONG_PRESS`
+            and any :type:`int` bigger than 0.
 
         """
         return self._action
 
     @action.setter
-    def action(
-        self, action: Union[Literal["SHORT_PRESS", "LONG_PRESS", "HOLD", "DOUBLE_PRESS"], str]
-    ):
-        if action in {"SHORT_PRESS", "LONG_PRESS", "HOLD"}:
+    def action(self, action: Union[int, str]):
+        if action in {ButtonInput.LONG_PRESS, ButtonInput.HOLD}:
             self._action = action
             return
         try:
-            if action == "DOUBLE_PRESS":
-                action = "2_MULTI_PRESS"
-            if not action.endswith("_MULTI_PRESS"):
+            if not isinstance(action, int):
                 raise ValueError
-            num = int(action.split("_")[0])
-            if num < 1:
+            if action < 1:
                 raise ValueError
-            if num == 1:
-                action = "SHORT_PRESS"
             self._action = action
         except ValueError:
             raise ValueError(f"Invalid action: {action}.")
@@ -446,15 +481,15 @@ def __init__(
         :param keypad.EventQueue event_queue: Sets :attr:`_event_queue`
             (the :class:`keypad.EventQueue` object the handler should read events from).
         :param set[ButtonInput] callable_inputs: Sets :attr:`callable_inputs`
-            (the :class:`ButtonInitConfig` objects used to define the callback functions).
+            (the :class:`ButtonInput` objects used to define the callback functions).
         :param int button_amount: The amount of buttons scanned by the :mod:`keypad` scanner
-            that created the event_queue parameter's argument :class:`keypad.EventQueue` object.
+            that created the *event_queue* parameter's argument :class:`keypad.EventQueue` object.
         :param dict[int, ButtonInitConfig] config: A dictionary containing
             :class:`ButtonInitConfig` objects used to initialise :class:`Button` objects.
             The dictionary's keys should be the index numbers of the target buttons.
             For each button that doesn't have a :class:`ButtonInitConfig` attached to it, an object
             containing the default values is created.
-        :raise ValueError: if *button_amount* is smaller than 1, or if it is not an :type:`int`..
+        :raise ValueError: if *button_amount* is smaller than 1, or if it is not an :type:`int`.
 
         .. attribute:: callable_inputs
             :type: set[ButtonInput]
@@ -507,7 +542,7 @@ def buttons(self) -> list[Button]:
 
     def update(self) -> set[ButtonInput]:
         """
-        Check if any button ended a multi press since the last time this method was called,
+        Check if any button ended a multi-press since the last time this method was called,
         process the next :class:`keypad.Event` in :attr:`_event_queue`, call all the relevant
         callback functions and return a set of the detected :class:`ButtonInput`\\ s.
 
@@ -553,7 +588,7 @@ def _handle_buttons(self) -> set[ButtonInput]:
             and calling them may cause **unexpected behaviour**. Please refrain from using them.
 
         Check if any button began being held down since the last time this mehod was called
-        and if any multi press ended, and return every detected :class:`ButtonInput`.
+        and if any multi-press ended, and return every detected :class:`ButtonInput`.
 
         :return: A set containing every detected :class:`ButtonInput`.
         :rtype: set[ButtonInput]
@@ -562,15 +597,13 @@ def _handle_buttons(self) -> set[ButtonInput]:
         current_time = ticks_ms()
         for button in self._buttons:
             if button._is_held(current_time):
-                inputs.add(ButtonInput("HOLD", button.button_number, timestamp=current_time))
+                inputs.add(
+                    ButtonInput(ButtonInput.HOLD, button.button_number, timestamp=current_time)
+                )
             else:
                 num = button._check_multi_press_timeout(current_time)
                 if num:
-                    inputs.add(
-                        ButtonInput(
-                            f"{num}_MULTI_PRESS", button.button_number, timestamp=current_time
-                        )
-                    )
+                    inputs.add(ButtonInput(num, button.button_number, timestamp=current_time))
         return inputs
 
     def _handle_event(self, event: Event) -> Union[ButtonInput, None]:
@@ -598,17 +631,21 @@ def _handle_event(self, event: Event) -> Union[ButtonInput, None]:
                 < button.long_press_threshold
             ):  # Short press
                 if not button.enable_multi_press:
-                    input_ = ButtonInput("SHORT_PRESS", event.key_number, timestamp=event.timestamp)
+                    input_ = ButtonInput(
+                        ButtonInput.SHORT_PRESS, event.key_number, timestamp=event.timestamp
+                    )
                 elif button._press_count == button.max_multi_press:
                     input_ = ButtonInput(
-                        f"{button.max_multi_press}_MULTI_PRESS",
+                        button.max_multi_press,
                         event.key_number,
                         timestamp=event.timestamp,
                     )
                 else:  # More short presses could follow
                     return None
             else:
-                input_ = ButtonInput("LONG_PRESS", event.key_number, timestamp=event.timestamp)
+                input_ = ButtonInput(
+                    ButtonInput.LONG_PRESS, event.key_number, timestamp=event.timestamp
+                )
                 button._is_holding = False
             button._last_press_time = None
             button._press_count = 0

examples/button_handler_doublebutton.py

@@ -102,14 +102,14 @@ def long_press_1_holding_0():
 config = ButtonInitConfig(max_multi_press=3)
 scanner = Keys([board.D9, board.A2], value_when_pressed=False)
 callback_inputs = {
-    ButtonInput("DOUBLE_PRESS", 0, double_press_0),
-    ButtonInput("DOUBLE_PRESS", 1, double_press_1),
-    ButtonInput("3_MULTI_PRESS", 0, triple_press_0),
-    ButtonInput("3_MULTI_PRESS", 1, triple_press_1),
-    ButtonInput("SHORT_PRESS", 0, short_press_0),
-    ButtonInput("SHORT_PRESS", 1, short_press_1),
-    ButtonInput("LONG_PRESS", 0, long_press_0),
-    ButtonInput("LONG_PRESS", 1, long_press_1),
+    ButtonInput(ButtonInput.DOUBLE_PRESS, 0, double_press_0),
+    ButtonInput(ButtonInput.DOUBLE_PRESS, 1, double_press_1),
+    ButtonInput(3, 0, triple_press_0),
+    ButtonInput(3, 1, triple_press_1),
+    ButtonInput(ButtonInput.SHORT_PRESS, 0, short_press_0),
+    ButtonInput(ButtonInput.SHORT_PRESS, 1, short_press_1),
+    ButtonInput(ButtonInput.LONG_PRESS, 0, long_press_0),
+    ButtonInput(ButtonInput.LONG_PRESS, 1, long_press_1),
 }
 button_handler = ButtonHandler(scanner.events, callback_inputs, 2, {0: config, 1: config})
 

examples/button_handler_singlebutton.py

@@ -8,7 +8,7 @@
 import board
 from keypad import Keys
 
-from button_handler import ButtonHandler, ButtonInput
+from button_handler import ButtonHandler, ButtonInitConfig, ButtonInput
 
 
 def double_press():
@@ -28,10 +28,10 @@ def hold():
 
 
 actions = {
-    ButtonInput("DOUBLE_PRESS", callback=double_press),
-    ButtonInput("SHORT_PRESS", callback=short_press),
-    ButtonInput("LONG_PRESS", callback=long_press),
-    ButtonInput("HOLD", callback=hold),
+    ButtonInput(ButtonInput.DOUBLE_PRESS, callback=double_press),
+    ButtonInput(ButtonInput.SHORT_PRESS, callback=short_press),
+    ButtonInput(ButtonInput.LONG_PRESS, callback=long_press),
+    ButtonInput(ButtonInput.HOLD, callback=hold),
 }
 
 scanner = Keys([board.D9], value_when_pressed=False)