add generic arg validation routines; add interval args to keypad

Author: dhalbert

locale/circuitpython.pot

@@ -83,15 +83,22 @@ msgstr ""
 msgid "%q indices must be integers, not %s"
 msgstr ""
 
-#: shared-bindings/keypad/KeyMatrix.c shared-bindings/keypad/Keys.c
-#: shared-bindings/keypad/ShiftRegisterKeys.c
+#: py/argcheck.c
 msgid "%q length must be %q"
 msgstr ""
 
 #: shared-bindings/vectorio/Polygon.c
 msgid "%q list must be a list"
 msgstr ""
 
+#: py/argcheck.c
+msgid "%q must <= %d"
+msgstr ""
+
+#: py/argcheck.c
+msgid "%q must be %d-%d"
+msgstr ""
+
 #: shared-bindings/usb_hid/Device.c
 msgid "%q must be 0-255"
 msgstr ""
@@ -100,18 +107,17 @@ msgstr ""
 msgid "%q must be 1-255"
 msgstr ""
 
-#: shared-bindings/keypad/Event.c
-msgid "%q must be > 0"
+#: py/argcheck.c
+msgid "%q must be >= %d"
 msgstr ""
 
-#: shared-bindings/memorymonitor/AllocationAlarm.c
+#: py/argcheck.c shared-bindings/memorymonitor/AllocationAlarm.c
 msgid "%q must be >= 0"
 msgstr ""
 
 #: shared-bindings/_bleio/CharacteristicBuffer.c
 #: shared-bindings/_bleio/PacketBuffer.c shared-bindings/displayio/Group.c
-#: shared-bindings/displayio/Shape.c shared-bindings/keypad/KeyMatrix.c
-#: shared-bindings/keypad/Keys.c shared-bindings/keypad/ShiftRegisterKeys.c
+#: shared-bindings/displayio/Shape.c
 #: shared-bindings/memorymonitor/AllocationAlarm.c
 #: shared-bindings/vectorio/Circle.c shared-bindings/vectorio/Rectangle.c
 msgid "%q must be >= 1"
@@ -121,6 +127,10 @@ msgstr ""
 msgid "%q must be None or between 1 and len(report_descriptor)-1"
 msgstr ""
 
+#: py/argcheck.c
+msgid "%q must be a string"
+msgstr ""
+
 #: shared-module/vectorio/Polygon.c
 msgid "%q must be a tuple of length 2"
 msgstr ""
@@ -129,14 +139,17 @@ msgstr ""
 msgid "%q must be between %d and %d"
 msgstr ""
 
+#: py/argcheck.c
+msgid "%q must of type %q"
+msgstr ""
+
 #: shared-bindings/keypad/KeyMatrix.c shared-bindings/keypad/Keys.c
 #: shared-bindings/keypad/ShiftRegisterKeys.c
 msgid "%q must store bytes"
 msgstr ""
 
 #: ports/raspberrypi/common-hal/rp2pio/StateMachine.c
-#: shared-bindings/canio/Match.c shared-bindings/keypad/KeyMatrix.c
-#: shared-bindings/keypad/Keys.c shared-bindings/keypad/ShiftRegisterKeys.c
+#: shared-bindings/canio/Match.c
 msgid "%q out of range"
 msgstr ""
 
@@ -953,10 +966,6 @@ msgstr ""
 msgid "Expected a UUID"
 msgstr ""
 
-#: shared-bindings/keypad/EventQueue.c
-msgid "Expected an %q"
-msgstr ""
-
 #: shared-bindings/_bleio/Adapter.c
 msgid "Expected an Address"
 msgstr ""

py/argcheck.c

@@ -162,3 +162,54 @@ NORETURN void mp_arg_error_unimpl_kw(void) {
     mp_raise_NotImplementedError(MP_ERROR_TEXT("keyword argument(s) not yet implemented - use normal args instead"));
 }
 #endif
+
+
+mp_int_t mp_arg_validate_int_min(mp_int_t i, mp_int_t min, qstr arg_name) {
+    if (i < min) {
+        mp_raise_ValueError_varg(translate("%q must be >= %d"), arg_name, min);
+    }
+    return i;
+}
+
+mp_int_t mp_arg_validate_int_max(mp_int_t i, mp_int_t max, qstr arg_name) {
+    if (i > max) {
+        mp_raise_ValueError_varg(translate("%q must <= %d"), arg_name, max);
+    }
+    return i;
+}
+
+mp_int_t mp_arg_validate_int_range(mp_int_t i, mp_int_t min, mp_int_t max, qstr arg_name) {
+    if (i < min || i > max) {
+        mp_raise_ValueError_varg(translate("%q must be %d-%d"), arg_name, min, max);
+    }
+    return i;
+}
+
+mp_float_t mp_arg_validate_obj_float_non_negative(mp_obj_t float_in, mp_float_t default_for_null, qstr arg_name) {
+    const mp_float_t f = (float_in == MP_OBJ_NULL)
+        ? default_for_null
+        : mp_obj_get_float(float_in);
+    if (f <= 0.0f) {
+        mp_raise_ValueError_varg(translate("%q must be >= 0"), arg_name);
+    }
+    return f;
+}
+
+size_t mp_arg_validate_length_with_name(mp_int_t i, size_t length, qstr arg_name, qstr length_name) {
+    mp_raise_ValueError_varg(translate("%q length must be %q"), MP_QSTR_pressed, MP_QSTR_num_keys);
+    return (size_t)i;
+}
+
+mp_obj_t mp_arg_validate_type(mp_obj_t obj, const mp_obj_type_t *type, qstr arg_name) {
+    if (!mp_obj_is_type(obj, type)) {
+        mp_raise_TypeError_varg(translate("%q must of type %q"), arg_name, type->name);
+    }
+    return obj;
+}
+
+mp_obj_t mp_arg_validate_string(mp_obj_t obj, qstr arg_name) {
+    if (!mp_obj_is_str(obj)) {
+        mp_raise_TypeError_varg(translate("%q must be a string"), arg_name);
+    }
+    return obj;
+}

py/runtime.h

@@ -90,6 +90,14 @@ void mp_arg_parse_all_kw_array(size_t n_pos, size_t n_kw, const mp_obj_t *args,
 NORETURN void mp_arg_error_terse_mismatch(void);
 NORETURN void mp_arg_error_unimpl_kw(void);
 
+mp_int_t mp_arg_validate_int_min(mp_int_t i, mp_int_t min, qstr arg_name);
+mp_int_t mp_arg_validate_int_max(mp_int_t i, mp_int_t j, qstr arg_name);
+mp_int_t mp_arg_validate_int_range(mp_int_t i, mp_int_t min, mp_int_t max, qstr arg_name);
+mp_float_t mp_arg_validate_obj_float_non_negative(mp_obj_t float_in, mp_float_t default_for_null, qstr arg_name);
+size_t mp_arg_validate_length_with_name(mp_int_t i, size_t length, qstr arg_name, qstr length_name);
+mp_obj_t mp_arg_validate_type(mp_obj_t obj, const mp_obj_type_t *type, qstr arg_name);
+mp_obj_t mp_arg_validate_string(mp_obj_t obj, qstr arg_name);
+
 static inline mp_obj_dict_t *PLACE_IN_ITCM(mp_locals_get)(void) {
     return MP_STATE_THREAD(dict_locals);
 }

shared-bindings/keypad/Event.c

@@ -52,12 +52,9 @@ STATIC mp_obj_t keypad_event_make_new(const mp_obj_type_t *type, size_t n_args,
     mp_arg_val_t args[MP_ARRAY_SIZE(allowed_args)];
     mp_arg_parse_all(n_args, pos_args, kw_args, MP_ARRAY_SIZE(allowed_args), allowed_args, args);
 
-    const mp_int_t key_num = args[ARG_key_num].u_int;
-    if (key_num < 0) {
-        mp_raise_ValueError_varg(translate("%q must be > 0"), MP_QSTR_key_num);
-    }
+    const mp_uint_t key_num = (mp_uint_t)mp_arg_validate_int_min(args[ARG_key_num].u_int, 0, MP_QSTR_key_num);
 
-    common_hal_keypad_event_construct(self, (mp_uint_t)key_num, args[ARG_pressed].u_bool);
+    common_hal_keypad_event_construct(self, key_num, args[ARG_pressed].u_bool);
     return MP_OBJ_FROM_PTR(self);
 }
 

shared-bindings/keypad/EventQueue.c

@@ -75,10 +75,8 @@ MP_DEFINE_CONST_FUN_OBJ_1(keypad_eventqueue_next_obj, keypad_eventqueue_next);
 STATIC mp_obj_t keypad_eventqueue_store_next(mp_obj_t self_in, mp_obj_t event_in) {
     keypad_eventqueue_obj_t *self = MP_OBJ_TO_PTR(self_in);
 
-    if (!mp_obj_is_type(event_in, &keypad_event_type)) {
-        mp_raise_ValueError_varg(translate("Expected an %q"), MP_QSTR_Event);
-    }
-    keypad_event_obj_t *event = MP_OBJ_TO_PTR(event_in);
+    keypad_event_obj_t *event = MP_OBJ_TO_PTR(mp_arg_validate_type(event_in, &keypad_event_type, MP_QSTR_event));
+
     return mp_obj_new_bool(common_hal_keypad_eventqueue_store_next(self, event));
 }
 MP_DEFINE_CONST_FUN_OBJ_2(keypad_eventqueue_store_next_obj, keypad_eventqueue_store_next);

shared-bindings/keypad/KeyMatrix.c

@@ -36,7 +36,7 @@
 //| class KeyMatrix:
 //|     """Manage a 2D matrix of keys with row and column pins."""
 //|
-//|     def __init__(self, row_pins: Sequence[microcontroller.Pin], col_pins: Sequence[microcontroller.Pin], columns_to_anodes: bool = True, max_events: int = 64) -> None:
+//|     def __init__(self, row_pins: Sequence[microcontroller.Pin], col_pins: Sequence[microcontroller.Pin], columns_to_anodes: bool = True, interval: float = 0.020, max_events: int = 64) -> None:
 //|         """
 //|         Create a `Keys` object that will scan the key matrix attached to the given row and column pins.
 //|         There should not be any pull-ups or pull-downs on the matrix.
@@ -54,7 +54,8 @@
 //|           If the matrix uses diodes, the diode anodes are typically connected to the column pins,
 //|           and the cathodes should be connected to the row pins. If your diodes are reversed,
 //|           set ``columns_to_anodes`` to ``False``.
-//|
+//|         :param float interval: Scan keys no more often
+//|           to allow for debouncing. Given in seconds.
 //|         :param int max_events: maximum size of `events` `EventQueue`:
 //|           maximum number of key transition events that are saved.
 //|           Must be >= 1.
@@ -65,11 +66,12 @@
 STATIC mp_obj_t keypad_keymatrix_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) {
     keypad_keymatrix_obj_t *self = m_new_obj(keypad_keymatrix_obj_t);
     self->base.type = &keypad_keymatrix_type;
-    enum { ARG_row_pins, ARG_col_pins, ARG_columns_to_anodes, ARG_max_events };
+    enum { ARG_row_pins, ARG_col_pins, ARG_columns_to_anodes, ARG_interval, ARG_max_events };
     static const mp_arg_t allowed_args[] = {
         { MP_QSTR_row_pins, MP_ARG_REQUIRED | MP_ARG_OBJ },
         { MP_QSTR_col_pins, MP_ARG_REQUIRED | MP_ARG_OBJ },
         { MP_QSTR_columns_to_anodes, MP_ARG_KW_ONLY | MP_ARG_BOOL, {.u_bool = true} },
+        { MP_QSTR_interval, MP_ARG_KW_ONLY | MP_ARG_OBJ, {.u_obj = MP_OBJ_NULL} },
         { MP_QSTR_max_events, MP_ARG_KW_ONLY | MP_ARG_INT, {.u_int = 64} },
     };
     mp_arg_val_t args[MP_ARRAY_SIZE(allowed_args)];
@@ -82,10 +84,9 @@ STATIC mp_obj_t keypad_keymatrix_make_new(const mp_obj_type_t *type, size_t n_ar
     mp_obj_t col_pins = args[ARG_col_pins].u_obj;
     const size_t num_col_pins = (size_t)MP_OBJ_SMALL_INT_VALUE(mp_obj_len(col_pins));
 
-    if (args[ARG_max_events].u_int < 1) {
-        mp_raise_ValueError_varg(translate("%q must be >= 1"), MP_QSTR_max_events);
-    }
-    const size_t max_events = (size_t)args[ARG_max_events].u_int;
+    const mp_float_t interval =
+        mp_arg_validate_obj_float_non_negative(args[ARG_interval].u_obj, 0.020f, MP_QSTR_interval);
+    const size_t max_events = (size_t)mp_arg_validate_int_min(args[ARG_max_events].u_int, 1, MP_QSTR_max_events);
 
     mcu_pin_obj_t *row_pins_array[num_row_pins];
     mcu_pin_obj_t *col_pins_array[num_col_pins];
@@ -102,7 +103,7 @@ STATIC mp_obj_t keypad_keymatrix_make_new(const mp_obj_type_t *type, size_t n_ar
         col_pins_array[col] = pin;
     }
 
-    common_hal_keypad_keymatrix_construct(self, num_row_pins, row_pins_array, num_col_pins, col_pins_array, args[ARG_columns_to_anodes].u_bool, max_events);
+    common_hal_keypad_keymatrix_construct(self, num_row_pins, row_pins_array, num_col_pins, col_pins_array, args[ARG_columns_to_anodes].u_bool, interval, max_events);
     return MP_OBJ_FROM_PTR(self);
 }
 
@@ -168,18 +169,14 @@ STATIC mp_obj_t keypad_keymatrix_key_num(mp_obj_t self_in, mp_obj_t row_in, mp_o
     keypad_keymatrix_obj_t *self = MP_OBJ_TO_PTR(self_in);
     check_for_deinit(self);
 
-    const mp_int_t row = mp_obj_get_int(row_in);
-    if (row < 0 || (size_t)row >= common_hal_keypad_keymatrix_get_num_rows(self)) {
-        mp_raise_ValueError_varg(translate("%q out of range"), MP_QSTR_row_num);
-    }
+    const mp_uint_t row = (mp_uint_t)mp_arg_validate_int_range(
+        mp_obj_get_int(row_in), 0, (mp_int_t)common_hal_keypad_keymatrix_get_num_rows(self), MP_QSTR_row);
 
-    const mp_int_t col = mp_obj_get_int(col_in);
-    if (col < 0 || (size_t)col >= common_hal_keypad_keymatrix_get_num_cols(self)) {
-        mp_raise_ValueError_varg(translate("%q out of range"), MP_QSTR_col_num);
-    }
+    const mp_int_t col = (mp_uint_t)mp_arg_validate_int_range(
+        mp_obj_get_int(col_in), 0, (mp_int_t)common_hal_keypad_keymatrix_get_num_cols(self), MP_QSTR_col);
 
     return MP_OBJ_NEW_SMALL_INT(
-        (mp_int_t)common_hal_keypad_keymatrix_key_num(self, (mp_uint_t)row, (mp_uint_t)col));
+        (mp_int_t)common_hal_keypad_keymatrix_key_num(self, row, col));
 }
 MP_DEFINE_CONST_FUN_OBJ_3(keypad_keymatrix_key_num_obj, keypad_keymatrix_key_num);
 
@@ -193,10 +190,8 @@ STATIC mp_obj_t keypad_keymatrix_pressed(mp_obj_t self_in, mp_obj_t key_num_in)
     keypad_keymatrix_obj_t *self = MP_OBJ_TO_PTR(self_in);
     check_for_deinit(self);
 
-    mp_int_t key_num = mp_obj_get_int(key_num_in);
-    if (key_num < 0 || (size_t)key_num >= common_hal_keypad_keymatrix_get_num_keys(self)) {
-        mp_raise_ValueError_varg(translate("%q out of range"), MP_QSTR_key_num);
-    }
+    mp_uint_t key_num = mp_arg_validate_int_range(
+        mp_obj_get_int(key_num_in), 0, (mp_int_t)common_hal_keypad_keymatrix_get_num_keys(self), MP_QSTR_key_num);
 
     return mp_obj_new_bool(common_hal_keypad_keymatrix_pressed(self, (mp_uint_t)key_num));
 }
@@ -220,9 +215,9 @@ STATIC mp_obj_t keypad_keymatrix_store_states(mp_obj_t self_in, mp_obj_t pressed
     if (bufinfo.typecode != 'b' && bufinfo.typecode != 'B' && bufinfo.typecode != BYTEARRAY_TYPECODE) {
         mp_raise_ValueError_varg(translate("%q must store bytes"), MP_QSTR_states);
     }
-    if (bufinfo.len != common_hal_keypad_keymatrix_get_num_keys(self)) {
-        mp_raise_ValueError_varg(translate("%q length must be %q"), MP_QSTR_states, MP_QSTR_num_keys);
-    }
+
+    (void)mp_arg_validate_length_with_name(bufinfo.len, common_hal_keypad_keymatrix_get_num_keys(self),
+        MP_QSTR_states, MP_QSTR_num_keys);
 
     common_hal_keypad_keymatrix_store_states(self, (uint8_t *)bufinfo.buf);
     return MP_ROM_NONE;

shared-bindings/keypad/KeyMatrix.h

@@ -32,7 +32,7 @@
 
 extern const mp_obj_type_t keypad_keymatrix_type;
 
-void common_hal_keypad_keymatrix_construct(keypad_keymatrix_obj_t *self, mp_uint_t num_row_pins, mcu_pin_obj_t *row_pins[], mp_uint_t num_col_pins, mcu_pin_obj_t *col_pins[], bool columns_to_anodes, size_t max_events);
+void common_hal_keypad_keymatrix_construct(keypad_keymatrix_obj_t *self, mp_uint_t num_row_pins, mcu_pin_obj_t *row_pins[], mp_uint_t num_col_pins, mcu_pin_obj_t *col_pins[], bool columns_to_anodes, mp_float_t interval, size_t max_events);
 
 void common_hal_keypad_keymatrix_deinit(keypad_keymatrix_obj_t *self);
 bool common_hal_keypad_keymatrix_deinited(keypad_keymatrix_obj_t *self);

shared-bindings/keypad/Keys.c

@@ -36,7 +36,7 @@
 //| class Keys:
 //|     """Manage a set of independent keys."""
 //|
-//|     def __init__(self, pins: Sequence[microcontroller.Pin], *, level_when_pressed: bool, pull: bool = True, max_events: int = 64) -> None:
+//|     def __init__(self, pins: Sequence[microcontroller.Pin], *, level_when_pressed: bool, pull: bool = True, interval: float = 0.020, max_events: int = 64) -> None:
 //|         """
 //|         Create a `Keys` object that will scan keys attached to the given sequence of pins.
 //|         Each key is independent and attached to its own pin.
@@ -56,6 +56,8 @@
 //|           If an external pull is already provided for all the pins, you can set ``pull`` to ``False``.
 //|           However, enabling an internal pull when an external one is already present is not a problem;
 //|           it simply uses slightly more current.
+//|         :param float interval: Scan keys no more often
+//|           to allow for debouncing. Given in seconds.
 //|         :param int max_events: maximum size of `events` `EventQueue`:
 //|           maximum number of key transition events that are saved.
 //|           Must be >= 1.
@@ -66,11 +68,12 @@
 STATIC mp_obj_t keypad_keys_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) {
     keypad_keys_obj_t *self = m_new_obj(keypad_keys_obj_t);
     self->base.type = &keypad_keys_type;
-    enum { ARG_pins, ARG_value_when_pressed, ARG_pull, ARG_max_events };
+    enum { ARG_pins, ARG_value_when_pressed, ARG_pull, ARG_interval, ARG_max_events };
     static const mp_arg_t allowed_args[] = {
         { MP_QSTR_pins, MP_ARG_REQUIRED | MP_ARG_OBJ },
         { MP_QSTR_value_when_pressed, MP_ARG_REQUIRED | MP_ARG_KW_ONLY | MP_ARG_BOOL },
         { MP_QSTR_pull, MP_ARG_KW_ONLY | MP_ARG_BOOL, {.u_bool = true} },
+        { MP_QSTR_interval, MP_ARG_KW_ONLY | MP_ARG_OBJ, {.u_obj = MP_OBJ_NULL } },
         { MP_QSTR_max_events, MP_ARG_KW_ONLY | MP_ARG_INT, {.u_int = 64} },
     };
     mp_arg_val_t args[MP_ARRAY_SIZE(allowed_args)];
@@ -81,11 +84,9 @@ STATIC mp_obj_t keypad_keys_make_new(const mp_obj_type_t *type, size_t n_args, c
     const size_t num_pins = (size_t)MP_OBJ_SMALL_INT_VALUE(mp_obj_len(pins));
 
     const bool value_when_pressed = args[ARG_value_when_pressed].u_bool;
-
-    if (args[ARG_max_events].u_int < 1) {
-        mp_raise_ValueError_varg(translate("%q must be >= 1"), MP_QSTR_max_events);
-    }
-    const size_t max_events = (size_t)args[ARG_max_events].u_int;
+    const mp_float_t interval =
+        mp_arg_validate_obj_float_non_negative(args[ARG_interval].u_obj, 0.020f, MP_QSTR_interval);
+    const size_t max_events = (size_t)mp_arg_validate_int_min(args[ARG_max_events].u_int, 1, MP_QSTR_max_events);
 
     mcu_pin_obj_t *pins_array[num_pins];
 
@@ -95,7 +96,7 @@ STATIC mp_obj_t keypad_keys_make_new(const mp_obj_type_t *type, size_t n_args, c
         pins_array[i] = pin;
     }
 
-    common_hal_keypad_keys_construct(self, num_pins, pins_array, value_when_pressed, args[ARG_pull].u_bool, max_events);
+    common_hal_keypad_keys_construct(self, num_pins, pins_array, value_when_pressed, args[ARG_pull].u_bool, interval, max_events);
 
     return MP_OBJ_FROM_PTR(self);
 }
@@ -163,10 +164,8 @@ STATIC mp_obj_t keypad_keys_pressed(mp_obj_t self_in, mp_obj_t key_num_in) {
     keypad_keys_obj_t *self = MP_OBJ_TO_PTR(self_in);
     check_for_deinit(self);
 
-    mp_int_t key_num = mp_obj_get_int(key_num_in);
-    if (key_num < 0 || (size_t)key_num >= common_hal_keypad_keys_get_num_keys(self)) {
-        mp_raise_ValueError_varg(translate("%q out of range"), MP_QSTR_key_num);
-    }
+    const mp_int_t key_num = mp_obj_get_int(key_num_in);
+    (void)mp_arg_validate_int_range(key_num, 0, common_hal_keypad_keys_get_num_keys(self), MP_QSTR_key_num);
 
     return mp_obj_new_bool(common_hal_keypad_keys_pressed(self, (mp_uint_t)key_num));
 }
@@ -190,9 +189,8 @@ STATIC mp_obj_t keypad_keys_store_states(mp_obj_t self_in, mp_obj_t pressed) {
     if (bufinfo.typecode != 'b' && bufinfo.typecode != 'B' && bufinfo.typecode != BYTEARRAY_TYPECODE) {
         mp_raise_ValueError_varg(translate("%q must store bytes"), MP_QSTR_pressed);
     }
-    if (bufinfo.len != common_hal_keypad_keys_get_num_keys(self)) {
-        mp_raise_ValueError_varg(translate("%q length must be %q"), MP_QSTR_pressed, MP_QSTR_num_keys);
-    }
+    (void)mp_arg_validate_length_with_name(bufinfo.len,common_hal_keypad_keys_get_num_keys(self),
+        MP_QSTR_pressed, MP_QSTR_num_keys);
 
     common_hal_keypad_keys_store_states(self, (uint8_t *)bufinfo.buf);
     return MP_ROM_NONE;

shared-bindings/keypad/Keys.h

@@ -32,7 +32,7 @@
 
 extern const mp_obj_type_t keypad_keys_type;
 
-void common_hal_keypad_keys_construct(keypad_keys_obj_t *self, mp_uint_t num_pins, mcu_pin_obj_t *pins[], bool value_when_pressed,  bool pull, size_t max_events);
+void common_hal_keypad_keys_construct(keypad_keys_obj_t *self, mp_uint_t num_pins, mcu_pin_obj_t *pins[], bool value_when_pressed,  bool pull, mp_float_t interval, size_t max_events);
 
 void common_hal_keypad_keys_deinit(keypad_keys_obj_t *self);
 bool common_hal_keypad_keys_deinited(keypad_keys_obj_t *self);