Merge pull request #15 from NetherlandsForensicInstitute/9-publish

9-publish to PyPi

.github/workflows/publish.yml

@@ -0,0 +1,72 @@
+# This workflow will upload a Python Package using Twine when a release is created
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python#publishing-to-package-registries
+
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+
+name: Upload Python Package
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+#  TODO issue #11: deduplicate this, and trigger the test.yml directly
+  test:
+    name: Test job
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: [ "3.9", "3.10", "3.11" ]
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{matrix.python-version}}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements.txt
+
+      - name: Modify sys.path and export it
+        id: modify-sys-path
+        run: |
+          echo "::set-output name=sys-path::$(realpath .)"
+        shell: bash
+
+      # Add your build/test steps here
+      - name: Run Tests
+        working-directory: test
+        run: python test_adb_pywrapper.py
+        env:
+          PYTHONPATH: ${{ steps.modify-sys-path.outputs.sys-path }}
+
+  publish:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+    - name: Set up Python
+      uses: actions/setup-python@v3
+      with:
+        python-version: '3.11'
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install build
+    - name: Build package
+      run: python -m build
+    - name: Publish package
+      uses: pypa/[email protected]
+      with:
+        user: __token__
+        password: ${{ secrets.PYPI_API_TOKEN }}

.github/workflows/test.yml

@@ -34,7 +34,7 @@ jobs:
       # Add your build/test steps here
       - name: Run Tests
         working-directory: test
-        run: python test_adb_py.py
+        run: python test_adb_pywrapper.py
         env:
           PYTHONPATH: ${{ steps.modify-sys-path.outputs.sys-path }}
 

.gitignore

@@ -1,4 +1,4 @@
-adb_py.egg-info
+*egg-info
 build
 venv
 dist

CHANGELOG.md

@@ -1,4 +1,7 @@
 ```
+v1.0.0 - Change name to adb-pywrapper and add action to release to PyPi
+```
+```
 v0.8 - Removed lru_cache function that caused get_prop output to be cached which is not advisable since these properties can change
 ```
 ```

CONTRIBUTING.md

@@ -0,0 +1,24 @@
+# Contributing Guidelines
+
+Thank you for considering contributing to our project! Please take a moment to review the following guidelines.
+
+## Pull Requests
+
+- All contributions to the project must be submitted via pull request.
+- Ensure that your pull request addresses a specific issue or feature request. If none exists, please open a new issue first to discuss the changes you'd like to make.
+- Follow the [GitHub Flow](https://guides.github.com/introduction/flow/) workflow:
+  1. Create a new branch from `main`. The branch name should start with the issue number.
+  2. Make your changes and commit them with descriptive commit messages.
+  3. Submit a pull request to the main repository's `main` branch.
+- Ensure that your code adheres to the project's coding standards and conventions.
+- Include unit tests if applicable and ensure that existing tests pass.
+- Provide a clear and detailed description of your changes in the pull request description.
+
+## Issues
+
+- Feel free to open an issue for bug reports, feature requests, or general feedback.
+- When opening an issue, please provide as much detail as possible, including steps to reproduce for bug reports.
+
+## License
+
+By contributing to this project, you agree that your contributions will be licensed under the project's [LICENSE](LICENSE.txt).

README.md

@@ -1,21 +1,23 @@
-# adb_py Documentation
+# adb-pywrapper
+A python wrapper for the Android Debug Bridge enabling interaction with Android devices and emulators.
+
+<img src="adb-pywrapper_logo.jpg" alt="adb-pywrapper logo" width="500"/>
 
-<img src="adb_py_logo.jpg" alt="adb_py logo" width="500"/>
 
 ## AdbDevice: Interacting with Android Devices using ADB in Python
 
-The `AdbDevice` class in the `adb_py` Python package facilitates seamless interaction with Android devices using the Android Debug Bridge (ADB) directly within Python scripts.
+The `AdbDevice` class in the `adb-pywrapper` Python package facilitates seamless interaction with Android devices using the Android Debug Bridge (ADB) directly within Python scripts.
 
 Installation
 ------------
 
-To install the `adb_py` package from the internal nexus pipy server, you can use `pip`:
+To install the `adb-pywrapper` package from the internal Nexus PyPI server, you can use `pip`:
 
 ```bash
-pip install adb_py
+pip install adb-pywrapper
 ```
 
-Before using `adb_py`, ensure that ADB is installed on your machine and added to PATH. You can download and install the Android SDK, which includes ADB, from the official Android developer website.
+Before using `adb-pywrapper`, ensure that ADB is installed on your machine and added to PATH. You can download and install the Android SDK, which includes ADB, from the official Android developer website.
 
 If running the below in a terminal gives you an output, you are ready to go!
 
@@ -28,7 +30,7 @@ adb --version
 Import the necessary modules:
 
 ```python
-from adb_py import AdbDevice, AdbResult, PullResult
+from adb-pywrapper import AdbDevice, AdbResult, PullResult
 ```
 
 ## Listing Connected Devices
@@ -191,7 +193,7 @@ ls(path)
 * snapshot_delete(delete=None)  
 
 ## Error Handling
-Be sure to handle errors gracefully in your code, as various operations may fail, adb_py tries to provide information where possible on success or failure in the `AdbResult` and `PullResult` objects.
+Be sure to handle errors gracefully in your code, as various operations may fail, adb-pywrapper tries to provide information where possible on success or failure in the `AdbResult` and `PullResult` objects.
 
 ## Contributing
-Contributions to the adb_py package are welcome. If you encounter any issues, have suggestions, or want to contribute, feel free to open an issue or PR.
+Contributions to the adb-pywrapper package are welcome. If you encounter any issues, have suggestions, or want to contribute, feel free to open an issue or PR. Find our contribution guidelines [here](CONTRIBUTING.md).

RELEASE-PROCESS.md

@@ -0,0 +1,17 @@
+# Release process
+
+## Versioning
+Semantic versioning should be used, eg 1.2.3.
+
+## Tag
+The tag should be of the form v{version}.
+
+## Creating a release 
+- In GitHub, go to releases.
+- Select `Draft a new release`.
+- Choose a tag - you can create a new tag here. Make sure it is the same as the version in `setup.py`.
+- Click `Generate release ntoes`.
+- Make sure `Set as latest release` is selected.
+- Click `Publish release`.
+
+- Creating a release in GitHub automatically triggers publication on PyPI.

setup.py

@@ -1,7 +1,16 @@
 from setuptools import setup
 
 setup(
-    name="adb_py",
-    version="0.8",
-    py_modules=["adb_py", "adb_init"],
+    name="adb-pywrapper",
+    version="1.0.0",
+    description="adb-pywrapper facilitates seamless interaction with Android devices using the Android Debug Bridge (ADB) "
+                "directly within Python scripts.",
+    long_description=f"{open('README.md').read()}",
+    long_description_content_type="text/markdown",
+    author="Netherlands Forensic Institute",
+    author_email="[email protected]",
+    url="https://github.com/NetherlandsForensicInstitute/adb-pywrapper",
+    licence="EUPL-1.2",
+    py_modules=["adb-pywrapper", "adb_init"],
+    test_suite="test",
 )

test/test_adb_py.py → test/test_adb_pywrapper.py

@@ -5,7 +5,7 @@
 
 from parameterized import parameterized
 
-from adb_py import AdbResult, AdbDevice
+from adb_pywrapper import AdbResult, AdbDevice
 
 PROCESS = subprocess.run('echo hello', shell=True, capture_output=True)
 MOCK_SUCCESSFULLY_PULLED_FILE = ['abc.apk', 'bla.jpg']
@@ -321,7 +321,7 @@ def test_get_state(self):
         self.assertFalse(result.success)
         self.assertIn('Invalid command', result.stderr)
 
-    @patch('adb_py.AdbDevice._snapshot_command')
+    @patch('adb_pywrapper.AdbDevice._snapshot_command')
     def test_emulator_snapshots_list(self, mock_snapshot_command):
         # Test emulator_snapshots_list function
         snapshot_list_output = """List of snapshots present on all disks:
@@ -336,8 +336,8 @@ def test_emulator_snapshots_list(self, mock_snapshot_command):
         mock_snapshot_command.assert_called_once_with('list')
         self.assertEqual(result, ['snap_2023-11-23_13-13-02', 'snap_2023-12-05_12-56-56'])
 
-    @patch('adb_py.AdbDevice._snapshot_exists')
-    @patch('adb_py.AdbDevice._snapshot_command')
+    @patch('adb_pywrapper.AdbDevice._snapshot_exists')
+    @patch('adb_pywrapper.AdbDevice._snapshot_command')
     def test_emulator_snapshot_load_existing(self, mock_snapshot_command, mock_snapshot_exists):
         # Test emulator_snapshot_load function with an existing snapshot
         mock_snapshot_exists.return_value = True
@@ -348,7 +348,7 @@ def test_emulator_snapshot_load_existing(self, mock_snapshot_command, mock_snaps
         mock_snapshot_exists.assert_called_once_with('snapshot1')
         mock_snapshot_command.assert_called_once_with('load', 'snapshot1')
 
-    @patch('adb_py.AdbDevice._snapshot_exists')
+    @patch('adb_pywrapper.AdbDevice._snapshot_exists')
     def test_emulator_snapshot_load_non_existing(self, mock_snapshot_exists):
         # Test emulator_snapshot_load function with a non-existing snapshot
         mock_snapshot_exists.return_value = False
@@ -358,8 +358,8 @@ def test_emulator_snapshot_load_non_existing(self, mock_snapshot_exists):
         mock_snapshot_exists.assert_called_once_with('non_existing_snapshot')
         self.assertFalse(result.success)
 
-    @patch('adb_py.AdbDevice._snapshot_exists')
-    @patch('adb_py.AdbDevice._snapshot_command')
+    @patch('adb_pywrapper.AdbDevice._snapshot_exists')
+    @patch('adb_pywrapper.AdbDevice._snapshot_command')
     def test_emulator_snapshot_save(self, mock_snapshot_command, mock_snapshot_exists):
         # Test emulator_snapshot_save function
         mock_snapshot_exists.return_value = False
@@ -370,9 +370,9 @@ def test_emulator_snapshot_save(self, mock_snapshot_command, mock_snapshot_exist
         mock_snapshot_exists.assert_called_once_with('snapshot1')
         mock_snapshot_command.assert_called_once_with('save', 'snapshot1')
 
-    @patch('adb_py.AdbDevice.emulator_snapshots_list', return_value=['snapshot1', 'snapshot2'])
-    @patch('adb_py.AdbDevice._snapshot_exists')
-    @patch('adb_py.AdbDevice._snapshot_command')
+    @patch('adb_pywrapper.AdbDevice.emulator_snapshots_list', return_value=['snapshot1', 'snapshot2'])
+    @patch('adb_pywrapper.AdbDevice._snapshot_exists')
+    @patch('adb_pywrapper.AdbDevice._snapshot_command')
     def test_emulator_snapshot_delete(self, mock_snapshot_command, mock_snapshot_exists, mock_emulator_snapshots_list):
         # Test emulator_snapshot_delete function
         mock_snapshot_exists.return_value = True  # Existing snapshots