Metadata-Version: 2.4
Name: ivs-sessions-browser
Version: 4.0.4
Summary: A terminal-based TUI for browsing IVS session schedules with fast filtering and keyboard navigation
Author: jole
License: MIT License
        
        Copyright (c) 2025 Jon Leithe
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
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: License :: OSI Approved :: MIT License
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: matplotlib>=3.8
Requires-Dist: tqdm>=4.65
Provides-Extra: dev
Requires-Dist: pytest>=7.0; 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
- **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` and `pdf_columns` 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.

---

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

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

---

## 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 "2022,2023"             # 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
--verbose-fetch                # show fetch/progress output even with --output
```

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

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 `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 `?` 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
  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)

Other:
  ?                        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.
- `--append` only applies to text output; PDF export always writes a new file.

Example:

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

---

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