Merge pull request #96 from jonyboi396825/develop

0.2b0

.github/workflows/test.yml

@@ -0,0 +1,48 @@
+name: Tests
+on:
+  push:
+    branches:
+      - develop
+      - master
+    paths-ignore:
+      - 'docs/**'
+      - '*.md'
+      - '*.rst'
+  pull_request:
+    branches:
+      - develop
+      - master
+    paths-ignore:
+      - 'docs/**'
+      - '*.md'
+      - '*.rst'
+jobs:
+  tests:
+    name: ${{ matrix.name }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - {name: Linux, python: '3.10', os: ubuntu-latest, tox: passive}
+          - {name: Windows, python: '3.10', os: windows-latest, tox: passive}
+          - {name: Mac, python: '3.10', os: macos-latest, tox: passive}
+          - {name: '3.9', python: '3.9', os: ubuntu-latest, tox: passive}
+          - {name: '3.8', python: '3.8', os: ubuntu-latest, tox: passive}
+          - {name: '3.7', python: '3.7', os: ubuntu-latest, tox: passive}
+          - {name: '3.6', python: '3.6', os: ubuntu-latest, tox: passive}
+          - {name: Typing, python: '3.10', os: ubuntu-latest, tox: typing}
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions/setup-python@v2
+        with:
+          python-version: ${{ matrix.python }}
+          cache: 'pip'
+          cache-dependency-path: 'requirements.txt'
+      - name: update pip
+        run: |
+          pip install -U wheel
+          pip install -U setuptools
+          python -m pip install -U pip
+      - run: pip install tox
+      - run: tox -e ${{ matrix.tox }}

CHANGELOG.md

@@ -1,3 +1,55 @@
+# 0.2 Beta Release 0
+
+Previous version: 0.1.*
+
+## IMPORTANT: BREAKING changes from previous version:
+
+- Deleted `Builtins` because of compatibility issues
+
+## Changes from previous version
+
+- Added logging using Python's `logging` module and also added logging to file when disconnects happen, addressing [#73](https://github.com/jonyboi396825/COM-Server/issues/73)
+- CLI now runs production server instead of development server by default, and now recommending production server, addressing [#97](https://github.com/jonyboi396825/COM-Server/issues/97)
+- Updated `__repr__` for `Connection`
+- Added new `ConnectionRoutes` class for adding resources which gives users more flexibility over their Flask app object than the old `RestApiHandler` (check docs for more details), addressing [#104](https://github.com/jonyboi396825/COM-Server/issues/104)
+- Added `start_app`, `start_conns`, `add_resources`, and `disconnect_conns` as helper functions to `ConnectionRoutes`, which allow it to start the connections and run the server.
+- `ConnectionRoutes` explicitly responds with `500 Internal Server Error` rather than relying on exceptions from the `Connection` class when the connection is disconnected.
+- Added the new V1 API which uses `ConnectionRoutes` and follows RESTful principles more than the V0 API, addressing [#86](https://github.com/jonyboi396825/COM-Server/issues/86)
+- Fixed type annotations such that it passes `mypy` static typing checks
+- Added `tox`, making CI with Github Actions easier
+- CLI now uses `click` instead of `docopt` and serves V1 API
+- Deleted CLI docs because help option is now better
+- Updated all `Getting Started` and homepages to use `ConnectionRoutes`
+
+# 0.1.4
+
+Previous version: 0.1.3
+
+## Changes from previous version
+
+- Fixed parts of docs that were written during version 0 that were not true/very confusing and misleading
+
+# 0.1.3
+
+Previous version: 0.1.2
+
+## Changes from previous version
+
+- Fixed broken links, addressing [#92](https://github.com/jonyboi396825/COM-Server/issues/92) and [#93](https://github.com/jonyboi396825/COM-Server/issues/93)
+
+# 0.1.2
+
+Previous version: 0.1.1
+
+## IMPORTANT: BREAKING changes from previous version:
+
+- Added versioning in built-in API, addressing [#90](https://github.com/jonyboi396825/COM-Server/issues/90)
+
+## Changes from previous version:
+
+- Fixed return type annotation in `api_server.py`, addressing [#88](https://github.com/jonyboi396825/COM-Server/issues/88)
+- Fixed dependency list in `setup.py`
+
 # 0.1.1
 
 Previous version: 0.1

CONTRIBUTING.md

@@ -79,18 +79,27 @@ Launch the server:
 
 Replace "<baud>" and "<serport>" with the baud and serial port of your serial device.
 
-Use pytest:
+Use the testing scripts:
 ```sh
-> pytest -vv 
+> python3 tests/passive_test.py -vv
+> python3 tests/active_test.py -vv
 ```
 
 Make sure that all tests pass.
 
-Some tests need the `com_server` command to be run or the Arduino to be plugged in. Make sure the listed command is run and and Arduino is plugged in to make sure that every test passes and none of them are skipped.
+Some tests need the `com_server` command to be run or the Arduino to be plugged in. Make sure to run both commands above and also ensure that the Arduino is plugged in.
 
-When writing tests, use the `pytest` library, and make them as specific as possible, testing a specific part of what you are making.
+When writing tests, use the `pytest` library, and make them as specific as possible, testing a specific part of what you are making. Tests that do not require a serial port or a server should go into the `tests/passive` directory, and tests that do require an Arduino should go into the `tests/active` directory.
 
-I am also open to those who write new tests to already existing code, especially ones that can test if the methods of the `BaseConnection` and `Connection` classes are behaving properly.
+I am also open to those who write new tests to already existing code.
+
+## Typing:
+
+If writing code in the `src/com_server` directory, please use `mypy` to check static typing by running:
+
+```sh
+> mypy -p com_server
+```
 
 ### Formatting:
 

README.md

@@ -9,27 +9,15 @@ COM-Server is a Python library and a local web server that hosts an API locally
 
 The serial communication uses [pyserial](https://pyserial.readthedocs.io/en/latest/pyserial.html) as its back-end and the server uses [flask-restful](https://flask-restful.readthedocs.io/en/latest/quickstart.html) and [Flask](https://flask.palletsprojects.com/en/2.0.x/). Reading their documentations may help with developing with COM-Server.
 
-**NOTE**: COM-Server has only been tested on:  
-Operating systems:
+**NOTE**: COM-Server is mainly tested on a Raspberry Pi connected to an Arduino UNO running Raspberry Pi OS Buster with Python 3.7.3. It has also been tested on:
 
-- Ubuntu 20.04 (Focal Fossa)
-- Raspberry Pi OS 10 (Buster)
-- Mac OS 10.15.x (Catalina)
-- Mac OS 11.6 (Big Sur)
-- Windows 10
+OS | Version
+---- | ----
+Linux | Ubuntu 20.04 with Python 3.8.10
+MacOS | Big Sur with Python 3.8.9
+Windows | Windows 10 with Python 3.9.7, Windows 11 with Python 3.9.7
 
-Python versions:
-
-- Python 3.7.2
-- Python 3.7.3
-- Python 3.8.10
-- Python 3.9.7
-- Python 3.10.0
-
-Serial ports:
-
-- Arduino UNO
-- Arduino Nano
+It is likely that this library will not work for non-USB ports. 
 
 ## Recommended use
 COM-Server is **not** meant to be used like a normal JSON API, even though it uses Flask and Flask-restful. If there are many different devices accessing the endpoints at the same time, data will be backed up, since the serial communication is relatively slow and things cannot be sent to the serial device at the same time. 
@@ -53,18 +41,24 @@ For beta releases, use the `--pre` option:
 
 ## Quickstart
 
+The examples below will start an API server that interacts with the port at http://0.0.0.0:8080
+
 ```py
-# launches a development server on http://0.0.0.0:8080
+# launches a server on http://0.0.0.0:8080
 
-import com_server
+from com_server import Connection, ConnectionRoutes, start_app
+from com_server.api import V1
+from flask import Flask
+from flask_restful import Api
 
-conn = com_server.Connection(<baud>, "<serport>") 
-handler = com_server.RestApiHandler(conn) 
-com_server.Builtins(handler) 
+app = Flask(__name__)
+api = Api(app)
 
-handler.run_dev(host="0.0.0.0", port=8080) 
+conn = Connection(<baud>, "<serport>") 
+handler = ConnectionRoutes(conn)
+V1(handler)
 
-conn.disconnect()
+start_app(app, api, handler)
 ```
 Replace "&lt;serport&gt;" and "&lt;baud&gt;" with the serial port and baud rate.