Skip to main content

Lumi

Lumi is a terminal app for exploring ATLAS conditions databases. It browses global tags, tags, IOVs and payloads on CREST, COOLR and file-system backends, diffs them across backends, and copies tags between databases, with an embedded Python shell alongside. It is built on CHAI and Textual.

Lumi TUI

Highlights

  • Several connections open at once, each a root of the browser tree with its own coloured chip. The source of every operation is wherever the cursor sits.
  • Payload views that adapt to the container type: single-IOV, multi-IOV (with a sub-IOV viewer and delta highlighting), vector and raw.
  • Diffs between any two IOVs or tags, on the same connection or across backends: two tags compare IOV by IOV, any pair opens its payload diff, and either saves as a text and JSON report.
  • A copy workbench that previews every IOV's status on the destination before anything is written, then runs the copy in the background while you keep browsing. It follows crest copy: a since-only resume (forced when COOLR is involved), a since/until range, tag only, multi-IOV and raw tags, hash-preserving copies within one connection, and a content check that tells a re-serialized payload from a changed one.
  • Tag Search, a tab beside the global tags tree: search tag names across connections by name or regex, including tags no global tag maps yet. The Tag panel always says which tag it shows and where it was opened from.
  • Read-only connections: COOLR and production CREST are never written to.
  • A Python console with the current database as db.
  • A source bar showing the current connection, its typical request time, and the CHAI operation in flight.
  • A per-session log file to attach to bug reports.

Installation

Lumi is published on PyPI as atlas-lumi and needs Python 3.12 or newer. It depends on atlas-chai, CHAI's Python bindings, which PyPI provides for Linux x86_64 only.

pipx installs Lumi into its own environment and puts lumi on your PATH. Where the default python3 is older than 3.12 (lxplus: 3.9), the flags point pipx at a python3.12, or let it download one:

pipx install --python 3.12 --fetch-missing-python atlas-lumi

uv tool install --python 3.12 atlas-lumi does the same with uv. On lxplus, a shared venv in the atlcond account already has Lumi. See Use existing venv.

To also import chai in your own scripts, pip install atlas-lumi into a virtual environment instead: the same environment then runs lumi and imports chai. Lumi's Python console runs in the environment Lumi is installed in, so a package you want there (say numpy) goes into that environment, with pip install or pipx inject atlas-lumi.

Other platforms

On any platform other than Linux x86_64, pip stops with "no matching distribution" for atlas-chai. Build an atlas-chai wheel locally first (Build a Wheel Locally) and install it into your environment. Installing Lumi then finds it already satisfied.

Quick start

lumi

On first run Lumi creates ~/.config/lumi/config.toml with a default cern connection to the CREST production server and connects to it, so you can start browsing straight away. Press ? for every key. The row at the bottom shows the keys that work where you are.

Configuration

Connections, the theme and the console's auto-imports live in ~/.config/lumi/config.toml. The connection manager and the settings popup edit it from inside Lumi and apply changes at once. Editing it by hand works too:

[connections.prod]
uri = "crest:https://crest.cern.ch/api-v6.0"
default = true

[connections.local]
uri = "crest_fs:/tmp/crest_data"
color = "sage"  # chip colour: a palette name or "#RRGGBB"

[connections.cool]
uri = "coolr:https://coolr-host:8080/coolrapi?db=CONDBR2&schema=COOLOFL_TILE"

[read_only]  # Connections copies never write to: by URI scheme, or by host
schemes = ["coolr"]
hosts = ["crest.cern.ch", "atlas-crest-mgr.cern.ch"]

[ui]
theme = "tokyo-night"

[shell]
auto_import = ["import numpy as np"]

Every URI starts with a CHAI scheme (crest:, crest_fs:, coolr:), and the schemes on offer are the CHAI plugins installed. Authentication is handled by each CHAI plugin. For CREST, see CREST Server Authentication. The settings popup lists every [ui] and [shell] option. The [read_only] lists above are the defaults; a connection's own read_only = true or false overrides them, except that COOLR is always read-only.

Session log

Each run writes a log file under ~/.local/state/lumi/logs/ (or $XDG_STATE_HOME/lumi/logs/): versions, connections, every Log tab entry, copy progress and the traceback of any unexpected error. Credentials are masked and payload contents are not logged. lumi --log-path prints where it is. Attach it when reporting a problem.

Troubleshooting

Quitting waits for a request in flight. Lumi never interrupts a CHAI call midway, since a write could be left half sent, so quitting during a slow request waits for that one call. CrestApi sets no network timeout, so an unresponsive server holds the terminal until the request fails.

Copying text over SSH. Lumi sends copied text over OSC 52, which reaches your local clipboard in terminals that support it. To select text with the mouse in a table, the tree or the console, hold the terminal's selection modifier while dragging (Option in iTerm2, Shift in most others).

Development

Clone the repository and install Lumi in editable mode with the development tools. On macOS, install a locally built atlas-chai wheel into the venv first (see Other platforms).

git clone https://gitlab.cern.ch/crest-db/lumi.git
cd lumi
python3.12 -m venv venv
venv/bin/pip install -e ".[dev]"

The test suite does not need CHAI: tests stub the chai module, and CI runs them without atlas-chai installed.

venv/bin/pytest --cov=lumi --cov-report=term-missing
venv/bin/ruff check src/ tests/
venv/bin/mypy src/

Releasing

  1. Run ./scripts/release.sh X.Y.Z. It bumps __version__ in src/lumi/__init__.py, the only place the version is set, and refuses a version that is not newer or is already tagged. It does not commit, tag or push.
  2. Commit the bump on a release/X.Y.Z branch and merge it to master.
  3. Tag the merge commit X.Y.Z (no v prefix, as in CHAI) and push the tag.
  4. The tag pipeline checks the tag against __version__, uploads to TestPyPI and smoke-tests the install from there. If it passes, run the manual publish_pypi job.

A version cannot be uploaded twice to either index. If anything is wrong after the TestPyPI upload, fix it and release the next patch version.

License

Apache-2.0

Metadata

Release files for atlas-lumi 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 atlas-lumi 0.2.0
File Size Uploaded Provenance Actions
atlas_lumi-0.2.0.tar.gz 177.9 kB Without provenance Details for atlas_lumi-0.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for atlas-lumi 0.2.0
File Interpreter ABI Platform Actions
atlas_lumi-0.2.0-py3-none-any.whl Python 3 none any Details for atlas_lumi-0.2.0-py3-none-any.whl

Total release size: 384.2 kB

Release files / atlas_lumi-0.2.0.tar.gz

Download URL atlas_lumi-0.2.0.tar.gz
Size 177.9 kB
Tags Source
SHA-256 checksum
How to use checksums
a1f91ea1056bd10bf08433b2db3426c9ad6522b47062c84037bfd36c58907554
BLAKE2b-256 checksum
How to use checksums
1ee93105e61da50837659840897464de147f6800d2067c97d7b4bd0cc983c7c7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.16

Release files / atlas_lumi-0.2.0-py3-none-any.whl

Download URL atlas_lumi-0.2.0-py3-none-any.whl
Size 206.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
9e3e09a3239c375057902b54cf940fccbcb907c4d1188f0484d6035df687aeba
BLAKE2b-256 checksum
How to use checksums
afaa90b8b11b7fedb4cf452f65ccf73053b34aa357566eaba8801ae5f5fe3e13
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.16

Security for atlas-lumi 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.

No provenance found

None of the files in this release were uploaded with provenance metadata.

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 No 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