diff --git a/.github/FUNDING.yml b/.github/FUNDING.yml
new file mode 100644
index 00000000..fe96485e
--- /dev/null
+++ b/.github/FUNDING.yml
@@ -0,0 +1,10 @@
+github: samuelhwilliams
+patreon: # Replace with a single Patreon username
+open_collective: # Replace with a single Open Collective username
+ko_fi: # Replace with a single Ko-fi username
+tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel
+community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry
+liberapay: # Replace with a single Liberapay username
+issuehunt: # Replace with a single IssueHunt username
+otechie: # Replace with a single Otechie username
+custom: # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2']
diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md
new file mode 100644
index 00000000..caa98832
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/bug_report.md
@@ -0,0 +1,35 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ''
+labels: bug
+assignees: ''
+
+---
+
+**Eel version**
+Please state the version of Eel you're using.
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+1. Go to '...'
+2. Click on '....'
+3. Scroll down to '....'
+4. See error
+
+**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.
+
+**Additional context**
+Add any other context about the problem here.
diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md
new file mode 100644
index 00000000..11fc491e
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/feature_request.md
@@ -0,0 +1,20 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: enhancement
+assignees: ''
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.
diff --git a/.github/ISSUE_TEMPLATE/help-me.md b/.github/ISSUE_TEMPLATE/help-me.md
new file mode 100644
index 00000000..07bab9c5
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/help-me.md
@@ -0,0 +1,39 @@
+---
+name: Help me
+about: Get help with Eel
+title: ''
+labels: help wanted
+assignees: ''
+
+---
+
+**Describe the problem**
+A clear and concise description of what you're trying to accomplish, and where you're having difficulty.
+
+**Code snippet(s)**
+Here is some code that can be easily used to reproduce the problem or understand what I need help with.
+
+- [ ] I know that if I don't provide sample code that allows someone to quickly step into my shoes, I may not get the help I want or my issue may be closed.
+
+```python
+import eel
+
+...
+```
+
+```html
+
+ ...
+
+```
+
+**Desktop (please complete the following information):**
+ - OS: [e.g. iOS]
+ - Browser [e.g. chrome, safari]
+ - Version [e.g. 22]
+
+**Smartphone (please complete the following information):**
+ - Device: [e.g. iPhone6]
+ - OS: [e.g. iOS8.1]
+ - Browser [e.g. stock browser, safari]
+ - Version [e.g. 22]
diff --git a/.github/workflows/codeql-analysis.yml b/.github/workflows/codeql-analysis.yml
new file mode 100644
index 00000000..a1621116
--- /dev/null
+++ b/.github/workflows/codeql-analysis.yml
@@ -0,0 +1,38 @@
+name: "CodeQL"
+
+on:
+ push:
+ branches: [main]
+ pull_request:
+ # The branches below must be a subset of the branches above
+ branches: [main]
+ 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
diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
new file mode 100644
index 00000000..8f67eff8
--- /dev/null
+++ b/.github/workflows/main.yml
@@ -0,0 +1,28 @@
+name: Publish
+
+on:
+ release:
+ types: [published]
+
+jobs:
+ build:
+
+ runs-on: ubuntu-latest
+
+ steps:
+ - name: Checkout repository
+ uses: actions/checkout@master
+ - name: Setup Python
+ uses: actions/setup-python@master
+ with:
+ python-version: 3.x
+ architecture: x64
+ - name: Install setuptools
+ run: pip install setuptools==76.1.0
+ - name: Build a source distribution
+ run: python setup.py sdist
+ - name: Publish to prod PyPI
+ uses: pypa/gh-action-pypi-publish@4f4304928fc886cd021893f6defb1bd53d0a1e5a
+ with:
+ user: __token__
+ password: ${{ secrets.pypi_token }}
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
new file mode 100644
index 00000000..3ae373a8
--- /dev/null
+++ b/.github/workflows/test.yml
@@ -0,0 +1,55 @@
+name: Test Eel
+
+on:
+ push:
+ branches: [main]
+ pull_request:
+ # The branches below must be a subset of the branches above
+ branches: [main]
+ workflow_dispatch:
+
+jobs:
+ test:
+ strategy:
+ fail-fast: false
+ matrix:
+ os: [ubuntu-24.04, windows-latest, macos-latest]
+ python-version: [3.7, 3.8, 3.9, "3.10", "3.11", "3.12"]
+ exclude:
+ - os: macos-latest
+ python-version: 3.7
+ - os: ubuntu-24.04
+ python-version: 3.7
+
+ runs-on: ${{ matrix.os }}
+
+ 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=240
+
+ typecheck:
+ strategy:
+ matrix:
+ os: [windows-latest]
+
+ runs-on: ${{ matrix.os }}
+
+ steps:
+ - name: Checkout repository
+ uses: actions/checkout@v2
+ - name: Setup python
+ uses: actions/setup-python@v2
+ with:
+ python-version: "3.x"
+ - name: Setup test execution environment.
+ run: pip3 install -r requirements-meta.txt
+ - name: Run tox tests
+ run: tox -e typecheck
diff --git a/.gitignore b/.gitignore
index 2abfe66a..781d9ca4 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,7 +1,11 @@
__pycache__
dist
build
+Drivers
Eel.egg-info
.tmp
.DS_Store
-*.pyc
\ No newline at end of file
+*.pyc
+*.swp
+venv/
+.tox
diff --git a/.python-version b/.python-version
new file mode 100644
index 00000000..c8cfe395
--- /dev/null
+++ b/.python-version
@@ -0,0 +1 @@
+3.10
diff --git a/.travis.yml b/.travis.yml
new file mode 100644
index 00000000..4a127478
--- /dev/null
+++ b/.travis.yml
@@ -0,0 +1,21 @@
+language: python
+cache: pip
+python:
+ - 2.7
+ - 3.6
+matrix:
+ allow_failures:
+ - python: 2.7
+install:
+ #- pip install -r requirements.txt
+ - pip install flake8 # pytest # add another testing frameworks later
+before_script:
+ # stop the build if there are Python syntax errors or undefined names
+ - flake8 . --count --select=E901,E999,F821,F822,F823 --show-source --statistics
+ # exit-zero treats all errors as warnings. The GitHub editor is 127 chars wide
+ - flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
+script:
+ - true # pytest --capture=sys # add other tests here
+notifications:
+ on_success: change
+ on_failure: change # `always` will be the setting once code changes slow down
diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 00000000..b91f88d4
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,95 @@
+# Change log
+
+### 0.18.2
+
+* Switch from using `pkg_resources` to `importlib.resources`: https://github.com/python-eel/Eel/pull/766
+
+### 0.18.1
+
+* Fix: Include `typing_extensions` in install requirements.
+
+### 0.18.0
+* Added support for MS Internet Explorer in #744.
+* Added supported for app_mode in the Edge browser in #744.
+* Improved type annotations in #683.
+
+### 0.17.0
+* Adds support for Python 3.11 and Python 3.12
+
+### v0.16.0
+* Drop support for Python versions below 3.7
+
+### 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)
+
+## v0.13.0
+* Drop support for Python versions below 3.6
+* Add `jinja2` as an extra for pip installation, e.g. `pip install eel[jinja2]`.
+* Bump dependencies in examples to dismiss github security notices. We probably want to set up a policy to ignore example dependencies as they shouldn't be considered a source of vulnerabilities.
+* Disable edge on non-Windows platforms until we implement proper support.
+
+### v0.12.4
+* Return greenlet task from `spawn()` ([#300](https://github.com/samuelhwilliams/Eel/pull/300))
+* Set JS mimetype to reduce errors on Windows platform ([#289](https://github.com/samuelhwilliams/Eel/pull/289))
+
+### v0.12.3
+* Search for Chromium on macOS.
+
+### v0.12.2
+* Fix a bug that prevents using middleware via a custom Bottle.
+
+### v0.12.1
+* Check that Chrome path is a file that exists on Windows before blindly returning it.
+
+## v0.12.0
+* Allow users to override the amount of time Python will wait for Javascript functions running via Eel to run before bailing and returning None.
+
+### v0.11.1
+* Fix the implementation of #203, allowing users to pass their own bottle instances into Eel.
+
+## v0.11.0
+* Added support for `app` parameter to `eel.start`, which will override the bottle app instance used to run eel. This
+allows developers to apply any middleware they wish to before handing over to eel.
+* Disable page caching by default via new `disable_cache` parameter to `eel.start`.
+* Add support for listening on all network interfaces via new `all_interfaces` parameter to `eel.start`.
+* Support for Microsoft Edge
+
+### v0.10.4
+* Fix PyPi project description.
+
+### v0.10.3
+* Fix a bug that prevented using Eel without Jinja templating.
+
+### v0.10.2
+* Only render templates from within the declared jinja template directory.
+
+### v0.10.1
+* Avoid name collisions when using Electron, so jQuery etc work normally
+
+## v0.10.0
+* Corrective version bump after new feature included in 0.9.13
+* Fix a bug with example 06 for Jinja templating; the `templates` kwarg to `eel.start` takes a filepath, not a bool.
+
+### v0.9.13
+* Add support for Jinja templating.
+
+### Earlier
+* No changelog notes for earlier versions.
diff --git a/README-developers.md b/README-developers.md
new file mode 100644
index 00000000..a0d00d6c
--- /dev/null
+++ b/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 git@github.com: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.7+). 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.7 in this case, run:
+
+```bash
+tox -e py36
+```
+
+To test Eel against all supported versions, run the following:
+
+```bash
+tox
+```
diff --git a/README.md b/README.md
index 1498fb2f..a2dfc4dc 100644
--- a/README.md
+++ b/README.md
@@ -1,29 +1,71 @@
# Eel
+
+> [!CAUTION]
+> This project is effectively unmaintained. It has not received regular update in a number of years, and there are no plans by active maintainers for this to change. Please treat this project in that light and use it with careful consideration towards how you will secure and maintain anything you build using it.
+
+[](https://pypi.org/project/Eel/)
+[](https://pypistats.org/packages/eel)
+
+[](https://pypi.org/project/Eel/)
+
Eel is a little Python library for making simple Electron-like offline HTML/JS GUI apps, with full access to Python capabilities and libraries.
-**It hosts a local webserver, then lets you annotate functions in Python so that they can be called from Javascript, and vice versa.**
+> **Eel hosts a local webserver, then lets you annotate functions in Python so that they can be called from Javascript, and vice versa.**
+
+Eel is designed to take the hassle out of writing short and simple GUI applications. If you are familiar with Python and web development, probably just jump to [this example](https://github.com/ChrisKnott/Eel/tree/master/examples/04%20-%20file_access) which picks random file names out of the given folder (something that is impossible from a browser).
-It is designed to take the hassle out of writing short and simple GUI applications. If you are familiar with Python and web development, probably just jump to [this example](https://github.com/ChrisKnott/Eel/tree/master/examples/04%20-%20file_access) which picks random file names out of the given folder (something that is impossible from a browser).
+

-
+
-### Intro
+- [Eel](#eel)
+ - [Intro](#intro)
+ - [Install](#install)
+ - [Usage](#usage)
+ - [Directory Structure](#directory-structure)
+ - [Starting the app](#starting-the-app)
+ - [App options](#app-options)
+ - [Chrome/Chromium flags](#chromechromium-flags)
+ - [Exposing functions](#exposing-functions)
+ - [Eello, World!](#eello-world)
+ - [Return values](#return-values)
+ - [Callbacks](#callbacks)
+ - [Synchronous returns](#synchronous-returns)
+ - [Asynchronous Python](#asynchronous-python)
+ - [Building distributable binary with PyInstaller](#building-distributable-binary-with-pyinstaller)
+ - [Microsoft Edge](#microsoft-edge)
+
+
+
+## Intro
There are several options for making GUI apps in Python, but if you want to use HTML/JS (in order to use jQueryUI or Bootstrap, for example) then you generally have to write a lot of boilerplate code to communicate from the Client (Javascript) side to the Server (Python) side.
The closest Python equivalent to Electron (to my knowledge) is [cefpython](https://github.com/cztomczak/cefpython). It is a bit heavy weight for what I wanted.
-Eel is not as fully-fledged as Electron or cefpython - it is probably not suitable for making full blown applications like Atom - but it is very suitable for making the GUI equivalent of little utility scripts that you use yourself.
+Eel is not as fully-fledged as Electron or cefpython - it is probably not suitable for making full blown applications like Atom - but it is very suitable for making the GUI equivalent of little utility scripts that you use internally in your team.
+
+For some reason many of the best-in-class number crunching and maths libraries are in Python (Tensorflow, Numpy, Scipy etc) but many of the best visualization libraries are in Javascript (D3, THREE.js etc). Hopefully Eel makes it easy to combine these into simple utility apps for assisting your development.
-### Install
+Join Eel's users and maintainers on [Discord](https://discord.com/invite/3nqXPFX), if you like.
+
+## Install
Install from pypi with `pip`:
- pip install eel
+```shell
+pip install eel
+```
+
+To include support for HTML templating, currently using [Jinja2](https://pypi.org/project/Jinja2/#description):
-### Usage
+```shell
+pip install eel[jinja2]
+```
-#### Structure
+## Usage
+
+### Directory Structure
An Eel application will be split into a frontend consisting of various web-technology files (.html, .js, .css) and a backend consisting of various Python scripts.
@@ -40,7 +82,7 @@ static_web_folder/ <-- Web folder
logo.png
```
-#### Starting the app
+### Starting the app
Suppose you put all the frontend files in a directory called `web`, including your start page `main.html`, then the app is started like this;
@@ -54,78 +96,118 @@ This will start a webserver on the default settings (http://localhost:8000) and
If Chrome or Chromium is installed then by default it will open in that in App Mode (with the `--app` cmdline flag), regardless of what the OS's default browser is set to (it is possible to override this behaviour).
-#### Exposing functions
+### App options
+
+Additional options can be passed to `eel.start()` as keyword arguments.
+
+Some of the options include the mode the app is in (e.g. 'chrome'), the port the app runs on, the host name of the app, and adding additional command line flags.
+
+As of Eel v0.12.0, the following options are available to `start()`:
+ - **mode**, a string specifying what browser to use (e.g. `'chrome'`, `'electron'`, `'edge'`,`'msie'`, `'custom'`). Can also be `None` or `False` to not open a window. *Default: `'chrome'`*
+ - **host**, a string specifying what hostname to use for the Bottle server. *Default: `'localhost'`)*
+ - **port**, an int specifying what port to use for the Bottle server. Use `0` for port to be picked automatically. *Default: `8000`*.
+ - **block**, a bool saying whether or not the call to `start()` should block the calling thread. *Default: `True`*
+ - **jinja_templates**, a string specifying a folder to use for Jinja2 templates, e.g. `my_templates`. *Default: `None`*
+ - **cmdline_args**, a list of strings to pass to the command to start the browser. For example, we might add extra flags for Chrome; ```eel.start('main.html', mode='chrome-app', port=8080, cmdline_args=['--start-fullscreen', '--browser-startup-dialog'])```. *Default: `[]`*
+ - **size**, a tuple of ints specifying the (width, height) of the main window in pixels *Default: `None`*
+ - **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. 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
+
+
+
+### Exposing functions
In addition to the files in the frontend folder, a Javascript library will be served at `/eel.js`. You should include this in any pages:
```html
```
+
Including this library creates an `eel` object which can be used to communicate with the Python side.
Any functions in the Python code which are decorated with `@eel.expose` like this...
+
```python
@eel.expose
def my_python_function(a, b):
print(a, b, a + b)
```
+
...will appear as methods on the `eel` object on the Javascript side, like this...
+
```javascript
-console.log('Calling Python...');
-eel.my_python_function(1, 2); // This calls the Python function that was decorated
+console.log("Calling Python...");
+eel.my_python_function(1, 2); // This calls the Python function that was decorated
```
Similarly, any Javascript functions which are exposed like this...
+
```javascript
eel.expose(my_javascript_function);
function my_javascript_function(a, b, c, d) {
- if(a < b){
+ if (a < b) {
console.log(c * d);
}
}
```
+
can be called from the Python side like this...
+
```python
print('Calling Javascript...')
eel.my_javascript_function(1, 2, 3, 4) # This calls the Javascript function
```
-When passing complex objects as arguments, bear in mind that internally they are converted to JSON and sent down a websocket.
-#### Eello, World!
+The exposed name can also be overridden by passing in a second argument. If your app minifies JavaScript during builds, this may be necessary to ensure that functions can be resolved on the Python side:
+
+```javascript
+eel.expose(someFunction, "my_javascript_function");
+```
+
+When passing complex objects as arguments, bear in mind that internally they are converted to JSON and sent down a websocket (a process that potentially loses information).
+
+### Eello, World!
+
+> See full example in: [examples/01 - hello_world](https://github.com/ChrisKnott/Eel/tree/master/examples/01%20-%20hello_world)
Putting this together into a **Hello, World!** example, we have a short HTML page, `web/hello.html`:
+
```html
-
- Hello, World!
-
-
-
-
-
-
-
- Hello, World!
-
+
+ Hello, World!
+
+
+
+
+
+
+
+ Hello, World!
+
```
and a short Python script `hello.py`:
+
```python
import eel
-eel.init('web') # Give folder containing web files
+# Set web files folder and optionally specify which file types to check for eel.expose()
+# *Default allowed_extensions are: ['.js', '.html', '.txt', '.htm', '.xhtml']
+eel.init('web', allowed_extensions=['.js', '.html'])
@eel.expose # Expose this function to Javascript
def say_hello_py(x):
@@ -138,77 +220,94 @@ eel.start('hello.html') # Start (this blocks and enters loop)
```
If we run the Python script (`python hello.py`), then a browser window will open displaying `hello.html`, and we will see...
+
```
Hello from Python World!
Hello from Javascript World!
```
+
...in the terminal, and...
+
```
Hello from Javascript World!
Hello from Python World!
```
-...in the browser console (press F12 to open).
+
+...in the browser console (press F12 to open).
You will notice that in the Python code, the Javascript function is called before the browser window is even started - any early calls like this are queued up and then sent once the websocket has been established.
-#### Return values
+### Return values
+
+While we want to think of our code as comprising a single application, the Python interpreter and the browser window run in separate processes. This can make communicating back and forth between them a bit of a mess, especially if we always had to explicitly _send_ values from one side to the other.
-While we want to think of our code as comprising a single application, the Python interpreter and the browser window run in separate processes. This can make communicating back and forth between them a bit of a mess, especially if we always had to explicitly *send* values from one side to the other.
+Eel supports two ways of retrieving _return values_ from the other side of the app, which helps keep the code concise.
-Eel supports two ways of retrieving *return values* from the other side of the app, which helps keep the code concise.
+To prevent hanging forever on the Python side, a timeout has been put in place for trying to retrieve values from
+the JavaScript side, which defaults to 10000 milliseconds (10 seconds). This can be changed with the `_js_result_timeout` parameter to `eel.init`. There is no corresponding timeout on the JavaScript side.
-##### Callbacks
+#### 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:
+
```javascript
eel.expose(js_random);
function js_random() {
return Math.random();
}
```
+
Then in Python we can retrieve random values from the Javascript side like so:
+
```python
def print_num(n):
print('Got this from Javascript:', n)
-# Call Javascript function, and pass explicit callback function
+# Call Javascript function, and pass explicit callback function
eel.js_random()(print_num)
# Do the same with an inline lambda as callback
eel.js_random()(lambda n: print('Got this from Javascript:', n))
```
+
(It works exactly the same the other way around).
-##### Synchronous returns
+#### Synchronous returns
In most situations, the calls to the other side are to quickly retrieve some piece of data, such as the state of a widget or contents of an input field. In these cases it is more convenient to just synchronously wait a few milliseconds then continue with your code, rather than breaking the whole thing up into callbacks.
To synchronously retrieve the return value, simply pass nothing to the second set of brackets. So in Python we would write:
+
```python
-n = eel.js_random()() # This immeadiately returns the value
+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.
-In Javascript, the language doesn't allow to us 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:
+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:
+
```javascript
async function run() {
// Inside a function marked 'async' we can use the 'await' keyword.
-
- let n = await eel.py_random()(); // Must prefix call with 'await', otherwise it's the same syntax
- console.log('Got this from Python: ' + n);
+
+ let n = await eel.py_random()(); // Must prefix call with 'await', otherwise it's the same syntax
+ console.log("Got this from Python: " + n);
}
run();
```
-### Asynchronous Python
+## Asynchronous Python
+
+Eel is built on Bottle and Gevent, which provide an asynchronous event loop similar to Javascript. A lot of Python's standard library implicitly assumes there is a single execution thread - to deal with this, Gevent can "[monkey patch](https://en.wikipedia.org/wiki/Monkey_patch)" many of the standard modules such as `time`. ~~This monkey patching is done automatically when you call `import eel`~~. If you need monkey patching you should `import gevent.monkey` and call `gevent.monkey.patch_all()` _before_ you `import eel`. Monkey patching can interfere with things like debuggers so should be avoided unless necessary.
+
+For most cases you should be fine by avoiding using `time.sleep()` and instead using the versions provided by `gevent`. For convenience, the two most commonly needed gevent methods, `sleep()` and `spawn()` are provided directly from Eel (to save importing `time` and/or `gevent` as well).
-Eel is built on Bottle and Gevent. If you use Python's built in `thread.sleep()` you will block the entire interpreter globally. Instead you should use the methods provided by Gevent. For simplicity, the two most commonly needed methods, `sleep()` and `spawn()` are provided directly from Eel.
+In this example...
-For example:
```python
import eel
eel.init('web')
@@ -216,30 +315,39 @@ eel.init('web')
def my_other_thread():
while True:
print("I'm a thread")
- eel.sleep(1.0) # Must use eel.sleep()
-
+ eel.sleep(1.0) # Use eel.sleep(), not time.sleep()
+
eel.spawn(my_other_thread)
eel.start('main.html', block=False) # Don't block on this call
while True:
print("I'm a main loop")
- eel.sleep(1.0) # Must use eel.sleep()
+ eel.sleep(1.0) # Use eel.sleep(), not time.sleep()
```
-We would then have three threads (greenlets) running;
+
+...we would then have three "threads" (greenlets) running;
+
1. Eel's internal thread for serving the web folder
2. The `my_other_thread` method, repeatedly printing **"I'm a thread"**
3. The main Python thread, which would be stuck in the final `while` loop, repeatedly printing **"I'm a main loop"**
-### Building a distributable binary
+## Building distributable binary with PyInstaller
+
+If you want to package your app into a program that can be run on a computer without a Python interpreter installed, you should use **PyInstaller**.
+
+1. Configure a virtualenv with desired Python version and minimum necessary Python packages
+2. Install PyInstaller `pip install PyInstaller`
+3. In your app's folder, run `python -m eel [your_main_script] [your_web_folder]` (for example, you might run `python -m eel hello.py web`)
+4. This will create a new folder `dist/`
+5. Valid PyInstaller flags can be passed through, such as excluding modules with the flag: `--exclude module_name`. For example, you might run `python -m eel file_access.py web --exclude win32com --exclude numpy --exclude cryptography`
+6. When happy that your app is working correctly, add `--onefile --noconsole` flags to build a single executable file
+
+Consult the [documentation for PyInstaller](http://PyInstaller.readthedocs.io/en/stable/) for more options.
-If you want to package your app into a program that can be run on a computer without a Python interpreter installed, you should use **pyinstaller**.
+## Microsoft Edge
-1. Install pyinstaller `pip install pyinstaller`
-2. In your app's folder, run `python -m eel [your_main_script] [your_web_folder]` (for example, you might run `python -m eel hello.py web`)
-3. This will create a new folder `dist/`
-4. Check the contents of this folder for extra modules that pyinstaller is incorrectly including
-5. Exclude these using the flag `--exclude module_name`. For example, you might run `python -m eel file_access.py web --exclude win32com --exclude numpy --exclude cryptography`
-7. When you are happy that your app is working correctly, add `--onefile --noconsole` flags to build a single executable file
+For Windows 10 users, Microsoft Edge (`eel.start(.., mode='edge')`) is installed by default and a useful fallback if a preferred browser is not installed. See the examples:
-Consult the [documentation for pyinstaller](http://pyinstaller.readthedocs.io/en/stable/) for more options.
+- A Hello World example using Microsoft Edge: [examples/01 - hello_world-Edge/](https://github.com/ChrisKnott/Eel/tree/master/examples/01%20-%20hello_world-Edge)
+- Example implementing browser-fallbacks: [examples/07 - CreateReactApp/eel_CRA.py](https://github.com/ChrisKnott/Eel/tree/master/examples/07%20-%20CreateReactApp/eel_CRA.py)
diff --git a/eel/__init__.py b/eel/__init__.py
index 016bf968..34fc7ce1 100644
--- a/eel/__init__.py
+++ b/eel/__init__.py
@@ -1,33 +1,112 @@
-import json as jsn, bottle as btl, bottle.ext.websocket as wbs, gevent as gvt
-import re as rgx, os, subprocess as sps, eel.browsers as brw, random as rnd, sys
-import pkg_resources as pkg
-
-_eel_js_file = pkg.resource_filename('eel', 'eel.js')
-_eel_js = open(_eel_js_file, encoding='utf8').read()
-_websockets = []
-_call_return_values = {}
-_call_return_callbacks = {}
-_call_number = 0
-_exposed_functions = {}
-_js_functions = []
-_start_geometry = {}
-_mock_queue = []
-_mock_queue_done = set()
-_default_options = {
- 'mode': 'chrome-app',
- 'host': 'localhost',
- 'port': 8000
-}
+from __future__ import annotations
+from builtins import range
+import traceback
+from io import open
+from typing import Union, Any, Dict, List, Set, Tuple, Optional, Callable
+from typing_extensions import Literal
+from eel.types import OptionsDictT, WebSocketT
+import gevent as gvt
+import json as jsn
+import bottle as btl
+try:
+ import bottle_websocket as wbs
+except ImportError:
+ import bottle.ext.websocket as wbs
+import re as rgx
+import os
+import eel.browsers as brw
+import pyparsing as pp
+import random as rnd
+import sys
+import importlib_resources
+import socket
+import mimetypes
+
+
+mimetypes.add_type('application/javascript', '.js')
+
+# https://setuptools.pypa.io/en/latest/pkg_resources.html
+# Use of pkg_resources is deprecated in favor of importlib.resources
+# Migration guide: https://importlib-resources.readthedocs.io/en/latest/migration.html
+_eel_js_reference = importlib_resources.files('eel') / 'eel.js'
+with importlib_resources.as_file(_eel_js_reference) as _eel_js_path:
+ _eel_js: str = _eel_js_path.read_text(encoding='utf-8')
+
+_websockets: List[Tuple[Any, WebSocketT]] = []
+_call_return_values: Dict[Any, Any] = {}
+_call_return_callbacks: Dict[float, Tuple[Callable[..., Any], Optional[Callable[..., Any]]]] = {}
+_call_number: int = 0
+_exposed_functions: Dict[Any, Any] = {}
+_js_functions: List[Any] = []
+_mock_queue: List[Any] = []
+_mock_queue_done: Set[Any] = set()
+_shutdown: Optional[gvt.Greenlet] = None # Later assigned as global by _websocket_close()
+root_path: str # Later assigned as global by init()
+
+# The maximum time (in milliseconds) that Python will try to retrieve a return value for functions executing in JS
+# Can be overridden through `eel.init` with the kwarg `js_result_timeout` (default: 10000)
+_js_result_timeout: int = 10000
+
+# Attribute holding the start args from calls to eel.start()
+_start_args: OptionsDictT = {}
+
+# == Temporary (suppressible) error message to inform users of breaking API change for v1.0.0 ===
+api_error_message: str = '''
+----------------------------------------------------------------------------------
+ 'options' argument deprecated in v1.0.0, see https://github.com/ChrisKnott/Eel
+ To suppress this error, add 'suppress_error=True' to start() call.
+ This option will be removed in future versions
+----------------------------------------------------------------------------------
+'''
+# ===============================================================================================
+
# Public functions
-def expose(name_or_function = None):
- if name_or_function == None: # Deal with '@eel.expose()' - treat as '@eel.expose'
+
+def expose(name_or_function: Optional[Callable[..., Any]] = None) -> Callable[..., Any]:
+ '''Decorator to expose Python callables via Eel's JavaScript API.
+
+ When an exposed function is called, a callback function can be passed
+ immediately afterwards. This callback will be called asynchronously with
+ the return value (possibly `None`) when the Python function has finished
+ executing.
+
+ Blocking calls to the exposed function from the JavaScript side are only
+ possible using the :code:`await` keyword inside an :code:`async function`.
+ These still have to make a call to the response, i.e.
+ :code:`await eel.py_random()();` inside an :code:`async function` will work,
+ but just :code:`await eel.py_random();` will not.
+
+ :Example:
+
+ In Python do:
+
+ .. code-block:: python
+
+ @expose
+ def say_hello_py(name: str = 'You') -> None:
+ print(f'{name} said hello from the JavaScript world!')
+
+ In JavaScript do:
+
+ .. code-block:: javascript
+
+ eel.say_hello_py('Alice')();
+
+ Expected output on the Python console::
+
+ Alice said hello from the JavaScript world!
+
+ '''
+ # Deal with '@eel.expose()' - treat as '@eel.expose'
+ if name_or_function is None:
return expose
-
- if type(name_or_function) == str: # Called as '@eel.expose("my_name")'
- name = name_or_function
- def decorator(function):
+
+ if isinstance(name_or_function, str): # Called as '@eel.expose("my_name")'
+ name = name_or_function
+
+ def decorator(function: Callable[..., Any]) -> Any:
_expose(name, function)
return function
return decorator
@@ -35,152 +114,541 @@ def decorator(function):
function = name_or_function
_expose(function.__name__, function)
return function
-
-def init(path):
- global root_path, _js_functions
+
+
+# PyParsing grammar for parsing exposed functions in JavaScript code
+# Examples: `eel.expose(w, "func_name")`, `eel.expose(func_name)`, `eel.expose((function (e){}), "func_name")`
+EXPOSED_JS_FUNCTIONS: pp.ZeroOrMore = pp.ZeroOrMore(
+ pp.Suppress(
+ pp.SkipTo(pp.Literal('eel.expose('))
+ + pp.Literal('eel.expose(')
+ + pp.Optional(
+ pp.Or([pp.nestedExpr(), pp.Word(pp.printables, excludeChars=',')]) + pp.Literal(',')
+ )
+ )
+ + pp.Suppress(pp.Regex(r'["\']?'))
+ + pp.Word(pp.printables, excludeChars='"\')')
+ + pp.Suppress(pp.Regex(r'["\']?\s*\)')),
+)
+
+
+def init(
+ path: str,
+ allowed_extensions: List[str] = ['.js', '.html', '.txt', '.htm', '.xhtml', '.vue'],
+ js_result_timeout: int = 10000) -> None:
+ '''Initialise Eel.
+
+ This function should be called before :func:`start()` to initialise the
+ parameters for the web interface, such as the path to the files to be
+ served.
+
+ :param path: Sets the path on the filesystem where files to be served to
+ the browser are located, e.g. :file:`web`.
+ :param allowed_extensions: A list of filename extensions which will be
+ parsed for exposed eel functions which should be callable from python.
+ Files with extensions not in *allowed_extensions* will still be served,
+ but any JavaScript functions, even if marked as exposed, will not be
+ accessible from python.
+ *Default:* :code:`['.js', '.html', '.txt', '.htm', '.xhtml', '.vue']`.
+ :param js_result_timeout: How long Eel should be waiting to register the
+ results from a call to Eel's JavaScript API before before timing out.
+ *Default:* :code:`10000` milliseconds.
+ '''
+ global root_path, _js_functions, _js_result_timeout
root_path = _get_real_path(path)
js_functions = set()
for root, _, files in os.walk(root_path):
for name in files:
+ if not any(name.endswith(ext) for ext in allowed_extensions):
+ continue
+
try:
- with open(os.path.join(root, name), encoding='utf8') as file:
+ with open(os.path.join(root, name), encoding='utf-8') as file:
contents = file.read()
expose_calls = set()
- for expose_call in rgx.findall(r'eel\.expose\((.*)\)', contents):
- expose_call = expose_call.strip()
- assert rgx.findall(r'[\(=]', expose_call) == [], "eel.expose() call contains '(' or '='"
+ matches = EXPOSED_JS_FUNCTIONS.parseString(contents).asList()
+ for expose_call in matches:
+ # Verify that function name is valid
+ msg = "eel.expose() call contains '(' or '='"
+ assert rgx.findall(r'[\(=]', expose_call) == [], msg
expose_calls.add(expose_call)
js_functions.update(expose_calls)
except UnicodeDecodeError:
- pass # Probably an image
+ pass # Malformed file probably
_js_functions = list(js_functions)
for js_function in _js_functions:
_mock_js_function(js_function)
-def start(*start_urls, block=True, options={}, size=None, position=None, geometry={}):
- for k, v in _default_options.items():
- if k not in options:
- options[k] = v
-
- _start_geometry['default'] = {'size': size, 'position': position}
- _start_geometry['pages'] = geometry
-
- brw.open(start_urls, options)
-
- run_lambda = lambda: btl.run(host=options['host'], port=options['port'], server=wbs.GeventWebSocketServer, quiet=True)
- if block:
+ _js_result_timeout = js_result_timeout
+
+
+def start(
+ *start_urls: str,
+ mode: Optional[Union[str, Literal[False]]] = 'chrome',
+ host: str = 'localhost',
+ port: int = 8000,
+ block: bool = True,
+ jinja_templates: Optional[str] = None,
+ cmdline_args: List[str] = ['--disable-http-cache'],
+ size: Optional[Tuple[int, int]] = None,
+ position: Optional[Tuple[int, int]] = None,
+ geometry: Dict[str, Tuple[int, int]] = {},
+ close_callback: Optional[Callable[..., Any]] = None,
+ app_mode: bool = True,
+ all_interfaces: bool = False,
+ disable_cache: bool = True,
+ default_path: str = 'index.html',
+ app: btl.Bottle = btl.default_app(),
+ shutdown_delay: float = 1.0,
+ suppress_error: bool = False) -> None:
+ '''Start the Eel app.
+
+ Suppose you put all the frontend files in a directory called
+ :file:`web`, including your start page :file:`main.html`, then the app
+ is started like this:
+
+ .. code-block:: python
+
+ import eel
+ eel.init('web')
+ eel.start('main.html')
+
+ This will start a webserver on the default settings
+ (http://localhost:8000) and open a browser to
+ http://localhost:8000/main.html.
+
+ If Chrome or Chromium is installed then by default it will open that in
+ *App Mode* (with the `--app` cmdline flag), regardless of what the OS's
+ default browser is set to (it is possible to override this behaviour).
+
+ :param mode: What browser is used, e.g. :code:`'chrome'`,
+ :code:`'electron'`, :code:`'edge'`, :code:`'custom'`. Can also be
+ `None` or `False` to not open a window. *Default:* :code:`'chrome'`.
+ :param host: Hostname used for Bottle server. *Default:*
+ :code:`'localhost'`.
+ :param port: Port used for Bottle server. Use :code:`0` for port to be
+ picked automatically. *Default:* :code:`8000`.
+ :param block: Whether the call to :func:`start()` blocks the calling
+ thread. *Default:* `True`.
+ :param jinja_templates: Folder for :mod:`jinja2` templates, e.g.
+ :file:`my_templates`. *Default:* `None`.
+ :param cmdline_args: A list of strings to pass to the command starting the
+ browser. For example, we might add extra flags to Chrome with
+ :code:`eel.start('main.html', mode='chrome-app', port=8080,
+ cmdline_args=['--start-fullscreen', '--browser-startup-dialog'])`.
+ *Default:* :code:`[]`.
+ :param size: Tuple specifying the (width, height) of the main window in
+ pixels. *Default:* `None`.
+ :param position: Tuple specifying the (left, top) position of the main
+ window in pixels. *Default*: `None`.
+ :param geometry: A dictionary of specifying the size/position for all
+ windows. The keys should be the relative path of the page, and the
+ values should be a dictionary of the form
+ :code:`{'size': (200, 100), 'position': (300, 50)}`. *Default:*
+ :code:`{}`.
+ :param close_callback: A lambda or function that is called when a websocket
+ or 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 the other websockets that are still open.
+ *Default:* `None`.
+ :param app_mode: Whether to run Chrome/Edge in App Mode. You can also
+ specify *mode* as :code:`mode='chrome-app'` as a shorthand to start
+ Chrome in App Mode.
+ :param all_interfaces: Whether to allow the :mod:`bottle` server to listen
+ for connections on all interfaces.
+ :param disable_cache: Sets the no-store response header when serving
+ assets.
+ :param default_path: The default file to retrieve for the root URL.
+ :param app: An instance of :class:`bottle.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 *app* is not a :class:`bottle.Bottle` instance,
+ you will need to call :code:`eel.register_eel_routes(app)` on your
+ custom app instance.
+ :param 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. *Default:* :code:`1.0` seconds.
+ :param suppress_error: Temporary (suppressible) error message to inform
+ users of breaking API change for v1.0.0. Set to `True` to suppress
+ the error message.
+ '''
+ _start_args.update({
+ 'mode': mode,
+ 'host': host,
+ 'port': port,
+ 'block': block,
+ 'jinja_templates': jinja_templates,
+ 'cmdline_args': cmdline_args,
+ 'size': size,
+ 'position': position,
+ 'geometry': geometry,
+ 'close_callback': close_callback,
+ 'app_mode': app_mode,
+ 'all_interfaces': all_interfaces,
+ 'disable_cache': disable_cache,
+ 'default_path': default_path,
+ 'app': app,
+ 'shutdown_delay': shutdown_delay,
+ 'suppress_error': suppress_error,
+ })
+
+ if _start_args['port'] == 0:
+ sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+ sock.bind(('localhost', 0))
+ _start_args['port'] = sock.getsockname()[1]
+ sock.close()
+
+ if _start_args['jinja_templates'] is not None:
+ from jinja2 import Environment, FileSystemLoader, select_autoescape
+ if not isinstance(_start_args['jinja_templates'], str):
+ raise TypeError("'jinja_templates' start_arg/option must be of type str")
+ templates_path = os.path.join(root_path, _start_args['jinja_templates'])
+ _start_args['jinja_env'] = Environment(
+ loader=FileSystemLoader(templates_path),
+ autoescape=select_autoescape(['html', 'xml'])
+ )
+
+ # verify shutdown_delay is correct value
+ if not isinstance(_start_args['shutdown_delay'], (int, float)):
+ raise ValueError(
+ '`shutdown_delay` must be a number, '
+ 'got a {}'.format(type(_start_args['shutdown_delay']))
+ )
+
+ # Launch the browser to the starting URLs
+ show(*start_urls)
+
+ def run_lambda() -> None:
+ if _start_args['all_interfaces'] is True:
+ HOST = '0.0.0.0'
+ else:
+ if not isinstance(_start_args['host'], str):
+ raise TypeError("'host' start_arg/option must be of type str")
+ HOST = _start_args['host']
+
+ app = _start_args['app']
+
+ if isinstance(app, btl.Bottle):
+ register_eel_routes(app)
+ else:
+ register_eel_routes(btl.default_app())
+
+ btl.run(
+ host=HOST,
+ port=_start_args['port'],
+ server=wbs.GeventWebSocketServer,
+ quiet=True,
+ app=app) # Always returns None
+
+ # Start the webserver
+ if _start_args['block']:
run_lambda()
else:
spawn(run_lambda)
-def sleep(seconds):
+
+def show(*start_urls: str) -> None:
+ '''Show the specified URL(s) in the browser.
+
+ Suppose you have two files in your :file:`web` folder. The file
+ :file:`hello.html` regularly includes :file:`eel.js` and provides
+ interactivity, and the file :file:`goodbye.html` does not include
+ :file:`eel.js` and simply provides plain HTML content not reliant on Eel.
+
+ First, we defien a callback function to be called when the browser
+ window is closed:
+
+ .. code-block:: python
+
+ def last_calls():
+ eel.show('goodbye.html')
+
+ Now we initialise and start Eel, with a :code:`close_callback` to our
+ function:
+
+ ..code-block:: python
+
+ eel.init('web')
+ eel.start('hello.html', mode='chrome-app', close_callback=last_calls)
+
+ When the websocket from :file:`hello.html` is closed (e.g. because the
+ user closed the browser window), Eel will wait *shutdown_delay* seconds
+ (by default 1 second), then call our :code:`last_calls()` function, which
+ opens another window with the :file:`goodbye.html` shown before our Eel app
+ terminates.
+
+ :param start_urls: One or more URLs to be opened.
+ '''
+ brw.open(list(start_urls), _start_args)
+
+
+def sleep(seconds: Union[int, float]) -> None:
+ '''A non-blocking sleep call compatible with the Gevent event loop.
+
+ .. note::
+ While this function simply wraps :func:`gevent.sleep()`, it is better
+ to call :func:`eel.sleep()` in your eel app, as this will ensure future
+ compatibility in case the implementation of Eel should change in some
+ respect.
+
+ :param seconds: The number of seconds to sleep.
+ '''
gvt.sleep(seconds)
-def spawn(function):
- gvt.spawn(function)
-
+
+def spawn(function: Callable[..., Any], *args: Any, **kwargs: Any) -> gvt.Greenlet:
+ '''Spawn a new Greenlet.
+
+ Calling this function will spawn a new :class:`gevent.Greenlet` running
+ *function* asynchronously.
+
+ .. caution::
+ If you spawn your own Greenlets to run in addition to those spawned by
+ Eel's internal core functionality, you will have to ensure that those
+ Greenlets will terminate as appropriate (either by returning or by
+ being killed via Gevent's kill mechanism), otherwise your app may not
+ terminate correctly when Eel itself terminates.
+
+ :param function: The function to be called and run as the Greenlet.
+ :param *args: Any positional arguments that should be passed to *function*.
+ :param **kwargs: Any key-word arguments that should be passed to
+ *function*.
+ '''
+ return gvt.spawn(function, *args, **kwargs)
+
+
# Bottle Routes
-@btl.route('/eel.js')
-def _eel():
- page = _eel_js.replace('/** _py_functions **/', '_py_functions: %s,' % list(_exposed_functions.keys()))
- page = page.replace('/** _start_geometry **/', '_start_geometry: %s,' % jsn.dumps(_start_geometry))
+
+def _eel() -> str:
+ start_geometry = {'default': {'size': _start_args['size'],
+ 'position': _start_args['position']},
+ 'pages': _start_args['geometry']}
+
+ page = _eel_js.replace('/** _py_functions **/',
+ '_py_functions: %s,' % list(_exposed_functions.keys()))
+ page = page.replace('/** _start_geometry **/',
+ '_start_geometry: %s,' % _safe_json(start_geometry))
+ btl.response.content_type = 'application/javascript'
+ _set_response_headers(btl.response)
return page
-
-@btl.route('/')
-def _static(path):
- return btl.static_file(path, root=root_path)
-@btl.get('/eel', apply=[wbs.websocket])
-def _websocket(ws):
+
+def _root() -> btl.Response:
+ if not isinstance(_start_args['default_path'], str):
+ raise TypeError("'default_path' start_arg/option must be of type str")
+ return _static(_start_args['default_path'])
+
+
+def _static(path: str) -> btl.Response:
+ response = None
+ if 'jinja_env' in _start_args and 'jinja_templates' in _start_args:
+ if not isinstance(_start_args['jinja_templates'], str):
+ raise TypeError("'jinja_templates' start_arg/option must be of type str")
+ template_prefix = _start_args['jinja_templates'] + '/'
+ if path.startswith(template_prefix):
+ n = len(template_prefix)
+ template = _start_args['jinja_env'].get_template(path[n:])
+ response = btl.HTTPResponse(template.render())
+
+ if response is None:
+ response = btl.static_file(path, root=root_path)
+
+ _set_response_headers(response)
+ return response
+
+
+def _websocket(ws: WebSocketT) -> None:
global _websockets
- _websockets += [ws]
-
+
for js_function in _js_functions:
_import_js_function(js_function)
-
+
page = btl.request.query.page
if page not in _mock_queue_done:
for call in _mock_queue:
- ws.send(jsn.dumps(call))
+ _repeated_send(ws, _safe_json(call))
_mock_queue_done.add(page)
-
+
+ _websockets += [(page, ws)]
+
while True:
msg = ws.receive()
- if msg != None:
+ if msg is not None:
message = jsn.loads(msg)
- if 'call' in message:
- return_val = _exposed_functions[message['name']](*message['args'])
- ws.send(jsn.dumps({'return': message['call'], 'value': return_val}))
- elif 'return' in message:
- call_id = message['return']
- if call_id in _call_return_callbacks:
- callback = _call_return_callbacks.pop(call_id)
- callback(message['value'])
- else:
- _call_return_values[call_id] = message['value']
- else:
- print('Invalid message received: ', message)
+ spawn(_process_message, message, ws)
else:
- _websockets.remove(ws)
+ _websockets.remove((page, ws))
break
-
- _websocket_close()
-
+
+ _websocket_close(page)
+
+
+BOTTLE_ROUTES: Dict[str, Tuple[Callable[..., Any], Dict[Any, Any]]] = {
+ "/eel.js": (_eel, dict()),
+ "/": (_root, dict()),
+ "/": (_static, dict()),
+ "/eel": (_websocket, dict(apply=[wbs.websocket]))
+}
+
+
+def register_eel_routes(app: btl.Bottle) -> None:
+ '''Register the required eel routes with `app`.
+
+ .. note::
+
+ :func:`eel.register_eel_routes()` is normally invoked implicitly by
+ :func:`eel.start()` and does not need to be called explicitly in most
+ cases. Registering the eel routes explicitly is only needed if you are
+ passing something other than an instance of :class:`bottle.Bottle` to
+ :func:`eel.start()`.
+
+ :Example:
+
+ >>> app = bottle.Bottle()
+ >>> eel.register_eel_routes(app)
+ >>> middleware = beaker.middleware.SessionMiddleware(app)
+ >>> eel.start(app=middleware)
+
+ '''
+ for route_path, route_params in BOTTLE_ROUTES.items():
+ route_func, route_kwargs = route_params
+ app.route(path=route_path, callback=route_func, **route_kwargs)
+
+
# Private functions
-def _get_real_path(path):
+
+def _safe_json(obj: Any) -> str:
+ return jsn.dumps(obj, default=lambda o: None)
+
+
+def _repeated_send(ws: WebSocketT, msg: str) -> None:
+ for attempt in range(100):
+ try:
+ ws.send(msg)
+ break
+ except Exception:
+ sleep(0.001)
+
+
+def _process_message(message: Dict[str, Any], ws: WebSocketT) -> None:
+ if 'call' in message:
+ error_info = {}
+ try:
+ return_val = _exposed_functions[message['name']](*message['args'])
+ status = 'ok'
+ except Exception as e:
+ err_traceback = traceback.format_exc()
+ traceback.print_exc()
+ return_val = None
+ status = 'error'
+ error_info['errorText'] = repr(e)
+ error_info['errorTraceback'] = err_traceback
+ _repeated_send(ws, _safe_json({ 'return': message['call'],
+ 'status': status,
+ 'value': return_val,
+ 'error': error_info,}))
+ elif 'return' in message:
+ call_id = message['return']
+ if call_id in _call_return_callbacks:
+ callback, error_callback = _call_return_callbacks.pop(call_id)
+ if message['status'] == 'ok':
+ callback(message['value'])
+ elif message['status'] == 'error' and error_callback is not None:
+ error_callback(message['error'], message['stack'])
+ else:
+ _call_return_values[call_id] = message['value']
+
+ else:
+ print('Invalid message received: ', message)
+
+
+def _get_real_path(path: str) -> str:
if getattr(sys, 'frozen', False):
- return os.path.join(sys._MEIPASS, path)
+ return os.path.join(sys._MEIPASS, path) # type: ignore # sys._MEIPASS is dynamically added by PyInstaller
else:
return os.path.abspath(path)
-def _mock_js_function(f):
+
+def _mock_js_function(f: str) -> None:
exec('%s = lambda *args: _mock_call("%s", args)' % (f, f), globals())
-
-def _import_js_function(f):
+
+
+def _import_js_function(f: str) -> None:
exec('%s = lambda *args: _js_call("%s", args)' % (f, f), globals())
-
-def _call_object(name, args):
+
+
+def _call_object(name: str, args: Any) -> Dict[str, Any]:
global _call_number
_call_number += 1
- call_id = _call_number + rnd.random()
+ call_id = _call_number + rnd.random()
return {'call': call_id, 'name': name, 'args': args}
-def _mock_call(name, args):
+
+def _mock_call(name: str, args: Any) -> Callable[[Optional[Callable[..., Any]], Optional[Callable[..., Any]]], Any]:
call_object = _call_object(name, args)
global _mock_queue
_mock_queue += [call_object]
return _call_return(call_object)
-
-def _js_call(name, args):
- call_object = _call_object(name, args)
- for ws in _websockets:
- ws.send(jsn.dumps(call_object))
+
+
+def _js_call(name: str, args: Any) -> Callable[[Optional[Callable[..., Any]], Optional[Callable[..., Any]]], Any]:
+ call_object = _call_object(name, args)
+ for _, ws in _websockets:
+ _repeated_send(ws, _safe_json(call_object))
return _call_return(call_object)
-def _call_return(call):
- call_id, name, args = call['call'], call['name'], call['args']
- def return_func(callback = None):
- if callback != None:
- _call_return_callbacks[call_id] = callback
+
+def _call_return(call: Dict[str, Any]) -> Callable[[Optional[Callable[..., Any]], Optional[Callable[..., Any]]], Any]:
+ global _js_result_timeout
+ call_id = call['call']
+
+ def return_func(callback: Optional[Callable[..., Any]] = None,
+ error_callback: Optional[Callable[..., Any]] = None) -> Any:
+ if callback is not None:
+ _call_return_callbacks[call_id] = (callback, error_callback)
else:
- for w in range(10000):
+ for w in range(_js_result_timeout):
if call_id in _call_return_values:
return _call_return_values.pop(call_id)
sleep(0.001)
return return_func
-
-def _expose(name, function):
- assert name not in _exposed_functions, 'Already exposed function with name "%s"' % name
+
+
+def _expose(name: str, function: Callable[..., Any]) -> None:
+ msg = 'Already exposed function with name "%s"' % name
+ assert name not in _exposed_functions, msg
_exposed_functions[name] = function
-def _websocket_close():
- # a websocket just closed
- # TODO: user definable behavior here
- sleep(1.0)
+
+def _detect_shutdown() -> None:
if len(_websockets) == 0:
sys.exit()
-
\ No newline at end of file
+
+
+def _websocket_close(page: str) -> None:
+ global _shutdown
+
+ close_callback = _start_args.get('close_callback')
+
+ if close_callback is not None:
+ if not callable(close_callback):
+ raise TypeError("'close_callback' start_arg/option must be callable or None")
+ sockets = [p for _, p in _websockets]
+ close_callback(page, sockets)
+ else:
+ if isinstance(_shutdown, gvt.Greenlet):
+ _shutdown.kill()
+
+ _shutdown = gvt.spawn_later(_start_args['shutdown_delay'], _detect_shutdown)
+
+
+def _set_response_headers(response: btl.Response) -> None:
+ if _start_args['disable_cache']:
+ # https://stackoverflow.com/a/24748094/280852
+ response.set_header('Cache-Control', 'no-store')
diff --git a/eel/__main__.py b/eel/__main__.py
index 42a1a6e2..74910995 100644
--- a/eel/__main__.py
+++ b/eel/__main__.py
@@ -1,18 +1,40 @@
-import sys, pkg_resources as pkg, PyInstaller.__main__ as pyi, os
+from __future__ import annotations
+import pkg_resources as pkg
+import PyInstaller.__main__ as pyi
+import os
+from argparse import ArgumentParser, Namespace
+from typing import List
-args = sys.argv[1:]
-main_script = args.pop(0)
-web_folder = args.pop(0)
+parser: ArgumentParser = ArgumentParser(description="""
+Eel is a little Python library for making simple Electron-like offline HTML/JS GUI apps,
+ with full access to Python capabilities and libraries.
+""")
+parser.add_argument(
+ "main_script",
+ type=str,
+ help="Main python file to run app from"
+)
+parser.add_argument(
+ "web_folder",
+ type=str,
+ help="Folder including all web files including file as html, css, ico, etc."
+)
+args: Namespace
+unknown_args: List[str]
+args, unknown_args = parser.parse_known_args()
+main_script: str = args.main_script
+web_folder: str = args.web_folder
-print("Building executable with main script '%s' and web folder '%s'...\n" % (main_script, web_folder))
+print("Building executable with main script '%s' and web folder '%s'...\n" %
+ (main_script, web_folder))
-eel_js_file = pkg.resource_filename('eel', 'eel.js')
-js_file_arg = '%s%seel' % (eel_js_file, os.pathsep)
-web_folder_arg = '%s%s%s' % (web_folder, os.pathsep, web_folder)
-
-needed_args = ['--hidden-import', 'bottle_websocket', '--add-data', js_file_arg, '--add-data', web_folder_arg]
-full_args = [main_script] + needed_args + args
+eel_js_file: str = pkg.resource_filename('eel', 'eel.js')
+js_file_arg: str = '%s%seel' % (eel_js_file, os.pathsep)
+web_folder_arg: str = '%s%s%s' % (web_folder, os.pathsep, web_folder)
+needed_args: List[str] = ['--hidden-import', 'bottle_websocket',
+ '--add-data', js_file_arg, '--add-data', web_folder_arg]
+full_args: List[str] = [main_script] + needed_args + unknown_args
print('Running:\npyinstaller', ' '.join(full_args), '\n')
pyi.run(full_args)
diff --git a/eel/browsers.py b/eel/browsers.py
index 9ea7f22c..183dd905 100644
--- a/eel/browsers.py
+++ b/eel/browsers.py
@@ -1,66 +1,93 @@
-import webbrowser as wbr, sys, subprocess as sps, os
-
-def open(start_pages, options):
- base_url = 'http://%s:%d/' % (options['host'], options['port'])
- start_urls = [base_url + page for page in start_pages]
-
- if options['mode'] in ['chrome', 'chrome-app']:
- chrome_path = find_chrome()
- if chrome_path != None:
- if options['mode'] == 'chrome-app':
- for url in start_urls:
- sps.Popen([chrome_path, '--disable-gpu', '--app=%s' % url])
- else:
- sps.Popen([chrome_path, '--disable-gpu', '--new-window'] + start_urls)
+from __future__ import annotations
+import subprocess as sps
+import webbrowser as wbr
+from typing import Union, List, Dict, Iterable, Optional
+from types import ModuleType
+
+from eel.types import OptionsDictT
+import eel.chrome as chm
+import eel.electron as ele
+import eel.edge as edge
+import eel.msIE as ie
+#import eel.firefox as ffx TODO
+#import eel.safari as saf TODO
+
+_browser_paths: Dict[str, str] = {}
+_browser_modules: Dict[str, ModuleType] = {'chrome': chm,
+ 'electron': ele,
+ 'edge': edge,
+ 'msie':ie}
+
+
+def _build_url_from_dict(page: Dict[str, str], options: OptionsDictT) -> str:
+ scheme = page.get('scheme', 'http')
+ host = page.get('host', 'localhost')
+ port = page.get('port', options["port"])
+ path = page.get('path', '')
+ if not isinstance(port, (int, str)):
+ raise TypeError("'port' option must be an integer")
+ return '%s://%s:%d/%s' % (scheme, host, int(port), path)
+
+
+def _build_url_from_string(page: str, options: OptionsDictT) -> str:
+ if not isinstance(options['port'], (int, str)):
+ raise TypeError("'port' option must be an integer")
+ base_url = 'http://%s:%d/' % (options['host'], int(options['port']))
+ return base_url + page
+
+
+def _build_urls(start_pages: Iterable[Union[str, Dict[str, str]]], options: OptionsDictT) -> List[str]:
+ urls: List[str] = []
+
+ for page in start_pages:
+ if isinstance(page, dict):
+ url = _build_url_from_dict(page, options)
else:
- raise EnvironmentError("Can't find Chrome or Chromium installation")
- elif False:
- pass # TODO: Firefox...?
+ url = _build_url_from_string(page, options)
+ urls.append(url)
+
+ return urls
+
+
+def open(start_pages: Iterable[Union[str, Dict[str, str]]], options: OptionsDictT) -> None:
+ # Build full URLs for starting pages (including host and port)
+ start_urls = _build_urls(start_pages, options)
+
+ mode = options.get('mode')
+ if not isinstance(mode, (str, type(None))) and mode is not False:
+ raise TypeError("'mode' option must by either a string, False, or None")
+ if mode is None or mode is False:
+ # Don't open a browser
+ pass
+ elif mode == 'custom':
+ # Just run whatever command the user provided
+ if not isinstance(options['cmdline_args'], list):
+ raise TypeError("'cmdline_args' option must be of type List[str]")
+ sps.Popen(options['cmdline_args'],
+ stdout=sps.PIPE, stderr=sps.PIPE, stdin=sps.PIPE)
+ elif mode in _browser_modules:
+ # Run with a specific browser
+ browser_module = _browser_modules[mode]
+ path = _browser_paths.get(mode)
+ if path is None:
+ # Don't know this browser's path, try and find it ourselves
+ path = browser_module.find_path()
+ _browser_paths[mode] = path
+
+ if path is not None:
+ browser_module.run(path, options, start_urls)
+ else:
+ raise EnvironmentError("Can't find %s installation" % browser_module.name)
else:
- # Use system default browser
+ # Fall back to system default browser
for url in start_urls:
wbr.open(url)
-def find_chrome():
- if sys.platform in ['win32', 'win64']:
- return find_chrome_win()
- elif sys.platform == 'darwin':
- return find_chrome_mac()
- elif sys.platform.startswith('linux'):
- return find_chrome_linux()
- else:
- return None
-
-def find_chrome_mac():
- default_dir = r'/Applications/Google Chrome.app/Contents/MacOS/Google Chrome'
- if os.path.exists(default_dir):
- return default_dir
- return None
-
-def find_chrome_linux():
- import shutil as shu
- chrome_names = ['chromium-browser',
- 'chromium',
- 'google-chrome',
- 'google-chrome-stable']
-
- for name in chrome_names:
- chrome = shu.which(name)
- if chrome is not None:
- return chrome
- return None
-
-def find_chrome_win():
- import winreg as reg
- reg_path = r'SOFTWARE\Microsoft\Windows\CurrentVersion\App Paths\chrome.exe'
-
- for install_type in reg.HKEY_LOCAL_MACHINE, reg.HKEY_CURRENT_USER:
- try:
- reg_key = reg.OpenKey(install_type, reg_path, 0, reg.KEY_READ)
- chrome_path = reg.QueryValue(reg_key, None)
- except WindowsError:
- pass
- reg_key.Close()
-
- return chrome_path
+
+def set_path(browser_name: str, path: str) -> None:
+ _browser_paths[browser_name] = path
+
+
+def get_path(browser_name: str) -> Optional[str]:
+ return _browser_paths.get(browser_name)
diff --git a/eel/chrome.py b/eel/chrome.py
new file mode 100644
index 00000000..a8112f5d
--- /dev/null
+++ b/eel/chrome.py
@@ -0,0 +1,92 @@
+from __future__ import annotations
+import sys
+import os
+import subprocess as sps
+from shutil import which
+from typing import List, Optional
+from eel.types import OptionsDictT
+
+# Every browser specific module must define run(), find_path() and name like this
+
+name: str = 'Google Chrome/Chromium'
+
+def run(path: str, options: OptionsDictT, start_urls: List[str]) -> None:
+ if not isinstance(options['cmdline_args'], list):
+ raise TypeError("'cmdline_args' option must be of type List[str]")
+ if options['app_mode']:
+ for url in start_urls:
+ sps.Popen([path, '--app=%s' % url] +
+ options['cmdline_args'],
+ stdout=sps.PIPE, stderr=sps.PIPE, stdin=sps.PIPE)
+ else:
+ args: List[str] = options['cmdline_args'] + start_urls
+ sps.Popen([path, '--new-window'] + args,
+ stdout=sps.PIPE, stderr=sys.stderr, stdin=sps.PIPE)
+
+
+def find_path() -> Optional[str]:
+ if sys.platform in ['win32', 'win64']:
+ return _find_chrome_win()
+ elif sys.platform == 'darwin':
+ return _find_chrome_mac() or _find_chromium_mac()
+ elif sys.platform.startswith('linux'):
+ return _find_chrome_linux()
+ else:
+ return None
+
+
+def _find_chrome_mac() -> Optional[str]:
+ default_dir = r'/Applications/Google Chrome.app/Contents/MacOS/Google Chrome'
+ if os.path.exists(default_dir):
+ return default_dir
+ # use mdfind ci to locate Chrome in alternate locations and return the first one
+ name = 'Google Chrome.app'
+ alternate_dirs = [x for x in sps.check_output(["mdfind", name]).decode().split('\n') if x.endswith(name)]
+ if len(alternate_dirs):
+ return alternate_dirs[0] + '/Contents/MacOS/Google Chrome'
+ return None
+
+
+def _find_chromium_mac() -> Optional[str]:
+ default_dir = r'/Applications/Chromium.app/Contents/MacOS/Chromium'
+ if os.path.exists(default_dir):
+ return default_dir
+ # use mdfind ci to locate Chromium in alternate locations and return the first one
+ name = 'Chromium.app'
+ alternate_dirs = [x for x in sps.check_output(["mdfind", name]).decode().split('\n') if x.endswith(name)]
+ if len(alternate_dirs):
+ return alternate_dirs[0] + '/Contents/MacOS/Chromium'
+ return None
+
+
+def _find_chrome_linux() -> Optional[str]:
+ chrome_names = ['chromium-browser',
+ 'chromium',
+ 'google-chrome',
+ 'google-chrome-stable']
+
+ for name in chrome_names:
+ chrome = which(name)
+ if chrome is not None:
+ return chrome
+ return None
+
+
+def _find_chrome_win() -> Optional[str]:
+ import winreg as reg
+ reg_path = r'SOFTWARE\Microsoft\Windows\CurrentVersion\App Paths\chrome.exe'
+ chrome_path: Optional[str] = None
+
+ for install_type in reg.HKEY_CURRENT_USER, reg.HKEY_LOCAL_MACHINE:
+ try:
+ reg_key = reg.OpenKey(install_type, reg_path, 0, reg.KEY_READ)
+ chrome_path = reg.QueryValue(reg_key, None)
+ reg_key.Close()
+ if not os.path.isfile(chrome_path):
+ continue
+ except WindowsError:
+ chrome_path = None
+ else:
+ break
+
+ return chrome_path
diff --git a/eel/edge.py b/eel/edge.py
new file mode 100644
index 00000000..7d785233
--- /dev/null
+++ b/eel/edge.py
@@ -0,0 +1,28 @@
+from __future__ import annotations
+import platform
+import subprocess as sps
+import sys
+from typing import List
+
+from eel.types import OptionsDictT
+
+name: str = 'Edge'
+
+
+def run(_path: str, options: OptionsDictT, start_urls: List[str]) -> None:
+ if not isinstance(options['cmdline_args'], list):
+ raise TypeError("'cmdline_args' option must be of type List[str]")
+ args: List[str] = options['cmdline_args']
+ if options['app_mode']:
+ cmd = 'start msedge --app={} '.format(start_urls[0])
+ cmd = cmd + (" ".join(args))
+ sps.Popen(cmd, stdout=sys.stdout, stderr=sys.stderr, stdin=sps.PIPE, shell=True)
+ else:
+ cmd = "start msedge --new-window "+(" ".join(args)) +" "+(start_urls[0])
+ sps.Popen(cmd,stdout=sys.stdout, stderr=sys.stderr, stdin=sps.PIPE, shell=True)
+
+def find_path() -> bool:
+ if platform.system() == 'Windows':
+ return True
+
+ return False
diff --git a/eel/eel.js b/eel/eel.js
index 6fea3a14..cc824206 100644
--- a/eel/eel.js
+++ b/eel/eel.js
@@ -1,22 +1,36 @@
eel = {
+ _host: window.location.origin,
+
+ set_host: function (hostname) {
+ eel._host = hostname
+ },
+
expose: function(f, name) {
if(name === undefined){
name = f.toString();
let i = 'function '.length, j = name.indexOf('(');
name = name.substring(i, j).trim();
}
-
+
eel._exposed_functions[name] = f;
},
-
+
+ guid: function() {
+ return eel._guid;
+ },
+
// These get dynamically added by library when file is served
/** _py_functions **/
/** _start_geometry **/
+ _guid: ([1e7]+-1e3+-4e3+-8e3+-1e11).replace(/[018]/g, c =>
+ (c ^ crypto.getRandomValues(new Uint8Array(1))[0] & 15 >> c / 4).toString(16)
+ ),
+
_exposed_functions: {},
-
+
_mock_queue: [],
-
+
_mock_py_functions: function() {
for(let i = 0; i < eel._py_functions.length; i++) {
let name = eel._py_functions[i];
@@ -27,7 +41,7 @@ eel = {
}
}
},
-
+
_import_py_function: function(name) {
let func_name = name;
eel[name] = function() {
@@ -36,102 +50,124 @@ eel = {
return eel._call_return(call_object);
}
},
-
+
_call_number: 0,
-
+
_call_return_callbacks: {},
-
+
_call_object: function(name, args) {
let arg_array = [];
for(let i = 0; i < args.length; i++){
arg_array.push(args[i]);
}
-
+
let call_id = (eel._call_number += 1) + Math.random();
return {'call': call_id, 'name': name, 'args': arg_array};
},
-
+
_sleep: function(ms) {
return new Promise(resolve => setTimeout(resolve, ms));
},
-
+
_toJSON: function(obj) {
return JSON.stringify(obj, (k, v) => v === undefined ? null : v);
},
-
+
_call_return: function(call) {
return function(callback = null) {
if(callback != null) {
- eel._call_return_callbacks[call.call] = callback;
+ eel._call_return_callbacks[call.call] = {resolve: callback};
} else {
- return new Promise(function(resolve) {
- eel._call_return_callbacks[call.call] = resolve;
+ return new Promise(function(resolve, reject) {
+ eel._call_return_callbacks[call.call] = {resolve: resolve, reject: reject};
});
}
}
},
-
+
_position_window: function(page) {
let size = eel._start_geometry['default'].size;
let position = eel._start_geometry['default'].position;
-
+
if(page in eel._start_geometry.pages) {
- size = eel._start_geometry.pages.size;
- position = eel._start_geometry.pages.position;
+ size = eel._start_geometry.pages[page].size;
+ position = eel._start_geometry.pages[page].position;
}
-
+
if(size != null){
window.resizeTo(size[0], size[1]);
}
-
+
if(position != null){
window.moveTo(position[0], position[1]);
- }
+ }
},
-
+
_init: function() {
eel._mock_py_functions();
-
+
document.addEventListener("DOMContentLoaded", function(event) {
let page = window.location.pathname.substring(1);
eel._position_window(page);
-
- let websocket_addr = (window.location.origin + '/eel').replace('http', 'ws');
+
+ let websocket_addr = (eel._host + '/eel').replace('http', 'ws');
websocket_addr += ('?page=' + page);
eel._websocket = new WebSocket(websocket_addr);
-
+
eel._websocket.onopen = function() {
for(let i = 0; i < eel._py_functions.length; i++){
let py_function = eel._py_functions[i];
eel._import_py_function(py_function);
}
-
+
while(eel._mock_queue.length > 0) {
let call = eel._mock_queue.shift();
eel._websocket.send(eel._toJSON(call));
}
};
-
+
eel._websocket.onmessage = function (e) {
let message = JSON.parse(e.data);
if(message.hasOwnProperty('call') ) {
// Python making a function call into us
if(message.name in eel._exposed_functions) {
- let return_val = eel._exposed_functions[message.name](...message.args);
- eel._websocket.send(eel._toJSON({'return': message.call, 'value': return_val}));
+ try {
+ let return_val = eel._exposed_functions[message.name](...message.args);
+ eel._websocket.send(eel._toJSON({'return': message.call, 'status':'ok', 'value': return_val}));
+ } catch(err) {
+ debugger
+ eel._websocket.send(eel._toJSON(
+ {'return': message.call,
+ 'status':'error',
+ 'error': err.message,
+ 'stack': err.stack}));
+ }
}
} else if(message.hasOwnProperty('return')) {
// Python returning a value to us
if(message['return'] in eel._call_return_callbacks) {
- eel._call_return_callbacks[message['return']](message.value);
+ if(message['status']==='ok'){
+ eel._call_return_callbacks[message['return']].resolve(message.value);
+ }
+ else if(message['status']==='error' && eel._call_return_callbacks[message['return']].reject) {
+ eel._call_return_callbacks[message['return']].reject(message['error']);
+ }
}
} else {
throw 'Invalid message ' + message;
}
-
+
};
});
}
-}
+};
-eel._init();
\ No newline at end of file
+eel._init();
+
+if(typeof require !== 'undefined'){
+ // Avoid name collisions when using Electron, so jQuery etc work normally
+ window.nodeRequire = require;
+ delete window.require;
+ delete window.exports;
+ delete window.module;
+}
diff --git a/eel/electron.py b/eel/electron.py
new file mode 100644
index 00000000..4ff8fcc1
--- /dev/null
+++ b/eel/electron.py
@@ -0,0 +1,29 @@
+from __future__ import annotations
+import sys
+import os
+import subprocess as sps
+from shutil import which
+from typing import List, Optional
+
+from eel.types import OptionsDictT
+
+name: str = 'Electron'
+
+def run(path: str, options: OptionsDictT, start_urls: List[str]) -> None:
+ if not isinstance(options['cmdline_args'], list):
+ raise TypeError("'cmdline_args' option must be of type List[str]")
+ cmd = [path] + options['cmdline_args']
+ cmd += ['.', ';'.join(start_urls)]
+ sps.Popen(cmd, stdout=sys.stdout, stderr=sys.stderr, stdin=sps.PIPE)
+
+
+def find_path() -> Optional[str]:
+ if sys.platform in ['win32', 'win64']:
+ # It doesn't work well passing the .bat file to Popen, so we get the actual .exe
+ bat_path = which('electron')
+ if bat_path:
+ return os.path.join(bat_path, r'..\node_modules\electron\dist\electron.exe')
+ elif sys.platform in ['darwin', 'linux']:
+ # This should work fine...
+ return which('electron')
+ return None
diff --git a/eel/msIE.py b/eel/msIE.py
new file mode 100644
index 00000000..7f7f2e26
--- /dev/null
+++ b/eel/msIE.py
@@ -0,0 +1,20 @@
+import platform
+import subprocess as sps
+import sys
+from typing import List
+
+from eel.types import OptionsDictT
+
+name: str = 'MSIE'
+
+
+def run(_path: str, options: OptionsDictT, start_urls: List[str]) -> None:
+ cmd = 'start microsoft-edge:{}'.format(start_urls[0])
+ sps.Popen(cmd, stdout=sys.stdout, stderr=sys.stderr, stdin=sps.PIPE, shell=True)
+
+
+def find_path() -> bool:
+ if platform.system() == 'Windows':
+ return True
+
+ return False
diff --git a/eel/py.typed b/eel/py.typed
new file mode 100644
index 00000000..e69de29b
diff --git a/eel/types.py b/eel/types.py
new file mode 100644
index 00000000..0cd2d6ee
--- /dev/null
+++ b/eel/types.py
@@ -0,0 +1,42 @@
+from __future__ import annotations
+from typing import Union, Dict, List, Tuple, Callable, Optional, Any, TYPE_CHECKING
+from typing_extensions import Literal, TypedDict, TypeAlias
+from bottle import Bottle
+
+# This business is slightly awkward, but needed for backward compatibility,
+# because Python <3.10 doesn't support TypeAlias, jinja2 may not be available
+# at runtime, and geventwebsocket.websocket doesn't have type annotations so
+# that direct imports will raise an error.
+if TYPE_CHECKING:
+ from jinja2 import Environment
+ JinjaEnvironmentT: TypeAlias = Environment
+ from geventwebsocket.websocket import WebSocket
+ WebSocketT: TypeAlias = WebSocket
+else:
+ JinjaEnvironmentT: TypeAlias = Any
+ WebSocketT: TypeAlias = Any
+
+OptionsDictT = TypedDict(
+ 'OptionsDictT',
+ {
+ 'mode': Optional[Union[str, Literal[False]]],
+ 'host': str,
+ 'port': int,
+ 'block': bool,
+ 'jinja_templates': Optional[str],
+ 'cmdline_args': List[str],
+ 'size': Optional[Tuple[int, int]],
+ 'position': Optional[Tuple[int, int]],
+ 'geometry': Dict[str, Tuple[int, int]],
+ 'close_callback': Optional[Callable[..., Any]],
+ 'app_mode': bool,
+ 'all_interfaces': bool,
+ 'disable_cache': bool,
+ 'default_path': str,
+ 'app': Bottle,
+ 'shutdown_delay': float,
+ 'suppress_error': bool,
+ 'jinja_env': JinjaEnvironmentT,
+ },
+ total=False
+)
diff --git a/examples/01 - hello_world-Edge/hello.py b/examples/01 - hello_world-Edge/hello.py
new file mode 100644
index 00000000..965b9d5b
--- /dev/null
+++ b/examples/01 - hello_world-Edge/hello.py
@@ -0,0 +1,38 @@
+import os
+import platform
+import sys
+
+# Use latest version of Eel from parent directory
+sys.path.insert(1, '../../')
+import eel
+
+# Use the same static files as the original Example
+os.chdir(os.path.join('..', '01 - hello_world'))
+
+# Set web files folder and optionally specify which file types to check for eel.expose()
+eel.init('web', allowed_extensions=['.js', '.html'])
+
+
+@eel.expose # Expose this function to Javascript
+def say_hello_py(x):
+ print('Hello from %s' % x)
+
+
+say_hello_py('Python World!')
+eel.say_hello_js('Python World!') # Call a Javascript function
+
+# Launch example in Microsoft Edge only on Windows 10 and above
+if sys.platform in ['win32', 'win64'] and int(platform.release()) >= 10:
+ eel.start('hello.html', mode='edge')
+else:
+ raise EnvironmentError('Error: System is not Windows 10 or above')
+
+# # Launching Edge can also be gracefully handled as a fall back
+# try:
+# eel.start('hello.html', mode='chrome-app', size=(300, 200))
+# except EnvironmentError:
+# # If Chrome isn't found, fallback to Microsoft Edge on Win10 or greater
+# if sys.platform in ['win32', 'win64'] and int(platform.release()) >= 10:
+# eel.start('hello.html', mode='edge')
+# else:
+# raise
diff --git a/examples/01 - hello_world/hello.py b/examples/01 - hello_world/hello.py
index f67fd8a2..eef64833 100644
--- a/examples/01 - hello_world/hello.py
+++ b/examples/01 - hello_world/hello.py
@@ -1,6 +1,7 @@
import eel
-eel.init('web') # Give folder containing web files
+# Set web files folder
+eel.init('web')
@eel.expose # Expose this function to Javascript
def say_hello_py(x):
@@ -9,4 +10,4 @@ def say_hello_py(x):
say_hello_py('Python World!')
eel.say_hello_js('Python World!') # Call a Javascript function
-eel.start('hello.html', size=(300, 200)) # Start
+eel.start('hello.html', size=(300, 200)) # Start
diff --git a/examples/02 - callbacks/callbacks.py b/examples/02 - callbacks/callbacks.py
index 75e342ce..408496bd 100644
--- a/examples/02 - callbacks/callbacks.py
+++ b/examples/02 - callbacks/callbacks.py
@@ -1,4 +1,5 @@
-import eel, random
+import eel
+import random
eel.init('web')
@@ -6,13 +7,31 @@
def py_random():
return random.random()
+@eel.expose
+def py_exception(error):
+ if error:
+ raise ValueError("Test")
+ else:
+ return "No Error"
+
def print_num(n):
print('Got this from Javascript:', n)
+
+def print_num_failed(error, stack):
+ print("This is an example of what javascript errors would look like:")
+ print("\tError: ", error)
+ print("\tStack: ", stack)
+
# Call Javascript function, and pass explicit callback function
eel.js_random()(print_num)
# Do the same with an inline callback
eel.js_random()(lambda n: print('Got this from Javascript:', n))
+# Show error handling
+eel.js_with_error()(print_num, print_num_failed)
+
+
eel.start('callbacks.html', size=(400, 300))
+
diff --git a/examples/02 - callbacks/web/callbacks.html b/examples/02 - callbacks/web/callbacks.html
index 17aea7d8..1bfa8e3b 100644
--- a/examples/02 - callbacks/web/callbacks.html
+++ b/examples/02 - callbacks/web/callbacks.html
@@ -1,4 +1,4 @@
-
+
Callbacks Demo
@@ -10,6 +10,12 @@
function js_random() {
return Math.random();
}
+
+ eel.expose(js_with_error);
+ function js_with_error() {
+ var test = 0;
+ test.something("does not exist");
+ }
function print_num(n) {
console.log('Got this from Python: ' + n);
@@ -20,11 +26,29 @@
// Do the same with an inline callback
eel.py_random()(n => console.log('Got this from Python: ' + n));
-
+
+ // show usage with promises
+ // show no error
+ eel.py_exception(false)().then((result) => {
+ // this will execute since we said no error
+ console.log("No Error")
+ }).catch((result) => {
+ console.log("This won't be seen if no error")
+ }
+ );
+ // show if an error occurrs
+ eel.py_exception(true)().then((result) => {
+ // this will not execute
+ console.log("No Error")
+ }).catch((result) => {
+ console.log("This is the repr(e) for an exception " + result.errorText);
+ console.log("This is the full traceback:\n" + result.errorTraceback);
+ }
+ )
Callbacks demo
-
\ No newline at end of file
+