qa4sm-api 0.1__tar.gz

qa4sm_api-0.1/.coveragerc

@@ -0,0 +1,34 @@
+# .coveragerc to control coverage.py
+[run]
+branch = True
+source = qa4sm_api
+data_file = .coverage
+omit =
+    */qa4sm_api/cli.py
+    qa4sm_api/cli.py
+    */tests/*
+
+[paths]
+source =
+    src/
+    */site-packages/
+
+[report]
+precision = 2
+
+# Regexes for lines to exclude from consideration
+exclude_lines =
+    # Have to re-enable the standard pragma
+    pragma: no cover
+
+    # Don't complain about missing debug-only code:
+    def __repr__
+    if self\.debug
+
+    # Don't complain if tests don't hit defensive assertion code:
+    raise AssertionError
+    raise NotImplementedError
+
+    # Don't complain if non-runnable code isn't run:
+    if 0:
+    if __name__ == .__main__::

qa4sm_api-0.1/.github/workflows/ci.yml

@@ -0,0 +1,127 @@
+# This workflow will install Python dependencies and run tests on
+# windows and linux systems with a variety of Python versions
+
+# For more information see:
+# https://help.github.com/actions/language-and-framework-guides/using-python-with-github-actions
+
+name: Automated Tests
+
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+  schedule:
+    - cron: '0 0 * * *' # daily
+
+jobs:
+  build:
+    name: py${{ matrix.python-version }}@${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        python-version: ['3.8', '3.13']
+        os: ["ubuntu-latest", "windows-latest", "macos-latest"]
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Fetch tags
+        run: git fetch --tags --force
+      - uses: conda-incubator/setup-miniconda@v3
+        with:
+          auto-update-conda: true
+          python-version: ${{ matrix.python-version }}
+          channel-priority: flexible
+          activate-environment: qa4sm_api
+          auto-activate-base: false
+      - name: Print environment infos
+        shell: bash -l {0}
+        run: |
+          conda info -a
+          conda list
+          pip list
+          which pip
+          which python
+      - name: Install dependencies and package
+        shell: bash -l {0}
+        run: |
+          pip install build -e .[testing]
+      - name: Run all tests
+        shell: bash -l {0}
+        run: |
+          pytest
+      - name: Export Environment
+        shell: bash -l {0}
+        run: |
+          mkdir -p artifacts
+          filename=env_py${{ matrix.python-version }}_${{ matrix.os }}.yml
+          conda env export --no-builds | grep -v "prefix" > artifacts/$filename
+      - name: Create wheel and dist package
+        shell: bash -l {0}
+        run: |
+          if [ "${{ matrix.os }}" == "windows-latest" ]
+          then
+            # build wheel on windows
+            python -m build --wheel --outdir artifacts/dist
+          else
+            # build both wheel and sdist on linux/mac
+            python -m build --wheel --sdist --outdir artifacts/dist
+          fi
+          ls artifacts/dist
+          twine check artifacts/dist/* || true
+      - name: Upload Coverage
+        shell: bash -l {0}
+        continue-on-error: true
+        run: |
+          pip install coveralls && coveralls --service=github
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          COVERALLS_FLAG_NAME: ${{ matrix.python-version }}
+          COVERALLS_PARALLEL: true
+      - name: Upload Artifacts
+        uses: actions/upload-artifact@v7
+        with:
+          name: Artifacts-py${{ matrix.python-version }}-${{ matrix.os }}
+          path: artifacts/*
+
+  publish-coverage:
+    name: Submit Coveralls 👚
+    needs: build
+    runs-on: ubuntu-latest
+    container: python:3-slim
+    steps:
+      - name: Finished
+        run: |
+          pip3 install --upgrade coveralls && coveralls --service=github --finish
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  publish-pypi-package:
+    name: Publish PyPI 🚀
+    # Trigger on release tags from the awst-austria repository
+    if: |
+      startsWith(github.ref, 'refs/tags/v') &&
+      startsWith(github.repository, 'awst-austria')
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - name: Print environment variables
+        run: |
+          echo "GITHUB_REF = $GITHUB_REF"
+          echo "GITHUB_REPOSITORY = $GITHUB_REPOSITORY"
+      - name: Download Artifacts
+        uses: actions/download-artifact@v4
+        with:
+          path: dist
+          merge-multiple: true
+      - name: Display downloaded files
+        run: ls -la dist/
+      - name: Upload to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          skip_existing: true
+          verbose: true
+          verify_metadata: true
+          packages_dir: dist/
+          password: ${{ secrets.PYPI_API_TOKEN }}

qa4sm_api-0.1/.github/workflows/deploy-docs.yml

@@ -0,0 +1,53 @@
+name: GitHub Pages Deploy
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: |
+          pip install -e ".[docs]"
+
+      - name: Build documentation
+        run: |
+          cd docs
+          sphinx-build -b html . _build/html
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/_build/html
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

qa4sm_api-0.1/.gitignore

@@ -0,0 +1,54 @@
+# Temporary and binary files
+*~
+*.py[cod]
+*.so
+*.cfg
+!.isort.cfg
+*.orig
+*.log
+*.pot
+__pycache__/*
+.cache/*
+.*.swp
+*/.ipynb_checkpoints/*
+.DS_Store
+
+# Project files
+.ropeproject
+.project
+.pydevproject
+.settings
+.idea
+.vscode
+tags
+
+# Package files
+*.egg
+*.eggs/
+.installed.cfg
+*.egg-info
+
+# Unittest and coverage
+htmlcov/*
+.coverage
+.coverage.*
+.tox
+junit*.xml
+coverage.xml
+.pytest_cache/
+
+# Build and docs folder/files
+build/*
+dist/*
+sdist/*
+docs/api/*
+docs/_rst/*
+docs/_build/*
+cover/*
+MANIFEST
+
+# Per-project virtualenvs
+.venv*/
+.conda*/
+.python-version
+artifacts

qa4sm_api-0.1/AUTHORS.rst

@@ -0,0 +1,5 @@
+============
+Contributors
+============
+
+* Wolfgang Preimesberger <wolfgang.preimesberger@geo.tuwien.ac.at>

qa4sm_api-0.1/CHANGELOG.rst

@@ -0,0 +1,10 @@
+=========
+Changelog
+=========
+
+Version 0.1
+===========
+
+- First version of Client API package
+- Allows triggering validation runs and downloading results
+- Used for the automated validation reports application

qa4sm_api-0.1/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Wolfgang Preimesberger
+
+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.

qa4sm_api-0.1/PKG-INFO

@@ -0,0 +1,215 @@
+Metadata-Version: 2.4
+Name: qa4sm_api
+Version: 0.1
+Summary: QA4SM webval API access
+Author-email: TU Wien <support@qa4sm.eu>
+License: MIT
+Project-URL: Homepage, https://github.com/awst-austria/qa4sm-api
+Project-URL: Documentation, https://awst-austria.github.io/qa4sm-api
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python
+Classifier: License :: OSI Approved :: MIT License
+Requires-Python: >=3.8
+Description-Content-Type: text/x-rst
+License-File: LICENSE.txt
+License-File: AUTHORS.rst
+Requires-Dist: pandas
+Requires-Dist: click
+Requires-Dist: requests
+Requires-Dist: tornado
+Provides-Extra: testing
+Requires-Dist: pytest; extra == "testing"
+Requires-Dist: pytest-cov; extra == "testing"
+Requires-Dist: coverage; extra == "testing"
+Provides-Extra: docs
+Requires-Dist: sphinx>=3.2.1; extra == "docs"
+Requires-Dist: sphinx_rtd_theme; extra == "docs"
+Requires-Dist: myst-parser>=0.18.1; extra == "docs"
+Dynamic: license-file
+
+.. coding: utf-8
+
+.. image:: https://img.shields.io/badge/CI-GitHub%20Actions-success?logo=github-actions
+   :alt: GitHub Actions
+   :target: https://github.com/awst-austria/qa4sm-api/actions
+.. image:: https://img.shields.io/coveralls/github/awst-austria/qa4sm-api/main?logo=coveralls
+   :alt: Coveralls
+   :target: https://coveralls.io/github/awst-austria/qa4sm-api
+.. image:: https://img.shields.io/pypi/v/qa4sm-api?logo=pypi
+   :alt: PyPI
+   :target: https://pypi.org/project/qa4sm-api/
+.. image:: https://img.shields.io/badge/Docs-Documentation-blue?logo=sphinx
+   :alt: Documentation
+   :target: https://awst-austria.github.io/qa4sm-api/readme.html
+
+
+=========
+qa4sm-api
+=========
+
+.. image:: https://qa4sm.eu/static/images/logo/qa4sm_logo_long.webp
+   :height: 50px
+
+Python client library for interacting with the **QA4SM** (Quality Assurance for Soil Moisture) validation service.
+QA4SM is an online platform for validating (satellite) soil moisture datasets.
+
+Features
+--------
+
+- **API Client**: Python API for QA4SM.eu web service
+- **Command Line Interface**: Convenient CLI for common operations
+- **Result Download**: Download NetCDF, graphics, and summary statistics
+- **Search datasets in the service**, **download validation configurations**, ...
+- **Programmatically trigger validation runs**
+
+Coming soon:
+
+- Programmatically upload your data for validation
+
+Installation
+============
+
+Install from PyPI:
+
+.. code-block:: bash
+
+   pip install qa4sm-api
+
+Or from source:
+
+.. code-block:: bash
+
+   git clone https://github.com/awst-austria/qa4sm-api.git
+   cd qa4sm-api
+   pip install -e .
+
+**Verify installation**
+
+Run the following commands in your console to verify that the page
+was installed.
+
+.. code-block:: bash
+
+   # Test installation
+   qa4sm --version
+
+   # Check available commands
+   qa4sm --help
+
+
+Authentication
+--------------
+In order to use the full API, you need to authenticate with QA4SM
+via your user token.
+
+1) Go to https://qa4sm.eu/ui/user-profile and request an API token
+2) Choose one of the following 2 options to add the token to the
+   local file ~/.qa4smapirc to use the API
+
+**Option 1: Manual setup**
+
+Create ``~/.qa4smapirc`` (Linux/MacOs) or ``%USERPROFILE%\.qa4smapirc`` (Windows)
+with your credentials:
+
+.. code-block:: ini
+
+   [qa4sm.eu]
+   token: your_api_token_here
+   username: your_username
+
+
+**Option 2: Automated setup**
+
+.. code-block:: bash
+
+   qa4sm api setup
+
+This prompts for your username and password and stores your API token in ``~/.qa4smapirc``.
+
+Documentation
+-------------
+
+Full documentation is available at https://awst-austria.github.io/qa4sm-api/
+
+Quick Start
+===========
+
+Here are some example commands on using the API in a python application.
+See the full documentation at https://awst-austria.github.io/qa4sm-api/
+for more examples.
+
+.. code-block:: python
+
+   >> from qa4sm_api.client_api import Connection, ValidationConfiguration
+   # Initialize connection
+   >> conn = Connection()
+   Hi, <username>! You're successfully logged in at https://qa4sm.eu/api/!
+
+
+.. code-block:: python
+
+   # Get a list of available datasets
+   >> conn.datasets()[['short_name']]
+    Out[10]:
+                            short_name
+    id
+    1                     C3S_combined
+    2                          SMAP_L3
+    3                            ASCAT
+    4                             ISMN
+    5                            GLDAS
+    6              ESA_CCI_SM_combined
+    7                          SMOS_IC
+    ...                         ...
+   # Get a list of versions for a datasets
+
+
+.. code-block:: python
+
+   >> conn.versions("C3S_combined")
+    Out[6]:
+         short_name pretty_name  ... time_range_end geographical_range
+    1   C3S_V201706     v201706  ...     2022-10-10               None
+    10  C3S_V201812     v201812  ...     2018-12-31               None
+    28  C3S_V201912     v201912  ...     2019-12-31               None
+    31  C3S_V202012     v202012  ...     2020-12-31               None
+    45  C3S_V202212     v202212  ...     2025-07-20               None
+    58  C3S_V202312     v202312  ...     2025-07-20               None
+    70  C3S_V202505     v202505  ...     2024-12-31               None
+
+
+.. code-block:: python
+
+   # Download the configuration for a validation run
+   >> config = conn.download_configuration("9aeb663b-e24e-4541-8331-6ec3e0318d1f")
+   >> print(config.data)
+   {'name_tag': 'Test Case  QA4SM_VA_metrics - Test scaling_no_scaling_DEFAULT', 'interval_from': '1978-11-01', 'interval_to': '2024-12-31', 'temporal_matching': 12, 'anomalies_method': 'none', 'anomalies_from': None, 'anomalies_to': None, 'min_lat': 34.0, 'min_lon': -11.2, 'max_lat': 71.6, 'max_lon': 48.3, 'scaling_method': 'none', 'metrics': [{'id': 'tcol', 'value': False}, {'id': 'bootstrap_tcol_cis', 'value': False}, {'id': 'stability_metrics', 'value': False}], 'intra_annual_metrics': {'intra_annual_metrics': False, 'intra_annual_type': '', 'intra_annual_overlap': None}, 'dataset_configs': [{'dataset_id': 1, 'version_id': 70, 'variable_id': 1, 'is_spatial_reference': False, 'is_temporal_reference': True, 'is_scaling_reference': False, 'basic_filters': [1], 'parametrised_filters': []}, {'dataset_id': 4, 'version_id': 69, 'variable_id': 4, 'is_spatial_reference': True, 'is_temporal_reference': False, 'is_scaling_reference': False, 'basic_filters': [1, 2], 'parametrised_filters': [{'id': 18, 'parameters': 'AMMA-CATCH,DAHRA,TAHMO,SD_DEM,CHINA,CTP_SMTMN,HiWATER_EHWSN,HSC_SEOLMACHEON,IIT_KANPUR,KHOREZM,MAQU,MONGOLIA,MySMNet,RUSWET-AGRO,RUSWET-GRASS,RUSWET-VALDAI,SKKU,SW-WHU,KIHS_CMC,KIHS_SMC,VDS,NAQU,NGARI,SMN-SDR,SONTE-China,WIT-Network,AACES,OZNET,SASMAS,BIEBRZA_S-1,CALABRIA,CAMPANIA,FMI,FR_Aqui,GROW,GTK,HOBE,HYDROL-NET_PERUGIA,IMA_CAN1,METEROBS,MOL-RAO,ORACLE,REMEDHUS,RSMN,SMOSMANIA,SWEX_POLAND,TERENO,UDC_SMOS,UMBRIA,UMSUOL,VAS,WEGENERNET,WSMN,HOAL,IPE,COSMOS-UK,LABFLUX,NVE,Ru_CFR,STEMS,TWENTE,XMS-CAT,ARM,AWDN,BNZ-LTER,FLUXNET-AMERIFLUX,ICN,IOWA,PBO_H2O,RISMA,SCAN,SNOTEL,SOILSCAPE,USCRN,USDA-ARS,TxSON,LAB-net,PTSMN'}, {'id': 24, 'parameters': '0.00,0.10'}]}], 'settings_changes': {'filters': [], 'anomalies': False, 'scaling': False, 'variables': [], 'versions': []}}
+
+.. code-block:: python
+
+   # Start a new validation using the local validation configuration
+   >> r = conn.start_validation(config)
+   # The validation run is now triggered under your user account, check https://qa4sm.eu/ui/my-validations
+   >> print(r.status)
+   'SCHEDULED'
+
+CLI Commands
+------------
+
+- ``qa4sm api setup`` - Configure authentication
+- ``qa4sm api check`` - Verify authentication
+- ``qa4sm validate CONFIG.json`` - Submit a validation run
+- ``qa4sm download config RUN_ID`` - Download configuration
+- ``qa4sm download results RUN_ID`` - Download validation results
+
+Use ``qa4sm --help`` for all commands.
+
+Testing
+-------
+
+Run tests:
+
+.. code-block:: bash
+
+   pip install -e ".[testing]"
+   pytest