ivs-sessions-browser 4.0.2__tar.gz

ivs_sessions_browser-4.0.2/.github/workflows/publish.yml

@@ -0,0 +1,56 @@
+name: Publish Python package
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - name: Install build backend
+        run: python -m pip install --upgrade build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Store distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

ivs_sessions_browser-4.0.2/.gitignore

@@ -0,0 +1,66 @@
+# Python bytecode and caches
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# Build / packaging
+build/
+dist/
+.eggs/
+*.egg-info/
+*.egg
+pip-wheel-metadata/
+
+# Test / type-check / lint caches
+.pytest_cache/
+.mypy_cache/
+.pytype/
+.ruff_cache/
+.coverage
+.coverage.*
+htmlcov/
+
+# Jupyter
+.ipynb_checkpoints/
+
+# IDE / editor files
+.idea/
+*.swp
+*.swo
+*~
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+
+# Local environment files
+.env
+.env.*
+
+# Local runtime artifacts
+.codex
+*.pid
+*.tmp
+
+operator_assignments.json
+src/ivs_sessions_browser/version.py
+
+# Files suggested to be ignored by user
+.editorconfig
+.pre-commit-config.yaml
+pyrightconfig.json
+pytest.ini
+ruff.toml
+src/ivs_sessions_browser/_version.py
+sessions*.pdf
+software_flow.md
+*.png

ivs_sessions_browser-4.0.2/.vscode/extensions.json

@@ -0,0 +1,11 @@
+{
+  "recommendations": [
+    "ms-python.python",
+    "ms-python.vscode-pylance",
+    "ms-python.debugpy",
+    "charliermarsh.ruff",
+    "tamasfe.even-better-toml"
+    , "ryuta46.multi-command"
+  ]
+}
+

ivs_sessions_browser-4.0.2/.vscode/keybindings.json.crap

@@ -0,0 +1,8 @@
+[
+  {
+    "key": "ctrl+numpad_divide",
+    "command": "multiCommand.commentAndNextLine",
+    "when": "editorTextFocus && !editorReadonly"
+  }
+]
+

ivs_sessions_browser-4.0.2/.vscode/launch.json

@@ -0,0 +1,31 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "ivs_sessions_browser (module)",
+      "type": "debugpy",
+      "request": "launch",
+      "module": "ivs_sessions_browser",
+      "args":["--scope", "both", "--filters", "stations:Ns|Nn", "--year", "2022-2024"],
+      "cwd": "${workspaceFolder}",
+      "env": {
+        "PYTHONPATH": "${workspaceFolder}/src"
+      },
+      "console": "integratedTerminal",
+      "justMyCode": true
+    },
+    {
+      "name": "run_sessions_browser.py (script)",
+      "type": "debugpy",
+      "request": "launch",
+      "program": "${workspaceFolder}/scripts/run_sessions_browser.py",
+      "cwd": "${workspaceFolder}",
+      "env": {
+        "PYTHONPATH": "${workspaceFolder}/src"
+      },
+      "console": "integratedTerminal",
+      "justMyCode": true
+    }
+  ]
+}
+

ivs_sessions_browser-4.0.2/.vscode/python.code-snippets

@@ -0,0 +1,30 @@
+{
+  "Docstring with filename": {
+    "scope": "python",
+    "prefix": "docf",
+    "description": "Docstring header with current filename",
+    "body": [
+      "\"\"\"",
+      "Defined in ${TM_FILENAME}",
+      "",
+      "${1:Describe what this function does.}",
+      "\"\"\""
+    ]
+  },
+  "Module docstring with filename": {
+    "scope": "python",
+    "prefix": "moddocf",
+    "description": "Module docstring including metadata and current filename",
+    "body": [
+      "\"\"\"",
+      "Defined in ${TM_FILENAME}",
+      "",
+      "Filename:       ${TM_FILENAME}",
+      "Author:         ${1:your_name}",
+      "Created:        ${CURRENT_YEAR}-${CURRENT_MONTH}-${CURRENT_DATE}",
+      "",
+      "Description:    ${2:Module description}",
+      "\"\"\""
+    ]
+  }
+}

ivs_sessions_browser-4.0.2/.vscode/settings.json

@@ -0,0 +1,50 @@
+{
+  // Use the repo venv
+  "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python",
+  // Make 'src' layout import-friendly for analysis/autocomplete
+  "python.analysis.extraPaths": [
+    "${workspaceFolder}/src"
+  ],
+  // Testing
+  "python.testing.pytestEnabled": true,
+  "python.testing.unittestEnabled": false,
+  "python.testing.pytestArgs": [
+    "-q"
+  ],
+  // Editor hygiene
+  "files.exclude": {
+    "**/__pycache__": true,
+    "**/*.pyc": true
+  },
+  "search.exclude": {
+    "**/__pycache__": true,
+    "**/*.pyc": true,
+    ".venv": true
+  },
+  // Optional but strongly recommended: format-on-save
+  "editor.formatOnSave": false,
+  "editor.codeActionsOnSave": {
+    "source.organizeImports": "never",
+    "source.fixAll": "never"
+},
+  "editor.tabSize": 4,
+  "editor.insertSpaces": true,
+  "editor.detectIndentation": false,
+  // Show vertical ruler at column 80
+  "editor.rulers": [80],
+  "editor.wordWrap": "off",
+  // Configure the multi-command sequences (requires ryuta46.multi-command extension)
+  "multiCommand.commands": [
+    {
+      "command": "multiCommand.commentAndNextLine",
+      "sequence": [
+        "editor.action.commentLine",
+        "cursorDown"
+      ]
+    }
+  ],
+  // Workbench color customizations: dim unused code instead of error color
+  "workbench.colorCustomizations": {
+    "editorUnnecessary.foreground": "#6c757d"
+  }
+}

ivs_sessions_browser-4.0.2/LICENSE

@@ -0,0 +1,21 @@
+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.

ivs_sessions_browser-4.0.2/PKG-INFO

@@ -0,0 +1,323 @@
+Metadata-Version: 2.4
+Name: ivs-sessions-browser
+Version: 4.0.2
+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/`.
+
+---
+
+## 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`.
+
+---
+
+## 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