jaydroid 0.1.0__tar.gz

jaydroid-0.1.0/PKG-INFO

@@ -0,0 +1,188 @@
+Metadata-Version: 2.4
+Name: jaydroid
+Version: 0.1.0
+Summary: A beginner-friendly Python wrapper for simulating Android actions via ADB (tap, swipe, power on/off).
+Author: Johnston Kweku Abubakar
+License: MIT
+Project-URL: Homepage, https://github.com/johnston-kweku/jaydroid
+Project-URL: Issues, https://github.com/johnston-kweku/jaydroid/issues
+Keywords: adb,android,automation,adb-wrapper
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Intended Audience :: Developers
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# jaydroid
+
+`jaydroid` is a small Python wrapper around [Android Debug Bridge (ADB)](https://developer.android.com/tools/adb). It provides helpers for connecting to an Android device, reading display dimensions and device info, sending button input, capturing the screen, and performing swipe and tap gestures.
+
+This is my first Python package, built as a way to learn how to design, structure, and publish one from scratch. I'm documenting the build process — bugs, refactors, and design decisions — as a video series. Expect it to keep growing.
+
+## Requirements
+
+- Python 3.8 or newer
+- ADB installed and available on your `PATH`
+- An Android device or emulator connected to ADB
+- USB debugging enabled when using a physical device
+
+Check the connection with:
+
+```bash
+adb devices
+```
+
+## Installation
+
+```bash
+pip install jaydroid
+```
+
+For local development, from the project directory:
+
+```bash
+python -m pip install -e .
+```
+
+## Quick start
+
+`jaydroid` exposes ready-to-use instances, so there's no setup required beyond connecting your device:
+
+```python
+from jaydroid import device, button, swipe, tap
+
+device.connect()
+
+button.wake(delay=1)
+swipe.swipe_up()
+tap.tap(360, 640)
+```
+
+`device.connect()` checks that a device or emulator is actually reachable over ADB and loads its display dimensions. It's the one required step before using anything that depends on screen size (like the directional swipe helpers).
+
+## Delays
+
+Every `Button`, `Screen`, `Swipe`, and `Tap` method accepts an optional `delay` argument, in seconds (default `0`). The delay runs *after* the action completes successfully — "do this, then wait" — so it's useful for giving the device a moment to catch up before your next command fires:
+
+```python
+button.wake(delay=1)
+swipe.swipe_up(delay=0.5)
+```
+
+If a command fails, the delay is skipped — you'll see the error immediately rather than waiting first.
+
+## Gestures
+
+### Swipe
+
+```python
+from jaydroid import swipe
+
+swipe.swipe_up()
+swipe.swipe_down()
+swipe.swipe_left()
+swipe.swipe_right()
+swipe.unlock()  # alias for swipe_up()
+```
+
+Directional swipes are calculated as a percentage of the connected device's display size, so they scale across different screens rather than relying on hardcoded pixels:
+
+- Left and right: 10% to 90% of display width, at 50% of height
+- Up and down: 50% of display width, from 80% to 10% of height
+
+For custom coordinates, use `swipe.swipe(x1, y1, x2, y2)`:
+
+```python
+swipe.swipe(600, 640, 100, 640, delay=0.5)
+```
+
+### Tap
+
+```python
+from jaydroid import tap
+
+tap.tap(360, 640)
+tap.double_tap(360, 640)
+tap.longpress(360, 640, duration=1000)
+```
+
+## Buttons
+
+```python
+from jaydroid import button
+
+button.power()
+button.wake()
+button.sleep()
+button.home()
+button.back()
+button.recent_apps()
+button.menu()
+button.volume_up()
+button.volume_down()
+```
+
+Each accepts `delay=0`.
+
+## Screen
+
+```python
+from jaydroid.screen import Screen
+
+screen = Screen()
+screen.capture()
+screen.screenshot(filename='screen.png', pull=True)
+screen.screenrecord(filename='recording.mp4', pull=True, duration=10)
+```
+
+`screenshot()` and `screenrecord()` save to `/sdcard/` on the device by default, and can optionally pull the file to your local directory with `pull=True`.
+
+## Device information
+
+```python
+from jaydroid import device
+
+device.connect()
+print(device.width, device.height)
+print(device.is_connected())
+print(device.get_android_version())
+print(device.battery_info())
+```
+
+- `width` and `height` are only available after `connect()` — accessing them beforehand raises `DeviceNotConnectedError`.
+- `is_connected()`, `get_android_version()`, and `battery_info()` check the ADB connection live each time they're called, so they don't require `connect()` to have been run first.
+- `battery_info()` returns a dictionary parsed from `adb shell dumpsys battery`. Core fields (`level`, `status`, `health`, `voltage`, `temperature`, `technology`, and the `*_powered` flags) are consistently present across devices, but the full set of keys can vary by manufacturer, since some OEMs include additional proprietary fields.
+
+## Errors
+
+`jaydroid` raises specific exceptions instead of generic ones, so you can catch exactly what went wrong:
+
+- `DeviceNotFoundError` — raised by `connect()` when no device or emulator is reachable over ADB.
+- `DeviceNotConnectedError` — raised when accessing `width`/`height` before `connect()` has been called.
+- `AdbCommandError` — raised when an ADB command itself fails (e.g. the device disconnects mid-session). Includes ADB's own error output.
+
+```python
+from jaydroid import device
+from jaydroid.exceptions import DeviceNotFoundError
+
+try:
+    device.connect()
+except DeviceNotFoundError:
+    print("No device connected — plug one in and try again.")
+```
+
+## Roadmap
+
+Planned additions include WiFi status, installed app listing, and more device/system information. This package is under active development.
+
+## Author
+
+Built by Johnston Kweku Abubakar ([@johnston-kweku](https://github.com/johnston-kweku)) — this is my first Python package, built while learning to design, structure, and publish one from scratch.
+
+## License
+
+This project is licensed under the MIT License. See [LICENSE](LICENSE).

jaydroid-0.1.0/README.md

@@ -0,0 +1,169 @@
+# jaydroid
+
+`jaydroid` is a small Python wrapper around [Android Debug Bridge (ADB)](https://developer.android.com/tools/adb). It provides helpers for connecting to an Android device, reading display dimensions and device info, sending button input, capturing the screen, and performing swipe and tap gestures.
+
+This is my first Python package, built as a way to learn how to design, structure, and publish one from scratch. I'm documenting the build process — bugs, refactors, and design decisions — as a video series. Expect it to keep growing.
+
+## Requirements
+
+- Python 3.8 or newer
+- ADB installed and available on your `PATH`
+- An Android device or emulator connected to ADB
+- USB debugging enabled when using a physical device
+
+Check the connection with:
+
+```bash
+adb devices
+```
+
+## Installation
+
+```bash
+pip install jaydroid
+```
+
+For local development, from the project directory:
+
+```bash
+python -m pip install -e .
+```
+
+## Quick start
+
+`jaydroid` exposes ready-to-use instances, so there's no setup required beyond connecting your device:
+
+```python
+from jaydroid import device, button, swipe, tap
+
+device.connect()
+
+button.wake(delay=1)
+swipe.swipe_up()
+tap.tap(360, 640)
+```
+
+`device.connect()` checks that a device or emulator is actually reachable over ADB and loads its display dimensions. It's the one required step before using anything that depends on screen size (like the directional swipe helpers).
+
+## Delays
+
+Every `Button`, `Screen`, `Swipe`, and `Tap` method accepts an optional `delay` argument, in seconds (default `0`). The delay runs *after* the action completes successfully — "do this, then wait" — so it's useful for giving the device a moment to catch up before your next command fires:
+
+```python
+button.wake(delay=1)
+swipe.swipe_up(delay=0.5)
+```
+
+If a command fails, the delay is skipped — you'll see the error immediately rather than waiting first.
+
+## Gestures
+
+### Swipe
+
+```python
+from jaydroid import swipe
+
+swipe.swipe_up()
+swipe.swipe_down()
+swipe.swipe_left()
+swipe.swipe_right()
+swipe.unlock()  # alias for swipe_up()
+```
+
+Directional swipes are calculated as a percentage of the connected device's display size, so they scale across different screens rather than relying on hardcoded pixels:
+
+- Left and right: 10% to 90% of display width, at 50% of height
+- Up and down: 50% of display width, from 80% to 10% of height
+
+For custom coordinates, use `swipe.swipe(x1, y1, x2, y2)`:
+
+```python
+swipe.swipe(600, 640, 100, 640, delay=0.5)
+```
+
+### Tap
+
+```python
+from jaydroid import tap
+
+tap.tap(360, 640)
+tap.double_tap(360, 640)
+tap.longpress(360, 640, duration=1000)
+```
+
+## Buttons
+
+```python
+from jaydroid import button
+
+button.power()
+button.wake()
+button.sleep()
+button.home()
+button.back()
+button.recent_apps()
+button.menu()
+button.volume_up()
+button.volume_down()
+```
+
+Each accepts `delay=0`.
+
+## Screen
+
+```python
+from jaydroid.screen import Screen
+
+screen = Screen()
+screen.capture()
+screen.screenshot(filename='screen.png', pull=True)
+screen.screenrecord(filename='recording.mp4', pull=True, duration=10)
+```
+
+`screenshot()` and `screenrecord()` save to `/sdcard/` on the device by default, and can optionally pull the file to your local directory with `pull=True`.
+
+## Device information
+
+```python
+from jaydroid import device
+
+device.connect()
+print(device.width, device.height)
+print(device.is_connected())
+print(device.get_android_version())
+print(device.battery_info())
+```
+
+- `width` and `height` are only available after `connect()` — accessing them beforehand raises `DeviceNotConnectedError`.
+- `is_connected()`, `get_android_version()`, and `battery_info()` check the ADB connection live each time they're called, so they don't require `connect()` to have been run first.
+- `battery_info()` returns a dictionary parsed from `adb shell dumpsys battery`. Core fields (`level`, `status`, `health`, `voltage`, `temperature`, `technology`, and the `*_powered` flags) are consistently present across devices, but the full set of keys can vary by manufacturer, since some OEMs include additional proprietary fields.
+
+## Errors
+
+`jaydroid` raises specific exceptions instead of generic ones, so you can catch exactly what went wrong:
+
+- `DeviceNotFoundError` — raised by `connect()` when no device or emulator is reachable over ADB.
+- `DeviceNotConnectedError` — raised when accessing `width`/`height` before `connect()` has been called.
+- `AdbCommandError` — raised when an ADB command itself fails (e.g. the device disconnects mid-session). Includes ADB's own error output.
+
+```python
+from jaydroid import device
+from jaydroid.exceptions import DeviceNotFoundError
+
+try:
+    device.connect()
+except DeviceNotFoundError:
+    print("No device connected — plug one in and try again.")
+```
+
+## Roadmap
+
+Planned additions include WiFi status, installed app listing, and more device/system information. This package is under active development.
+
+## Author
+
+Built by Johnston Kweku Abubakar ([@johnston-kweku](https://github.com/johnston-kweku)) — this is my first Python package, built while learning to design, structure, and publish one from scratch.
+
+## License
+
+This project is licensed under the MIT License. See [LICENSE](LICENSE).

jaydroid-0.1.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "jaydroid"
+version = "0.1.0"
+description = "A beginner-friendly Python wrapper for simulating Android actions via ADB (tap, swipe, power on/off)."
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [
+    { name = "Johnston Kweku Abubakar" }
+]
+keywords = ["adb", "android", "automation", "adb-wrapper"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Intended Audience :: Developers",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/johnston-kweku/jaydroid"
+Issues = "https://github.com/johnston-kweku/jaydroid/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]

jaydroid-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

jaydroid-0.1.0/src/jaydroid/__init__.py

@@ -0,0 +1,20 @@
+"""
+jaydroid — a beginner-friendly Python wrapper for simulating Android actions via ADB.
+
+Example:
+    import jaydroid
+
+    jaydroid.device.connect()
+    jaydroid.tap.tap(500, 800)
+"""
+
+from .core import device, button, swipe, tap, Device, Button, Screen, Gesture
+from .exceptions import DeviceNotFoundError, DeviceNotConnectedError
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "device", "button", "swipe", "tap",
+    "Device", "Button", "Screen", "Gesture",
+    "DeviceNotFoundError", "DeviceNotConnectedError",
+]

jaydroid-0.1.0/src/jaydroid/button.py

@@ -0,0 +1,137 @@
+from .utils import adb
+
+class Button:
+    """
+    Methods for simulating common Android hardware and navigation buttons.
+
+    ADB must be installed and available on ``PATH``, and a device or emulator
+    must be connected before calling these methods.
+
+    Each button method accepts ``delay`` in seconds and waits after its ADB
+    action completes. The default delay is ``0``.
+    """
+    def power(self, delay=0):
+        """
+        Toggle the device's screen with a power-button press.
+
+        The screen is turned on when it is off and turned off when it is on.
+
+        Returns:
+            subprocess.CompletedProcess: The result of the ADB command.
+
+        Args:
+            delay (int | float): Seconds to wait after the key event completes.
+                Defaults to ``0``.
+        """
+
+        return adb('shell', 'input', 'keyevent', '26', delay=delay)
+
+    def volume_up(self, delay=0):
+        """
+        Increase the device's system volume by one default increment.
+
+        Returns:
+            subprocess.CompletedProcess: The result of the ADB command.
+
+        Args:
+            delay (int | float): Seconds to wait after the key event completes.
+                Defaults to ``0``.
+        """
+        return adb('shell', 'input', 'keyevent', '24', delay=delay)
+
+    def volume_down(self, delay=0):
+        """
+        Decrease the device's system volume by one default increment.
+
+        Returns:
+            subprocess.CompletedProcess: The result of the ADB command.
+
+        Args:
+            delay (int | float): Seconds to wait after the key event completes.
+                Defaults to ``0``.
+        """
+        return adb('shell', 'input', 'keyevent', '25', delay=delay)
+
+    def home(self, delay=0):
+        """
+        Navigate to the device home screen.
+
+        Returns:
+            subprocess.CompletedProcess: The result of the ADB command.
+
+        Args:
+            delay (int | float): Seconds to wait after the key event completes.
+                Defaults to ``0``.
+        """
+        return adb('shell', 'input', 'keyevent', '3', delay=delay)
+
+    def back(self, delay=0):
+        """
+        Navigate back one step in the current Android interface.
+
+        Returns:
+            subprocess.CompletedProcess: The result of the ADB command.
+
+        Args:
+            delay (int | float): Seconds to wait after the key event completes.
+                Defaults to ``0``.
+        """
+        return adb('shell', 'input', 'keyevent', '4', delay=delay)
+    
+    def recent_apps(self, delay=0):
+        """
+        Open the Android recent-apps view.
+
+        Returns:
+            subprocess.CompletedProcess: The result of the ADB command.
+
+        Args:
+            delay (int | float): Seconds to wait after the key event completes.
+                Defaults to ``0``.
+        """
+        return adb('shell', 'input', 'keyevent', '187', delay=delay)
+
+    def menu(self, delay=0):
+        """
+        Send the Android menu-button key event.
+
+        The effect depends on the active application and Android version.
+
+        Returns:
+            subprocess.CompletedProcess: The result of the ADB command.
+
+        Args:
+            delay (int | float): Seconds to wait after the key event completes.
+                Defaults to ``0``.
+        """
+        return adb('shell', 'input', 'keyevent', '82', delay=delay)
+
+    def wake(self, delay=0):
+        """
+        Wake the device's screen if it is off.
+
+        This has no effect when the device is already awake.
+
+        Returns:
+            subprocess.CompletedProcess: The result of the ADB command.
+
+        Args:
+            delay (int | float): Seconds to wait after the key event completes.
+                Defaults to ``0``.
+        """
+        return adb('shell', 'input', 'keyevent', '224', delay=delay)
+
+    def sleep(self, delay=0):
+        """
+        Put the device's screen to sleep.
+
+        Returns:
+            subprocess.CompletedProcess: The result of the ADB command.
+
+        Args:
+            delay (int | float): Seconds to wait after the key event completes.
+                Defaults to ``0``.
+        """
+        return adb('shell', 'input', 'keyevent', '223', delay=delay)
+
+

jaydroid-0.1.0/src/jaydroid/core.py

@@ -0,0 +1,27 @@
+r"""
+Utilities for sending Android Debug Bridge (ADB) input commands.
+
+The connected Android device must have developer options and USB debugging
+enabled. Most operations return the :class:`subprocess.CompletedProcess`
+instance produced by :func:`subprocess.run`, allowing callers to inspect the
+command's output and return code.
+"""
+
+
+from .device import Device
+from .gesture import Gesture
+from .button import Button
+from .screen import Screen
+
+
+
+
+
+
+device = Device()
+button = Button()
+swipe = Gesture.Swipe(device=device)
+tap = Gesture.Tap(device=device)
+
+
+

jaydroid-0.1.0/src/jaydroid/device.py

@@ -0,0 +1,147 @@
+from .utils import adb
+from .exceptions import DeviceNotFoundError, DeviceNotConnectedError
+
+class Device:
+    """
+    Manage connection state and display dimensions for an Android device.
+
+    Create a ``Device`` instance before using gesture helpers, then call
+    :meth:`connect` to verify that an ADB device is available and load its
+    display dimensions.
+
+    Device information helpers query the connected device through ADB and
+    raise ``DeviceNotConnectedError`` when a connection is required but absent.
+    """
+
+    def __init__(self):
+        self._width = None
+        self._height = None
+
+    def connect(self):
+        """Connect to the first available ADB device and load its display size.
+
+        Raises:
+            DeviceNotFoundError: If no device or emulator is available through
+                ADB.
+        """
+        result = adb('devices')
+        devices = result.stdout.splitlines()
+        header = devices.pop(0)
+        devices = [item for item in devices if item]
+        if not devices:
+            raise DeviceNotFoundError('Error: No device(s) connected')
+
+        self.setup()
+
+
+    @property
+    def width(self):
+        """The connected device's display width in pixels.
+
+        Raises:
+            DeviceNotConnectedError: If :meth:`connect` has not completed.
+        """
+        if self._width is not None:
+            return self._width
+        raise DeviceNotConnectedError('Error: No device/emulator connected. Did you forget to run connect()? See documentation')
+
+
+    @property
+    def height(self):
+        """The connected device's display height in pixels.
+
+        Raises:
+            DeviceNotConnectedError: If :meth:`connect` has not completed.
+        """
+        if self._height is not None:
+            return self._height
+        raise DeviceNotConnectedError('Error: No device/emulator connected. Did you forget to run connect()? See documentation')
+
+
+
+    def setup(self):
+        """Refresh and store the device display width and height.
+
+        Raises:
+            RuntimeError: If the device does not return a recognized display
+                resolution.
+        """
+        self._width, self._height = self.get_screen_size()
+
+    def get_screen_size(self):
+        """Return the physical display size as ``(width, height)``.
+
+        Raises:
+            RuntimeError: If ADB does not return a ``Physical size: WIDTHxHEIGHT``
+                line.
+        """
+        result = adb('shell', 'wm', 'size')
+        screen_info = result.stdout.splitlines()
+        for info in screen_info:
+            if info.startswith('Physical'):
+                screen = info
+                break
+        else:
+            raise RuntimeError('Connected device did not return a recognized resolution format.\
+                                You can use swipe() to enter custom coordinates')
+        text, resolution = screen.split(':')
+        resolution = resolution.strip()
+        width, height = resolution.split('x')
+        return int(width), int(height)
+
+
+    def is_connected(self):
+        """Return whether an Android device or emulator is connected through ADB.
+
+        Returns:
+            bool: ``True`` when at least one device is connected; otherwise,
+                ``False``.
+        """
+        result = adb('devices')
+        devices = result.stdout.splitlines()
+        header = devices.pop(0)
+        devices = [item for item in devices if item]
+        return bool(devices)
+
+    def get_android_version(self):
+        """Return the Android release version of the connected device.
+
+        Returns:
+            str: The Android release version reported by ADB.
+
+        Raises:
+            DeviceNotConnectedError: If no device or emulator is connected.
+        """
+        if self.is_connected():
+            result =  adb('shell', 'getprop', 'ro.build.version.release')
+            android_version = result.stdout.strip()
+            return android_version
+        error = 'No device was detected. Connect an android device and try again.'
+        raise DeviceNotConnectedError(error)
+
+    def battery_info(self):
+        """Return battery information reported by the connected device.
+
+        Returns:
+            dict: Battery properties parsed from ``adb shell dumpsys battery``.
+
+        Raises:
+            DeviceNotConnectedError: If no device or emulator is connected.
+        """
+        if self.is_connected():
+            result = adb('shell', 'dumpsys', 'battery')
+            info = result.stdout
+            info = info.splitlines()
+            info.pop(0)
+            info = [line.strip() for line in info if line.count(':') == 1]
+
+            battery_information = {}
+            for line in info:
+                key, value = line.split(':')
+                key, value = key.strip(), value.strip()
+
+                battery_information[key] = value
+
+            return battery_information
+        error = 'No device was detected. Connect an android device and try again.'
+        raise DeviceNotConnectedError(error)

jaydroid-0.1.0/src/jaydroid/exceptions.py

@@ -0,0 +1,8 @@
+class DeviceNotFoundError(Exception):
+    pass
+
+class DeviceNotConnectedError(Exception):
+    pass
+
+class AdbCommandError(Exception):
+    pass

jaydroid-0.1.0/src/jaydroid/gesture.py

@@ -0,0 +1,139 @@
+from .utils import adb
+import time
+
+
+class Gesture:
+    """Gesture helpers for a connected Android device.
+
+    Args:
+        device (Device): Device whose display dimensions are used for the
+            built-in directional gestures.
+
+    Gesture methods accept ``delay`` in seconds and wait after the ADB action
+    completes. The default delay is ``0``.
+    """
+
+    def __init__(self, device):
+        """Create gesture helpers associated with ``device``."""
+        self.device = device
+        self.swipe = Gesture.Swipe(device)
+        self.tap = Gesture.Tap(device)
+
+    class Swipe():
+        """Helpers for sending coordinate-based swipe gestures.
+
+        Built-in directional gestures calculate their coordinates as a
+        percentage of the associated device's display dimensions.
+        """
+        def __init__(self, device):
+            """Create a swipe helper associated with ``device``."""
+            self.device = device
+
+        def swipe(self, x1, y1, x2, y2, delay=0):
+            """Swipe from ``(x1, y1)`` to ``(x2, y2)`` in screen pixels.
+
+            Args:
+                delay (int | float): Seconds to wait after the swipe completes.
+                    Defaults to ``0``.
+            """
+            return adb('shell', 'input', 'swipe', str(x1), str(y1), str(x2), str(y2), delay=delay)
+
+
+        def swipe_up(self, delay=0):
+            """Swipe upward using the built-in screen coordinates.
+
+            Args:
+                delay (int | float): Seconds to wait after the swipe completes.
+                    Defaults to ``0``.
+            """
+            x1 = int(self.device.width * 0.5)
+            y1 = int(self.device.height * 0.60)
+            y2 = int(self.device.height * 0.10)
+            return adb('shell', 'input', 'swipe', str(x1), str(y1), str(x1), str(y2), delay=delay)
+
+        def unlock(self, delay=0):
+            """Attempt to unlock the device with an upward swipe.
+
+            Args:
+                delay (int | float): Seconds to wait after the swipe completes.
+                    Defaults to ``0``.
+            """
+            return self.swipe_up(delay=delay)
+
+        def swipe_down(self, delay=0):
+            """Swipe downward using the built-in screen coordinates.
+
+            Args:
+                delay (int | float): Seconds to wait after the swipe completes.
+                    Defaults to ``0``.
+            """
+            x1 = int(self.device.width * 0.5)
+            y1 = int(self.device.height * 0.10)
+            y2 = int(self.device.height * 0.80)
+
+            return adb('shell', 'input', 'swipe', str(x1), str(y1), str(x1), str(y2), delay=delay)
+
+
+        def swipe_right(self, delay=0):
+            """Swipe right using the built-in screen coordinates.
+
+            Args:
+                delay (int | float): Seconds to wait after the swipe completes.
+                    Defaults to ``0``.
+            """
+            x1 = int(self.device.width * 0.10)
+            y1 = int(self.device.height * 0.50)
+            x2 = int(self.device.width * 0.70)
+            return adb('shell', 'input', 'swipe', str(x1), str(y1), str(x2), str(y1), delay=delay)
+
+        def swipe_left(self, delay=0):
+            """Swipe left using the built-in screen coordinates.
+
+            Args:
+                delay (int | float): Seconds to wait after the swipe completes.
+                    Defaults to ``0``.
+            """
+            x1 = int(self.device.width * 0.70)
+            y1 = int(self.device.height * 0.50)
+            x2 = int(self.device.width * 0.10)
+            return adb('shell', 'input', 'swipe', str(x1), str(y1), str(x2), str(y1), delay=delay)
+
+    class Tap:
+        """Helpers for sending coordinate-based tap gestures.
+
+        Tap coordinates are expressed in screen pixels.
+        """
+        def __init__(self, device):
+            """Create a tap helper associated with ``device``."""
+            self.device = device
+
+        def tap(self, x, y, delay=0):
+            """Tap at ``(x, y)`` in screen pixels.
+
+            Args:
+                delay (int | float): Seconds to wait after the tap completes.
+                    Defaults to ``0``.
+            """
+            return adb('shell', 'input', 'tap', str(x), str(y), delay=delay)
+
+        def double_tap(self, x, y, delay=0):
+            """Double-tap near ``(x, y)`` in screen pixels.
+
+            Args:
+                delay (int | float): Seconds to wait after each tap completes.
+                    Defaults to ``0``.
+            """
+            self.tap(x, y, delay=delay)
+            time.sleep(0.05)
+            return self.tap(x, y, delay=delay)
+
+        def longpress(self, x, y, duration=3000, delay=0):
+            """Press at ``(x, y)`` for ``duration`` milliseconds.
+
+            Args:
+                delay (int | float): Seconds to wait after the long press
+                    completes. Defaults to ``0``.
+            """
+            return adb('shell', 'input', 'swipe', str(x), str(y), str(x), str(y), str(duration), delay=delay)
+
+

jaydroid-0.1.0/src/jaydroid/screen.py

@@ -0,0 +1,106 @@
+from .utils import adb
+
+class Screen:
+    """Methods for capturing screenshots and recording the device screen.
+
+    Each method accepts ``delay`` in seconds and waits after its ADB action
+    completes. For methods that run multiple commands, the delay is applied
+    after each command. The default delay is ``0``.
+    """
+
+    def capture(self, delay=0):
+        """
+        Send the Android screenshot key event.
+
+        This method does not save or pull an image file. Use :meth:`screenshot`
+        to capture the screen to a file.
+
+        Note:
+            This key event is less universally reliable across OEM skins than
+            calling :meth:`screenshot` directly.
+
+        Returns:
+            subprocess.CompletedProcess: The result of the ADB command.
+
+        Args:
+            delay (int | float): Seconds to wait after the capture completes.
+                Defaults to ``0``.
+        """
+
+        return adb('shell', 'input', 'keyevent', '120', delay=delay)
+
+
+    def screenshot(self, filename=None, pull=False, delay=0):
+        """
+        Save a screenshot on the connected device.
+
+        Args:
+            filename (str | None): Name of the image file on the device.
+                Defaults to ``'screenshot.png'``. The file is saved under
+                ``/sdcard/``.
+            pull (bool): If ``True``, copy the screenshot to the current local
+                directory after capturing it. Defaults to ``False``.
+            delay (int | float): Seconds to wait after each ADB command.
+                Defaults to ``0``.
+
+        Returns:
+            subprocess.CompletedProcess: The result of ``adb pull`` when
+                ``pull`` is ``True``; otherwise, the result of the capture
+                command.
+        """
+        if not filename:
+            filename = 'screenshot.png'
+        remote_path = f'/sdcard/{filename}'
+
+        res_capture = adb('shell', 'screencap', '-p', remote_path, delay=delay)
+
+        if pull:
+            res_pull = adb('pull', remote_path, check=True, delay=delay)
+            return res_pull
+
+        return res_capture
+
+
+    def screenrecord(self, filename=None, pull=False, duration=10, delay=0):
+        """
+        Record the device screen to an MP4 file.
+
+        Args:
+            filename (str | None): Name of the video file on the device.
+                Defaults to ``'recording.mp4'``. The file is saved under
+                ``/sdcard/``.
+            pull (bool): If ``True``, copy the recording to the current local
+                directory after recording it. Defaults to ``False``.
+            duration (int | float): Maximum recording duration in seconds.
+                Defaults to ``10``.
+            delay (int | float): Seconds to wait after each ADB command.
+                Defaults to ``0``.
+
+        Returns:
+            subprocess.CompletedProcess: The result of ``adb pull`` when
+                ``pull`` is ``True``; otherwise, the result of the recording
+                command.
+            str: ``'File format unsupported.'`` when ``filename`` does not
+                use the ``.mp4`` extension.
+        """
+        if not filename:
+            filename = 'recording.mp4'
+
+        name, file_format = filename.rsplit('.', 1)
+        if file_format != 'mp4':
+            return "File format unsupported."
+
+
+        remote_path = f'/sdcard/{filename}'
+
+        res_record = adb(
+            'shell', 'screenrecord', '--time-limit', str(duration), remote_path,
+            delay=delay
+        )
+
+        if pull:
+            res_pull = adb('pull', remote_path, check=True, delay=delay)
+            return res_pull
+
+        return res_record
+

jaydroid-0.1.0/src/jaydroid/utils.py

@@ -0,0 +1,32 @@
+import time, subprocess
+from .exceptions import AdbCommandError
+
+
+def adb(*args, **kwargs):
+    """Run an ADB command and return its completed-process result.
+
+    Args:
+        *args (str): Arguments passed to the ``adb`` executable.
+        **kwargs: Additional keyword arguments passed to
+            :func:`subprocess.run`. Output is captured and decoded as text by
+            default.
+        delay (int | float): Seconds to wait after the command completes.
+            Defaults to ``0``.
+
+    Returns:
+        subprocess.CompletedProcess: The result of the ADB command.
+    """
+    kwargs.setdefault('capture_output', True)
+    kwargs.setdefault('text', True)
+    delay_value = kwargs.pop('delay', 0)
+    
+    result =  subprocess.run(
+        ['adb', *args],
+        **kwargs
+    )
+
+    if result.returncode != 0:
+        raise AdbCommandError(result.stderr)
+    time.sleep(delay_value)
+    return result
+

jaydroid-0.1.0/src/jaydroid.egg-info/PKG-INFO

@@ -0,0 +1,188 @@
+Metadata-Version: 2.4
+Name: jaydroid
+Version: 0.1.0
+Summary: A beginner-friendly Python wrapper for simulating Android actions via ADB (tap, swipe, power on/off).
+Author: Johnston Kweku Abubakar
+License: MIT
+Project-URL: Homepage, https://github.com/johnston-kweku/jaydroid
+Project-URL: Issues, https://github.com/johnston-kweku/jaydroid/issues
+Keywords: adb,android,automation,adb-wrapper
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Intended Audience :: Developers
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# jaydroid
+
+`jaydroid` is a small Python wrapper around [Android Debug Bridge (ADB)](https://developer.android.com/tools/adb). It provides helpers for connecting to an Android device, reading display dimensions and device info, sending button input, capturing the screen, and performing swipe and tap gestures.
+
+This is my first Python package, built as a way to learn how to design, structure, and publish one from scratch. I'm documenting the build process — bugs, refactors, and design decisions — as a video series. Expect it to keep growing.
+
+## Requirements
+
+- Python 3.8 or newer
+- ADB installed and available on your `PATH`
+- An Android device or emulator connected to ADB
+- USB debugging enabled when using a physical device
+
+Check the connection with:
+
+```bash
+adb devices
+```
+
+## Installation
+
+```bash
+pip install jaydroid
+```
+
+For local development, from the project directory:
+
+```bash
+python -m pip install -e .
+```
+
+## Quick start
+
+`jaydroid` exposes ready-to-use instances, so there's no setup required beyond connecting your device:
+
+```python
+from jaydroid import device, button, swipe, tap
+
+device.connect()
+
+button.wake(delay=1)
+swipe.swipe_up()
+tap.tap(360, 640)
+```
+
+`device.connect()` checks that a device or emulator is actually reachable over ADB and loads its display dimensions. It's the one required step before using anything that depends on screen size (like the directional swipe helpers).
+
+## Delays
+
+Every `Button`, `Screen`, `Swipe`, and `Tap` method accepts an optional `delay` argument, in seconds (default `0`). The delay runs *after* the action completes successfully — "do this, then wait" — so it's useful for giving the device a moment to catch up before your next command fires:
+
+```python
+button.wake(delay=1)
+swipe.swipe_up(delay=0.5)
+```
+
+If a command fails, the delay is skipped — you'll see the error immediately rather than waiting first.
+
+## Gestures
+
+### Swipe
+
+```python
+from jaydroid import swipe
+
+swipe.swipe_up()
+swipe.swipe_down()
+swipe.swipe_left()
+swipe.swipe_right()
+swipe.unlock()  # alias for swipe_up()
+```
+
+Directional swipes are calculated as a percentage of the connected device's display size, so they scale across different screens rather than relying on hardcoded pixels:
+
+- Left and right: 10% to 90% of display width, at 50% of height
+- Up and down: 50% of display width, from 80% to 10% of height
+
+For custom coordinates, use `swipe.swipe(x1, y1, x2, y2)`:
+
+```python
+swipe.swipe(600, 640, 100, 640, delay=0.5)
+```
+
+### Tap
+
+```python
+from jaydroid import tap
+
+tap.tap(360, 640)
+tap.double_tap(360, 640)
+tap.longpress(360, 640, duration=1000)
+```
+
+## Buttons
+
+```python
+from jaydroid import button
+
+button.power()
+button.wake()
+button.sleep()
+button.home()
+button.back()
+button.recent_apps()
+button.menu()
+button.volume_up()
+button.volume_down()
+```
+
+Each accepts `delay=0`.
+
+## Screen
+
+```python
+from jaydroid.screen import Screen
+
+screen = Screen()
+screen.capture()
+screen.screenshot(filename='screen.png', pull=True)
+screen.screenrecord(filename='recording.mp4', pull=True, duration=10)
+```
+
+`screenshot()` and `screenrecord()` save to `/sdcard/` on the device by default, and can optionally pull the file to your local directory with `pull=True`.
+
+## Device information
+
+```python
+from jaydroid import device
+
+device.connect()
+print(device.width, device.height)
+print(device.is_connected())
+print(device.get_android_version())
+print(device.battery_info())
+```
+
+- `width` and `height` are only available after `connect()` — accessing them beforehand raises `DeviceNotConnectedError`.
+- `is_connected()`, `get_android_version()`, and `battery_info()` check the ADB connection live each time they're called, so they don't require `connect()` to have been run first.
+- `battery_info()` returns a dictionary parsed from `adb shell dumpsys battery`. Core fields (`level`, `status`, `health`, `voltage`, `temperature`, `technology`, and the `*_powered` flags) are consistently present across devices, but the full set of keys can vary by manufacturer, since some OEMs include additional proprietary fields.
+
+## Errors
+
+`jaydroid` raises specific exceptions instead of generic ones, so you can catch exactly what went wrong:
+
+- `DeviceNotFoundError` — raised by `connect()` when no device or emulator is reachable over ADB.
+- `DeviceNotConnectedError` — raised when accessing `width`/`height` before `connect()` has been called.
+- `AdbCommandError` — raised when an ADB command itself fails (e.g. the device disconnects mid-session). Includes ADB's own error output.
+
+```python
+from jaydroid import device
+from jaydroid.exceptions import DeviceNotFoundError
+
+try:
+    device.connect()
+except DeviceNotFoundError:
+    print("No device connected — plug one in and try again.")
+```
+
+## Roadmap
+
+Planned additions include WiFi status, installed app listing, and more device/system information. This package is under active development.
+
+## Author
+
+Built by Johnston Kweku Abubakar ([@johnston-kweku](https://github.com/johnston-kweku)) — this is my first Python package, built while learning to design, structure, and publish one from scratch.
+
+## License
+
+This project is licensed under the MIT License. See [LICENSE](LICENSE).

jaydroid-0.1.0/src/jaydroid.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+LICENSE
+README.md
+pyproject.toml
+src/jaydroid/__init__.py
+src/jaydroid/button.py
+src/jaydroid/core.py
+src/jaydroid/device.py
+src/jaydroid/exceptions.py
+src/jaydroid/gesture.py
+src/jaydroid/screen.py
+src/jaydroid/utils.py
+src/jaydroid.egg-info/PKG-INFO
+src/jaydroid.egg-info/SOURCES.txt
+src/jaydroid.egg-info/dependency_links.txt
+src/jaydroid.egg-info/top_level.txt
+tests/test_core.py

jaydroid-0.1.0/src/jaydroid.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

jaydroid-0.1.0/src/jaydroid.egg-info/top_level.txt

@@ -0,0 +1 @@
+jaydroid

jaydroid-0.1.0/tests/test_core.py

@@ -0,0 +1,6 @@
+from jaydroid.core import device, swipe, button, tap
+
+device.connect()
+
+
+print(device.battery_info()['temperature'])