sustax-client 0.1.2__tar.gz

sustax-client-0.1.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020-2026 Geoskop Sociedad Limitada
+
+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.

sustax-client-0.1.2/PKG-INFO

@@ -0,0 +1,224 @@
+Metadata-Version: 2.1
+Name: sustax-client
+Version: 0.1.2
+Summary: Python client and CSV parser for the Sustax User API (SUA)
+Author-email: Geoskop Sociedad Limitada <info@geoskop.tech>
+License: MIT
+Project-URL: Homepage, https://sustax.earth
+Project-URL: Documentation, https://sustax.earth/docs/workflows-and-pipelines-how-to-pass-sustax-data-to-different-interpreters-2/
+Project-URL: Source, https://gitlab.com/joan.saladich/sustax-client
+Project-URL: Issues, https://gitlab.com/joan.saladich/sustax-client/-/issues
+Keywords: sustax,climate,api,csv,geoskop
+Classifier: Development Status :: 3 - Alpha
+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 :: Only
+Classifier: Programming Language :: Python :: 3.9
+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
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: pandas>=2.0
+Requires-Dist: requests>=2.31
+Requires-Dist: urllib3>=2.0
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+
+# sustax-client
+
+A small Python package for the **Sustax User API** and for parsing the Sustax global climate models by means of CSV files exported by Sustax (see https://sustax.earth). This repository is prepared in a standard `src/` layout so it can be:
+
+- developed locally with `pip install -e .`
+- published to the GitLab PyPI registry
+- later published to PyPI after a final package-name check
+
+## What is included
+
+- `SustaxClient` for authentication, catalog lookup, pricing, purchases, downloads, status polling, coordinates, and balance checks
+- `load_sustax_file()` to load Sustax CSV files into pandas DataFrames or nested numpy-friendly dictionaries
+- tests for the parser and client input validation
+- Python and R examples
+- GitLab CI config for build and package publishing
+
+## Repository layout
+
+```text
+sustax-client/
+├── .gitignore
+├── .gitlab-ci.yml
+├── LICENSE
+├── README.md
+├── pyproject.toml
+├── src/
+│   └── sustax_client/
+│       ├── __init__.py
+│       ├── client.py
+│       └── parser.py
+├── tests/
+│   ├── test_client.py
+│   └── test_parser.py
+└── examples/
+    ├── python/
+    │   └── quickstart.py
+    └── r/
+        └── quickstart.R
+```
+
+## Installation
+
+### Local development
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install --upgrade pip
+python -m pip install -e .[dev]
+```
+
+### From a package registry
+
+Once published:
+
+```bash
+pip install sustax-client
+```
+
+If you publish first to the GitLab package registry, use that registry URL in `pip` or `.pypirc`.
+
+## Quick start
+
+### 1. Authenticate and inspect the catalog
+
+```python
+from sustax_client import SustaxClient
+
+with SustaxClient() as client:
+    client.authenticate("your_username", "your_password")
+    catalog = client.get_variables_id()
+    print(catalog)
+```
+
+### 2. Preview pricing for a point request
+
+```python
+from sustax_client import SustaxClient
+
+with SustaxClient() as client:
+    client.authenticate("your_username", "your_password")
+    quote = client.view_price_request(
+        lat=41.3874,
+        lon=2.1686,
+        year_from=2020,
+        year_to=2030,
+        sustax_code_ids=[12345],
+    )
+    print(quote)
+```
+
+### 3. Buy, download, and unzip a request
+
+```python
+from sustax_client import SustaxClient
+
+with SustaxClient() as client:
+    client.authenticate("your_username", "your_password")
+    request_info = client.buy_data(
+        lat=41.3874,
+        lon=2.1686,
+        year_from=2020,
+        year_to=2030,
+        sustax_code_ids=[12345],
+        acceptance_sustax_disclaimer=True,
+    )
+    zip_path = client.download_file(request_info["url"], dest_dir="downloads")
+    extracted = client.unzip_download(dest_dir="downloads/unzipped")
+    print(zip_path)
+    print(extracted)
+```
+
+### 4. Load a Sustax CSV with pandas
+
+```python
+from sustax_client import load_sustax_file
+
+climate_df, metrics_df, metadata = load_sustax_file(
+    "downloads/unzipped/example.csv",
+    return_pandas_df=True,
+    return_metadata=True,
+)
+
+print(climate_df.head())
+print(metrics_df.head())
+print(metadata)
+```
+
+## Supported request modes
+
+The packaged client supports the three location modes described in the Sustax documentation:
+
+- point coordinates: `lat`, `lon`
+- ROI / bounding box: `lat=[north, south]`, `lon=[west, east]`
+- postal code lookup: `postal_code`, `country`
+
+## CSV parser behavior
+
+`load_sustax_file()` assumes the exported file is a Sustax CSV with three main blocks:
+
+- metadata
+- accuracy metrics
+- climate payload time series
+
+By default it returns two pandas DataFrames:
+
+- climate payload indexed by time
+- metrics indexed by scenario
+
+Set `return_pandas_df=False` if you prefer nested dictionaries and a numpy datetime array.
+
+## Development
+
+Run tests:
+
+```bash
+pytest
+```
+
+Build distributions:
+
+```bash
+python -m build
+```
+
+## Publish to GitLab package registry
+
+The included `.gitlab-ci.yml` publishes a package with `build` and `twine` when a tag is pushed.
+
+Required CI variables:
+
+- `TWINE_USERNAME`
+- `TWINE_PASSWORD`
+
+## Before publishing to PyPI
+
+Do these checks first:
+
+1. Confirm the final package name is available on PyPI.
+2. Confirm the project license you want to use.
+3. Replace the placeholder contact metadata in `pyproject.toml` if needed.
+4. Decide whether examples should stay in the main repo or move to docs.
+
+## License
+
+MIT

sustax-client-0.1.2/README.md

@@ -0,0 +1,186 @@
+# sustax-client
+
+A small Python package for the **Sustax User API** and for parsing the Sustax global climate models by means of CSV files exported by Sustax (see https://sustax.earth). This repository is prepared in a standard `src/` layout so it can be:
+
+- developed locally with `pip install -e .`
+- published to the GitLab PyPI registry
+- later published to PyPI after a final package-name check
+
+## What is included
+
+- `SustaxClient` for authentication, catalog lookup, pricing, purchases, downloads, status polling, coordinates, and balance checks
+- `load_sustax_file()` to load Sustax CSV files into pandas DataFrames or nested numpy-friendly dictionaries
+- tests for the parser and client input validation
+- Python and R examples
+- GitLab CI config for build and package publishing
+
+## Repository layout
+
+```text
+sustax-client/
+├── .gitignore
+├── .gitlab-ci.yml
+├── LICENSE
+├── README.md
+├── pyproject.toml
+├── src/
+│   └── sustax_client/
+│       ├── __init__.py
+│       ├── client.py
+│       └── parser.py
+├── tests/
+│   ├── test_client.py
+│   └── test_parser.py
+└── examples/
+    ├── python/
+    │   └── quickstart.py
+    └── r/
+        └── quickstart.R
+```
+
+## Installation
+
+### Local development
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install --upgrade pip
+python -m pip install -e .[dev]
+```
+
+### From a package registry
+
+Once published:
+
+```bash
+pip install sustax-client
+```
+
+If you publish first to the GitLab package registry, use that registry URL in `pip` or `.pypirc`.
+
+## Quick start
+
+### 1. Authenticate and inspect the catalog
+
+```python
+from sustax_client import SustaxClient
+
+with SustaxClient() as client:
+    client.authenticate("your_username", "your_password")
+    catalog = client.get_variables_id()
+    print(catalog)
+```
+
+### 2. Preview pricing for a point request
+
+```python
+from sustax_client import SustaxClient
+
+with SustaxClient() as client:
+    client.authenticate("your_username", "your_password")
+    quote = client.view_price_request(
+        lat=41.3874,
+        lon=2.1686,
+        year_from=2020,
+        year_to=2030,
+        sustax_code_ids=[12345],
+    )
+    print(quote)
+```
+
+### 3. Buy, download, and unzip a request
+
+```python
+from sustax_client import SustaxClient
+
+with SustaxClient() as client:
+    client.authenticate("your_username", "your_password")
+    request_info = client.buy_data(
+        lat=41.3874,
+        lon=2.1686,
+        year_from=2020,
+        year_to=2030,
+        sustax_code_ids=[12345],
+        acceptance_sustax_disclaimer=True,
+    )
+    zip_path = client.download_file(request_info["url"], dest_dir="downloads")
+    extracted = client.unzip_download(dest_dir="downloads/unzipped")
+    print(zip_path)
+    print(extracted)
+```
+
+### 4. Load a Sustax CSV with pandas
+
+```python
+from sustax_client import load_sustax_file
+
+climate_df, metrics_df, metadata = load_sustax_file(
+    "downloads/unzipped/example.csv",
+    return_pandas_df=True,
+    return_metadata=True,
+)
+
+print(climate_df.head())
+print(metrics_df.head())
+print(metadata)
+```
+
+## Supported request modes
+
+The packaged client supports the three location modes described in the Sustax documentation:
+
+- point coordinates: `lat`, `lon`
+- ROI / bounding box: `lat=[north, south]`, `lon=[west, east]`
+- postal code lookup: `postal_code`, `country`
+
+## CSV parser behavior
+
+`load_sustax_file()` assumes the exported file is a Sustax CSV with three main blocks:
+
+- metadata
+- accuracy metrics
+- climate payload time series
+
+By default it returns two pandas DataFrames:
+
+- climate payload indexed by time
+- metrics indexed by scenario
+
+Set `return_pandas_df=False` if you prefer nested dictionaries and a numpy datetime array.
+
+## Development
+
+Run tests:
+
+```bash
+pytest
+```
+
+Build distributions:
+
+```bash
+python -m build
+```
+
+## Publish to GitLab package registry
+
+The included `.gitlab-ci.yml` publishes a package with `build` and `twine` when a tag is pushed.
+
+Required CI variables:
+
+- `TWINE_USERNAME`
+- `TWINE_PASSWORD`
+
+## Before publishing to PyPI
+
+Do these checks first:
+
+1. Confirm the final package name is available on PyPI.
+2. Confirm the project license you want to use.
+3. Replace the placeholder contact metadata in `pyproject.toml` if needed.
+4. Decide whether examples should stay in the main repo or move to docs.
+
+## License
+
+MIT

sustax-client-0.1.2/pyproject.toml

@@ -0,0 +1,63 @@
+[build-system]
+requires = ["setuptools==68.2.2", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sustax-client"
+version = "0.1.2"
+description = "Python client and CSV parser for the Sustax User API (SUA)"
+readme = "README.md"
+requires-python = ">=3.9"
+license = {text = "MIT"}
+authors = [
+  {name = "Geoskop Sociedad Limitada", email = "info@geoskop.tech"}
+]
+keywords = ["sustax", "climate", "api", "csv", "geoskop"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "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.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Scientific/Engineering",
+  "Topic :: Software Development :: Libraries :: Python Modules"
+]
+dependencies = [
+  "numpy>=1.24",
+  "pandas>=2.0",
+  "requests>=2.31",
+  "urllib3>=2.0"
+]
+
+[project.optional-dependencies]
+dev = [
+  "build>=1.2",
+  "pytest>=8.0",
+  "twine>=5.0"
+]
+
+[project.urls]
+Homepage = "https://sustax.earth"
+Documentation = "https://sustax.earth/docs/workflows-and-pipelines-how-to-pass-sustax-data-to-different-interpreters-2/"
+Source = "https://gitlab.com/joan.saladich/sustax-client"
+Issues = "https://gitlab.com/joan.saladich/sustax-client/-/issues"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+include-package-data = false
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+minversion = "8.0"
+addopts = "-q"
+testpaths = ["tests"]

sustax-client-0.1.2/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

sustax-client-0.1.2/src/sustax_client/__init__.py

@@ -0,0 +1,11 @@
+"""sustax-client: Python package for the Sustax User API and CSV parsing."""
+
+from .client import SustaxClient
+from .parser import load_sustax_file
+
+__all__ = [
+    "SustaxClient",
+    "load_sustax_file",
+]
+
+__version__ = "0.1.1"