api

Author: ChristianBeilschmidt

README.md

@@ -2,6 +2,11 @@
 
 This package allows easy access to Geo Engine functionality from Python environments.
 
+## Test
+
+Create a virtual environment (e.g., `python3 -m venv env`).
+Then, install the dependencies with `python3 -m pip install -e .`
+
 ## Build
 
 You can build the package with `python3 -m build`.

geoengine/__init__.py

@@ -1,2 +1,4 @@
-from .auth import Session
-from .lib import initialize, Accessor
+from .auth import Session, get_session, initialize, reset
+from .lib import Accessor, geopandas_by_workflow, geopandas_by_workflow_id
+from .types import Bbox
+from .error import GeoEngineException, InputException, UninitializedException

geoengine/auth.py

@@ -1,24 +1,65 @@
+from typing import Dict
+from geoengine.error import GeoEngineException, UninitializedException
 import requests as req
-from uuid import UUID
 
 
 class Session:
     '''
     A Geo Engine session
     '''
 
-    def __init__(self, id: UUID) -> None:
-        self.id = id
+    def __init__(self, server_url: str) -> None:
+        '''
+        Initialize communication between this library and a Geo Engine instance
+        '''
 
+        # TODO: username and password for Pro version
 
-def initialize_session(server_url: str) -> Session:
+        session = req.post(f'{server_url}/anonymous').json()
+
+        if 'error' in session:
+            raise GeoEngineException(session)
+
+        self.__id = session['id']
+        self.__valid_until = session['validUntil']
+        self.__server_url = server_url
+
+    def auth_headers(self) -> Dict[str, str]:
+        return {'Authorization': 'Bearer ' + self.__id}
+
+    def server_url(self) -> str:
+        return self.__server_url
+
+
+session: Session = None
+
+
+def get_session() -> Session:
+    global session
+
+    if session is None:
+        raise UninitializedException()
+
+    return session
+
+
+def initialize(server_url: str) -> None:
     '''
     Initialize communication between this library and a Geo Engine instance
     '''
 
-    # TODO: username and password for Pro version
+    global session
+
+    session = Session(server_url)
+
+
+def reset() -> None:
+    '''
+    Resets the current session
+    '''
+
+    global session
 
-    session = req.post(f'{server_url}/anonymous').json()
-    session_id = session['id']
+    # TODO: active logout for Pro version
 
-    Session(session_id)
+    session = None

geoengine/error.py

@@ -0,0 +1,23 @@
+from typing import Dict
+
+
+class GeoEngineException(Exception):
+    def __init__(self, reponse: Dict[str, str]) -> None:
+        self.error = reponse['error'] if 'error' in reponse else '?'
+        self.message = reponse['message'] if 'message' in reponse else '?'
+
+    def __str__(self) -> str:
+        return f"{self.error}: {self.message}"
+
+
+class InputException(Exception):
+    def __init__(self, message: str) -> None:
+        self.__message = message
+
+    def __str__(self) -> str:
+        return f"{self.__message}"
+
+
+class UninitializedException(Exception):
+    def __str__(self) -> str:
+        return "You have to call `initialize` before using other functionality"

geoengine/lib.py

@@ -1,6 +1,9 @@
 
-from geoengine.auth import Session, initialize_session
-from typing import Any
+from logging import debug
+from geoengine.types import Bbox
+from geoengine.error import GeoEngineException
+from geoengine.auth import Session, get_session
+from typing import Any, Dict
 import geopandas as gpd
 import requests as req
 from owslib.wfs import WebFeatureService
@@ -15,9 +18,77 @@ def get_features(self, workflow_id: Any, bbox: Any) -> gpd.GeoDataFrame:
         pass
 
 
-def initialize(server_url: str) -> Accessor:
-    '''
-    Initialize communication between this library and a Geo Engine instance
-    '''
+class WorkflowId:
+    def __init__(self, response: Dict[str, str]) -> None:
+        if not 'id' in response:
+            raise GeoEngineException(response)
 
-    Accessor(initialize_session(server_url))
+        self.__id = response['id']
+
+    def __str__(self) -> str:
+        return self.__id
+
+
+def register_workflow(workflow: str) -> WorkflowId:
+    session = get_session()
+
+    workflow_response = req.post(
+        f'{session.server_url()}/workflow',
+        json=workflow,
+        headers=session.auth_headers()
+    ).json()
+
+    return WorkflowId(workflow_response)
+
+
+def geopandas_by_workflow_id(workflow_id: WorkflowId, bbox: Bbox) -> gpd.GeoDataFrame:
+    session = get_session()
+
+    # wfs = WebFeatureService(url=f'{session.server_url()}/wfs', version='2.0.0')
+
+    # TODO: add resolution
+    # TODO: customize SRS
+    params = dict(
+        service='WFS',
+        version="2.0.0",
+        request='GetFeature',
+        outputFormat='application/json',
+        typeNames=f'registry:{workflow_id}',
+        bbox=bbox.bbox_str(),
+        time=bbox.time_str(),
+        srsName='EPSG:4326',
+    )
+
+    wfs_url = req.Request(
+        'GET', url=f'{session.server_url()}/wfs', params=params).prepare().url
+
+    debug(f'WFS URL:\n{wfs_url}')
+    print(f'WFS URL:\n{wfs_url}')
+
+    data_response = req.get(wfs_url, headers=session.auth_headers())
+
+    def geo_json_with_time_to_geopandas(data_response):
+        '''
+        GeoJson has no standard for time, so we parse the when field
+        separately and attach it to the data frame as columns `start`
+        and `end`.
+        '''
+
+        data = gpd.read_file(StringIO(data_response.text))
+
+        geo_json = data_response.json()
+        start = [f['when']['start'] for f in geo_json['features']]
+        end = [f['when']['end'] for f in geo_json['features']]
+
+        data['start'] = gpd.pd.to_datetime(start)
+        data['end'] = gpd.pd.to_datetime(end)
+
+        return data
+
+    return geo_json_with_time_to_geopandas(data_response)
+
+
+def geopandas_by_workflow(workflow: str, bbox: Bbox) -> gpd.GeoDataFrame:
+    workflow_id = register_workflow(workflow)
+
+    return geopandas_by_workflow_id(workflow_id, bbox)

geoengine/types.py

@@ -0,0 +1,38 @@
+from geoengine.error import InputException
+from typing import Tuple
+from datetime import datetime
+
+
+class Bbox:
+    def __init__(self, spatial_bbox: Tuple[float, float, float, float], time_interval: Tuple[datetime, datetime], resolution=0.1) -> None:
+        xmin = spatial_bbox[0]
+        ymin = spatial_bbox[1]
+        xmax = spatial_bbox[2]
+        ymax = spatial_bbox[3]
+
+        if (xmin > xmax) or (ymin > ymax):
+            raise InputException("Bbox: Malformed since min must be <= max")
+
+        self.__spatial_bbox = spatial_bbox
+
+        if time_interval[0] > time_interval[1]:
+            raise InputException("Time inverval: Start must be <= End")
+
+        self.__time_interval = time_interval
+
+        if resolution <= 0:
+            raise InputException("Resoultion: Must be positive")
+
+        self.__resolution = resolution
+
+    def bbox_str(self) -> str:
+        return ','.join(map(str, self.__spatial_bbox))
+
+    def time_str(self) -> str:
+        if self.__time_interval[0] == self.__time_interval[1]:
+            return self.__time_interval[0].isoformat(timespec='milliseconds')
+
+        return '/'.join(map(str, self.__time_interval))
+
+    def resolution(self) -> float:
+        return self.__resolution

setup.cfg

@@ -21,6 +21,7 @@ install_requires =
     requests
     geopandas
     owslib
+    requests_mock # actually a dev-dependency
 
 [options.packages.find]
 where = .

setup.py

@@ -0,0 +1,2 @@
+from setuptools import setup
+setup()