ivs-sessions-browser 4.0.11

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
• 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
│     ├─ 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:

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

{
  "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
• ⌨️ 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, code hyperlinks, and operator row colors.
• --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