Skip to main content

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

  1. 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.

  2. CDP sidecar mode (working today, via the lum-cdp console 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 in data/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 the lum-cdp console script. Bridge logic covered by an automated fake-CDP test harness in tests/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_DIR is 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)

Source distribution for loominum 0.2.0
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)

Table of built distributions (wheels) for loominum 0.2.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Release history Release notifications | RSS feed

This release

0.2.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page