0
# Eel
1

2
A little Python library for making simple Electron-like offline HTML/JS GUI apps, with full access to Python capabilities and libraries. Eel hosts a local webserver, then lets you annotate functions in Python so that they can be called from JavaScript, and vice versa.
3

4
## Package Information
5

6
- **Package Name**: Eel
7
- **Language**: Python
8
- **Installation**: `pip install eel`
9
- **Optional Dependencies**: `pip install eel[jinja2]` (for HTML templating)
10

11
## Core Imports
12

13
```python
14
import eel
15
```
16

17
Function-specific imports:
18

19
```python
20
from eel import expose, init, start, show, sleep, spawn
21
```
22

23
## Basic Usage
24

25
```python
26
import eel
27

28
# Set web files folder
29
eel.init('web')
30

31
# Expose Python function to JavaScript
32
@eel.expose
33
def say_hello_py(name):
34
    print(f'Hello from {name}')
35

36
# Start the app with a browser window
37
eel.start('index.html', size=(800, 600))
38
```
39

40
## Architecture
41

42
Eel bridges Python and JavaScript through a WebSocket connection:
43

44
- **Local Web Server**: Bottle-based server hosting web files and WebSocket endpoint
45
- **Function Exposure**: Python functions decorated with `@eel.expose` become callable from JavaScript
46
- **Bidirectional Communication**: JavaScript functions exposed via `eel.expose()` become callable from Python
47
- **Browser Integration**: Automatic detection and launching of Chrome, Edge, Electron, or system browser
48
- **Event Loop**: Gevent-based asynchronous handling for non-blocking operations
49

50
This design enables seamless integration between Python's scientific computing capabilities and JavaScript's visualization libraries while maintaining the simplicity needed for desktop GUI applications.
51

52
## Capabilities
53

54
### Core Application Functions
55

56
Essential functions for initializing and running Eel applications, including setup, function exposure, and application lifecycle management.
57

58
```python { .api }
59
def init(path: str, allowed_extensions: List[str] = ['.js', '.html', '.txt', '.htm', '.xhtml', '.vue'], js_result_timeout: int = 10000) -> None: ...
60
def expose(name_or_function: Optional[Callable[..., Any]] = None) -> Callable[..., Any]: ...
61
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: ...
62
def show(*start_urls: str) -> None: ...
63
```
64

65
[Core Functions](./core-functions.md)
66

67
### Asynchronous Operations
68

69
Functions for managing asynchronous execution and non-blocking operations within the Gevent event loop.
70

71
```python { .api }
72
def sleep(seconds: Union[int, float]) -> None: ...
73
def spawn(function: Callable[..., Any], *args: Any, **kwargs: Any) -> Greenlet: ...
74
```
75

76
[Async Operations](./async-operations.md)
77

78
### Browser Management
79

80
Browser-specific modules and functions for launching applications in different browsers with custom configurations.
81

82
```python { .api }
83
def register_eel_routes(app: btl.Bottle) -> None: ...
84

85
# From eel.browsers module
86
def set_path(browser_name: str, path: str) -> None: ...
87
def get_path(browser_name: str) -> Optional[str]: ...
88
def open(start_pages: Iterable[Union[str, Dict[str, str]]], options: OptionsDictT) -> None: ...
89
```
90

91
Browser modules available:
92
- `eel.chrome` - Google Chrome/Chromium support
93
- `eel.electron` - Electron support
94
- `eel.edge` - Microsoft Edge support
95
- `eel.msIE` - Internet Explorer support
96

97
[Browser Management](./browser-management.md)
98

99
### Build Tools and Distribution
100

101
Command-line interface for building distributable executables using PyInstaller integration.
102

103
```python { .api }
104
# Command-line interface
105
python -m eel main_script web_folder [PyInstaller arguments...]
106
```
107

108
[Build Tools](./build-tools.md)
109

110
## Types
111

112
```python { .api }
113
from typing import Union, Dict, List, Tuple, Optional, Callable, Any
114
from typing_extensions import Literal, TypedDict
115
from bottle import Bottle
116

117
OptionsDictT = TypedDict('OptionsDictT', {
118
    'mode': Optional[Union[str, Literal[False]]],
119
    'host': str,
120
    'port': int,
121
    'block': bool,
122
    'jinja_templates': Optional[str],
123
    'cmdline_args': List[str],
124
    'size': Optional[Tuple[int, int]],
125
    'position': Optional[Tuple[int, int]],
126
    'geometry': Dict[str, Tuple[int, int]],
127
    'close_callback': Optional[Callable[..., Any]],
128
    'app_mode': bool,
129
    'all_interfaces': bool,
130
    'disable_cache': bool,
131
    'default_path': str,
132
    'app': Bottle,
133
    'shutdown_delay': float,
134
    'suppress_error': bool,
135
    'jinja_env': JinjaEnvironmentT
136
}, total=False)
137

138
# Type aliases
139
JinjaEnvironmentT = Any  # jinja2.Environment when available
140
WebSocketT = Any  # geventwebsocket.websocket.WebSocket
141
Greenlet = Any  # gevent.Greenlet
142
```