loominum
A Python library for driving and observing a live browser session from Python code, with bidirectional async event flow. Python pushes JavaScript into the page; the page emits events back.
Two transports
-
JS-injection mode (working today) — a one-time paste-bootstrap opens a WebSocket from the page back to the Python server. Site-agnostic, no Chrome flags, but bootstrap is manual and injection dies on navigation unless re-pasted.
-
CDP sidecar mode (working today, via the
lum-cdpconsole script) — a Python sidecar speaks Chrome DevTools Protocol to a CDP-enabled browser and impersonates a browser to the Loominum server. Gives nav-surviving injection (Page.addScriptToEvaluateOnNewDocument) and CAPTCHA-safe trusted-event dispatch (Input.dispatchKeyEvent/dispatchMouseEvent). Requires the browser launched with--remote-debugging-port.
Same lum.exec / on / add_init / navigate API across both transports.
Use cases
- Authenticated API automation (call APIs in browser context with session cookies)
- Scrape orchestration with DOM-event triggers
- Download monitoring (watch DOM for ready-links, hand off filenames to Python)
- Form automation
- Interactive Python-REPL → browser debugging
Status
src/loominum/— JS-injection implementation. Site-agnostic API surface; ships with localhost defaults indata/loominum/config.json(port 7773, TLS off).src/loominum/README.md— the API documentation (server/client/browser).src/loominum/EVENTS.md— event-system documentation.src/loominum/NGINX.md— deployment notes for fronting the server with nginx (TLS termination, path-based routing).- CDP sidecar — implemented in
src/loominum/cdp.py; run via thelum-cdpconsole script. Bridge logic covered by an automated fake-CDP test harness intests/test_cdp.py.
Layout
loominum/
├── README.md this file
├── HANDOFF.md design doc for the next agent picking this up
├── src/loominum/ library source (JS-injection base + CDP sidecar)
│ ├── __init__.py
│ ├── server.py WS server — handles both the /remote browser and /client python endpoints
│ ├── client.py Python client
│ ├── config.py config schema + discovery (discover_config, LumConf.auto)
│ ├── cdp.py CDP sidecar transport (lum-cdp)
│ ├── htdocs/ served static files: remote.js (the bootstrap),
│ │ evtcap.js (console tap helper), install-cert scripts
│ ├── scripts/ cert install helpers
│ ├── README.md API reference
│ ├── EVENTS.md event system
│ └── NGINX.md nginx deployment notes
├── data/loominum/
│ └── config.json template — localhost defaults, no TLS
└── tests/
├── test_cdp.py CDP bridge tests (fake-CDP harness)
├── test_config.py config discovery + env-override tests
└── test_lum.py manual live-server smoke script
Installation
pip install loominum
Installs the lum (server) and lum-cdp (CDP sidecar) console scripts.
Configuration
Loominum runs with localhost defaults and no config file required. To
customize, drop a config.json in any conventional location or override
single settings via environment variables — full precedence rules in
src/loominum/README.md.
{
"verbose": false,
"log_file": "log/lum.log",
"server_url": "http://127.0.0.1:7773",
"client_url": "http://127.0.0.1:7773",
"cert_sans": null
}
Quick paths:
- A file:
./loominum.json,~/.config/loominum/config.json, or$LOOMINUM_CONFIG=/full/path.json. (PRJ_DIRis still honored for back-compat but no longer required.) - A single setting:
LOOMINUM_SERVER_URL,LOOMINUM_CLIENT_URL,LOOMINUM_LOG_FILE,LOOMINUM_CERT_SANS,LOOMINUM_VERBOSE.
For TLS: set cert_sans to a comma-separated list of hostnames/IPs to
include in the cert SANs (e.g. "localhost,192.168.1.100") and use an
https:// scheme on server_url. Cert install helpers under
src/loominum/scripts/.
Quick start (current JS-injection mode)
lum # or, from a source checkout: PYTHONPATH=src python -m loominum.server
Then in the browser DevTools console of the target page:
fetch('http://127.0.0.1:7773/remote.js?t='+Date.now()).then(r=>r.text()).then(eval);
Then from Python:
import asyncio
from loominum import LumClient
async def main():
async with LumClient() as client:
title = await client.exec('document.title')
print(title)
asyncio.run(main())
See src/loominum/README.md for the full API.
Quick start (CDP sidecar mode)
Launch a Chromium-based browser with remote debugging enabled:
chromium --remote-debugging-port=9222
Then start the server and the sidecar (it discovers the target tab, auto-injects the page bridge, and impersonates a browser to the server):
lum & # start the server (installed console script)
lum-cdp --target-url example.com
From Python, the API is identical to JS-injection mode:
import asyncio
from loominum import LumClient
async def main():
async with LumClient() as client:
print(await client.exec('document.title'))
asyncio.run(main())
The CDP transport survives page navigations (init code re-runs on every new
document) and can dispatch trusted input via CDPTransport.dispatch_key,
type_text, and click.
Testing
pytest tests/test_cdp.py
Covers the bridge with a fake CDP browser (no real Chrome required). A real-
browser scenario auto-runs when localhost:9222 is reachable and otherwise
skips.
License
Apache-2.0 — see LICENSE.
Metadata
Release files for loominum 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| loominum-0.2.0.tar.gz | 62.3 kB | With provenance | Details for loominum-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| loominum-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for loominum-0.2.0-py3-none-any.whl |
Total release size: 122.0 kB
Release files / loominum-0.2.0.tar.gz
| Download URL | loominum-0.2.0.tar.gz |
|---|---|
| Size | 62.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
29daec7aa354b48234d23681f0a9cdd5313f944bb91de243086131075ae4aeb2
|
|
BLAKE2b-256 checksum How to use checksums |
6402bd8d6eafddc7cbab51199ab593270f50dad06a9e58c5d24ae33fa72d474a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 23, 2026.
Transparency logRelease files / loominum-0.2.0-py3-none-any.whl
| Download URL | loominum-0.2.0-py3-none-any.whl |
|---|---|
| Size | 59.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
ee2e59a96adcc9aa91fcfb0b393e090e4cc44fb73caba308bcee81432f58f159
|
|
BLAKE2b-256 checksum How to use checksums |
5daba7b967f77202a307e914ef0d40ede1d2d94046fc195ba4d50fa27a094318
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 23, 2026.
Transparency logSecurity for loominum 0.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for loominum-0.2.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 23, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.