Merge pull request #217 from isl-org/python_style_check

Python style check

.github/workflows/python.yml

@@ -0,0 +1,35 @@
+# This workflow will check the python code using black
+
+name: Python style check
+
+on:
+  push:
+    branches: [ master ]
+    paths:
+    - 'controller/**'
+    - 'policy/**'
+    - '.github/workflows/python.yml'
+  pull_request:
+    branches: [ master ]
+    paths:
+    - 'controller/**'
+    - 'policy/**'
+    - '.github/workflows/python.yml'
+
+jobs:
+  style-check:
+    name: Python style check
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v2
+      - name: Set up python
+        uses: actions/setup-python@v2
+        with:
+          python-version: 3.7
+      - name: Install dependencies
+        run: | 
+          python -m pip install 'black[jupyter]'
+      - name: Check style
+        run: |
+          black --check .

CONTRIBUTING.md

@@ -10,41 +10,74 @@
 1. Submit an issue describing the changes you want to implement. If it's only minor changes/bug-fixes, you can skip to step 3.
 2. After the scope was discussed in the issue, assign it to yourself. It should show up in the "To do" column in the OpenBot project.
 3. Fork the project and clone it locally:
-    
+
    `git clone https://github.com/<user_id>/OpenBot.git`
 
 4. Create a branch:
 
-   `git checkout -b <branch-name>` 
-   
+   `git checkout -b <branch-name>`
+
    where `<branch-name>` concisely describes the scope of the work.
-   
+
 5. Do the work, write good commit messages, push your branch to the forked repository:
-   
-   ```
+
+   ```bash
    git add <modified file>
    git commit -m <meaningful description>
    git push --set-upstream origin <branch-name>
    ```
-   
+
 6. Create a [pull request](https://github.com/intel-isl/OpenBot/pulls) in GitHub and link the issue to it. It should show up in the "In progress" column in the OpenBot project.
 7. Work on any code review feedback you may receive and push it to your fork. The pull request gets updated automatically.
 8. Get a cold drink of your choice to reward yourself for making the world a better place.
 
 ## Guidelines
 
-- Use same style and formatting as rest of code. 
-  - For the Android code you can run:
-    1. `./gradlew checkStyle` --> returns java files with incorrect style. 
-    2. `./gradlew applyStyle` --> applies neccessary style changes to all java files.
-  - For the Arduino and Python code, just try to blend in.
+- Use same style and formatting as rest of code.
+  - For the Java (Android) and Python code see [below](#Formatting).
+  - For any other code, just try to blend in.
 - Update documentation associated with code changes you made.
-- If you want to include 3rd party dependencies, please discuss this in the issue first. 
+- If you want to include 3rd party dependencies, please discuss this in the issue first.
 - Pull requests should implement single features with as few changes as possible.
 - Make sure you don't include temporary or binary files (the gitignores should mostly take care of this).
 - Rebase/merge master into your branch before you submit the pull request.
 - If possible, test your code on Windows, Linux and OSX.
 
+## Formatting
+
+### Java
+
+We use a gradle script for formatting java code. Make sure you are in the `android` directory.
+
+You can check your code with:
+
+```bash
+./gradlew checkStyle
+```
+
+You can apply the style to all files by running:
+
+```bash
+./gradlew applyStyle
+```
+
+### Python
+
+We use [black](https://pypi.org/project/black/) for formatting python code.
+
+You can check your code in the current directory with:
+
+```bash
+black --check .
+```
+
+You can apply the style to all files in the current directory by running:
+
+```bash
+black .
+```
+
+## Further resources
 
 If you are looking for more information about contributing to open-source projects, here are two good references:
 

README.md

@@ -32,7 +32,7 @@ OpenBot leverages smartphones as brains for low-cost robots. We have designed a
 - Build your own [Robot Body](body/README.md)
 - Flash the [Arduino Firmware](firmware/README.md)
 - Install the [Android Apps](android/README.md)
-- Control the robot via [Python](python/README.md)
+- Try the [Python Controller](controller/README.md)
 - Train your own [Driving Policy](policy/README.md)
 
 ## Get the source code

python/README.md → controller/README.md

@@ -2,25 +2,31 @@
 
 This python program allows you to control the robot from a (wireless) keyboard and receive a video stream from the camera. The program can run on any computer connected to the same network as the robot's phone. It was developed and tested on a Raspberry Pi 3 and a MacBook.
 
-## Install dependencies
+## Dependencies
 
-If you have already installed the conda environment, make sure it is activated.
+We recommend to create a conda environment for OpenBot (if not already done). Instructions on installing conda can be found [here](https://docs.conda.io/projects/conda/en/latest/user-guide/install/). You can create a new environment with the following command:
 
+```bash
+conda create -n openbot python=3.7
 ```
+
+If you do not want install the dependencies globally, activate your conda environment first:
+
+```bash
 conda activate openbot
 ```
 
-To install the dependencies, you can use the following command. 
+Make sure you are in the folder `controller` within your local OpenBot repository. Now, you can install all the dependencies with the following command:
 
-```
+```bash
 pip install -r requirements.txt
 ```
 
 ## Controlling the robot
 
-NOTE: After a successful connection, it may not be possible to connect again unless the robot app is restarted. 
+NOTE: After a successful connection, it may not be possible to connect again unless the robot app is restarted.
 
-The python scripts will wait for an incoming connection. On the phone with the robot app, go to the FreeRoam fragment and toggle the control mode to the phone icon. The robot will now try to connect to the Python script (same way as it would connect to the controller app). Alternatively, you can also use the DefaultActivity and select `Phone` as controller. 
+The python scripts will wait for an incoming connection. On the phone with the robot app, go to the FreeRoam fragment and toggle the control mode to the phone icon. The robot will now try to connect to the Python script (same way as it would connect to the controller app). Alternatively, you can also use the DefaultActivity and select `Phone` as controller.
 
 ### Using Pygame
 
@@ -64,7 +70,7 @@ Run the controller:
 
 Here is the usage:
 
-```
+```bash
     W:        Increase speed
     S:        Decrease speed
     A:        Turn more left

python/common.py → controller/common.py

@@ -1,13 +1,15 @@
 import socket
-import zeroconf # DO: pip3 install zeroconf
+import zeroconf  # DO: pip3 install zeroconf
 import threading
 import sched, time
 
+
 def get_ip():
     with socket.socket(socket.AF_INET, socket.SOCK_DGRAM) as s:
-        s.connect(('1.2.3.4', 1))  # dummy connect
+        s.connect(("1.2.3.4", 1))  # dummy connect
         return s.getsockname()[0]
 
+
 class ServerSocket:
     MSGLEN = 512
 
@@ -26,7 +28,7 @@ def accept(self):
         self.server_socket = conn
 
     def send(self, msg):
-        sent = self.server_socket.send(msg.encode('utf-8'))
+        sent = self.server_socket.send(msg.encode("utf-8"))
 
     def receive(self):
         chunks = []
@@ -35,9 +37,9 @@ def receive(self):
             chunk = self.server_socket.recv(1)
 
             chunks.append(chunk)
-            if chunk == b'\n' or chunk == b'':
+            if chunk == b"\n" or chunk == b"":
                 break
-        return b''.join(chunks).decode('utf-8')
+        return b"".join(chunks).decode("utf-8")
 
     def close(self):
         try:
@@ -46,27 +48,32 @@ def close(self):
         except:
             print("Could not close all sockets")
 
+
 class DriveValue:
     """
     This represents a drive value for either left or right control. Valid values are between -1.0 and 1.0
     """
 
     MAX = 1.0
     MIN = -1.0
-    DELTA = .05
+    DELTA = 0.05
 
     value = 0.0
 
     def reset(self):
         self.value = 0.0
         return self.value
 
-    def incr(self, by_value = 0):
-        self.value = min(self.MAX, self.value + (by_value if by_value != 0 else self.DELTA))
+    def incr(self, by_value=0):
+        self.value = min(
+            self.MAX, self.value + (by_value if by_value != 0 else self.DELTA)
+        )
         return round(self.value, 3)
 
-    def decr(self, by_value = 0):
-        self.value = max(self.MIN, self.value - (by_value if by_value != 0 else self.DELTA))
+    def decr(self, by_value=0):
+        self.value = max(
+            self.MIN, self.value - (by_value if by_value != 0 else self.DELTA)
+        )
         return round(self.value, 3)
 
     def max(self):
@@ -92,7 +99,7 @@ def __init__(self, left, right, duration, steps, s_socket):
         """
 
         if duration < steps:
-            raise Exception('Duration too small')
+            raise Exception("Duration too small")
 
         self.left = left
         self.right = right
@@ -127,32 +134,36 @@ def send_command(self):
             self.event = self.scheduler.enter(self.interval, 1, self.send_command)
 
         try:
-            self.s_socket.send('{{driveCmd: {{l:{l}, r:{r} }} }}\n'.format(l=self.left.getValue(), r=self.right.getValue()))    
+            self.s_socket.send(
+                "{{driveCmd: {{l:{l}, r:{r} }} }}\n".format(
+                    l=self.left.getValue(), r=self.right.getValue()
+                )
+            )
         except Exception as e:
-            print(f'Stopping scheduler...got exception {e}\r')
-            if self.event is not None and not self.scheduler.empty() :
+            print(f"Stopping scheduler...got exception {e}\r")
+            if self.event is not None and not self.scheduler.empty():
                 self.scheduler.cancel(self.event)
         finally:
             if not self.scheduler.empty():
                 self.scheduler.cancel(self.event)
 
 
 def register(name, port, properties={}):
-    type_="_openbot._tcp.local."
+    type_ = "_openbot._tcp.local."
 
     ipAddr = socket.inet_pton(socket.AF_INET, get_ip())
 
     info = zeroconf.ServiceInfo(
         type_="_openbot._tcp.local.",
-        name=name + '.' + type_,
+        name=name + "." + type_,
         addresses=[ipAddr],
         port=port,
         weight=0,
         priority=0,
-        properties=properties)
+        properties=properties,
+    )
 
     zc = zeroconf.Zeroconf([get_ip()])
     zc.register_service(info)
 
     return (zc, info)
-