Metadata-Version: 2.3
Name: eocube
Version: 0.1.6
Summary: Support tool and library for EOCube.Ro
License: Apache-2.0
Keywords: earth observation,cube,geospatial,cli,s3,cloudnative,stac
Author: Marian Neagul
Author-email: marian.neagul@e-uvt.ro
Requires-Python: >=3.12,<4.0
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: GIS
Provides-Extra: auth
Provides-Extra: cli
Provides-Extra: core
Provides-Extra: cube
Provides-Extra: eco
Provides-Extra: raster
Provides-Extra: services
Requires-Dist: ascii-magic ; extra == "cli" or extra == "eco"
Requires-Dist: authlib ; extra == "auth" or extra == "cli" or extra == "eco"
Requires-Dist: backoff ; extra == "auth" or extra == "cli" or extra == "eco"
Requires-Dist: click (>=8.3,<9.0) ; extra == "cli" or extra == "eco"
Requires-Dist: dask (>=2025.7,<2026.0) ; extra == "cube" or extra == "eco"
Requires-Dist: flask ; extra == "cli" or extra == "eco"
Requires-Dist: fsspec (>=2025.10,<2026.0) ; extra == "core"
Requires-Dist: geopandas (>=1.1,<2.0) ; extra == "cube" or extra == "services" or extra == "eco"
Requires-Dist: keyring ; extra == "cli" or extra == "eco"
Requires-Dist: matplotlib (>=3.10,<4.0) ; extra == "cli" or extra == "eco"
Requires-Dist: numpy (>=2.3,<3.0) ; extra == "raster" or extra == "cube" or extra == "eco"
Requires-Dist: owslib ; extra == "services" or extra == "eco"
Requires-Dist: pystac (>=1.14,<2.0) ; extra == "core"
Requires-Dist: pystac-client (>=0.9,<0.10) ; extra == "core"
Requires-Dist: python-dateutil (>=2.9,<3.0)
Requires-Dist: python-i18n ; extra == "core"
Requires-Dist: pyyaml (>=6.0,<7.0)
Requires-Dist: rasterio (>=1.4,<2.0) ; extra == "raster" or extra == "cube" or extra == "eco"
Requires-Dist: requests (>=2.32,<3.0)
Requires-Dist: rich (>=14.0.0,<15.0.0) ; extra == "cli" or extra == "eco"
Requires-Dist: s3fs (>=2025.10,<2026.0) ; extra == "core"
Requires-Dist: xarray (>=2025.12,<2026.0) ; extra == "raster" or extra == "cube" or extra == "eco"
Project-URL: Documentation, https://rocs.pages.dev.info.uvt.ro/tools/eocube-tools/
Project-URL: Homepage, https://eocube.ro
Project-URL: Repository, https://gitlab.dev.info.uvt.ro/rocs/tools/eocube-tools
Description-Content-Type: text/markdown

# EOCube.RO Tools
![Grant Funded](https://img.shields.io/badge/funded_by-UEFISCDI-blueviolet)
[![pipeline status](https://gitlab.dev.info.uvt.ro/rocs/tools/eocube-tools/badges/main/pipeline.svg)](https://gitlab.dev.info.uvt.ro/rocs/tools/eocube-tools/-/pipelines)

This repository holds the `eocube` python library currently providing a set of minimal 
tools aimed to be used on the STAC Catalogs and data hosted by the ROCS Project

## Installing

### Option 1: From PyPi
```bash
pip install "eocube[cli]"
```

Visit https://pypi.org/project/eocube/ for more oficial packages.

### Option 2: From GitLab Package Registry
```bash
pip install eocube[cli] --index-url https://gitlab.dev.info.uvt.ro/api/v4/projects/3491/packages/pypi/simple
```
Visit the [GitLab Package Registry](https://gitlab.dev.info.uvt.ro/rocs/tools/eocube-tools/-/packages) for available development packages

### Option 3: From Git (development branch)
```bash
pip install "eocube[cli] @ git+https://gitlab.dev.info.uvt.ro/rocs/tools/eocube-tools.git@main"
```

## Command Line Tools
You can use the command line tool by calling the `eocube` library.

```bash
Usage: eocube [OPTIONS] COMMAND [ARGS]...

Options:
  --help  Show this message and exit.

Commands:
  services
```

### 🔐 Authentication
#### Login
In order to authenticate against our service provider you need to call:

```bash
eocube auth login
```

This will open a browser window and perform the standard authentication.

#### Logout

In order to invalidate the session and delete local token issue you need to call:
```bash
eocube auth login
```

#### User Info
For obtaining user information you can call:

```bash
eocube auth login
```

### 🧰 Internal Services
### 🌍 External Services
#### Geo-Spatial.Org Services

Some basic services from the Geo-Spatial.Org are provided. All the tools provide the 
option to save the result in a `GeoJSON` file. 

```
Usage: eocube services geospatialorg [OPTIONS] COMMAND [ARGS]...

Options:
  --help  Show this message and exit.

Commands:
  get-administrative-unit-by-code
                                  Uses the SIRUTA Code to retrieve the...
  get-administrative-unit-by-name
                                  Retrieves the administrative unit by name
  get-county-by-mnemonic          Retrieves the county by mnemonic
  get-county-by-name              Retrieves the county by name
```

## Library Tools
### Raster
  - `eocube.raster.utils.get_raster_patches()`: Function generating patches over an rasterio `DatasetReaser`

We welcome contributions! If you'd like to improve `eocube`, fix bugs, or propose new features, follow the steps below to set up your development environment.

## 🛠️ Development Setup (with Poetry)

This project uses [Poetry](https://python-poetry.org/) for dependency management and packaging.

### 1. Install Poetry

Follow the official instructions:  
👉 https://python-poetry.org/docs/#installation

Or, if you're on a Unix-like system:

```bash
pip install poetry
```

Or

```bash
curl -sSL https://install.python-poetry.org | python3 -
```

Make sure it’s available:

```bash
poetry --version
```

### 2. Clone the repository
```bash
git clone https://gitlab.dev.info.uvt.ro/rocs/tools/eocube-tools.git
cd eocube-tools
```

### 3. Create a feature branch

**Never commit directly to main!**

Create a new branch for your work:

```bash
git checkout -b my-feature-branch # Replace with something meaningful
```

### 4. Install development dependencies
```bash
poetry install --with dev
```

This will install both the main library and the development tools (`black`, `pip-audit`, `twine`, etc).

### 5. Activate the shell (optional)

```bash
poetry shell
```

You can now run commands like `eocube`, `pytest`, or `black` directly.

## ✅ Submitting Changes
1. Push your branch to GitLab:
   ```bash
   git push --set-upstream origin my-feature-branch
   ```
2. Open a Merge Request (MR) via the GitLab UI.
3. Your MR will be reviewed and must be approved by a project maintainer before it can be merged.


## 🧹 Code Style
Make sure your code is properly formated. Non-compliant code will be rejected.
We use [Black](https://black.readthedocs.io/en/stable/) for consistent formatting. Before committing:

```bash
poetry run black .
```

## 🙏 Acknowledgements

This work was supported by a grant of the Ministry of Research, Innovation and Digitization, 
CCCDI - UEFISCDI, project number **PN-IV-P6-6.3-SOL-2024-2-0248**, within PNCDI IV.

## 📜 Licensing
After updating do not forget to update the NOTICE file with:

```bash
pip-licenses --from=mixed --format=plain --with-urls -i eocube > NOTICE
```

## 🚀 Releasing a new version

Publication to PyPi is intentionally manual. Each released wheel embeds the
git commit it was built from, surfaced via `eocube --version`:

```bash
$ eocube --version
eocube 0.1.2, commit 5ba2a1f8f812 (clean)
```

The `(clean)` marker is only present when the working tree had no uncommitted
changes at build time — releases must always be `(clean)`.

### Recommended flow: `scripts/release.sh`

The repository ships a release helper that enforces a clean build, embeds the
git provenance, sanity-checks the produced wheel, and uploads it to PyPi:

```bash
# 1. Bump the version and commit everything
poetry version patch                               # 0.1.1 → 0.1.2
git add pyproject.toml
git commit -m "release v$(poetry version -s)"
git tag "v$(poetry version -s)"

# 2. Build, verify, and publish
./scripts/release.sh
```

`release.sh` will:

1. Refuse to proceed if the working tree has uncommitted changes or untracked
   files under `src/` — guaranteeing a `(clean)` stamp.
2. Wipe `dist/`, stamp `src/eocube/_build_info.py` with the current
   `git rev-parse HEAD`, run `poetry build`, then restore the placeholder
   `_build_info.py` so the stamped values never land in the repository.
3. Install the produced wheel into a throwaway virtualenv and assert that
   `eocube --version` reports `(clean)`. If not, the upload is aborted.
4. Prompt for confirmation, then run
   `poetry run twine upload --verbose -s -i 5C5D049F dist/*`.

Useful flags:

| Flag | Purpose |
|---|---|
| `--no-publish` | Build + verify only, skip the PyPi upload |
| `--yes` / `-y` | Skip the confirmation prompt (CI-friendly) |
| `--help` | Print the inline usage block |

Adapt the GPG key id (`5C5D049F`) inside `scripts/release.sh` to match your
own signing key if you maintain a fork.

After a successful upload, push the tag:

```bash
git push --tags
```

### Manual fallback

If you need to build/publish without the helper script, the equivalent
commands are:

```bash
rm -fr build/ dist/*
./scripts/stamp-build-info.sh                              # embed git provenance
poetry build
git checkout -- src/eocube/_build_info.py                  # restore the placeholder
poetry run twine upload --verbose -s -i 5C5D049F dist/*
```

Skipping `stamp-build-info.sh` is allowed but the resulting wheel will report
`eocube X.Y.Z` with no commit suffix.
