Metadata-Version: 2.4
Name: geoengine
Version: 0.9.1
Summary: A package for easy access to Geo Engine instances
Author-email: Geo Engine GmbH <info@geoengine.de>
Project-URL: Homepage, https://www.geoengine.io
Project-URL: Repository, https://github.com/geo-engine/geoengine/python
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Database :: Front-Ends
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Topic :: Software Development :: Libraries
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Information Technology
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: geoengine-api-client==0.9.1
Requires-Dist: geopandas<2.0,>=1.0
Requires-Dist: matplotlib<3.11,>=3.6
Requires-Dist: numpy<2.5,>=1.24
Requires-Dist: owslib<0.36,>=0.27
Requires-Dist: pillow<13,>=10.0
Requires-Dist: pyarrow<24,>=17.0
Requires-Dist: python-dotenv<1.3,>=0.19
Requires-Dist: rasterio<2,>=1.3
Requires-Dist: requests<3,>=2.26
Requires-Dist: rioxarray<0.23,>=0.9.1
Requires-Dist: StrEnum<0.5,>=0.4.6
Requires-Dist: vega<4.2,>=3.5
Requires-Dist: websockets<17,>=14.2
Requires-Dist: xarray<2026.3,>=2024.4
Requires-Dist: urllib3<2.7,>=2.1
Requires-Dist: pydantic<2.13,>=2.10.6
Requires-Dist: skl2onnx<1.21,>=1.20
Provides-Extra: dev
Requires-Dist: build<1.5,>=0.7; extra == "dev"
Requires-Dist: mypy<2.0,>=1.14; extra == "dev"
Requires-Dist: pdoc3<0.12,>=0.10; extra == "dev"
Requires-Dist: ruff<0.16,>=0.12.3; extra == "dev"
Requires-Dist: setuptools<83,>=62; extra == "dev"
Requires-Dist: twine<6.3,>=3.4; extra == "dev"
Requires-Dist: types-requests<3,>=2.26; extra == "dev"
Requires-Dist: types-setuptools<83,>=71.1; extra == "dev"
Requires-Dist: wheel<0.47,>=0.37; extra == "dev"
Provides-Extra: test
Requires-Dist: psycopg<4,>=3.2; extra == "test"
Requires-Dist: pytest<10,>=6.3; extra == "test"
Requires-Dist: pytest-cov<7.1,>=6.0; extra == "test"
Requires-Dist: requests_mock<2,>=1.9; extra == "test"
Requires-Dist: scikit-learn<1.9,>=1.7; extra == "test"
Provides-Extra: examples
Requires-Dist: cartopy<0.26,>=0.22; extra == "examples"
Requires-Dist: ipympl<0.11,>=0.9.4; extra == "examples"
Requires-Dist: ipyvuetify<1.12,>=1.10; extra == "examples"
Requires-Dist: ipywidgets<9,>=8.1.5; extra == "examples"
Requires-Dist: nbconvert<8,>=7; extra == "examples"
Requires-Dist: scipy<2,>=1.7; extra == "examples"
Requires-Dist: voila<0.6,>=0.5; extra == "examples"

# Geo Engine Python Package

[![CI](https://github.com/geo-engine/geoengine-python/actions/workflows/ci.yml/badge.svg?event=merge_group)](https://github.com/geo-engine/geoengine-python/actions/workflows/ci.yml?query=event%3Amerge_group)
[![Coverage Status](https://coveralls.io/repos/github/geo-engine/geoengine-python/badge.svg)](https://coveralls.io/github/geo-engine/geoengine-python)
[![Documentation](https://img.shields.io/badge/documentation-python.docs.geoengine.io-blue)](https://python.docs.geoengine.io/)

This package allows easy access to Geo Engine functionality from Python environments.

## Test

### Create a virtual environment

Create a virtual environment (e.g., `python3 -m venv env`).

```bash
# create new venv
python3 -m venv env
# activate new venv
source env/bin/activate
```

#### Re-create virtual environment

```bash
# go out of old venv
deactivate
# delete old venv
rm -r .venv
# create new venv
python3 -m venv .venv
# activate new venv
source .venv/bin/activate
```

### Install dependencies

Then, install the dependencies with:

```bash
python3 -m pip install -e .
python3 -m pip install -e .[test]
```

### Run tests

Run tests with:

```bash
pytest
```

#### Test instance

You have to set the environment variable `GEOENGINE_TEST_CODE_PATH` to the code folder of the Geo Engine instance you want to test against.
Dotenv is supported, so you can create a `.env` file in the root of the project.

#### Coverage

You can check the coverage with:

```bash
pytest --cov=geoengine
```

### Test examples

You can test the examples with:

```bash
python3 -m pip install -e .[examples]
./test_all_notebooks.py
```

Or you can test a single example with:

```bash
./test_notebook.py examples/ndvi_ports.ipynb
```

## Dependencies

Since we use `cartopy`, you need to have the following system dependencies installed.

- GEOS
- PROJ

For Ubuntu, you can use this command:

```bash
sudo apt-get install libgeos-dev libproj-dev
```

## Build

You can build the package with:

```bash
python3 -m pip install -e .[dev]
python3 -m build
```

## Formatting

This package is formatted according to `ruff`.
You can check it by calling:

```bash
python3 -m ruff format --check
```

Our tip is to install `ruff` and use it to format the code.

### VSCode

If you use VSCode, you can install the [ruff extension](https://marketplace.visualstudio.com/items?itemName=charliermarsh.ruff) and set it as the default formatter.

## Lints

Our CI automatically checks for lint errors.
We use `ruff` to check the code.
You can check it by calling:

```bash
python3 -m ruff check
```

Our tip is to activate linting with `ruff` in your IDE.

## Type Checking

Our CI automatically checks for typing errors.
We use `mypy` to check the code.
You can check it by calling:

```bash
python3 -m mypy geoengine
python3 -m mypy tests
```

Using the config file `mypy.ini`, you can suppress missing stub errors for external libraries.
You can ignore a library by adding two lines to the config file. For example, suppressing matplotlib would look like this:

```ini
[mypy-matplotlib.*]
ignore_missing_imports = True

```

If there are typing-stubs packages you can install using `pip`, you can use these packages instead of ignoring the reported errors.
To find out, which packages could be installed you can use the following command:

```bash
python3 -m mypy geoengine --install-types
python3 -m mypy tests --install-types
```

Keep in mind, that you need to add the missing stubs by extending the dependencies in `setup.cfg` or ignoring them with `mypy.ini`.

Our tip is to activate type checking with `mypy` in your IDE.

## All checks from above

You can call `./check.sh` to run all the checks that are shown above.

## Documentation

Generate documentation HTML with:

```bash
pdoc3 --html --output-dir docs geoengine
```

## Examples

There are several examples in the `examples` folder.
It is necessary to install the dependencies with:

```bash
python3 -m pip install -e .[examples]
```

## Distribute to PyPI

### Test-PyPI

```bash
python3 -m build
python3 -m twine upload --repository testpypi dist/*
```

### PyPI

```bash
python3 -m build
python3 -m twine upload --repository pypi dist/*
```

## Try it out

Start a python terminal and try it out:

```python
import geoengine as ge
from datetime import datetime

ge.initialize("https://nightly.peter.geoengine.io/api")

time = datetime.strptime('2014-04-01T12:00:00.000Z', "%Y-%m-%dT%H:%M:%S.%f%z")

workflow = ge.workflow_by_id('4cdf1ffe-cb67-5de2-a1f3-3357ae0112bd')

print(workflow.get_result_descriptor())

workflow.get_dataframe(ge.Bbox([-60.0, 5.0, 61.0, 6.0], [time, time]))
```

## Authentication

If the Geo Engine server requires authentication, you can set your credentials in the following ways:

1. in the initialize method: `ge.initialize("https://nightly.peter.geoengine.io/api", ("email", "password"))`
2. as environment variables `export GEOENGINE_EMAIL="email"` and `export GEOENGINE_PASSWORD="password"`
3. in a .env file in the current working directory with the content:

```bash
GEOENGINE_EMAIL="email"
GEOENGINE_PASSWORD="password"
```
