Metadata-Version: 2.4
Name: sta-dggs-client
Version: 0.1.0
Summary: A client library for the OGC SensorThings DGGS (Cell) extension
Home-page: https://github.com/securedimensions/STA-DGGS-Python-Client
Author: Andreas Matheus
Author-email: andreas.matheus@secure-dimensions.de
License: LGPL3
Keywords: ogc,sta-dggs,sensorthingsapi,DGGS,IoT
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: demjson3>=3.0.5
Requires-Dist: furl>=2.1.3
Requires-Dist: geojson>=2.5.0
Requires-Dist: jsonpickle>=2.0.0
Requires-Dist: requests>=2.26.0
Requires-Dist: jsonpatch
Requires-Dist: python-dateutil
Requires-Dist: sd-frost-sta-client>=1.1.47
Dynamic: author
Dynamic: author-email
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: requires-dist
Dynamic: summary

# OGC STA-DGGS (SensorThings Cell) Python Client

This STA-DGGS Python Client implements the SensorThings Discrete Global Grid System extension (entity type `Cell`). The aim is to isolate Cell from STAplus and STA so it can be used on its own or stacked with the [STAplus Python Client](https://github.com/securedimensions/STAplus-Python-Client).

This implementation is an extension to the [STA Python Client](https://github.com/securedimensions/STA-Python-Client).

## Python Version
This library requires Python 3.11 or better to support parsing ISO datetime values (`datetime.datetime.fromisoformat`).

## Features
* Support for the STA-DGGS `Cell` entity
* Cell attributes: `zoneId`, `zoneLevel`, `system`, `boundary`, `encodingType`, `properties`
* Navigations: Datastreams, MultiDatastreams, Observations, Parent, Children
* Reverse `Cell` navigation on Datastream, MultiDatastream, and Observation
* CRUD operations and queries
* `compose()` with STAplus for the combined STAplus + DGGS data model

## Installation via PyPi
Installation via pip: `pip install sta-dggs-client`

## STA-DGGS only

```python
import sta_dggs_client as dggs

url = "<your domain>/FROST-Server/v1.1"
service = dggs.STADGGSService(url)

cell = dggs.Cell(zone_id='u281t', zone_level=5, system='H3')
service.create(cell)
```

## Combined with STAplus

A client that needs both STAplus (Party, License, Campaign, …) and Cell uses `compose()`. That returns one service whose Datastream, MultiDatastream, and Observation classes carry both models. `compose()` requires `staplus-client` to be installed. STA-DGGS itself does not depend on STAplus.

```python
import staplus_client as plus
import sta_dggs_client as dggs
service = dggs.compose(url, auth_handler=auth)
ds = plus.Datastream(name='Temperature', description='temp',
                     party=party, cell=cell)
mds = plus.MultiDatastream(name='Air quality', description='multi',
                           party=party, cell=cell)
obs = plus.Observation(result=21.5, cell=cell)
```

`compose()` rebinds `plus.Datastream` (and MultiDatastream, Observation) so existing STAplus code keeps working, including `datastream.cell = dggs.Cell(zone_id)`. `compose()` takes the same arguments as `SensorThingsService` in STA-Python-Client: `url`, `auth_handler`, and `proxies`. You can also pass an existing `STAplusService` instance:

```python
service = dggs.compose(plus.STAplusService(url, auth_handler=auth))
```

## Limitations
`Cell/boundary` should be JSON-serializable (typically a GeoJSON Geometry). `encodingType`, when set, should be one of:

* `application/geo+json`
* `application/vnd.geo+json`
* `application/vnd.ogc.fg+json`
* `application/wkt`
