adb-dbg 0.1.0__tar.gz

adb_dbg-0.1.0/.gitignore

@@ -0,0 +1,28 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Virtual environments
+.venv/
+venv/
+
+# Build artifacts
+build/
+dist/
+
+# IDE
+.idea/
+.vscode/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Secrets
+.env
+.env.*
+!.env.example

adb_dbg-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tirrou Oussama
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

adb_dbg-0.1.0/PKG-INFO

@@ -0,0 +1,115 @@
+Metadata-Version: 2.5
+Name: adb-dbg
+Version: 0.1.0
+Summary: A lightweight Android process debugger with automatic PID reconnection.
+Project-URL: Homepage, https://github.com/TirrouOussama/adb-dbg
+Project-URL: Repository, https://github.com/TirrouOussama/adb-dbg
+Project-URL: Issues, https://github.com/TirrouOussama/adb-dbg/issues
+Author: Tirrou Oussama
+License-Expression: MIT
+License-File: LICENSE
+Keywords: adb,android,android-debugging,debugging,logcat
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Debuggers
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# adb-dbg
+
+A lightweight Android process debugger that automatically monitors an Android application's PID and reconnects Logcat whenever the process restarts.
+
+## Features
+
+- Automatically detects connected Android devices.
+- Selects the device automatically when only one is connected.
+- Supports explicit device selection when multiple devices are connected.
+- Monitors Android application processes.
+- Supports secondary Android processes (`PACKAGE:SERVICE`).
+- Automatically reconnects Logcat when a process terminates or restarts.
+- Detects unexpected Logcat termination and reconnects.
+- Clean shutdown with Ctrl+C.
+
+## Requirements
+
+- Python 3.9+
+- Android Debug Bridge (ADB)
+- At least one authorized Android device connected through ADB.
+
+ADB must be available in your system PATH.
+
+## Installation
+
+Clone the repository:
+
+```bash
+git clone https://github.com/TirrouOussama/adb-dbg.git
+cd adb-dbg
+```
+
+## Usage
+
+### Automatic device selection
+
+```bash
+adb-dbg PACKAGE
+```
+
+Example:
+
+```bash
+adb-dbg org.awfer.awferrides
+```
+
+### Secondary process
+
+```bash
+adb-dbg PACKAGE SERVICE
+```
+
+Example:
+
+```bash
+adb-dbg org.awfer.awferdriver tripd
+```
+
+### Explicit device selection
+
+```bash
+adb-dbg DEVICE PACKAGE [SERVICE]
+```
+
+Example:
+
+```bash
+adb-dbg RZCX31JLK1N org.awfer.awferdriver tripd
+```
+
+### Help
+
+```bash
+adb-dbg --help
+```
+
+## How it works
+
+1. Detects authorized ADB devices.
+2. Selects the target device.
+3. Finds the Android process using `pidof`.
+4. Attaches Logcat to the process PID.
+5. Monitors the PID every 0.5 seconds.
+6. Detects process termination or restart.
+7. Reconnects Logcat using the new PID.
+8. If the process is not running, waits until it becomes available.
+
+## Controls
+
+- `Ctrl+C`: Stop the debugger.
+
+## License
+
+MIT License. See [LICENSE](LICENSE).

adb_dbg-0.1.0/README.md

@@ -0,0 +1,94 @@
+# adb-dbg
+
+A lightweight Android process debugger that automatically monitors an Android application's PID and reconnects Logcat whenever the process restarts.
+
+## Features
+
+- Automatically detects connected Android devices.
+- Selects the device automatically when only one is connected.
+- Supports explicit device selection when multiple devices are connected.
+- Monitors Android application processes.
+- Supports secondary Android processes (`PACKAGE:SERVICE`).
+- Automatically reconnects Logcat when a process terminates or restarts.
+- Detects unexpected Logcat termination and reconnects.
+- Clean shutdown with Ctrl+C.
+
+## Requirements
+
+- Python 3.9+
+- Android Debug Bridge (ADB)
+- At least one authorized Android device connected through ADB.
+
+ADB must be available in your system PATH.
+
+## Installation
+
+Clone the repository:
+
+```bash
+git clone https://github.com/TirrouOussama/adb-dbg.git
+cd adb-dbg
+```
+
+## Usage
+
+### Automatic device selection
+
+```bash
+adb-dbg PACKAGE
+```
+
+Example:
+
+```bash
+adb-dbg org.awfer.awferrides
+```
+
+### Secondary process
+
+```bash
+adb-dbg PACKAGE SERVICE
+```
+
+Example:
+
+```bash
+adb-dbg org.awfer.awferdriver tripd
+```
+
+### Explicit device selection
+
+```bash
+adb-dbg DEVICE PACKAGE [SERVICE]
+```
+
+Example:
+
+```bash
+adb-dbg RZCX31JLK1N org.awfer.awferdriver tripd
+```
+
+### Help
+
+```bash
+adb-dbg --help
+```
+
+## How it works
+
+1. Detects authorized ADB devices.
+2. Selects the target device.
+3. Finds the Android process using `pidof`.
+4. Attaches Logcat to the process PID.
+5. Monitors the PID every 0.5 seconds.
+6. Detects process termination or restart.
+7. Reconnects Logcat using the new PID.
+8. If the process is not running, waits until it becomes available.
+
+## Controls
+
+- `Ctrl+C`: Stop the debugger.
+
+## License
+
+MIT License. See [LICENSE](LICENSE).

adb_dbg-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "adb-dbg"
+version = "0.1.0"
+description = "A lightweight Android process debugger with automatic PID reconnection."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+authors = [
+    { name = "Tirrou Oussama" }
+]
+keywords = [
+    "android",
+    "adb",
+    "debugging",
+    "logcat",
+    "android-debugging"
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Debuggers"
+]
+
+[project.urls]
+Homepage = "https://github.com/TirrouOussama/adb-dbg"
+Repository = "https://github.com/TirrouOussama/adb-dbg"
+Issues = "https://github.com/TirrouOussama/adb-dbg/issues"
+
+[project.scripts]
+adb-dbg = "adb_dbg.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/adb_dbg"]

adb_dbg-0.1.0/src/adb_dbg/__init__.py

@@ -0,0 +1,3 @@
+"""ADB-Debugger: monitor Android processes and automatically reconnect logcat."""
+
+__version__ = "0.1.0"

adb_dbg-0.1.0/src/adb_dbg/cli.py

@@ -0,0 +1,263 @@
+
+"""Android process debugger with automatic PID reconnection."""
+
+import argparse
+import shutil
+import subprocess
+import sys
+import time
+
+
+def get_devices(adb):
+    """Return authorized ADB device serials."""
+
+    result = subprocess.run(
+        [adb, "devices"],
+        capture_output=True,
+        text=True,
+    )
+
+    if result.returncode != 0:
+        raise RuntimeError("Unable to retrieve ADB devices.")
+
+    devices = []
+
+    for line in result.stdout.splitlines()[1:]:
+        fields = line.split()
+
+        if len(fields) >= 2 and fields[1] == "device":
+            devices.append(fields[0])
+
+    return devices
+
+
+def get_process_pid(adb, device, process):
+    """Return the first PID belonging to the Android process."""
+
+    result = subprocess.run(
+        [adb, "-s", device, "shell", "pidof", process],
+        capture_output=True,
+        text=True,
+    )
+
+    output = result.stdout.strip().replace("\r", "")
+
+    if not output:
+        return None
+
+    return output.split()[0]
+
+
+def stop_logcat(logcat):
+    """Stop the current logcat subprocess."""
+
+    if logcat is None or logcat.poll() is not None:
+        return
+
+    logcat.terminate()
+
+    try:
+        logcat.wait(timeout=2)
+    except subprocess.TimeoutExpired:
+        logcat.kill()
+        logcat.wait()
+
+
+def build_parser():
+    parser = argparse.ArgumentParser(
+        prog="adb-dbg",
+        description=(
+            "Monitor an Android process and automatically reconnect "
+            "logcat when its PID changes."
+        ),
+        usage=(
+            "adb-dbg [-h] PACKAGE [SERVICE]\n"
+            "       adb-dbg [-h] DEVICE PACKAGE [SERVICE]"
+        ),
+        epilog=(
+            "Examples:\n"
+            "  adb-dbg org.awfer.awferrides\n"
+            "  adb-dbg org.awfer.awferdriver tripd\n"
+            "  adb-dbg DEVICE_SERIAL com.example.anyapp\n"
+            "  adb-dbg DEVICE_SERIAL com.example.anyapp service"
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+
+    parser.add_argument(
+        "arguments",
+        nargs="*",
+        metavar="ARG",
+    )
+
+    return parser
+
+
+def main(argv=None):
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    arguments = args.arguments
+
+    if not arguments:
+        parser.error("Missing application package.")
+
+    if len(arguments) > 3:
+        parser.error("Too many arguments.")
+
+    adb = shutil.which("adb")
+
+    if adb is None:
+        print(
+            "ERROR: ADB is not installed or not in PATH.",
+            file=sys.stderr,
+        )
+        return 1
+
+    try:
+        devices = get_devices(adb)
+    except (OSError, RuntimeError) as exc:
+        print(f"ERROR: {exc}", file=sys.stderr)
+        return 1
+
+    if not devices:
+        print(
+            "ERROR: No connected or authorized ADB devices.",
+            file=sys.stderr,
+        )
+        return 1
+
+    device = None
+    package = None
+    service = ""
+
+    # Explicit device selection.
+    if arguments[0] in devices:
+        if len(arguments) < 2:
+            parser.error("Missing application package after device serial.")
+
+        device = arguments[0]
+        package = arguments[1]
+        service = arguments[2] if len(arguments) == 3 else ""
+
+    else:
+        if len(devices) > 1:
+            print(
+                "ERROR: Multiple ADB devices connected.",
+                file=sys.stderr,
+            )
+            print("\nSpecify a device:", file=sys.stderr)
+
+            for serial in devices:
+                print(f"  {serial}", file=sys.stderr)
+
+            print(
+                f"\nExample:\n  adb-dbg {devices[0]} "
+                f"{arguments[0]}",
+                file=sys.stderr,
+            )
+            return 1
+
+        if len(arguments) == 3:
+            parser.error(
+                "Invalid device serial. "
+                "Use DEVICE PACKAGE [SERVICE]."
+            )
+
+        device = devices[0]
+        package = arguments[0]
+        service = arguments[1] if len(arguments) == 2 else ""
+
+    process = f"{package}:{service}" if service else package
+
+    print("======================================")
+    print("       ANDROID PROCESS DEBUGGER")
+    print("======================================")
+    print(f"Device:  {device}")
+    print(f"Package: {package}")
+    print(f"Process: {process}")
+    print("======================================")
+
+    logcat = None
+
+    try:
+        while True:
+            try:
+                pid = get_process_pid(adb, device, process)
+            except OSError as exc:
+                print(f"ADB error: {exc}", file=sys.stderr)
+                time.sleep(1)
+                continue
+
+            if not pid:
+                print(
+                    f"[{time.strftime('%H:%M:%S')}] "
+                    f"Waiting for {process}...",
+                    flush=True,
+                )
+                time.sleep(1)
+                continue
+
+            print()
+            print(f"[{time.strftime('%H:%M:%S')}] ATTACHED")
+            print(f"Process: {process}")
+            print(f"PID:     {pid}")
+            print("--------------------------------------", flush=True)
+
+            try:
+                logcat = subprocess.Popen(
+                    [
+                        adb,
+                        "-s",
+                        device,
+                        "logcat",
+                        "-v",
+                        "threadtime",
+                        f"--pid={pid}",
+                    ]
+                )
+            except OSError as exc:
+                print(f"ERROR: Unable to start logcat: {exc}")
+                time.sleep(1)
+                continue
+
+            while True:
+                time.sleep(0.5)
+
+                try:
+                    current_pid = get_process_pid(
+                        adb,
+                        device,
+                        process,
+                    )
+                except OSError:
+                    current_pid = None
+
+                if current_pid != pid:
+                    print()
+                    print(
+                        f"[{time.strftime('%H:%M:%S')}] "
+                        "PROCESS CHANGED"
+                    )
+                    print(f"Old PID: {pid}")
+                    print(f"New PID: {current_pid or 'DEAD'}")
+                    print("Reconnecting...")
+                    break
+
+                if logcat.poll() is not None:
+                    print("Logcat exited. Reconnecting...")
+                    break
+
+            stop_logcat(logcat)
+            logcat = None
+
+    except KeyboardInterrupt:
+        print("\nDebugger stopped.")
+
+    finally:
+        stop_logcat(logcat)
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())