ivs-sessions-browser 4.0.13

A terminal-based TUI for browsing IVS session schedules with fast filtering and keyboard navigation

IVS Sessions Browser v4 (dev)

A terminal-based TUI for browsing IVS session schedules: 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 -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/FILTER_SYNTAX.md
• ⌨️ docs/KEY_BINDINGS.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:

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

git clone [e-mail]: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

pip install -e .

You can now run:

ivs-sessions-browser

On Windows, use .\.venv\Scripts\ivs-sessions-browser.exe.

To create the editable default config files without starting the TUI:

ivs-sessions-browser --init-config

To read the bundled manual page:

ivs-sessions-browser --man

---

How to run (terminal)

You have multiple equivalent ways. Pick your favorite:

A) Console script (recommended after install)

ivs-sessions-browser

B) Wrapper script

run_browser is included in the project root:

./run_browser

C) Run the package as a module

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.

{
  "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
• ⌨️ Keys: 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:

./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:

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.

---

Acknowledgments

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