pyodex 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- pyodex-0.1.0/.github/workflows/publish.yml +27 -0
- pyodex-0.1.0/.gitignore +7 -0
- pyodex-0.1.0/PKG-INFO +213 -0
- pyodex-0.1.0/README.md +206 -0
- pyodex-0.1.0/examples/fireworks/main.py +82 -0
- pyodex-0.1.0/examples/fireworks/overlay.body.html +1 -0
- pyodex-0.1.0/examples/fireworks/overlay.css +3 -0
- pyodex-0.1.0/examples/fireworks/pyodex.lock +57 -0
- pyodex-0.1.0/examples/fireworks/pyodex.toml +13 -0
- pyodex-0.1.0/examples/single_script/my-cool-ext.pyodex.lock +44 -0
- pyodex-0.1.0/examples/single_script/my_cool_ext.py +39 -0
- pyodex-0.1.0/proxy/build_binaries.sh +19 -0
- pyodex-0.1.0/proxy/python_websocket_proxy.py +210 -0
- pyodex-0.1.0/pyodex_bundle.py +73 -0
- pyodex-0.1.0/pyproject.toml +20 -0
- pyodex-0.1.0/src/pyodex/__init__.py +5 -0
- pyodex-0.1.0/src/pyodex/builder.py +257 -0
- pyodex-0.1.0/src/pyodex/capabilities/314.0.8.json +449 -0
- pyodex-0.1.0/src/pyodex/cli.py +172 -0
- pyodex-0.1.0/src/pyodex/compat.json +442 -0
- pyodex-0.1.0/src/pyodex/compat.py +290 -0
- pyodex-0.1.0/src/pyodex/deps.py +97 -0
- pyodex-0.1.0/src/pyodex/packages.py +336 -0
- pyodex-0.1.0/src/pyodex/pyodide_caps.py +121 -0
- pyodex-0.1.0/src/pyodex/runtime/pyodex_natural.py +540 -0
- pyodex-0.1.0/src/pyodex/runtime/pyodex_runtime.py +401 -0
- pyodex-0.1.0/src/pyodex/scaffold.py +55 -0
- pyodex-0.1.0/src/pyodex/templates/bootstrap.js +104 -0
- pyodex-0.1.0/src/pyodex/templates/injector.js +157 -0
- pyodex-0.1.0/src/pyodex/templates/overlay.html +67 -0
- pyodex-0.1.0/tests/test_core.py +114 -0
- pyodex-0.1.0/uv.lock +245 -0
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
name: publish
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
release:
|
|
5
|
+
types: [published]
|
|
6
|
+
workflow_dispatch:
|
|
7
|
+
|
|
8
|
+
jobs:
|
|
9
|
+
test:
|
|
10
|
+
runs-on: ubuntu-latest
|
|
11
|
+
steps:
|
|
12
|
+
- uses: actions/checkout@v4
|
|
13
|
+
- uses: astral-sh/setup-uv@v5
|
|
14
|
+
- run: uv sync --group dev
|
|
15
|
+
- run: uv run pytest -q
|
|
16
|
+
|
|
17
|
+
pypi:
|
|
18
|
+
needs: test
|
|
19
|
+
runs-on: ubuntu-latest
|
|
20
|
+
environment: pypi
|
|
21
|
+
permissions:
|
|
22
|
+
id-token: write # OIDC -> PyPI trusted publishing, no API token stored
|
|
23
|
+
steps:
|
|
24
|
+
- uses: actions/checkout@v4
|
|
25
|
+
- uses: astral-sh/setup-uv@v5
|
|
26
|
+
- run: uv build
|
|
27
|
+
- run: uv publish --trusted-publishing always
|
pyodex-0.1.0/.gitignore
ADDED
pyodex-0.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,213 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: pyodex
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Framework for building Chrome (MV3) extensions whose logic runs in Python via Pyodide.
|
|
5
|
+
Requires-Python: >=3.12
|
|
6
|
+
Description-Content-Type: text/markdown
|
|
7
|
+
|
|
8
|
+
# pyodex — Python Chrome extensions on Pyodide
|
|
9
|
+
|
|
10
|
+
Write a Chrome (Manifest V3) extension in Python. `pyodex` scaffolds the project,
|
|
11
|
+
bundles a local Pyodide runtime, resolves your Python dependencies for the
|
|
12
|
+
wasm32 target, and emits a loadable unpacked extension.
|
|
13
|
+
|
|
14
|
+
## Fastest path: one script
|
|
15
|
+
|
|
16
|
+
Write a PEP 723 script with a `[tool.pyodex]` block, then:
|
|
17
|
+
|
|
18
|
+
```
|
|
19
|
+
uv run pyodex_bundle.py my_cool_ext.py
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
That resolves deps for wasm32, bundles Pyodide, and writes
|
|
23
|
+
`dist/<slug>/` (unpacked) plus `dist/<slug>.zip`. See
|
|
24
|
+
`examples/single_script/my_cool_ext.py`.
|
|
25
|
+
|
|
26
|
+
```python
|
|
27
|
+
# /// script
|
|
28
|
+
# dependencies = ["requests", "numpy"]
|
|
29
|
+
#
|
|
30
|
+
# [tool.pyodex]
|
|
31
|
+
# name = "My Cool Ext"
|
|
32
|
+
# matches = ["<all_urls>"]
|
|
33
|
+
# url_filter = "shyft"
|
|
34
|
+
# overlay_css = "#p { top: 60px }"
|
|
35
|
+
# [tool.pyodex.vendor]
|
|
36
|
+
# "lib.js" = "https://cdn.jsdelivr.net/npm/some-lib/dist/index.umd.js"
|
|
37
|
+
# ///
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
Flags: `--out DIR`, `--no-zip`, `--refresh-lock`.
|
|
41
|
+
|
|
42
|
+
## Project mode
|
|
43
|
+
|
|
44
|
+
```
|
|
45
|
+
uv sync
|
|
46
|
+
uv run pyodex init myext --match "*://*.example.com/*"
|
|
47
|
+
uv run pyodex build myext # -> myext/dist/myext/
|
|
48
|
+
uv run pyodex zip myext # -> myext/dist/myext.zip
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
Load `dist/<slug>/` via `chrome://extensions` → Developer mode → Load unpacked.
|
|
52
|
+
|
|
53
|
+
## Project layout
|
|
54
|
+
|
|
55
|
+
```
|
|
56
|
+
myext/
|
|
57
|
+
├── pyodex.toml # name, version, matches, url_filter, scripts, vendor, ...
|
|
58
|
+
├── main.py # entry point, runs inside Pyodide (PEP 723 deps supported)
|
|
59
|
+
├── overlay.css # optional styles for the overlay page
|
|
60
|
+
├── overlay.body.html # optional markup injected into the overlay <body>
|
|
61
|
+
└── pyodex.lock # generated: pinned wasm32 wheel versions
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
## How it runs
|
|
65
|
+
|
|
66
|
+
1. `injector.js` (content script) adds a transparent, click-through iframe over
|
|
67
|
+
the page pointing at `overlay.html`.
|
|
68
|
+
2. `bootstrap.js` loads Pyodide from the extension's own `pyodide/` folder,
|
|
69
|
+
unpacks bundled wheels into site-packages, patches `urllib`, then runs `main.py`.
|
|
70
|
+
3. `pyodex_runtime` (importable from `main.py`) gives you `Overlay`, `on`, `el`,
|
|
71
|
+
`Page` (talk to host page), `WebSocketClient`, `TcpSocket`, `fetch_json`, `vendored`.
|
|
72
|
+
|
|
73
|
+
## Dependencies (PEP 723)
|
|
74
|
+
|
|
75
|
+
Declare packages inline in `main.py`:
|
|
76
|
+
|
|
77
|
+
```python
|
|
78
|
+
# /// script
|
|
79
|
+
# dependencies = ["requests", "numpy>=2"]
|
|
80
|
+
# ///
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
On build, `pyodex`:
|
|
84
|
+
|
|
85
|
+
- resolves with `uv pip compile --python-platform wasm32-pyodide2025`, so only
|
|
86
|
+
wheels that run in Pyodide are accepted (`py3-none-any` or `pyodide_2025_0_wasm32`);
|
|
87
|
+
- pins results in `pyodex.lock`, reused until the dependency list changes;
|
|
88
|
+
- downloads each wheel once into a global read-only store
|
|
89
|
+
(`~/.cache/pyodex/store/<name>/<version>/`, files `0444`), preferring Pyodide's
|
|
90
|
+
own CDN build when the version matches, else PyPI with sha256 check;
|
|
91
|
+
- links wheels into `dist/wheels/` copy-on-write: reflink where the filesystem
|
|
92
|
+
supports it, else hardlink (store file is read-only, so writes fail), else copy.
|
|
93
|
+
|
|
94
|
+
`pyodex.toml` `pyodide_packages = [...]` adds extra requirements the same way.
|
|
95
|
+
Packages Pyodide ships itself (numpy, pandas, cryptography, ...) are pinned to
|
|
96
|
+
Pyodide's own build via uv constraints and fetched from the Pyodide CDN.
|
|
97
|
+
|
|
98
|
+
## Compatibility registry
|
|
99
|
+
|
|
100
|
+
Like haru-pack's thick-app checks: a package is **good** only if a functional
|
|
101
|
+
probe passed inside Pyodide under Node, **bad** if resolve/fetch/import/probe
|
|
102
|
+
failed, **import-only** if it imports but has no probe. Shipped results live in
|
|
103
|
+
`src/pyodex/compat.json`; local runs append to `~/.cache/pyodex/compat.json`.
|
|
104
|
+
Builds refuse known-bad packages unless `--allow-bad`.
|
|
105
|
+
|
|
106
|
+
```
|
|
107
|
+
uv run pyodex compat test requests numpy redis
|
|
108
|
+
uv run pyodex compat test --top 50 --shipped
|
|
109
|
+
uv run pyodex compat list --filter bad
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
Top-50 PyPI as of 2026-11: 45 good, 4 import-only, 1 bad (uvicorn: no
|
|
113
|
+
`create_server`). Known bad by probe: redis, aiohttp, pymongo, paramiko,
|
|
114
|
+
psycopg2 (sockets / threads / no wasm wheel). Use `TcpSocket` + proxy for
|
|
115
|
+
those protocols. Add probes in `compat.py` `PROBES`.
|
|
116
|
+
|
|
117
|
+
## HTTP from Python
|
|
118
|
+
|
|
119
|
+
`http = true` (default) bundles `requests`, `urllib3`, `pyodide-http` and friends.
|
|
120
|
+
`requests` works unmodified (urllib3 ≥ 2.2 has a native Emscripten backend).
|
|
121
|
+
`urllib.request` is patched by `pyodide-http` at boot. For async use
|
|
122
|
+
`pyodex_runtime.fetch_json` / `pyodide.http.pyfetch`.
|
|
123
|
+
|
|
124
|
+
`host_permissions` (default `<all_urls>`) controls which origins the overlay may fetch.
|
|
125
|
+
|
|
126
|
+
## Natural Python (`pyodex_natural`)
|
|
127
|
+
|
|
128
|
+
Installed before `main.py` runs (`natural = true`, default). Each shim gates on
|
|
129
|
+
a detected capability and leaves stdlib alone if unsupported.
|
|
130
|
+
|
|
131
|
+
- **socket / ssl**: plain blocking `socket.create_connection`, `recv`, `sendall`
|
|
132
|
+
work via JSPI `run_sync` over the proxy. `ssl.wrap_socket` routes through the
|
|
133
|
+
proxy's `/tls/HOST/PORT` path (proxy verifies TLS upstream). Lets stdlib
|
|
134
|
+
`http.client`, `smtplib`, `redis-py` style code run unchanged.
|
|
135
|
+
- **input() / getpass**: `window.prompt`. **webbrowser.open**: `window.open`.
|
|
136
|
+
- **time.sleep**: yields to event loop instead of spinning.
|
|
137
|
+
- **persistent cwd**: `/home/pyodide/data` on IndexedDB. `open('x','w')`
|
|
138
|
+
survives reload. `pyodex_natural.save()` or `with persist():` flushes.
|
|
139
|
+
Autosave every 2 s.
|
|
140
|
+
- **pip_install("pkg")**: micropip at runtime (bundled).
|
|
141
|
+
- **print**: mirrored to the browser console as `[py] ...`.
|
|
142
|
+
|
|
143
|
+
```python
|
|
144
|
+
import pyodex_natural
|
|
145
|
+
pyodex_natural.config.proxy = "ws://127.0.0.1:1234"
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
Capabilities detected at boot land on `window.pyodexCaps` (DevTools).
|
|
149
|
+
|
|
150
|
+
## Pyodide capability snapshots
|
|
151
|
+
|
|
152
|
+
```
|
|
153
|
+
uv run pyodex pyodide probe # runs detect() in Node, saves src/pyodex/capabilities/<ver>.json
|
|
154
|
+
uv run pyodex pyodide latest # newest GitHub release tag
|
|
155
|
+
uv run pyodex pyodide probe --version 315.0.0
|
|
156
|
+
uv run pyodex pyodide diff 314.0.8 315.0.0
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
Snapshot holds: JSPI, FS types, ffi surface, JS API keys, stdlib gaps, every
|
|
160
|
+
shipped package version. `diff` lists added/removed/changed entries so new
|
|
161
|
+
runtime features show up as a to-do for shims.
|
|
162
|
+
|
|
163
|
+
## Raw TCP via proxy
|
|
164
|
+
|
|
165
|
+
Browsers block raw sockets. Run the bundled bridge:
|
|
166
|
+
|
|
167
|
+
```
|
|
168
|
+
uv run proxy/python_websocket_proxy.py --port 1234 --allow localhost:*
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
Then in the extension:
|
|
172
|
+
|
|
173
|
+
```python
|
|
174
|
+
from pyodex_runtime import TcpSocket
|
|
175
|
+
sock = await TcpSocket.connect("localhost", 6379)
|
|
176
|
+
sock.send(b"PING\r\n")
|
|
177
|
+
print(await sock.recv_until(b"\n"))
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
Routes: `ws://127.0.0.1:1234/` → `--target HOST:PORT`; `ws://.../tcp/HOST/PORT` and
|
|
181
|
+
`ws://.../tls/HOST/PORT` (proxy opens TLS upstream) → dynamic, gated by `--allow` rules (`name`, glob, or CIDR; port `n`, `a-b`, `*`).
|
|
182
|
+
`--token X` requires `?token=X`. Binds `127.0.0.1` by default.
|
|
183
|
+
|
|
184
|
+
Standalone binaries (haru-pack, thick tier, offline):
|
|
185
|
+
|
|
186
|
+
```
|
|
187
|
+
bash proxy/build_binaries.sh # host + windows-x86_64 -> dist/proxy/
|
|
188
|
+
bash proxy/build_binaries.sh linux-aarch64 # explicit targets
|
|
189
|
+
./dist/proxy/python_websocket_proxy --port 1234 --allow localhost:*
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
## Example
|
|
193
|
+
|
|
194
|
+
`examples/fireworks` — fireworks-js driven from Python on any URL containing
|
|
195
|
+
`shyft`, plus a `requests` demo and optional TCP remote control (`nc -l 9999`,
|
|
196
|
+
type `launch` / `stop`).
|
|
197
|
+
|
|
198
|
+
```
|
|
199
|
+
uv run pyodex build examples/fireworks
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
## CLI
|
|
203
|
+
|
|
204
|
+
```
|
|
205
|
+
pyodex init <dir> [--name N] [--match PATTERN ...]
|
|
206
|
+
pyodex build <dir> [--out DIR]
|
|
207
|
+
pyodex zip <dir> [--out FILE]
|
|
208
|
+
pyodex fetch [--pyodide-version V] [--force]
|
|
209
|
+
pyodex compat test|list [PKG ...] [--top N] [--shipped] [--filter STATUS]
|
|
210
|
+
pyodex pyodide probe|latest|diff [--version V] [OLD NEW]
|
|
211
|
+
```
|
|
212
|
+
|
|
213
|
+
Cache location: `$PYODEX_CACHE` or `~/.cache/pyodex`.
|
pyodex-0.1.0/README.md
ADDED
|
@@ -0,0 +1,206 @@
|
|
|
1
|
+
# pyodex — Python Chrome extensions on Pyodide
|
|
2
|
+
|
|
3
|
+
Write a Chrome (Manifest V3) extension in Python. `pyodex` scaffolds the project,
|
|
4
|
+
bundles a local Pyodide runtime, resolves your Python dependencies for the
|
|
5
|
+
wasm32 target, and emits a loadable unpacked extension.
|
|
6
|
+
|
|
7
|
+
## Fastest path: one script
|
|
8
|
+
|
|
9
|
+
Write a PEP 723 script with a `[tool.pyodex]` block, then:
|
|
10
|
+
|
|
11
|
+
```
|
|
12
|
+
uv run pyodex_bundle.py my_cool_ext.py
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
That resolves deps for wasm32, bundles Pyodide, and writes
|
|
16
|
+
`dist/<slug>/` (unpacked) plus `dist/<slug>.zip`. See
|
|
17
|
+
`examples/single_script/my_cool_ext.py`.
|
|
18
|
+
|
|
19
|
+
```python
|
|
20
|
+
# /// script
|
|
21
|
+
# dependencies = ["requests", "numpy"]
|
|
22
|
+
#
|
|
23
|
+
# [tool.pyodex]
|
|
24
|
+
# name = "My Cool Ext"
|
|
25
|
+
# matches = ["<all_urls>"]
|
|
26
|
+
# url_filter = "shyft"
|
|
27
|
+
# overlay_css = "#p { top: 60px }"
|
|
28
|
+
# [tool.pyodex.vendor]
|
|
29
|
+
# "lib.js" = "https://cdn.jsdelivr.net/npm/some-lib/dist/index.umd.js"
|
|
30
|
+
# ///
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
Flags: `--out DIR`, `--no-zip`, `--refresh-lock`.
|
|
34
|
+
|
|
35
|
+
## Project mode
|
|
36
|
+
|
|
37
|
+
```
|
|
38
|
+
uv sync
|
|
39
|
+
uv run pyodex init myext --match "*://*.example.com/*"
|
|
40
|
+
uv run pyodex build myext # -> myext/dist/myext/
|
|
41
|
+
uv run pyodex zip myext # -> myext/dist/myext.zip
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
Load `dist/<slug>/` via `chrome://extensions` → Developer mode → Load unpacked.
|
|
45
|
+
|
|
46
|
+
## Project layout
|
|
47
|
+
|
|
48
|
+
```
|
|
49
|
+
myext/
|
|
50
|
+
├── pyodex.toml # name, version, matches, url_filter, scripts, vendor, ...
|
|
51
|
+
├── main.py # entry point, runs inside Pyodide (PEP 723 deps supported)
|
|
52
|
+
├── overlay.css # optional styles for the overlay page
|
|
53
|
+
├── overlay.body.html # optional markup injected into the overlay <body>
|
|
54
|
+
└── pyodex.lock # generated: pinned wasm32 wheel versions
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
## How it runs
|
|
58
|
+
|
|
59
|
+
1. `injector.js` (content script) adds a transparent, click-through iframe over
|
|
60
|
+
the page pointing at `overlay.html`.
|
|
61
|
+
2. `bootstrap.js` loads Pyodide from the extension's own `pyodide/` folder,
|
|
62
|
+
unpacks bundled wheels into site-packages, patches `urllib`, then runs `main.py`.
|
|
63
|
+
3. `pyodex_runtime` (importable from `main.py`) gives you `Overlay`, `on`, `el`,
|
|
64
|
+
`Page` (talk to host page), `WebSocketClient`, `TcpSocket`, `fetch_json`, `vendored`.
|
|
65
|
+
|
|
66
|
+
## Dependencies (PEP 723)
|
|
67
|
+
|
|
68
|
+
Declare packages inline in `main.py`:
|
|
69
|
+
|
|
70
|
+
```python
|
|
71
|
+
# /// script
|
|
72
|
+
# dependencies = ["requests", "numpy>=2"]
|
|
73
|
+
# ///
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
On build, `pyodex`:
|
|
77
|
+
|
|
78
|
+
- resolves with `uv pip compile --python-platform wasm32-pyodide2025`, so only
|
|
79
|
+
wheels that run in Pyodide are accepted (`py3-none-any` or `pyodide_2025_0_wasm32`);
|
|
80
|
+
- pins results in `pyodex.lock`, reused until the dependency list changes;
|
|
81
|
+
- downloads each wheel once into a global read-only store
|
|
82
|
+
(`~/.cache/pyodex/store/<name>/<version>/`, files `0444`), preferring Pyodide's
|
|
83
|
+
own CDN build when the version matches, else PyPI with sha256 check;
|
|
84
|
+
- links wheels into `dist/wheels/` copy-on-write: reflink where the filesystem
|
|
85
|
+
supports it, else hardlink (store file is read-only, so writes fail), else copy.
|
|
86
|
+
|
|
87
|
+
`pyodex.toml` `pyodide_packages = [...]` adds extra requirements the same way.
|
|
88
|
+
Packages Pyodide ships itself (numpy, pandas, cryptography, ...) are pinned to
|
|
89
|
+
Pyodide's own build via uv constraints and fetched from the Pyodide CDN.
|
|
90
|
+
|
|
91
|
+
## Compatibility registry
|
|
92
|
+
|
|
93
|
+
Like haru-pack's thick-app checks: a package is **good** only if a functional
|
|
94
|
+
probe passed inside Pyodide under Node, **bad** if resolve/fetch/import/probe
|
|
95
|
+
failed, **import-only** if it imports but has no probe. Shipped results live in
|
|
96
|
+
`src/pyodex/compat.json`; local runs append to `~/.cache/pyodex/compat.json`.
|
|
97
|
+
Builds refuse known-bad packages unless `--allow-bad`.
|
|
98
|
+
|
|
99
|
+
```
|
|
100
|
+
uv run pyodex compat test requests numpy redis
|
|
101
|
+
uv run pyodex compat test --top 50 --shipped
|
|
102
|
+
uv run pyodex compat list --filter bad
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
Top-50 PyPI as of 2026-11: 45 good, 4 import-only, 1 bad (uvicorn: no
|
|
106
|
+
`create_server`). Known bad by probe: redis, aiohttp, pymongo, paramiko,
|
|
107
|
+
psycopg2 (sockets / threads / no wasm wheel). Use `TcpSocket` + proxy for
|
|
108
|
+
those protocols. Add probes in `compat.py` `PROBES`.
|
|
109
|
+
|
|
110
|
+
## HTTP from Python
|
|
111
|
+
|
|
112
|
+
`http = true` (default) bundles `requests`, `urllib3`, `pyodide-http` and friends.
|
|
113
|
+
`requests` works unmodified (urllib3 ≥ 2.2 has a native Emscripten backend).
|
|
114
|
+
`urllib.request` is patched by `pyodide-http` at boot. For async use
|
|
115
|
+
`pyodex_runtime.fetch_json` / `pyodide.http.pyfetch`.
|
|
116
|
+
|
|
117
|
+
`host_permissions` (default `<all_urls>`) controls which origins the overlay may fetch.
|
|
118
|
+
|
|
119
|
+
## Natural Python (`pyodex_natural`)
|
|
120
|
+
|
|
121
|
+
Installed before `main.py` runs (`natural = true`, default). Each shim gates on
|
|
122
|
+
a detected capability and leaves stdlib alone if unsupported.
|
|
123
|
+
|
|
124
|
+
- **socket / ssl**: plain blocking `socket.create_connection`, `recv`, `sendall`
|
|
125
|
+
work via JSPI `run_sync` over the proxy. `ssl.wrap_socket` routes through the
|
|
126
|
+
proxy's `/tls/HOST/PORT` path (proxy verifies TLS upstream). Lets stdlib
|
|
127
|
+
`http.client`, `smtplib`, `redis-py` style code run unchanged.
|
|
128
|
+
- **input() / getpass**: `window.prompt`. **webbrowser.open**: `window.open`.
|
|
129
|
+
- **time.sleep**: yields to event loop instead of spinning.
|
|
130
|
+
- **persistent cwd**: `/home/pyodide/data` on IndexedDB. `open('x','w')`
|
|
131
|
+
survives reload. `pyodex_natural.save()` or `with persist():` flushes.
|
|
132
|
+
Autosave every 2 s.
|
|
133
|
+
- **pip_install("pkg")**: micropip at runtime (bundled).
|
|
134
|
+
- **print**: mirrored to the browser console as `[py] ...`.
|
|
135
|
+
|
|
136
|
+
```python
|
|
137
|
+
import pyodex_natural
|
|
138
|
+
pyodex_natural.config.proxy = "ws://127.0.0.1:1234"
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
Capabilities detected at boot land on `window.pyodexCaps` (DevTools).
|
|
142
|
+
|
|
143
|
+
## Pyodide capability snapshots
|
|
144
|
+
|
|
145
|
+
```
|
|
146
|
+
uv run pyodex pyodide probe # runs detect() in Node, saves src/pyodex/capabilities/<ver>.json
|
|
147
|
+
uv run pyodex pyodide latest # newest GitHub release tag
|
|
148
|
+
uv run pyodex pyodide probe --version 315.0.0
|
|
149
|
+
uv run pyodex pyodide diff 314.0.8 315.0.0
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
Snapshot holds: JSPI, FS types, ffi surface, JS API keys, stdlib gaps, every
|
|
153
|
+
shipped package version. `diff` lists added/removed/changed entries so new
|
|
154
|
+
runtime features show up as a to-do for shims.
|
|
155
|
+
|
|
156
|
+
## Raw TCP via proxy
|
|
157
|
+
|
|
158
|
+
Browsers block raw sockets. Run the bundled bridge:
|
|
159
|
+
|
|
160
|
+
```
|
|
161
|
+
uv run proxy/python_websocket_proxy.py --port 1234 --allow localhost:*
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
Then in the extension:
|
|
165
|
+
|
|
166
|
+
```python
|
|
167
|
+
from pyodex_runtime import TcpSocket
|
|
168
|
+
sock = await TcpSocket.connect("localhost", 6379)
|
|
169
|
+
sock.send(b"PING\r\n")
|
|
170
|
+
print(await sock.recv_until(b"\n"))
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
Routes: `ws://127.0.0.1:1234/` → `--target HOST:PORT`; `ws://.../tcp/HOST/PORT` and
|
|
174
|
+
`ws://.../tls/HOST/PORT` (proxy opens TLS upstream) → dynamic, gated by `--allow` rules (`name`, glob, or CIDR; port `n`, `a-b`, `*`).
|
|
175
|
+
`--token X` requires `?token=X`. Binds `127.0.0.1` by default.
|
|
176
|
+
|
|
177
|
+
Standalone binaries (haru-pack, thick tier, offline):
|
|
178
|
+
|
|
179
|
+
```
|
|
180
|
+
bash proxy/build_binaries.sh # host + windows-x86_64 -> dist/proxy/
|
|
181
|
+
bash proxy/build_binaries.sh linux-aarch64 # explicit targets
|
|
182
|
+
./dist/proxy/python_websocket_proxy --port 1234 --allow localhost:*
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
## Example
|
|
186
|
+
|
|
187
|
+
`examples/fireworks` — fireworks-js driven from Python on any URL containing
|
|
188
|
+
`shyft`, plus a `requests` demo and optional TCP remote control (`nc -l 9999`,
|
|
189
|
+
type `launch` / `stop`).
|
|
190
|
+
|
|
191
|
+
```
|
|
192
|
+
uv run pyodex build examples/fireworks
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
## CLI
|
|
196
|
+
|
|
197
|
+
```
|
|
198
|
+
pyodex init <dir> [--name N] [--match PATTERN ...]
|
|
199
|
+
pyodex build <dir> [--out DIR]
|
|
200
|
+
pyodex zip <dir> [--out FILE]
|
|
201
|
+
pyodex fetch [--pyodide-version V] [--force]
|
|
202
|
+
pyodex compat test|list [PKG ...] [--top N] [--shipped] [--filter STATUS]
|
|
203
|
+
pyodex pyodide probe|latest|diff [--version V] [OLD NEW]
|
|
204
|
+
```
|
|
205
|
+
|
|
206
|
+
Cache location: `$PYODEX_CACHE` or `~/.cache/pyodex`.
|
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
"""Fireworks example: Python drives fireworks-js, plus optional remote triggers.
|
|
2
|
+
|
|
3
|
+
Demonstrates:
|
|
4
|
+
* vendored JS lib called from Python (fireworks-js)
|
|
5
|
+
* HTTP from Python via `requests` (bundled shim)
|
|
6
|
+
* optional WebSocket control channel through python_websocket_proxy
|
|
7
|
+
"""
|
|
8
|
+
|
|
9
|
+
import asyncio
|
|
10
|
+
|
|
11
|
+
from pyodex_runtime import Overlay, TcpSocket, document, jsobj, on, status, vendored
|
|
12
|
+
|
|
13
|
+
ui = Overlay()
|
|
14
|
+
container = document.getElementById("fireworks-container")
|
|
15
|
+
btn = ui.button("Launch Fireworks 🎇", top=16, left=16, id="py-fireworks-btn")
|
|
16
|
+
|
|
17
|
+
config = jsobj({
|
|
18
|
+
"autoresize": True,
|
|
19
|
+
"opacity": 0.5,
|
|
20
|
+
"acceleration": 1.05,
|
|
21
|
+
"friction": 0.97,
|
|
22
|
+
"gravity": 1.5,
|
|
23
|
+
"particles": 60,
|
|
24
|
+
"explosion": 6,
|
|
25
|
+
"intensity": 35,
|
|
26
|
+
})
|
|
27
|
+
Fireworks = vendored("Fireworks")
|
|
28
|
+
fireworks = Fireworks.new(container, config)
|
|
29
|
+
|
|
30
|
+
running = False
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
def set_running(value: bool) -> None:
|
|
34
|
+
global running
|
|
35
|
+
running = value
|
|
36
|
+
if running:
|
|
37
|
+
fireworks.start()
|
|
38
|
+
btn.innerText = "Stop Fireworks 🎆"
|
|
39
|
+
else:
|
|
40
|
+
fireworks.stop()
|
|
41
|
+
btn.innerText = "Launch Fireworks 🎇"
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
@on(btn, "click")
|
|
45
|
+
def toggle(_event):
|
|
46
|
+
set_running(not running)
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
# --- HTTP from Python: `requests` works because urllib3 has an Emscripten backend.
|
|
50
|
+
def demo_http() -> None:
|
|
51
|
+
try:
|
|
52
|
+
import requests
|
|
53
|
+
|
|
54
|
+
r = requests.get("https://httpbin.org/get", timeout=10)
|
|
55
|
+
print("[fireworks] requests ok:", r.status_code, r.json().get("origin"))
|
|
56
|
+
except Exception as e: # noqa: BLE001
|
|
57
|
+
print("[fireworks] requests failed:", e)
|
|
58
|
+
|
|
59
|
+
|
|
60
|
+
# --- Remote control over raw TCP via the proxy. Run:
|
|
61
|
+
# uv run proxy/python_websocket_proxy.py --port 1234 --allow localhost:*
|
|
62
|
+
# then `nc -l 9999` and type `launch` / `stop`.
|
|
63
|
+
async def remote_control() -> None:
|
|
64
|
+
try:
|
|
65
|
+
sock = await TcpSocket.connect("localhost", 9999, timeout=3)
|
|
66
|
+
except Exception: # noqa: BLE001
|
|
67
|
+
return # proxy not running; feature is optional
|
|
68
|
+
print("[fireworks] remote control connected")
|
|
69
|
+
while True:
|
|
70
|
+
line = await sock.recv_until(b"\n")
|
|
71
|
+
if not line:
|
|
72
|
+
break
|
|
73
|
+
cmd = line.strip().lower()
|
|
74
|
+
if cmd == b"launch":
|
|
75
|
+
set_running(True)
|
|
76
|
+
elif cmd == b"stop":
|
|
77
|
+
set_running(False)
|
|
78
|
+
|
|
79
|
+
|
|
80
|
+
demo_http()
|
|
81
|
+
asyncio.ensure_future(remote_control())
|
|
82
|
+
status(None)
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
<div id="fireworks-container"></div>
|
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
{
|
|
2
|
+
"hash": "318e4b2394264c79",
|
|
3
|
+
"python": "3.14",
|
|
4
|
+
"platform": "wasm32-pyodide2025",
|
|
5
|
+
"requirements": [
|
|
6
|
+
"pyodide-http",
|
|
7
|
+
"requests",
|
|
8
|
+
"urllib3",
|
|
9
|
+
"charset-normalizer",
|
|
10
|
+
"idna",
|
|
11
|
+
"certifi"
|
|
12
|
+
],
|
|
13
|
+
"pins": [
|
|
14
|
+
{
|
|
15
|
+
"name": "certifi",
|
|
16
|
+
"version": "2026.4.22",
|
|
17
|
+
"sha256": "c2c0091986db798df5fd84582d289496f31244a898ec032b7015278c2d82c80c",
|
|
18
|
+
"url": "https://cdn.jsdelivr.net/pyodide/v314.0.8/full/certifi-2026.4.22-py3-none-any.whl",
|
|
19
|
+
"file": "certifi-2026.4.22-py3-none-any.whl"
|
|
20
|
+
},
|
|
21
|
+
{
|
|
22
|
+
"name": "charset-normalizer",
|
|
23
|
+
"version": "3.4.7",
|
|
24
|
+
"sha256": "9e437ef92fa51f06eedeb1ef092c0a887bd24fe0d40b1e900191117ce1653121",
|
|
25
|
+
"url": "https://cdn.jsdelivr.net/pyodide/v314.0.8/full/charset_normalizer-3.4.7-py3-none-any.whl",
|
|
26
|
+
"file": "charset_normalizer-3.4.7-py3-none-any.whl"
|
|
27
|
+
},
|
|
28
|
+
{
|
|
29
|
+
"name": "idna",
|
|
30
|
+
"version": "3.11",
|
|
31
|
+
"sha256": "1619419bc899f07c7a608a12e8238e5e0bc15bb25fec90cfe20a86bb849ba0d8",
|
|
32
|
+
"url": "https://cdn.jsdelivr.net/pyodide/v314.0.8/full/idna-3.11-py3-none-any.whl",
|
|
33
|
+
"file": "idna-3.11-py3-none-any.whl"
|
|
34
|
+
},
|
|
35
|
+
{
|
|
36
|
+
"name": "pyodide-http",
|
|
37
|
+
"version": "0.2.2",
|
|
38
|
+
"sha256": "f987d500bccd6ef49b6a9b8dcdb9b2fc41fd6f5b0e7305cef06acfcd74bbc55f",
|
|
39
|
+
"url": "https://cdn.jsdelivr.net/pyodide/v314.0.8/full/pyodide_http-0.2.2-py3-none-any.whl",
|
|
40
|
+
"file": "pyodide_http-0.2.2-py3-none-any.whl"
|
|
41
|
+
},
|
|
42
|
+
{
|
|
43
|
+
"name": "requests",
|
|
44
|
+
"version": "2.33.1",
|
|
45
|
+
"sha256": "6d62c51c4e7707386bfc2ef54845c16cdaeb99606c064357cccfe4d621285175",
|
|
46
|
+
"url": "https://cdn.jsdelivr.net/pyodide/v314.0.8/full/requests-2.33.1-py3-none-any.whl",
|
|
47
|
+
"file": "requests-2.33.1-py3-none-any.whl"
|
|
48
|
+
},
|
|
49
|
+
{
|
|
50
|
+
"name": "urllib3",
|
|
51
|
+
"version": "2.6.3",
|
|
52
|
+
"sha256": "86b7c1af060597b115bcde5e36798039ca50b221afe14aa03d3437ac09b02a75",
|
|
53
|
+
"url": "https://cdn.jsdelivr.net/pyodide/v314.0.8/full/urllib3-2.6.3-py3-none-any.whl",
|
|
54
|
+
"file": "urllib3-2.6.3-py3-none-any.whl"
|
|
55
|
+
}
|
|
56
|
+
]
|
|
57
|
+
}
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
[extension]
|
|
2
|
+
name = "Shyft Python Fireworks"
|
|
3
|
+
version = "1.0.0"
|
|
4
|
+
description = "Pyodide-powered fireworks button on any page whose URL contains 'shyft'."
|
|
5
|
+
matches = ["<all_urls>"]
|
|
6
|
+
url_filter = "shyft"
|
|
7
|
+
entry = "main.py"
|
|
8
|
+
scripts = ["fireworks.js"]
|
|
9
|
+
http = true
|
|
10
|
+
host_permissions = ["<all_urls>"]
|
|
11
|
+
|
|
12
|
+
[vendor]
|
|
13
|
+
"fireworks.js" = "https://cdn.jsdelivr.net/npm/fireworks-js@2.10.8/dist/index.umd.js"
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
{
|
|
2
|
+
"hash": "dd2462d5ccae9748",
|
|
3
|
+
"python": "3.14",
|
|
4
|
+
"platform": "wasm32-pyodide2025",
|
|
5
|
+
"requirements": [
|
|
6
|
+
"pyodide-http",
|
|
7
|
+
"requests",
|
|
8
|
+
"urllib3",
|
|
9
|
+
"charset-normalizer",
|
|
10
|
+
"idna",
|
|
11
|
+
"certifi",
|
|
12
|
+
"numpy"
|
|
13
|
+
],
|
|
14
|
+
"pins": [
|
|
15
|
+
{
|
|
16
|
+
"name": "certifi",
|
|
17
|
+
"version": "2026.4.22"
|
|
18
|
+
},
|
|
19
|
+
{
|
|
20
|
+
"name": "charset-normalizer",
|
|
21
|
+
"version": "3.4.7"
|
|
22
|
+
},
|
|
23
|
+
{
|
|
24
|
+
"name": "idna",
|
|
25
|
+
"version": "3.11"
|
|
26
|
+
},
|
|
27
|
+
{
|
|
28
|
+
"name": "numpy",
|
|
29
|
+
"version": "2.4.6"
|
|
30
|
+
},
|
|
31
|
+
{
|
|
32
|
+
"name": "pyodide-http",
|
|
33
|
+
"version": "0.2.2"
|
|
34
|
+
},
|
|
35
|
+
{
|
|
36
|
+
"name": "requests",
|
|
37
|
+
"version": "2.33.1"
|
|
38
|
+
},
|
|
39
|
+
{
|
|
40
|
+
"name": "urllib3",
|
|
41
|
+
"version": "2.6.3"
|
|
42
|
+
}
|
|
43
|
+
]
|
|
44
|
+
}
|