feat: Python package (#80)

* feat: create pyadb_client python package

* feat: add push / pull methods

* feat: add shell_command for USB

* feat(ci): add python package build

.github/workflows/python-build.yml

@@ -0,0 +1,20 @@
+name: Python - Build
+
+on: [push, pull_request]
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  build-release-python:
+    name: "build-release-python"
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: pyadb_client
+    steps:
+    - uses: actions/checkout@v4
+    - name: Install Python dependencies
+      run: pip install .
+    - name: Build project
+      run: maturin build --release

.github/workflows/python-release.yml

@@ -0,0 +1,30 @@
+name: Rust - Release creation
+
+on:
+  release:
+    types: [created]
+
+jobs:
+  create-release:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: pyadb_client
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Python dependencies
+        run: pip install .
+
+      - name: Publish Python package
+        run: maturin publish --non-interactive
+        env:
+          MATURIN_PYPI_TOKEN: ${{ secrets.MATURIN_PYPI_TOKEN }}
+
+      - name: "Publish GitHub artefacts"
+        uses: softprops/action-gh-release@v2
+        with:
+          files: |
+            target/wheels/pyadb_client*.whl
+            target/wheels/pyadb_client*.tar.gz

.github/workflows/rust-release.yml

@@ -9,8 +9,7 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - name: "Checkout repository"
-        uses: actions/checkout@v4
+      - uses: actions/checkout@v4
 
       - name: "Set up Rust"
         uses: actions-rs/toolchain@v1

.gitignore

@@ -1,3 +1,5 @@
 target
-Cargo.lock
-.vscode
+/Cargo.lock
+/.vscode
+venv
+/.mypy_cache

Cargo.toml

@@ -1,5 +1,5 @@
 [workspace]
-members = ["adb_cli", "adb_client"]
+members = ["adb_cli", "adb_client", "pyadb_client"]
 resolver = "2"
 
 [workspace.package]

README.md

@@ -30,6 +30,7 @@ Main features of this library:
     - Over **TCP/IP**
 - Implements hidden `adb` features, like `framebuffer`
 - Highly configurable
+- Provides wrappers to use directly from Python code
 - Easy to use !
 
 ## adb_client
@@ -41,10 +42,16 @@ Improved documentation available [here](./adb_client/README.md).
 ## adb_cli
 
 Rust binary providing an improved version of Google's official `adb` CLI, by using `adb_client` library.
-Provides an usage example of the library.
+Provides a "real-world" usage example of this library.
 
 Improved documentation available [here](./adb_cli/README.md).
 
+## pyadb_client
+
+Python wrapper using `adb_client` library to export classes usable directly from a Python environment.
+
+Improved documentation available [here](./pyadb_client/README.md)
+
 ## Related publications
 
 - [Diving into ADB protocol internals (1/2)](https://www.synacktiv.com/publications/diving-into-adb-protocol-internals-12)

pyadb_client/Cargo.toml

@@ -0,0 +1,20 @@
+[package]
+name = "pyadb_client"
+description = "Python wrapper for adb_client library"
+authors.workspace = true
+edition.workspace = true
+homepage.workspace = true
+keywords.workspace = true
+license.workspace = true
+repository.workspace = true
+version.workspace = true
+readme = "README.md"
+
+[lib]
+name = "pyadb_client"
+crate-type = ["cdylib"]
+
+[dependencies]
+anyhow = { version = "1.0.94" }
+adb_client = { version = "2.0.6" }
+pyo3 = { version = "0.23.3", features = ["extension-module", "anyhow"] }

pyadb_client/README.md

@@ -0,0 +1,44 @@
+# pyadb_client
+
+Python library to communicate with ADB devices. Built on top of Rust `adb_client` library.
+
+## Examples
+
+### Use ADB server
+
+```python
+server = pyadb_client.PyADBServer("127.0.0.1:5037")
+for i, device in enumerate(server.devices()):
+    print(i, device.identifier, device.state)
+
+# Get only connected device
+device = server.get_device()
+print(device, device.identifier)
+```
+
+### Push a file on device
+
+```python
+usb_device = PyADBUSBDevice.autodetect()
+usb_device.push("file.txt", "/data/local/tmp/file.txt")
+```
+
+## Local development
+
+```bash
+# Create Python virtual environment
+cd pyadb_client
+python3 -m venv .venv
+source .venv/bin/activate
+
+# Install needed dependencies
+pip install -e .
+
+# Build development package
+maturin develop
+
+# Build release Python package
+maturin build --release
+
+# Publish Python package
+```

pyadb_client/pyproject.toml

@@ -0,0 +1,13 @@
+[build-system]
+requires = ["maturin>=1,<2"]
+build-backend = "maturin"
+
+[project]
+dependencies = ["maturin", "patchelf"]
+name = "pyadb_client"
+dynamic = ["version"] # Let the build system automatically set package version
+classifiers = [
+    "Programming Language :: Rust",
+    "Programming Language :: Python :: Implementation :: CPython",
+    "Programming Language :: Python :: Implementation :: PyPy",
+]

pyadb_client/src/adb_server.rs

@@ -0,0 +1,37 @@
+use std::net::SocketAddrV4;
+
+use adb_client::ADBServer;
+use anyhow::Result;
+use pyo3::{pyclass, pymethods, PyResult};
+
+use crate::{PyADBServerDevice, PyDeviceShort};
+
+#[pyclass]
+pub struct PyADBServer(ADBServer);
+
+#[pymethods]
+impl PyADBServer {
+    #[new]
+    pub fn new(address: String) -> PyResult<Self> {
+        let address = address.parse::<SocketAddrV4>()?;
+        Ok(ADBServer::new(address).into())
+    }
+
+    pub fn devices(&mut self) -> Result<Vec<PyDeviceShort>> {
+        Ok(self.0.devices()?.into_iter().map(|v| v.into()).collect())
+    }
+
+    pub fn get_device(&mut self) -> Result<PyADBServerDevice> {
+        Ok(self.0.get_device()?.into())
+    }
+
+    pub fn get_device_by_name(&mut self, name: String) -> Result<PyADBServerDevice> {
+        Ok(self.0.get_device_by_name(&name)?.into())
+    }
+}
+
+impl From<ADBServer> for PyADBServer {
+    fn from(value: ADBServer) -> Self {
+        Self(value)
+    }
+}

pyadb_client/src/adb_server_device.rs

@@ -0,0 +1,38 @@
+use adb_client::{ADBDeviceExt, ADBServerDevice};
+use anyhow::Result;
+use pyo3::{pyclass, pymethods};
+use std::{fs::File, path::PathBuf};
+
+#[pyclass]
+pub struct PyADBServerDevice(pub ADBServerDevice);
+
+#[pymethods]
+impl PyADBServerDevice {
+    #[getter]
+    pub fn identifier(&self) -> String {
+        self.0.identifier.clone()
+    }
+
+    pub fn shell_command(&mut self, commands: Vec<String>) -> Result<Vec<u8>> {
+        let mut output = Vec::new();
+        let commands: Vec<&str> = commands.iter().map(|x| &**x).collect();
+        self.0.shell_command(&commands, &mut output)?;
+        Ok(output)
+    }
+
+    pub fn push(&mut self, input: PathBuf, dest: PathBuf) -> Result<()> {
+        let mut reader = File::open(input)?;
+        Ok(self.0.push(&mut reader, dest.to_string_lossy())?)
+    }
+
+    pub fn pull(&mut self, input: PathBuf, dest: PathBuf) -> Result<()> {
+        let mut writer = File::create(dest)?;
+        Ok(self.0.pull(&input.to_string_lossy(), &mut writer)?)
+    }
+}
+
+impl From<ADBServerDevice> for PyADBServerDevice {
+    fn from(value: ADBServerDevice) -> Self {
+        Self(value)
+    }
+}

pyadb_client/src/adb_usb_device.rs

@@ -0,0 +1,39 @@
+use std::{fs::File, path::PathBuf};
+
+use adb_client::{ADBDeviceExt, ADBUSBDevice};
+use anyhow::Result;
+use pyo3::{pyclass, pymethods};
+
+#[pyclass]
+pub struct PyADBUSBDevice(ADBUSBDevice);
+
+#[pymethods]
+impl PyADBUSBDevice {
+    #[staticmethod]
+    pub fn autodetect() -> Result<Self> {
+        Ok(ADBUSBDevice::autodetect()?.into())
+    }
+
+    pub fn shell_command(&mut self, commands: Vec<String>) -> Result<Vec<u8>> {
+        let mut output = Vec::new();
+        let commands: Vec<&str> = commands.iter().map(|x| &**x).collect();
+        self.0.shell_command(&commands, &mut output)?;
+        Ok(output)
+    }
+
+    pub fn push(&mut self, input: PathBuf, dest: PathBuf) -> Result<()> {
+        let mut reader = File::open(input)?;
+        Ok(self.0.push(&mut reader, &dest.to_string_lossy())?)
+    }
+
+    pub fn pull(&mut self, input: PathBuf, dest: PathBuf) -> Result<()> {
+        let mut writer = File::create(dest)?;
+        Ok(self.0.pull(&input.to_string_lossy(), &mut writer)?)
+    }
+}
+
+impl From<ADBUSBDevice> for PyADBUSBDevice {
+    fn from(value: ADBUSBDevice) -> Self {
+        Self(value)
+    }
+}

pyadb_client/src/lib.rs

@@ -0,0 +1,20 @@
+mod adb_server;
+mod adb_server_device;
+mod adb_usb_device;
+mod models;
+pub use adb_server::*;
+pub use adb_server_device::*;
+pub use adb_usb_device::*;
+pub use models::*;
+
+use pyo3::prelude::*;
+
+#[pymodule]
+fn pyadb_client(m: &Bound<'_, PyModule>) -> PyResult<()> {
+    m.add_class::<PyADBServer>()?;
+    m.add_class::<PyDeviceShort>()?;
+    m.add_class::<PyADBServerDevice>()?;
+    m.add_class::<PyADBUSBDevice>()?;
+
+    Ok(())
+}

pyadb_client/src/models/devices.rs

@@ -0,0 +1,26 @@
+use adb_client::DeviceShort;
+use pyo3::{pyclass, pymethods};
+
+// Check https://docs.rs/rigetti-pyo3/latest/rigetti_pyo3 to automatically build this code
+
+#[pyclass]
+pub struct PyDeviceShort(DeviceShort);
+
+#[pymethods]
+impl PyDeviceShort {
+    #[getter]
+    pub fn identifier(&self) -> String {
+        self.0.identifier.clone()
+    }
+
+    #[getter]
+    pub fn state(&self) -> String {
+        self.0.state.to_string()
+    }
+}
+
+impl From<DeviceShort> for PyDeviceShort {
+    fn from(value: DeviceShort) -> Self {
+        Self(value)
+    }
+}

pyadb_client/src/models/mod.rs

@@ -0,0 +1,2 @@
+mod devices;
+pub use devices::PyDeviceShort;