Skip to content

Commit f65a6fc

Browse files
Fadi002Fadi002
committed
Initial commit
0 parents  commit f65a6fc

19 files changed

+5423
-0
lines changed

‎API_USAGE.md‎

Lines changed: 272 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,272 @@
1+
<!-- thanks to ChatGPT for the markdown xD -->
2+
# PyWire API Usage Guide 📚
3+
4+
This document provides a detailed guide on how to use the PyWire API to build interactive desktop applications with Python and web technologies. PyWire aims for Eel-compatibility, making it easy for developers familiar with Eel to transition. 🚀
5+
6+
## Core Concepts ✨
7+
8+
PyWire facilitates communication between your Python backend and your web-based frontend (HTML, CSS, JavaScript). It allows you to:
9+
10+
- **Expose Python functions to JavaScript**: Call Python functions directly from your frontend JavaScript code.
11+
- **Call JavaScript functions from Python**: Execute JavaScript functions from your Python backend.
12+
- **Manage application lifecycle**: Initialize, start, and stop your PyWire application.
13+
14+
## API Reference 📖
15+
16+
### `pywire.init(web_folder)`
17+
18+
Initializes the PyWire application, specifying the folder where your web assets (HTML, CSS, JavaScript) are located.
19+
20+
- `web_folder` (str): The path to the directory containing your web files. This path is relative to where your Python script is run.
21+
22+
**Example:**
23+
24+
```python
25+
import pywire
26+
27+
pywire.init("web") # Assuming your web files are in a folder named 'web'
28+
```
29+
30+
### `pywire.expose(name_or_function=None)`
31+
32+
Decorator or function to expose a Python function to the JavaScript frontend. Once exposed, the function can be called from JavaScript using `pywire.function_name(...)`.
33+
34+
- `name_or_function` (callable or str, optional): The Python function to expose, or a string representing the name to expose the function as in JavaScript. If `None`, it's used as a decorator.
35+
36+
**Examples:**
37+
38+
**As a decorator:**
39+
40+
```python
41+
import pywire
42+
43+
@pywire.expose
44+
def greet(name):
45+
return f"Hello, {name}!"
46+
```
47+
48+
**As a function:**
49+
50+
```python
51+
import pywire
52+
53+
def add_numbers(a, b):
54+
return a + b
55+
56+
pywire.expose(add_numbers) # Exposes as 'add_numbers' in JavaScript
57+
58+
def subtract_numbers(a, b):
59+
return a - b
60+
61+
pywire.expose(name="subtract", function=subtract_numbers) # Exposes as 'subtract' in JavaScript
62+
```
63+
64+
### `pywire.start(page='index.html', mode=None, host='localhost', port=8000, size=None, position=None)`
65+
66+
Starts the PyWire application, launching the web frontend in a browser or a desktop window.
67+
68+
- `page` (str, optional): The initial HTML page to load. Defaults to `index.html`.
69+
- `mode` (str, optional): The browser mode to use (e.g., `'chrome'`, `'edge'`, `'electron'`). If `None`, PyWire tries to find an available browser.
70+
- `host` (str, optional): The host address for the web server. Defaults to `localhost`.
71+
- `port` (int, optional): The port for the web server. Defaults to `8000`.
72+
- `size` (tuple, optional): A tuple `(width, height)` to set the initial window size.
73+
- `position` (tuple, optional): A tuple `(x, y)` to set the initial window position.
74+
75+
**Example:**
76+
77+
```python
78+
import pywire
79+
80+
pywire.init("web")
81+
pywire.start(page="main.html", size=(800, 600), port=8080)
82+
```
83+
84+
### `pywire.sleep(seconds)`
85+
86+
Pauses the execution of the Python script for a specified number of seconds. This is a utility function often used in examples.
87+
88+
- `seconds` (int or float): The number of seconds to sleep.
89+
90+
**Example:**
91+
92+
```python
93+
import pywire
94+
import time
95+
96+
print("Waiting for 5 seconds...")
97+
pywire.sleep(5)
98+
print("Done waiting!")
99+
```
100+
101+
### `pywire.call_js(function_name, *args)`
102+
103+
Calls a JavaScript function from Python. The JavaScript function must be defined in the global scope of your web page.
104+
105+
- `function_name` (str): The name of the JavaScript function to call.
106+
- `*args`: Arguments to pass to the JavaScript function.
107+
108+
**Example (Python):**
109+
110+
```python
111+
import pywire
112+
113+
# Assuming 'displayMessage' is a JavaScript function in your frontend
114+
pywire.call_js("displayMessage", "Message from Python!")
115+
```
116+
117+
**Example (JavaScript - in `index.html` or linked JS file):**
118+
119+
```javascript
120+
function displayMessage(message) {
121+
alert(message);
122+
}
123+
```
124+
125+
### `pywire.call_js_async(function_name, *args)`
126+
127+
Asynchronously calls a JavaScript function from Python. This is useful for non-blocking calls where you don't need an immediate return value.
128+
129+
- `function_name` (str): The name of the JavaScript function to call.
130+
- `*args`: Arguments to pass to the JavaScript function.
131+
132+
**Example (Python):**
133+
134+
```python
135+
import pywire
136+
137+
pywire.call_js_async("updateUI", {"status": "loading", "progress": 50})
138+
```
139+
140+
### `pywire.emit_event(event_name, *args)`
141+
142+
Emits a custom event that can be listened to by JavaScript or Python functions.
143+
144+
- `event_name` (str): The name of the event to emit.
145+
- `*args`: Data to pass along with the event.
146+
147+
**Example (Python):**
148+
149+
```python
150+
import pywire
151+
152+
pywire.emit_event("data_updated", {"new_value": 123})
153+
```
154+
155+
**Example (JavaScript):**
156+
157+
```javascript
158+
pywire.on_event("data_updated", (data) => {
159+
console.log("Data updated event received:", data);
160+
});
161+
```
162+
163+
### `pywire.on_event(event_name, handler_function)`
164+
165+
Registers a handler function to be called when a specific event is emitted.
166+
167+
- `event_name` (str): The name of the event to listen for.
168+
- `handler_function` (callable): The Python function to call when the event is emitted.
169+
170+
**Example (Python):**
171+
172+
```python
173+
import pywire
174+
175+
def handle_custom_event(data):
176+
print(f"Custom event received with data: {data}")
177+
178+
pywire.on_event("custom_event", handle_custom_event)
179+
180+
# Later, in your application logic or from JavaScript:
181+
pywire.emit_event("custom_event", {"status": "completed"})
182+
```
183+
184+
### `pywire.stop()`
185+
186+
Stops the running PyWire application.
187+
188+
**Example:**
189+
190+
```python
191+
import pywire
192+
import time
193+
194+
pywire.init("web")
195+
pywire.start(block=False) # Start non-blocking
196+
time.sleep(10) # Run for 10 seconds
197+
pywire.stop()
198+
```
199+
200+
### `pywire.get_exposed_functions()`
201+
202+
Returns a list of names of all Python functions currently exposed to the JavaScript frontend.
203+
204+
**Example:**
205+
206+
```python
207+
import pywire
208+
209+
@pywire.expose
210+
def func1(): pass
211+
212+
@pywire.expose
213+
def func2(): pass
214+
215+
print(pywire.get_exposed_functions())
216+
# Expected output: ['func1', 'func2'] (order may vary)
217+
```
218+
219+
### `pywire.set_custom_browser(browser_path)`
220+
221+
Sets a custom path to a browser executable to be used by PyWire.
222+
223+
- `browser_path` (str): The absolute path to the browser executable.
224+
225+
**Example:**
226+
227+
```python
228+
import pywire
229+
230+
pywire.set_custom_browser("/usr/bin/google-chrome")
231+
```
232+
233+
### `pywire.get_browser_info()`
234+
235+
Returns information about the browser currently being used by PyWire.
236+
237+
**Example:**
238+
239+
```python
240+
import pywire
241+
242+
info = pywire.get_browser_info()
243+
print(f"Browser Name: {info.get("name")}")
244+
print(f"Browser Version: {info.get("version")}")
245+
```
246+
247+
## JavaScript Integration 🌐
248+
249+
PyWire injects a `pywire.js` bridge file into your web pages. You **must** include this script in your HTML files for communication to work:
250+
251+
```html
252+
<script type="text/javascript" src="/pywire.js"></script>
253+
```
254+
255+
After including `pywire.js`, you can call exposed Python functions directly:
256+
257+
```javascript
258+
// Call an exposed Python function 'my_python_function'
259+
async function callMyPythonFunction() {
260+
let result = await pywire.my_python_function("some_argument");
261+
console.log("Result from Python:", result);
262+
}
263+
264+
// Listen for events emitted from Python
265+
pywire.on_event("python_event", (data) => {
266+
console.log("Event from Python received:", data);
267+
});
268+
```
269+
270+
This guide covers the primary functionalities of PyWire. For more advanced use cases and examples, please refer to the `example/` directory in the PyWire project. 💡
271+
272+

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2025 Fadi1337
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
<!-- thanks to ChatGPT for the markdown xD -->
2+
# PyWire 🚀
3+
4+
PyWire is a lightweight Python library that allows you to create simple desktop GUI applications using HTML, CSS, and JavaScript, while giving full access to Python’s functionality and libraries. It's designed to make cross-platform desktop app development with web technologies a breeze! ✨
5+
6+
## 💡 Inspiration
7+
8+
PyWire is heavily inspired by and aims to be compatible with the excellent [Eel project](https://github.com/python-eel/Eel). We've taken the core ideas and built upon them to provide a robust and easy-to-use solution for integrating Python with web frontends. Our goal is to offer a similar developer experience with additional features and optimizations. 🐍🌐
9+
10+
## 📦 Installation
11+
12+
You can install PyWire directly from PyPI:
13+
14+
```bash
15+
pip install pywire-eel
16+
```
17+
18+
Or from github
19+
```bash
20+
pip install git+https://github.com/Fadi002/PyWire
21+
```
22+
23+
## 🌟 Features
24+
25+
- **Seamless Python-JavaScript Interoperability**: Call Python functions from JavaScript and vice-versa with ease. 🔄
26+
- **Cross-Platform Compatibility**: Build apps that run on Windows, macOS, and Linux. 💻
27+
- **Web Technologies**: Leverage your existing knowledge of HTML, CSS, and JavaScript to build beautiful UIs. 🎨
28+
- **Lightweight & Fast**: Designed for performance and minimal overhead. ⚡
29+
- **Eel-compatible API**: Familiar API for developers coming from the Eel ecosystem. 🤝
30+
31+
## 🚀 Getting Started
32+
33+
Here's a quick example to get you started:
34+
35+
```python
36+
import pywire
37+
38+
@pywire.expose
39+
def say_hello(name):
40+
print(f"Hello from Python: {name}!")
41+
return f"Hello, {name}! This is from Python."
42+
43+
pywire.init('web') # 'web' is the folder containing your HTML, CSS, JS files
44+
pywire.start('index.html') # 'index.html' is your main HTML file
45+
```
46+
47+
And in your `web/index.html`:
48+
49+
```html
50+
<!DOCTYPE html>
51+
<html>
52+
<head>
53+
<script src="bridge.js"></script> <!-- This must be included in your html -->
54+
<title>PyWire App</title>
55+
<script type="text/javascript" src="/pywire.js"></script>
56+
<script type="text/javascript">
57+
async function callPython() {
58+
let result = await pywire.say_hello("World");
59+
document.getElementById('output').innerText = result;
60+
}
61+
</script>
62+
</head>
63+
<body>
64+
<h1>Welcome to PyWire!</h1>
65+
<button onclick="callPython()">Call Python Function</button>
66+
<p id="output"></p>
67+
</body>
68+
</html>
69+
```
70+
71+
## 🤝 Contributing
72+
73+
We welcome contributions! If you'd like to contribute, please fork the repository and create a pull request. For major changes, please open an issue first to discuss what you would like to change. 💖
74+
75+
## 📄 License
76+
77+
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. ©️
78+
79+

0 commit comments

Comments
 (0)