Merge branch 'main' into custom-json-encoder-decoder

Author: samuelhwilliams

.github/ISSUE_TEMPLATE/bug_report.md

@@ -23,13 +23,13 @@ Steps to reproduce the behavior:
 **Expected behavior**
 A clear and concise description of what you expected to happen.
 
+**System Information**
+ - OS: [e.g. Windows 10 x64, Linux Ubuntu, macOS 12]
+ - Browser: [e.g. Chrome 108.0.5359.99 (Official Build) (64-bit), Safari 16, Firefox 107.0.1]
+ - Python Distribution: [e.g. Python.org 3.9, Anaconda3 2021.11 3.9, ActivePython 3.9]
+
 **Screenshots**
 If applicable, add screenshots to help explain your problem.
 
-**Desktop (please complete the following information):**
- - OS: [e.g. iOS]
- - Browser [e.g. chrome, safari]
- - Version [e.g. 22]
-
 **Additional context**
 Add any other context about the problem here.

.github/workflows/codeql-analysis.yml

@@ -0,0 +1,38 @@
+name: "CodeQL"
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+    # The branches below must be a subset of the branches above
+    branches: [master]
+  schedule:
+    - cron: '0 11 * * 0'
+
+jobs:
+  analyse:
+    name: Analyse
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v2
+      with:
+        # We must fetch at least the immediate parents so that if this is
+        # a pull request then we can checkout the head.
+        fetch-depth: 2
+
+    # If this run was triggered by a pull request event, then checkout
+    # the head of the pull request instead of the merge commit.
+    - run: git checkout HEAD^2
+      if: ${{ github.event_name == 'pull_request' }}
+
+    # Initializes the CodeQL tools for scanning.
+    - name: Initialize CodeQL
+      uses: github/codeql-action/init@v1
+      # Override language selection by uncommenting this and choosing your languages
+      with:
+        languages: javascript, python
+
+    - name: Perform CodeQL Analysis
+      uses: github/codeql-action/analyze@v1

.github/workflows/test.yml

@@ -0,0 +1,43 @@
+name: Test Eel
+
+on:
+  push:
+    branches: [ master ]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-20.04, windows-latest, macos-latest]
+        python-version: [3.6, 3.7, 3.8, 3.9, "3.10"]
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v2
+      - name: Setup python
+        uses: actions/setup-python@v2
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Setup test execution environment.
+        run: pip3 install -r requirements-meta.txt
+      - name: Run tox tests
+        run: tox -- --durations=0 --timeout=30
+
+  typecheck:
+    runs-on: windows-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v2
+      - name: Setup python
+        uses: actions/setup-python@v2
+        with:
+          python-version: "3.10"
+      - name: Setup test execution environment.
+        run: pip3 install -r requirements-meta.txt
+      - name: Run tox tests
+        run: tox -e typecheck

.gitignore

@@ -1,9 +1,11 @@
 __pycache__
 dist
 build
+Drivers
 Eel.egg-info
 .tmp
 .DS_Store
 *.pyc
 *.swp
 venv/
+.tox

.python-version

@@ -0,0 +1,5 @@
+3.6.15
+3.7.14
+3.8.14
+3.9.13
+3.10.8

CHANGELOG.md

@@ -1,5 +1,23 @@
 # Change log
 
+### v0.15.3
+* Comprehensive type hints implement by @thatfloflo in https://github.com/python-eel/Eel/pull/577.
+
+### v0.15.2
+* Adds `register_eel_routes` to handle applying Eel routes to non-Bottle custom app instances.
+
+### v0.15.1
+* Bump bottle dependency from 0.12.13 to 0.12.20 to address the critical CVE-2022-31799 and moderate CVE-2020-28473.
+
+### v0.15.0
+* Add `shutdown_delay` as a `start()` function parameter ([#529](https://github.com/python-eel/Eel/pull/529))
+
+### v0.14.0
+* Change JS function name parsing to use PyParsing rather than regex, courtesy @KyleKing.
+
+### v0.13.2
+* Add `default_path` start arg to define a default file to retrieve when hitting the root URL.
+
 ### v0.13.1
 * Shut down the Eel server less aggressively when websockets get closed (#337)
 

README-developers.md

@@ -0,0 +1,51 @@
+# Eel Developers
+
+## Setting up your environment
+
+In order to start developing with Eel you'll need to checkout the code, set up a development and testing environment, and check that everything is in order.
+
+### Clone the repository
+```bash
+git clone [email protected]:python-eel/Eel.git
+```
+
+### (Recommended) Create a virtual environment
+It's recommended that you use virtual environments for this project. Your process for setting up a virutal environment will vary depending on OS and tool of choice, but might look something like this:
+
+```bash
+python3 -m venv venv
+source venv/bin/activate
+```
+
+**Note**: `venv` is listed in the `.gitignore` file so it's the recommended virtual environment name
+    
+
+### Install project requirements
+
+```bash
+pip3 install -r requirements.txt        # eel's 'prod' requirements
+pip3 install -r requirements-test.txt   # pytest and selenium
+pip3 install -r requirements-meta.txt   # tox 
+```
+
+### (Recommended) Run Automated Tests
+Tox is configured to run tests against each major version we support (3.6+). In order to run Tox as configured, you will need to install multiple versions of Python. See the pinned minor versions in `.python-version` for recommendations.
+
+#### Tox Setup
+Our Tox configuration requires [Chrome](https://www.google.com/chrome) and [ChromeDriver](https://chromedriver.chromium.org/home). See each of those respective project pages for more information on setting each up.
+
+**Note**: Pay attention to the version of Chrome that is installed on your OS because you need to select the compatible ChromeDriver version.
+
+#### Running Tests
+
+To test Eel against a specific version of Python you have installed, e.g. Python 3.6 in this case, run:
+
+```bash
+tox -e py36
+```
+
+To test Eel against all supported versions, run the following:
+
+```bash
+tox
+```

README.md

@@ -116,8 +116,8 @@ As of Eel v0.12.0, the following options are available to `start()`:
  - **position**, a tuple of ints specifying the (left, top) of the main window in pixels *Default: `None`*
  - **geometry**, a dictionary specifying the size and position for all windows. The keys should be the relative path of the page, and the values should be a dictionary of the form `{'size': (200, 100), 'position': (300, 50)}`. *Default: {}*
  - **close_callback**, a lambda or function that is called when a websocket to a window closes (i.e. when the user closes the window). It should take two arguments; a string which is the relative path of the page that just closed, and a list of other websockets that are still open. *Default: `None`*
- - **app**, an instance of Bottle which will be used rather than creating a fresh one. This can be used to install middleware on the
- instance before starting eel, e.g. for session management, authentication, etc.
+ - **app**, an instance of Bottle which will be used rather than creating a fresh one. This can be used to install middleware on the instance before starting eel, e.g. for session management, authentication, etc. If your `app` is not a Bottle instance, you will need to call `eel.register_eel_routes(app)` on your custom app instance.
+ - **shutdown_delay**, timer configurable for Eel's shutdown detection mechanism, whereby when any websocket closes, it waits `shutdown_delay` seconds, and then checks if there are now any websocket connections. If not, then Eel closes. In case the user has closed the browser and wants to exit the program. By default, the value of **shutdown_delay** is `1.0` second
 
 
 
@@ -251,7 +251,7 @@ the JavaScript side, which defaults to 10000 milliseconds (10 seconds). This can
 
 #### Callbacks
 
-When you call an exposed function, you can immediately pass a callback function afterwards. This callback will automatically be called asynchrounously with the return value when the function has finished executing on the other side.
+When you call an exposed function, you can immediately pass a callback function afterwards. This callback will automatically be called asynchronously with the return value when the function has finished executing on the other side.
 
 For example, if we have the following function defined and exposed in Javascript:
 
@@ -288,7 +288,7 @@ n = eel.js_random()()  # This immediately returns the value
 print('Got this from Javascript:', n)
 ```
 
-You can only perform synchronous returns after the browser window has started (after calling `eel.start()`), otherwise obviously the call with hang.
+You can only perform synchronous returns after the browser window has started (after calling `eel.start()`), otherwise obviously the call will hang.
 
 In Javascript, the language doesn't allow us to block while we wait for a callback, except by using `await` from inside an `async` function. So the equivalent code from the Javascript side would be: