Seven functions. Clean and easy. Infinite possibilities.
Project description
itworksbetter
Seven functions. One loop. Infinite possibilities.
itworksbetter is a tiny Python library that creates a live communication bridge between Python and your browser.
No frameworks. No WebSockets. No async confusion. No frontend setup.
Just:
msg = iwb.catch()
iwb.throw("hello")
That’s it.
Why itworksbetter?
Most browser ↔ Python communication tools are heavy.
You usually need:
- Flask
- FastAPI
- SocketIO
- React/Vue
- Routes
- APIs
- async/await
- frontend tooling
itworksbetter strips all of that away.
You write a single Python loop.
The browser becomes your UI instantly.
Perfect for:
- AI tools
- Browser dashboards
- Python assistants
- Internal tools
- Local automation
- Rapid prototypes
- Teaching
- Experiments
- Live terminals
- Custom browser interfaces
Installation
pip install itworksbetter
The Philosophy
Seven functions.
One loop.
Infinite possibilities.
while True:
if msg := iwb.catch():
iwb.throw(f"You said: {msg['text']}")
That loop is your backend.
Quick Start
10-Line Echo Bot
import time
import itworksbetter as iwb
iwb.lazy(title="Echo Bot", theme="dark")
iwb.init()
while True:
if msg := iwb.catch():
iwb.throw(f"You said: {msg.get('text', '')}")
time.sleep(0.01)
Run it:
python app.py
Your browser opens automatically.
Type messages into the UI.
Python receives them instantly.
How It Works
itworksbetter runs a lightweight local HTTP server.
The browser:
- sends messages to Python
- polls for responses
- displays live output
Internally it uses:
- queues
- threads
- HTTP
- JSON
No external services required.
Everything stays local.
The Seven Functions
1. lazy()
Configure the browser UI before launch.
iwb.lazy(title="My App", theme="light")
Parameters
| Parameter | Type | Default |
|---|---|---|
title |
str |
"itworksbetter" |
theme |
str |
"dark" |
Themes
Supported:
"dark""light"
2. init()
Start the local server and connect to your browser.
iwb.init()
Example
iwb.init(port=8080)
Parameters
| Parameter | Type | Default |
|---|---|---|
port |
int |
8000 |
open |
bool |
True |
auto_fallback |
bool |
True |
Features
- Automatically opens your browser
- Auto-finds an open port if needed
- Runs the server in a background thread
- Cleans itself up on exit
Example Output
✅ Using port: 8000
🚀 itworksbetter v1.0.0 running at http://localhost:8000
📡 Echo Bot | Theme: dark
💡 Waiting for messages...
3. catch()
Receive messages from the browser.
msg = iwb.catch()
Returns
Message received
{"text": "hello"}
No message waiting
None
Typical Usage
if msg := iwb.catch():
print(msg["text"])
4. throw()
Send data to the browser.
iwb.throw("hello")
Supports
Any JSON-serializable data:
iwb.throw("text")
iwb.throw({
"user": "alex",
"online": True
})
iwb.throw([1, 2, 3])
iwb.throw(123)
The browser UI automatically formats and displays the output.
5. close()
Shutdown the server cleanly.
iwb.close()
What it does
- Stops browser polling
- Shuts down the HTTP server
- Frees the port immediately
- Clears message queues
Useful if you want to restart the server without restarting Python.
6. help()
Show a built-in mini guide.
iwb.help()
Displays:
- all functions
- examples
- quick usage tips
Great for learning the API quickly.
7. engine()
Get the JavaScript browser engine.
js = iwb.engine()
This lets you build completely custom browser UIs while still using the same Python communication system.
Custom UI Example
Python
import itworksbetter as iwb
import time
iwb.init()
while True:
if msg := iwb.catch():
iwb.throw({
"reply": msg["text"].upper()
})
time.sleep(0.01)
HTML
<!DOCTYPE html>
<html>
<body>
<input id="msg">
<button id="send">Send</button>
<pre id="output"></pre>
<script>
/* paste iwb.engine() output here */
</script>
<script>
const input = document.getElementById("msg");
const output = document.getElementById("output");
document.getElementById("send").onclick = () => {
itworksbetter.send(input.value);
};
itworksbetter.listen((data) => {
output.textContent += JSON.stringify(data) + "\n";
});
</script>
</body>
</html>
Architecture
The library uses two internal queues:
| Queue | Direction |
|---|---|
_incoming |
Browser → Python |
_outgoing |
Python → Browser |
Communication flow:
Browser → /send → Python queue
Python → /recv → Browser poll
Polling interval:
50msby default
Design Goals
itworksbetter was built to be:
- Minimal
- Easy to learn
- Beginner-friendly
- Fast to prototype with
- Pure Python
- Easy to debug
- Easy to customize
Not a replacement for full production frameworks.
Instead, it focuses on:
- simplicity
- immediacy
- experimentation
- local tools
- rapid development
Example Projects
You can build:
- AI chat interfaces
- Browser terminals
- Live dashboards
- Python control panels
- Automation UIs
- Teaching demos
- Monitoring tools
- Local admin panels
- Game prototypes
- Browser-based utilities
Complete Example
import time
import itworksbetter as iwb
iwb.lazy(
title="Assistant",
theme="dark"
)
iwb.init(port=8000)
while True:
if msg := iwb.catch():
text = msg.get("text", "")
if text == "ping":
iwb.throw({"response": "pong"})
elif text == "time":
iwb.throw({
"time": time.time()
})
else:
iwb.throw({
"echo": text
})
time.sleep(0.01)
Notes
- Everything runs locally
- Uses standard HTTP
- No WebSockets required
- No external dependencies
- Works with any frontend framework
- Browser communication is JSON-based
Version
Current version:
1.0.0
License:
Copyright (c) 2026 Atheer B. Muzzammil
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Most tools make browser communication feel harder than it needs to be.
itworksbetter reduces it down to:
catch()throw()- one loop
And surprisingly, that’s enough for a lot of powerful ideas.
Go build today with itworksbetter!
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file itworksbetter-1.0.0.tar.gz.
File metadata
- Download URL: itworksbetter-1.0.0.tar.gz
- Upload date:
- Size: 19.0 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.2.0 CPython/3.13.7
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
749134dda107bb608a2c8d97c78428809002b3e5445ed57af5696abe75227e51
|
|
| MD5 |
c1821cab3869e96d939b1c8b2f668d34
|
|
| BLAKE2b-256 |
966e23567b53b44a4927bc3c818bc98b1bad41eaf1ec3401805e9db049c8c75e
|
File details
Details for the file itworksbetter-1.0.0-py3-none-any.whl.
File metadata
- Download URL: itworksbetter-1.0.0-py3-none-any.whl
- Upload date:
- Size: 23.2 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.2.0 CPython/3.13.7
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
9e9e6172b38da04d52293b87071010ec457842a72cce29a8d9e3d040b8abca92
|
|
| MD5 |
0aa97cc68b28ceeed0b16b324097f0e9
|
|
| BLAKE2b-256 |
7552356ee81bd18894d81828b3a41e47b7234b19d08904bd03bec59b10cdcaa7
|
