Metadata-Version: 2.4
Name: atlas-lumi
Version: 0.2.0
Summary: Terminal-based conditions database explorer for ATLAS/LHC
Author: CERN ATLAS
Maintainer-email: Joe Gibson <joseph.gibson@cern.ch>
License-Expression: Apache-2.0
Project-URL: Repository, https://gitlab.cern.ch/crest-db/lumi
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: textual<9,>=8.2.3
Requires-Dist: tomlkit<1,>=0.13
Requires-Dist: atlas-chai<3,>=2.8
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
Requires-Dist: ruff>=0.8; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Dynamic: license-file

# 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](https://gitlab.cern.ch/crest-db/chai) and [Textual](https://textual.textualize.io/).

![Lumi TUI](https://gitlab.cern.ch/crest-db/lumi/-/raw/master/lumi-screenshot.png)

## 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](https://pipx.pypa.io/) 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:

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

`uv tool install --python 3.12 atlas-lumi` does the same with [uv](https://docs.astral.sh/uv/). On lxplus, a shared venv in the `atlcond` account already has Lumi. See [Use existing venv](https://gitlab.cern.ch/crest-db/chai/-/blob/master/README-lxplus.md#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](https://gitlab.cern.ch/crest-db/chai/-/blob/master/python/WHEEL_BUILDING.md#build-a-wheel-locally)) and install it into your environment. Installing Lumi then finds it already satisfied.

## Quick start

```bash
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:

```toml
[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](https://gitlab.cern.ch/crest-db/CrestApi#authorization). 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](#other-platforms)).

```bash
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.

```bash
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
