Metadata-Version: 2.4
Name: ivs-sessions-browser
Version: 4.0.11
Summary: A terminal-based TUI for browsing IVS session schedules with fast filtering and keyboard navigation
Author: jole
License-Expression: MIT
Project-URL: Homepage, https://github.com/jonleithe/ivs_sessions_browser
Project-URL: Repository, https://github.com/jonleithe/ivs_sessions_browser
Project-URL: Documentation, https://github.com/jonleithe/ivs_sessions_browser/tree/v4/docs
Project-URL: Issues, https://github.com/jonleithe/ivs_sessions_browser/issues
Keywords: ivs,vlbi,sessions,tui,curses
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console :: Curses
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.31
Requires-Dist: beautifulsoup4>=4.12
Requires-Dist: python-dateutil>=2.8
Requires-Dist: reportlab>=4.0
Requires-Dist: openpyxl>=3.1
Requires-Dist: matplotlib>=3.8
Requires-Dist: tqdm>=4.65
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Requires-Dist: wheel>=0.43; extra == "dev"
Dynamic: license-file

# IVS Sessions Browser v4 (dev)

A terminal-based TUI for browsing [IVS session schedules](https://ivscc.gsfc.nasa.gov/sessions/): master and intensives, with fast filtering, keyboard navigation, and colorized status.

It is worth noting that this script is developed on Linux, for Linux terminal and optimized for a dark background!
It is not tested by me on anything else.
If you have any question, comment or feedback to this script; [Send email](mailto:dev@jonleithe.no?subject=Contact%20from%20github)
   -jole 2026

- **TUI**: curses interface with smooth navigation
- **Filters**: powerful, composable query language
- **Colors**: quick status scanning (Released / Processing / Waiting / Cancelled / None)
- **Open in browser**: jump to the IVS page for a session
- **Station filtering**: filter active/removed/all station sets in expressions
- **Jump to today**: one-key shortcut to the current session row
- **Exports**: save visible rows to text, colored PDF, or XLSX
- **Statistics**: inspect session totals and station contribution plots
- **Inline help**: `?` shows a centered help box

See also:
- 📄 [`docs/USER_GUIDE.md`](docs/USER_GUIDE.md)
- 🔎 [`docs/FILTER_SYNTAX.md`](docs/FILTER_SYNTAX.md)
- ⌨️ [`docs/KEY_BINDINGS.md`](docs/KEY_BINDINGS.md)
- 🗺️ [`docs/ROADMAP.md`](docs/ROADMAP.md)

---

## Project layout

```
ivs_sessions_browser/
├─ docs/
│  ├─ ARCHITECTURE.md
│  ├─ FILTER_SYNTAX.md
│  ├─ KEY_BINDINGS.md
│  ├─ ROADMAP.md
│  └─ USER_GUIDE.md
├─ scripts/
│  └─ run_sessions_browser.py	# launcher (imports package main)
├─ src/
│  └─ ivs_sessions_browser/
│     ├─ __init__.py			# CLI entry point (main())
│     ├─ __main__.py			# allows `python -m ivs_sessions_browser`
│     ├─ operators.json		# packaged default operator bindings
│     ├─ defs.py				# constants, headers, argument help text
│     ├─ fetch_sessions.py		# network fetch + response handling
│     ├─ filter_and_sort.py		# filtering and sorting logic
│     ├─ ivstypes.py			# type definitions and data classes
│     ├─ operators.py			# operator management and persistence
│     ├─ sessions_browser.py	# main TUI loop and orchestration
│     ├─ tui.py					# TUI rendering (headers, rows, help)
│     ├─ tui_state.py			# UI state dataclass and theme
│     └─ version.py				# version info (generated by setuptools-scm)
├─ operators.json				# source copy of default operator bindings
├─ operator_assignments.json	# local assignment file, ignored by git
├─ pyproject.toml
├─ requirements.txt				# python requirements for the project
├─ run_browser					# bash wrapper script
├─ LICENSE
└─ README.md
```

> **Note:** The project uses the **src/** layout. For development, install it with `pip install -e .`.
> Inside PyCharm, mark `src/` as **Sources Root** or use the editable virtualenv interpreter.
> User-editable settings are read from `~/.config/ivs-sessions-browser/`.
> Missing `operators.json`, `pdf_columns`, `startup_defaults.json`, and `manual_sessions.json` files are created there from defaults the first time `ivs-sessions-browser` runs.
> Edit `~/.config/ivs-sessions-browser/operators.json` to replace the default `U1`-`U5` operator labels with your local operator names.
> Edit `~/.config/ivs-sessions-browser/startup_defaults.json` to choose default startup `year`, `scope`, `filters`, and `mirrors` values.
> Edit `~/.config/ivs-sessions-browser/manual_sessions.json` to add sessions that are not present in the IVS schedules.
> The app also records the last displayed "what's new" version in `~/.config/ivs-sessions-browser/app_state.json`.

---

## Requirements

- Python **3.10+**
- Linux/macOS terminal with curses support
  Windows users: `pip install windows-curses`
- Internet access to fetch schedules from ivscc.gsfc.nasa.gov, or any of the mirror sites

---

## Installation

### From PyPI

For normal use as a command-line app, `pipx` is recommended:

```bash
pipx install ivs-sessions-browser
ivs-sessions-browser --init-config
ivs-sessions-browser
```

On Linux distributions with externally managed Python environments, avoid
installing into system Python with `pip --break-system-packages`.

### From source

```bash
git clone git@github.com:jonleithe/ivs_sessions_browser.git
cd ivs_sessions_browser

python3 -m venv .venv
source .venv/bin/activate            # Windows PowerShell: .\.venv\Scripts\Activate.ps1

pip install -r requirements.txt
```

### Editable development install

```bash
pip install -e .
```

You can now run:
```bash
ivs-sessions-browser
```
On Windows, use `.\.venv\Scripts\ivs-sessions-browser.exe`.

To create the editable default config files without starting the TUI:
```bash
ivs-sessions-browser --init-config
```

To read the bundled manual page:
```bash
ivs-sessions-browser --man
```

---

## How to run (terminal)

You have multiple equivalent ways. Pick your favorite:

### A) Console script (recommended after install)

```bash
ivs-sessions-browser
```

### B) Wrapper script

`run_browser` is included in the project root:

```bash
./run_browser
```

### C) Run the package as a module

```bash
python -m ivs_sessions_browser
```

---

## Usage

Most usage is interactive (TUI). Command-line flags typically include:

```
--year 2025                    # single year
--year "2021,2025"             # explicit multi-year list
--year "2022-2025"             # inclusive year range
--scope master|intensive|both  # select scope
--filters "code:R1|R4"         # initial filter expression
--output -                     # write text output to stdout and exit
--pretty-print OP|TYPE|STATIONS
--format pdf                  # write a colored PDF using the same pretty-printed lines
--format xlsx                 # write an Excel workbook with spreadsheet cells
--no-mirrors                  # disable startup default mirror checking for this run
--verbose-fetch                # show fetch/progress output even with --output
--import-local                 # import local .vex/.skd files from the current directory
--init-config                  # create default user config files and exit. Usually done after install.
--man                          # show the bundled manual page and exit
```

Run with `-h/--help` (help) to see current options.

When `--year`, `--scope`, `--filters`, or `--mirrors` are omitted, the app
checks `~/.config/ivs-sessions-browser/startup_defaults.json` before falling
back to built-in defaults. Command-line arguments always override the file.

```json
{
  "filters": "status:released; stations:Nn",
  "mirrors": false,
  "scope": "both",
  "year": null
}
```

Once inside the TUI:
- Use arrow keys / PgUp / PgDn / Home / End to navigate
- Press `T` to jump to today
- Press `/` to enter/edit a filter
- Press `C` to clear filters
- Press `D` to save the current filter as the startup default
- Press `A` or `+` to add a manual session inline
- Press `Del` to delete the selected manual session
- Press `0-5` to assign an operator to the selected session (or clear with '0')
- Press `Enter` to open the selected session in your browser
- Press `P` to export visible rows to PDF
- Press `X` to export visible rows to XLSX
- Press `S` to show session statistics
- Press `G` to save/open a station contribution plot; repeated presses cycle session %, hours, and weighted hours
- Press `?` for inline help
- Press `q/Q` to quit

### Inline help (`?`)

```
Navigation:
  ↑ ↓ PgUp PgDn Home End   Move around the session list
  T                        Jump to today’s session
  Enter                    Open session page in web browser
  q or Q                   Quit

Filtering:
  /                        Enter a filter expression
  C                        Clear current filters
  D                        Save current filter as startup default
  Examples:
    code:R1|R4             → match sessions with code R1 or R4
    stations:Nn&Ns         → sessions including both Nn and Ns
    stations_removed:Ft|Ur → removed stations include Ft or Ur

Operator Assignment:
  0-5                      Assign operator to selected session
                          (operators configured in ~/.config/ivs-sessions-browser/operators.json)

Manual Sessions:
  A or +                   Add a manual session inline
  Del                      Delete the selected manual session
  --import-local           Import local .vex/.skd files into manual_sessions.json

Other:
  P                        Export visible rows to PDF and open it
  X                        Export visible rows to XLSX and open it
  S                        Show session statistics
  G                        Save/open station contribution plot
  ?                        Show this help screen

Notes:
- Station names are **case-sensitive**
- Other fields are **case-insensitive**
- Clauses separated by `;` are AND
- Tokens separated by space, `,`, `+`, or `|` are OR
```

Full details:
- 🔎 Filtering: [`docs/FILTER_SYNTAX.md`](docs/FILTER_SYNTAX.md)
- ⌨️ Keys: [`docs/KEY_BINDINGS.md`](docs/KEY_BINDINGS.md)

## Export formats

- `--format text` writes the ANSI-colored textual listing.
- `--format pdf` writes a monospaced PDF that preserves the existing header and row colors from the textual export.
- `--format xlsx` writes spreadsheet cells with headers, filters, frozen first row, code hyperlinks, and operator row colors.
- `--append` only applies to text output; PDF and XLSX export always write a new file.

Example:

```bash
./run_browser --year 2025 --output sessions.pdf --format pdf
./run_browser --year 2025 --output sessions.xlsx --format xlsx
```

---

## Filter basics (quick primer)

- Clauses separated by `;` are **AND**.
- **Stations** fields are **case-sensitive**.
- Other fields are **case-insensitive**.
- Within a non-station field, tokens split by space/comma/`+`/`|` are **OR**.

Examples:
- `code:R1|R4` → codes matching R1 **or** R4
- `stations:Nn&Ns` → requires **both** Nn **and** Ns present (active stations)
- `stations_removed:Ag|Kk` → removed stations include Ag **or** Kk
- `stations_active:Ft|Ur` → active stations include Ft **or** Ur
- `stations_all:Ke|Oe` → any stations (active or removed) include Ke **or** Oe
- Combine filters: `code:R1|R4; stations:Nn&Ns; status:released`

---

## Troubleshooting

**`ModuleNotFoundError: No module named 'ivs_sessions_browser'`**
Use one of:
- `pip install -e .`, then `ivs-sessions-browser`
- `./run_browser` wrapper
- In PyCharm, use the project virtualenv or mark `src/` as Sources Root

**Windows: curses import error**
Install: `pip install windows-curses`.

**No colors / weird characters**
Use a modern terminal with UTF-8 and 256-color support; ensure `$TERM` is e.g. `xterm-256color`.

---

## Versioning

This project uses **setuptools-scm**. Version strings are derived from Git tags.
To cut a release:
```bash
git tag v4.0.0
git push --tags
```

---

## Contributing

- Keep the TUI responsive; avoid blocking network calls on the UI thread.
- Prefer small, focused modules under `src/ivs_sessions_browser/`.
- Write clear commit messages; tag releases for versioning.

---

## License

MIT — see [LICENSE](LICENSE).

---

## Acknowledgments

- IVS Central Bureau & Goddard Space Flight Center for session listings
- Contributors and testers across Ny-Ålesund & Brandal observatories
