Feat/optional python (#2)

* feat: make python bindings optional

* annotate pyo3 references to allow conditional compilation
* address minor linting issues

The new feature flag (`python`) allows turning the python bindings off. This may be desirable in projects that don't interoperate with Python.

If the `python` feature is not explicitly disabled, it remains on by default.

* chore: remove commented out code

---------

Co-authored-by: pax <pm@paxinvict.us>

Author: irobot

Cargo.lock

@@ -21,4 +21,9 @@ strum_macros = "0.27.2"
 
 [dependencies.pyo3]
 version = "0.26.0"
-features = ["abi3-py38"]  # "abi3-py38" tells pyo3 (and maturin) to build using the stable ABI with minimum Python version 3.8.
+features = ["abi3-py38", "multiple-pymethods"]  # "abi3-py38" tells pyo3 (and maturin) to build using the stable ABI with minimum Python version 3.8.
+optional = true
+
+[features]
+default = ["python"]
+python = ["dep:pyo3"]

Cargo.toml

@@ -34,6 +34,15 @@ fn main() {
 }
 ```
 
+### Disable Python Bindings
+
+The `python` feature flag is enabled by default. In projects that don't interoperate with Python, the Python bindings can be disabled by turning off default features. In `Cargo.toml`:
+
+```toml
+[dependencies]
+qmk-via-api = { version = "0.3.0", default-features = false }
+```
+
 ## Python
 
 Install with pip:

README.md

@@ -4,9 +4,12 @@ use crate::api_commands::{
 };
 use crate::utils;
 use hidapi::HidApi;
-use pyo3::prelude::*;
 use std::str::FromStr;
 use std::vec;
+use core::result::Result;
+
+#[cfg(feature = "python")]
+use pyo3::prelude::*;
 
 const COMMAND_START: u8 = 0x00;
 
@@ -21,14 +24,14 @@ pub type Layer = u8;
 pub type Row = u8;
 pub type Column = u8;
 
-#[pyclass]
+#[cfg_attr(feature = "python", pyclass)]
 #[derive(Clone, Copy, Debug)]
 pub struct MatrixInfo {
     pub rows: u8,
     pub cols: u8,
 }
 
-#[pyclass]
+#[cfg_attr(feature = "python", pyclass)]
 #[derive(Clone, Copy, Debug)]
 pub enum KeyboardValue {
     Uptime = 0x01,
@@ -53,18 +56,50 @@ impl FromStr for KeyboardValue {
     }
 }
 
-#[pyclass(unsendable)]
+#[cfg_attr(feature = "python", pyclass(unsendable))]
 pub struct KeyboardApi {
     device: hidapi::HidDevice,
 }
 
+#[cfg(feature = "python")]
 #[pymethods]
 impl KeyboardApi {
     #[new]
-    pub fn new(vid: u16, pid: u16, usage_page: u16) -> PyResult<Self> {
-        let api = HidApi::new().map_err(|e| {
-            PyErr::new::<pyo3::exceptions::PyRuntimeError, _>(format!("Error: {}", e))
-        })?;
+    pub fn py_new(vid: u16, pid: u16, usage_page: u16) -> Result<Self, Error> {
+        KeyboardApi::new(vid, pid, usage_page)
+    }
+}
+
+#[cfg(feature = "python")]
+impl From<Error> for PyErr {
+    fn from(err: Error) -> Self {
+        PyErr::new::<pyo3::exceptions::PyRuntimeError, _>(err.0)
+    }
+}
+
+pub struct Error(pub String);
+
+impl std::fmt::Display for Error {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.write_str(self.0.as_str())
+    }
+}
+
+impl From<String> for Error {
+    fn from(err: String) -> Self {
+        Error(err)
+    }
+}
+
+impl From<&str> for Error {
+    fn from(err: &str) -> Self {
+        Error(err.to_string())
+    }
+}
+
+impl KeyboardApi {
+    pub fn new(vid: u16, pid: u16, usage_page: u16) -> Result<KeyboardApi, Error> {
+        let api = HidApi::new().map_err(|e| format!("Error: {e}"))?;
 
         let device = api
             .device_list()
@@ -73,16 +108,16 @@ impl KeyboardApi {
                     && device.product_id() == pid
                     && device.usage_page() == usage_page
             })
-            .ok_or_else(|| {
-                PyErr::new::<pyo3::exceptions::PyRuntimeError, _>("Could not find keyboard.")
-            })?
+            .ok_or("Could not find keyboard.")?
             .open_device(&api)
-            .map_err(|_| {
-                PyErr::new::<pyo3::exceptions::PyRuntimeError, _>("Could not open HID device.")
-            })?;
+            .map_err(|_| "Could not open HID device.")?;
 
         Ok(KeyboardApi { device })
     }
+}
+
+#[cfg_attr(feature = "python", pymethods)]
+impl KeyboardApi {
 
     /// Sends a raw HID command prefixed with the command byte and returns the response if successful.
     pub fn hid_command(&self, command: ViaCommandId, bytes: Vec<u8>) -> Option<Vec<u8>> {
@@ -188,23 +223,21 @@ impl KeyboardApi {
     fn fast_read_raw_matrix(&self, matrix_info: MatrixInfo, layer: Layer) -> Option<Vec<u16>> {
         const MAX_KEYCODES_PARTIAL: usize = 14;
         let length = matrix_info.rows as usize * matrix_info.cols as usize;
-        let buffer_list = vec![0; length.div_ceil(MAX_KEYCODES_PARTIAL) as usize];
+        let buffer_len = length.div_ceil(MAX_KEYCODES_PARTIAL);
         let mut remaining = length;
         let mut result = Vec::new();
-        for _ in 0..buffer_list.len() {
+        for _ in 0..buffer_len {
             if remaining < MAX_KEYCODES_PARTIAL {
-                self.get_keymap_buffer(
+                if let Some(val) = self.get_keymap_buffer(
                     layer as u16 * length as u16 * 2 + 2 * (length - remaining) as u16,
                     (remaining * 2) as u8,
-                )
-                .map(|val| result.extend(val));
+                ) { result.extend(val) }
                 remaining = 0;
             } else {
-                self.get_keymap_buffer(
+                if let Some(val) = self.get_keymap_buffer(
                     layer as u16 * length as u16 * 2 + 2 * (length - remaining) as u16,
                     (MAX_KEYCODES_PARTIAL * 2) as u8,
-                )
-                .map(|val| result.extend(val));
+                ) { result.extend(val) }
                 remaining -= MAX_KEYCODES_PARTIAL;
             }
         }
@@ -217,7 +250,7 @@ impl KeyboardApi {
         for i in 0..length {
             let row = (i as u16 / matrix_info.cols as u16) as u8;
             let col = (i as u16 % matrix_info.cols as u16) as u8;
-            self.get_key(layer, row, col).map(|val| res.push(val));
+            if let Some(val) = self.get_key(layer, row, col) { res.push(val) }
         }
         Some(res)
     }
@@ -238,8 +271,7 @@ impl KeyboardApi {
             for (key_idx, keycode) in layer.iter().enumerate() {
                 let row = (key_idx as u16 / matrix_info.cols as u16) as u8;
                 let col = (key_idx as u16 % matrix_info.cols as u16) as u8;
-                self.set_key(layer_idx as u8, row, col, *keycode)
-                    .map(|_| ());
+                self.set_key(layer_idx as u8, row, col, *keycode);
             }
         }
         Some(())
@@ -257,8 +289,7 @@ impl KeyboardApi {
             let buffer = shifted_data[offset..end].to_vec();
             let mut bytes = vec![offset_bytes.0, offset_bytes.1, buffer.len() as u8];
             bytes.extend(buffer);
-            self.hid_command(ViaCommandId::DynamicKeymapSetBuffer, bytes)
-                .map(|_| ());
+            self.hid_command(ViaCommandId::DynamicKeymapSetBuffer, bytes);
         }
         Some(())
     }

src/api.rs

@@ -1,6 +1,7 @@
+#[cfg(feature = "python")]
 use pyo3::prelude::*;
 
-#[pyclass]
+#[cfg_attr(feature = "python", pyclass)]
 #[derive(Clone, Copy, Debug, PartialEq)]
 pub enum ViaCommandId {
     GetProtocolVersion = 0x01,
@@ -26,7 +27,7 @@ pub enum ViaCommandId {
     DynamicKeymapSetEncoder = 0x15,
 }
 
-#[pyclass]
+#[cfg_attr(feature = "python", pyclass)]
 #[derive(Clone, Copy, Debug, PartialEq)]
 pub enum ViaChannelId {
     IdCustomChannel = 0,
@@ -37,14 +38,14 @@ pub enum ViaChannelId {
     IdQmkLedMatrixChannel = 5,
 }
 
-#[pyclass]
+#[cfg_attr(feature = "python", pyclass)]
 #[derive(Clone, Copy, Debug, PartialEq)]
 pub enum ViaQmkBacklightValue {
     IdQmkBacklightBrightness = 1,
     IdQmkBacklightEffect = 2,
 }
 
-#[pyclass]
+#[cfg_attr(feature = "python", pyclass)]
 #[derive(Clone, Copy, Debug, PartialEq)]
 pub enum ViaQmkRgblightValue {
     IdQmkRgblightBrightness = 1,
@@ -53,7 +54,7 @@ pub enum ViaQmkRgblightValue {
     IdQmkRgblightColor = 4,
 }
 
-#[pyclass]
+#[cfg_attr(feature = "python", pyclass)]
 #[derive(Clone, Copy, Debug, PartialEq)]
 pub enum ViaQmkRgbMatrixValue {
     IdQmkRgbMatrixBrightness = 1,
@@ -62,15 +63,15 @@ pub enum ViaQmkRgbMatrixValue {
     IdQmkRgbMatrixColor = 4,
 }
 
-#[pyclass]
+#[cfg_attr(feature = "python", pyclass)]
 #[derive(Clone, Copy, Debug, PartialEq)]
 pub enum ViaQmkLedMatrixValue {
     IdQmkLedMatrixBrightness = 1,
     IdQmkLedMatrixEffect = 2,
     IdQmkLedMatrixEffectSpeed = 3,
 }
 
-#[pyclass]
+#[cfg_attr(feature = "python", pyclass)]
 #[derive(Clone, Copy, Debug, PartialEq)]
 pub enum ViaQmkAudioValue {
     IdQmkAudioEnable = 1,

src/api_commands.rs

@@ -1,15 +1,17 @@
-use pyo3::prelude::*;
-
 pub mod api;
 pub mod api_commands;
 pub mod keycodes;
 pub mod scan;
 pub mod utils;
 
+#[cfg(feature = "python")]
+use pyo3::prelude::*;
+
+#[cfg(feature = "python")]
 #[pymodule]
 fn qmk_via_api(_py: Python, m: &Bound<'_, PyModule>) -> PyResult<()> {
     m.add_class::<api::KeyboardApi>()?;
     m.add_class::<scan::KeyboardDeviceInfo>()?;
     m.add_function(wrap_pyfunction!(scan::scan_keyboards, m)?)?;
     Ok(())
-}
+}

src/lib.rs

@@ -1,34 +1,30 @@
 use hidapi::HidApi;
+
+#[cfg(feature = "python")]
 use pyo3::prelude::*;
 
 const VIA_USAGE_PAGE: u16 = 0xff60;
 
 /// Information about a connected VIA-compatible keyboard.
-#[pyclass]
+#[cfg_attr(feature = "python", pyclass(get_all))]
 #[derive(Clone, Debug)]
 pub struct KeyboardDeviceInfo {
     /// USB vendor ID
-    #[pyo3(get)]
     pub vendor_id: u16,
     /// USB product ID
-    #[pyo3(get)]
     pub product_id: u16,
     /// HID usage page (expected to be 0xFF60 for VIA)
-    #[pyo3(get)]
     pub usage_page: u16,
     /// Optional manufacturer string
-    #[pyo3(get)]
     pub manufacturer: Option<String>,
     /// Optional product string
-    #[pyo3(get)]
     pub product: Option<String>,
     /// Optional serial number string
-    #[pyo3(get)]
     pub serial_number: Option<String>,
 }
 
 /// Scan for connected VIA keyboards.
-#[pyfunction]
+#[cfg_attr(feature = "python", pyfunction)]
 pub fn scan_keyboards() -> Vec<KeyboardDeviceInfo> {
     let api = match HidApi::new() {
         Ok(a) => a,
@@ -37,15 +33,15 @@ pub fn scan_keyboards() -> Vec<KeyboardDeviceInfo> {
 
     api.device_list()
         .filter(|d| d.usage_page() == VIA_USAGE_PAGE)
-        .filter_map(|d| {
-            Some(KeyboardDeviceInfo {
+        .map(|d| {
+            KeyboardDeviceInfo {
                 vendor_id: d.vendor_id(),
                 product_id: d.product_id(),
                 usage_page: d.usage_page(),
                 manufacturer: d.manufacturer_string().map(|s| s.to_string()),
                 product: d.product_string().map(|s| s.to_string()),
                 serial_number: d.serial_number().map(|s| s.to_string()),
-            })
+            }
         })
         .collect()
 }

src/scan.rs

@@ -32,7 +32,7 @@ pub fn shift_buffer_to_16_bit(buffer: &[u8]) -> Vec<u16> {
     shifted_buffer
 }
 
-pub fn shift_buffer_from_16_bit(buffer: &Vec<u16>) -> Vec<u8> {
+pub fn shift_buffer_from_16_bit(buffer: &[u16]) -> Vec<u8> {
     let mut flattened = Vec::new();
     for value in buffer.iter() {
         let (hi, lo) = shift_from_16_bit(*value);