simurg-ppp 0.1.0__tar.gz

simurg_ppp-0.1.0/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+All notable user-facing changes should be documented in this file.
+
+This project uses semantic versioning while the public API is small and evolving.
+
+## 0.1.0 - 2026-08-31
+
+- Package the project for PyPI as `simurg-ppp`.
+- Add the installed `simurg-ppp` console command.
+- Expose the future SIMURG plugin entry point `simurg.commands = ppp`.
+- Keep compatibility wrappers for `python -m ppp_client`, `python ppp_client.py`, and `ppp_tui.py`.
+- Include workflow, RINEX, PPP task, plotting, storage, and TUI functionality.

simurg_ppp-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,48 @@
+# Contributing
+
+## Development Setup
+
+Use Python 3.10 or newer.
+
+```bash
+python -m venv .venv
+. .venv/bin/activate
+pip install -e .
+pip install pytest twine build
+```
+
+Poetry can also be used for release workflows:
+
+```bash
+poetry install
+```
+
+## Checks
+
+Run the full test suite before submitting changes:
+
+```bash
+python -m pytest -q
+poetry check
+```
+
+Build and inspect release artifacts before uploading:
+
+```bash
+poetry build
+python -m twine check dist/*
+```
+
+## Project Layout
+
+- `src/ppp_client/` contains installable runtime code.
+- `src/ppp_client/tui/` contains the terminal UI workflow.
+- `src/ppp_client/tools/` contains adapters for external RINEX tools.
+- `tests/` contains regression coverage for CLI, packaging, workflow, storage, and parsing behavior.
+- `docs/` contains user and maintainer-facing documentation assets.
+- `usecases/` contains runnable examples for manual workflow exploration.
+
+## Release Notes
+
+Update `CHANGELOG.md` for every user-facing change. Keep the package version in
+`pyproject.toml` aligned with the next release entry.

simurg_ppp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SIMURG PPP maintainers
+
+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.

simurg_ppp-0.1.0/PKG-INFO

@@ -0,0 +1,177 @@
+Metadata-Version: 2.1
+Name: simurg-ppp
+Version: 0.1.0
+Summary: SIMURG PPP client and workflow tools
+License: MIT
+Keywords: gnss,ppp,precise-point-positioning,rinex,simurg
+Author: SIMURG PPP maintainers
+Requires-Python: >=3.10
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+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 :: Only
+Classifier: Topic :: Scientific/Engineering
+Requires-Dist: matplotlib
+Requires-Dist: requests
+Description-Content-Type: text/markdown
+
+# SIMURG PPP
+
+SIMURG PPP is a Python client for running Precise Point Positioning workflows with SIMURG RINEX sources and a PPP processing service. It provides small command-line commands for individual PPP tasks, workflow commands for site/date processing, and an interactive terminal UI for selecting SIMURG sites and running batches.
+
+The package is published as `simurg-ppp` and imports as `ppp_client`.
+
+```bash
+pip install simurg-ppp
+```
+
+## TUI
+
+Run `simurg-ppp` with no subcommand to launch the interactive terminal UI:
+
+```bash
+simurg-ppp
+```
+
+The TUI guides the SIMURG PPP workflow from the terminal. It can check service availability, verify external RINEX tools, select stored groups, choose dates, load processed SIMURG sites, select sites manually or from pasted input, and run workflow batches while showing progress and logs. Launching the TUI also creates config automatically on first run when no standard config exists; feel free to change it if needed.
+
+Useful TUI options:
+
+```bash
+simurg-ppp --skip-startup
+simurg-ppp --date 2025-11-11
+simurg-ppp --storage-root workflow-data
+simurg-ppp --select-only
+```
+
+For non-interactive site/date processing, use workflow commands:
+
+```bash
+simurg-ppp workflow start irkj 2025-11-11
+simurg-ppp workflow proceed irkj 2025-11-11
+simurg-ppp workflow status irkj 2025-11-11
+simurg-ppp workflow report irkj 2025-11-11
+```
+
+## CLI
+
+Use the atomic commands when you already have a local RINEX file or a PPP task id. 
+
+Create configuration first if it is fresh installation and you didn't run TUI app.
+
+```bash
+simurg-ppp config init
+```
+
+`config init` creates the runtime config file and workflow storage layout in
+standard system locations when permissions allow it, or in standard per-user
+locations otherwise. Use `--storage-root` when you need a one-off storage
+override.
+
+### Atomic Commands
+
+Create a PPP task from a RINEX file:
+
+```bash
+simurg-ppp calculate irkj3150.25o
+```
+
+Check a PPP task status:
+
+```bash
+simurg-ppp check 0934dd49-0e75-47c9-a447-3728094929d7
+```
+
+Plot XYZ result series to a PNG:
+
+```bash
+simurg-ppp plot 0934dd49-0e75-47c9-a447-3728094929d7 results.png --xyz
+```
+
+## Python Usage (API)
+
+Run a single SIMURG site/date workflow from Python:
+
+```python
+from pathlib import Path
+
+from ppp_client.tui.workflow_runner import (
+    WorkflowRunOptions,
+    configure_logging,
+    run_site_date_workflow,
+)
+
+configure_logging()
+result = run_site_date_workflow(
+    "irkj",
+    "2025-11-11",
+    WorkflowRunOptions(
+        storage_root=Path("workflow-data"),
+        force_start=False,
+        poll_seconds=60.0,
+        timeout_seconds=3600.0,
+    ),
+)
+
+if not result.ok:
+    raise RuntimeError(result.error)
+
+print(result.report)
+```
+
+Use lower-level helpers directly when you want to compose your own flow:
+
+```python
+from ppp_client import check_task, create_task, plot_xyz_result_points
+from ppp_client.results import collect_result_points
+
+task = create_task("irkj3150.25o")
+details = check_task(task["id"])
+points = collect_result_points(details)
+plot_xyz_result_points(points, "results.png")
+```
+
+## SIMURG Ecosystem
+
+This package does not install a root `simurg` command. It exposes a future plugin entry point named `ppp`, so a later umbrella package can provide:
+
+```bash
+simurg ppp
+simurg ppp workflow status irkj 2025-11-11
+```
+
+## Development
+
+Install the package in editable mode, then install development tools:
+
+```bash
+python -m venv .venv
+. .venv/bin/activate
+pip install -e .
+pip install pytest twine build
+```
+
+Run checks:
+
+```bash
+python -m pytest -q
+poetry check
+```
+
+Build release artifacts:
+
+```bash
+poetry build
+python -m twine check dist/*
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) and [docs/release.md](docs/release.md) for maintainer workflows.
+

simurg_ppp-0.1.0/README.md

@@ -0,0 +1,151 @@
+# SIMURG PPP
+
+SIMURG PPP is a Python client for running Precise Point Positioning workflows with SIMURG RINEX sources and a PPP processing service. It provides small command-line commands for individual PPP tasks, workflow commands for site/date processing, and an interactive terminal UI for selecting SIMURG sites and running batches.
+
+The package is published as `simurg-ppp` and imports as `ppp_client`.
+
+```bash
+pip install simurg-ppp
+```
+
+## TUI
+
+Run `simurg-ppp` with no subcommand to launch the interactive terminal UI:
+
+```bash
+simurg-ppp
+```
+
+The TUI guides the SIMURG PPP workflow from the terminal. It can check service availability, verify external RINEX tools, select stored groups, choose dates, load processed SIMURG sites, select sites manually or from pasted input, and run workflow batches while showing progress and logs. Launching the TUI also creates config automatically on first run when no standard config exists; feel free to change it if needed.
+
+Useful TUI options:
+
+```bash
+simurg-ppp --skip-startup
+simurg-ppp --date 2025-11-11
+simurg-ppp --storage-root workflow-data
+simurg-ppp --select-only
+```
+
+For non-interactive site/date processing, use workflow commands:
+
+```bash
+simurg-ppp workflow start irkj 2025-11-11
+simurg-ppp workflow proceed irkj 2025-11-11
+simurg-ppp workflow status irkj 2025-11-11
+simurg-ppp workflow report irkj 2025-11-11
+```
+
+## CLI
+
+Use the atomic commands when you already have a local RINEX file or a PPP task id. 
+
+Create configuration first if it is fresh installation and you didn't run TUI app.
+
+```bash
+simurg-ppp config init
+```
+
+`config init` creates the runtime config file and workflow storage layout in
+standard system locations when permissions allow it, or in standard per-user
+locations otherwise. Use `--storage-root` when you need a one-off storage
+override.
+
+### Atomic Commands
+
+Create a PPP task from a RINEX file:
+
+```bash
+simurg-ppp calculate irkj3150.25o
+```
+
+Check a PPP task status:
+
+```bash
+simurg-ppp check 0934dd49-0e75-47c9-a447-3728094929d7
+```
+
+Plot XYZ result series to a PNG:
+
+```bash
+simurg-ppp plot 0934dd49-0e75-47c9-a447-3728094929d7 results.png --xyz
+```
+
+## Python Usage (API)
+
+Run a single SIMURG site/date workflow from Python:
+
+```python
+from pathlib import Path
+
+from ppp_client.tui.workflow_runner import (
+    WorkflowRunOptions,
+    configure_logging,
+    run_site_date_workflow,
+)
+
+configure_logging()
+result = run_site_date_workflow(
+    "irkj",
+    "2025-11-11",
+    WorkflowRunOptions(
+        storage_root=Path("workflow-data"),
+        force_start=False,
+        poll_seconds=60.0,
+        timeout_seconds=3600.0,
+    ),
+)
+
+if not result.ok:
+    raise RuntimeError(result.error)
+
+print(result.report)
+```
+
+Use lower-level helpers directly when you want to compose your own flow:
+
+```python
+from ppp_client import check_task, create_task, plot_xyz_result_points
+from ppp_client.results import collect_result_points
+
+task = create_task("irkj3150.25o")
+details = check_task(task["id"])
+points = collect_result_points(details)
+plot_xyz_result_points(points, "results.png")
+```
+
+## SIMURG Ecosystem
+
+This package does not install a root `simurg` command. It exposes a future plugin entry point named `ppp`, so a later umbrella package can provide:
+
+```bash
+simurg ppp
+simurg ppp workflow status irkj 2025-11-11
+```
+
+## Development
+
+Install the package in editable mode, then install development tools:
+
+```bash
+python -m venv .venv
+. .venv/bin/activate
+pip install -e .
+pip install pytest twine build
+```
+
+Run checks:
+
+```bash
+python -m pytest -q
+poetry check
+```
+
+Build release artifacts:
+
+```bash
+poetry build
+python -m twine check dist/*
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) and [docs/release.md](docs/release.md) for maintainer workflows.

simurg_ppp-0.1.0/docs/release.md

@@ -0,0 +1,62 @@
+# Release Process
+
+This project publishes the distribution name `simurg-ppp` and imports as
+`ppp_client`.
+
+## Preflight
+
+1. Confirm the project license file exists and `pyproject.toml` exposes license
+   metadata for the PyPI project page.
+2. Confirm `pyproject.toml` contains the intended version.
+3. Confirm `CHANGELOG.md` contains an entry for that version.
+4. Run checks:
+
+   ```bash
+   make check
+   ```
+
+## Build
+
+```bash
+make build
+python -m twine check dist/*
+```
+
+For a local release preflight that checks the built artifacts and runs Poetry's
+upload dry-run without requiring a license decision yet:
+
+```bash
+make release-preflight
+```
+
+For public PyPI publication, the stricter release gate must pass:
+
+```bash
+make release-check
+```
+
+## Install Smoke Test
+
+```bash
+python -m venv /tmp/simurg-ppp-release
+/tmp/simurg-ppp-release/bin/pip install dist/simurg_ppp-0.1.0-py3-none-any.whl
+/tmp/simurg-ppp-release/bin/simurg-ppp --help
+```
+
+The installed distribution must not create a root `simurg` executable.
+
+## Publish
+
+Use TestPyPI first for a release candidate:
+
+```bash
+export TEST_PYPI_TOKEN=pypi-...
+make upload-testpypi
+```
+
+Publish to PyPI after the TestPyPI package installs cleanly:
+
+```bash
+export PYPI_TOKEN=pypi-...
+make upload-pypi
+```

simurg_ppp-0.1.0/pyproject.toml

@@ -0,0 +1,93 @@
+[build-system]
+requires = ["poetry-core>=2.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[project]
+name = "simurg-ppp"
+version = "0.1.0"
+description = "SIMURG PPP client and workflow tools"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [
+    { name = "SIMURG PPP maintainers" },
+]
+maintainers = [
+    { name = "SIMURG PPP maintainers" },
+]
+keywords = [
+    "gnss",
+    "ppp",
+    "precise-point-positioning",
+    "rinex",
+    "simurg",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering",
+]
+dependencies = [
+    "requests",
+    "matplotlib",
+]
+
+[project.scripts]
+simurg-ppp = "ppp_client.cli_entry:main"
+
+[project.entry-points."simurg.commands"]
+ppp = "ppp_client.simurg_plugin:main"
+
+[tool.poetry]
+name = "simurg-ppp"
+version = "0.1.0"
+description = "SIMURG PPP client and workflow tools"
+readme = "README.md"
+authors = ["SIMURG PPP maintainers"]
+license = "MIT"
+keywords = [
+    "gnss",
+    "ppp",
+    "precise-point-positioning",
+    "rinex",
+    "simurg",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Scientific/Engineering",
+]
+packages = [
+    { include = "ppp_client", from = "src" },
+]
+include = [
+    { path = "CHANGELOG.md", format = "sdist" },
+    { path = "CONTRIBUTING.md", format = "sdist" },
+    { path = "LICENSE", format = "sdist" },
+    { path = "docs/release.md", format = "sdist" },
+]
+
+[tool.poetry.dependencies]
+python = ">=3.10"
+requests = "*"
+matplotlib = "*"
+
+[tool.poetry.scripts]
+simurg-ppp = "ppp_client.cli_entry:main"
+
+[tool.poetry.plugins."simurg.commands"]
+ppp = "ppp_client.simurg_plugin:main"

simurg_ppp-0.1.0/src/ppp_client/__init__.py

@@ -0,0 +1,29 @@
+"""Public PPP client helpers."""
+
+from .api import BASE_URL, check_task, create_task
+from .cli import build_parser, main
+from .plotting import plot_xyz_result_points
+from .results import PPPResultPoint, collect_result_points
+from .rinex import (
+    date_from_rinex_filename,
+    date_from_rinex_short_filename,
+    prepare_rinex_file,
+)
+from .simurg import download_processed_file, list_processed_sites
+
+
+__all__ = [
+    "BASE_URL",
+    "PPPResultPoint",
+    "build_parser",
+    "check_task",
+    "collect_result_points",
+    "create_task",
+    "date_from_rinex_filename",
+    "date_from_rinex_short_filename",
+    "download_processed_file",
+    "list_processed_sites",
+    "main",
+    "plot_xyz_result_points",
+    "prepare_rinex_file",
+]

simurg_ppp-0.1.0/src/ppp_client/__main__.py

@@ -0,0 +1,7 @@
+import sys
+
+from .cli import main
+
+
+if __name__ == "__main__":
+    sys.exit(main())

simurg_ppp-0.1.0/src/ppp_client/api.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import requests
+
+from .config import ClientConfig, DEFAULT_PPP_SERVICE_BASE_URL
+from .rinex import date_from_rinex_filename
+
+
+BASE_URL = DEFAULT_PPP_SERVICE_BASE_URL
+
+#TODO add models for response so the user should not rely on plains strings as keys
+
+def create_task(
+    file_path: str | Path,
+    date: str | None = None,
+    config: ClientConfig | None = None,
+) -> dict[str, Any]:
+    """Upload a RINEX file and create a PPP task."""
+    path = Path(file_path)
+    task_date = date if date is not None else date_from_rinex_filename(path)
+    base_url = _base_url(config)
+    with path.open("rb") as rinex_file:
+        response = requests.post(
+            f"{base_url}/tasks",
+            headers={"accept": "application/json"},
+            files={"rinex_file": (path.name, rinex_file)},
+            data={"date": task_date},
+            timeout=60,
+        )
+
+    response.raise_for_status()
+    return response.json()
+
+
+def check_task(task_id: str, config: ClientConfig | None = None) -> dict[str, Any]:
+    """Return the current PPP task details."""
+    base_url = _base_url(config)
+    response = requests.get(
+        f"{base_url}/tasks/{task_id}",
+        headers={"accept": "application/json"},
+        timeout=60,
+    )
+    response.raise_for_status()
+    return response.json()
+
+
+def _base_url(config: ClientConfig | None) -> str:
+    if config is None:
+        return BASE_URL
+    return config.ppp_service_base_url