Metadata-Version: 2.4
Name: ivs-sessions-browser
Version: 4.0.13
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
- **Manual sessions**: add sessions inline or import local VEX/SKD schedule files
- **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
│     ├─ manual_sessions.py		# manual session validation, storage, and rows
│     ├─ operators.py			# operator management and persistence
│     ├─ pdf_export.py			# colored PDF export
│     ├─ session_file_import.py	# local .vex/.skd import into manual sessions
│     ├─ sessions_browser.py	# main TUI loop and orchestration
│     ├─ statistics.py			# statistics popup and station plots
│     ├─ tui.py					# TUI rendering (headers, rows, help)
│     ├─ tui_state.py			# UI state dataclass and theme
│     ├─ xlsx_export.py			# XLSX spreadsheet export
│     └─ 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 filters and colored rows
--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 `F1`-`F12` to toggle a start-month filter from January to December
- 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
  F1-F12                   Toggle start month Jan-Dec
  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
  Tab / Shift+Tab          Move between Type, Code, Start, Dur, Stations, Ops, Corr
  Enter / Esc              Save or cancel manual-add
  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
- `start:` accepts month names like `jun` or `june`
```

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, clickable code links, and operator row colors. Session code links are written so their font color follows the rest of the row.
- `--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
