03/10 merge with upstream pygeoapi and handle conflict

Author: Csenongmin

.github/workflows/main.yml

@@ -24,6 +24,7 @@ jobs:
           - python-version: '3.12'
     env:
       PYGEOAPI_CONFIG: "$(pwd)/pygeoapi-config.yml"
+      DOCKER_API_VERSION: "1.44"
 
     services:
       postgres:
@@ -42,7 +43,6 @@ jobs:
         docker pull elasticsearch:8.17.0 &
         docker pull opensearchproject/opensearch:2.18.0 &
         docker pull mongo:8.0.4 &
-        docker pull ghcr.io/cgs-earth/sensorthings-action:0.1.0 &
         docker pull postgis/postgis:14-3.2 &
     - name: Clear up GitHub runner diskspace
       run: |
@@ -96,7 +96,7 @@ jobs:
       with:
         mongodb-version: '8.0.4'
     - name: Install and run SensorThingsAPI
-      uses: cgs-earth/sensorthings-action@v0.1.0
+      uses: cgs-earth/sensorthings-action@v0.1.2
     - name: Install sqlite and gpkg dependencies
       uses: awalsh128/cache-apt-pkgs-action@v1.4.3
       with:
@@ -126,6 +126,7 @@ jobs:
         pip3 install -r requirements-provider.txt
         pip3 install -r requirements-manager.txt
         pip3 install -r requirements-django.txt
+        pip3 install -r requirements-pubsub.txt
         pip3 install .
         pip3 install GDAL==`gdal-config --version`
     - name: setup test data ⚙️

Dockerfile

@@ -5,7 +5,7 @@
 #          Francesco Bartoli <xbartolone@gmail.com>
 #          Angelos Tzotsos <gcpp.kalxas@gmail.com>
 #
-# Copyright (c) 2025 Tom Kralidis
+# Copyright (c) 2026 Tom Kralidis
 # Copyright (c) 2019 Just van den Broecke
 # Copyright (c) 2025 Francesco Bartoli
 # Copyright (c) 2025 Angelos Tzotsos
@@ -34,7 +34,7 @@
 #
 # =================================================================
 
-FROM ubuntu:noble-20251013
+FROM ubuntu:noble
 
 LABEL maintainer="Just van den Broecke <justb4@gmail.com>"
 
@@ -133,7 +133,7 @@ ADD . /pygeoapi
 RUN python3 -m venv --system-site-packages /venv \
     && /venv/bin/python3 -m pip install --no-cache-dir -r requirements-docker.txt \
     && /venv/bin/python3 -m pip install --no-cache-dir -r requirements-admin.txt \
-    && /venv/bin/python3 -m pip install --no-cache-dir gunicorn \
+    && /venv/bin/python3 -m pip install --no-cache-dir "gunicorn<24" \
     && /venv/bin/python3 -m pip install --no-cache-dir -e .
 
 # Set default config and entrypoint for Docker Image

SECURITY.md

@@ -13,5 +13,5 @@ The pygeoapi Project Steering Committee (PSC) will release patches for security
 
 | Version | Supported          |
 | ------- | ------------------ |
-| 0.10.x  | :white_check_mark: |
-| < 0.10  | :x:                |
+| 0.2x    | :white_check_mark: |
+| < 0.20  | :x:                |

docker/entrypoint.sh

@@ -46,6 +46,9 @@ fi
 if [[ -z "$PYGEOAPI_OPENAPI" ]]; then
     export PYGEOAPI_OPENAPI="${PYGEOAPI_HOME}/local.openapi.yml"
 fi
+if [[ -z "$PYGEOAPI_ASYNCAPI" ]]; then
+    export PYGEOAPI_ASYNCAPI="${PYGEOAPI_HOME}/local.asyncapi.yml"
+fi
 
 # gunicorn env settings with defaults
 SCRIPT_NAME=${SCRIPT_NAME:=/}
@@ -87,6 +90,11 @@ echo "Trying to generate openapi.yml"
 
 echo "openapi.yml generated continue to pygeoapi"
 
+echo "Trying to generate asyncapi.yml"
+/venv/bin/pygeoapi asyncapi generate ${PYGEOAPI_CONFIG} --output-file ${PYGEOAPI_ASYNCAPI}
+
+[[ $? -ne 0 ]] && echo "asyncapi.yml could not be generated; skipping"
+
 start_gunicorn() {
     # SCRIPT_NAME should not have value '/'
     [[ "${SCRIPT_NAME}" = '/' ]] && export SCRIPT_NAME="" && echo "make SCRIPT_NAME empty from /"

docs/source/administration.rst

@@ -24,12 +24,6 @@ To generate the OpenAPI document, run the following:
 
 This will dump the OpenAPI document as YAML to your system's ``stdout``.  To save to a file on disk, run:
 
-.. code-block:: bash
-
-   pygeoapi openapi generate /path/to/my-pygeoapi-config.yml > /path/to/my-pygeoapi-openapi.yml
-
-You can also write to a file explicitly via the ``--output-file`` option:
-
 .. code-block:: bash
 
    pygeoapi openapi generate /path/to/my-pygeoapi-config.yml --output-file /path/to/my-pygeoapi-openapi.yml
@@ -38,7 +32,7 @@ To generate the OpenAPI document as JSON, run:
 
 .. code-block:: bash
 
-   pygeoapi openapi generate /path/to/my-pygeoapi-config.yml -f json > /path/to/my-pygeoapi-openapi.json
+   pygeoapi openapi generate /path/to/my-pygeoapi-config.yml --format json --output-file /path/to/my-pygeoapi-openapi.json
 
 .. note::
    Generate as YAML or JSON?  If your OpenAPI YAML definition is slow to render as JSON,
@@ -83,6 +77,11 @@ In UNIX:
     # or if OpenAPI JSON
     export PYGEOAPI_OPENAPI=/path/to/my-pygeoapi-openapi.json
 
+    # if your server supports AsyncAPI and Pub/Sub
+    export PYGEOAPI_ASYNCAPI=/path/to/my-pygeoapi-asyncapi.yml
+    # or if AsyncAPI JSON
+    export PYGEOAPI_ASYNCAPI=/path/to/my-pygeoapi-asyncapi.json
+
 In Windows:
 
 .. code-block:: bat
@@ -92,6 +91,14 @@ In Windows:
     # or if OpenAPI JSON
     set PYGEOAPI_OPENAPI=/path/to/my-pygeoapi-openapi.json
 
+    # if your server supports AsyncAPI and Pub/Sub
+    set PYGEOAPI_ASYNCAPI=/path/to/my-pygeoapi-asyncapi.yml
+    # or if AsyncAPI JSON
+    set PYGEOAPI_ASYNCAPI=/path/to/my-pygeoapi-asyncapi.json
+
+.. note::
+
+    More information on AsyncAPI and Pub/Sub can be found at :ref:`pubsub`.
 
 Summary
 -------

docs/source/conf.py

@@ -112,7 +112,7 @@ def __getattr__(cls, name):
 # built documents.
 #
 # The short X.Y version.
-version = '0.23.dev0'
+version = '0.24.dev0'
 # The full version, including alpha/beta/rc tags.
 release = version
 

docs/source/configuration.rst

@@ -14,6 +14,7 @@ file whatever you wish; typical filenames end with ``.yml``.
 pygeoapi configuration contains the following core sections:
 
 - ``server``: server-wide settings
+- ``pubsub``: Publish-Subscribe settings (optional)
 - ``logging``: logging configuration
 - ``metadata``: server-wide metadata (contact, licensing, etc.)
 - ``resources``: dataset collections, processes and stac-collections offered by the server
@@ -90,6 +91,23 @@ For more information related to API design rules (the ``api_rules`` property in
         url_prefix: 'v{api_major}'  # adds a /v1 prefix to all URL paths
         version_header: X-API-Version  # add a response header of this name with the API version
 
+``pubsub``
+^^^^^^^^^^
+
+The ``pubsub`` section provides directives for enabling publication of CloudEvent messaages on item-based transactions
+
+
+.. code-block:: yaml
+
+  pubsub:
+      name: MQTT
+      broker:
+          url: mqtt://localhost:1883
+          channel: my/service/topic
+
+.. seealso::
+   :ref:`pubsub` for more information on Publish-Subscribe capabilities
+
 
 ``logging``
 ^^^^^^^^^^^
@@ -225,6 +243,14 @@ default.
                   begin: 2000-10-30T18:24:39Z  # start datetime in RFC3339
                   end: 2007-10-30T08:57:29Z  # end datetime in RFC3339
                   trs: http://www.opengis.net/def/uom/ISO-8601/0/Gregorian  # TRS
+                  resolution: P1D  # ISO 8601 duration
+                  default: 2000-10-30T18:24:39Z  # default time
+              # additional extents can be added as desired (1..n)
+              foo:
+                  url: https://example.org/def  # required URL of the extent
+                  range: [0, 10] # required overall range/extent
+                  units: °C  # optional units
+                  values: [0, 2, 5, 5, 10]  # optional, enumeration of values
           providers:  # list of 1..n required connections information
               - type: feature  # underlying data geospatial type. Allowed values are: feature, coverage, record, tile, edr
                 name: CSV  # required: plugin name or import path. See Plugins section for more information.

docs/source/index.rst

@@ -39,6 +39,7 @@ reference documentation on all aspects of the project.
    openapi
    publishing/index
    transactions
+   pubsub
    admin-api
    security
    plugins

docs/source/plugins.rst

@@ -30,10 +30,15 @@ The core pygeoapi plugin registry can be found in ``pygeoapi.plugin.PLUGINS``.
 
 Each plugin type implements its relevant base class as the API contract:
 
-* data providers: ``pygeoapi.provider.base``
-* output formats: ``pygeoapi.formatter.base``
-* processes: ``pygeoapi.process.base``
-* process_manager: ``pygeoapi.process.manager.base``
+* data providers:
+
+  * features/records/maps: ``pygeoapi.provider.base.BaseProvider``
+  * edr: ``pygeoapi.provider.base_edr.BaseEDRProvider``
+  * tiles: ``pygeoapi.provider.tile.BaseTileProvider``
+
+* output formats: ``pygeoapi.formatter.base.BaseFormatter``
+* processes: ``pygeoapi.process.base.BaseProcessor``
+* process_manager: ``pygeoapi.process.manager.base.BaseManager``
 
 .. todo:: link PLUGINS to API doc
 
@@ -150,7 +155,7 @@ option 2 above).
 Example: custom pygeoapi vector data provider
 ---------------------------------------------
 
-Lets consider the steps for a vector data provider plugin:
+Let's consider the steps for a vector data provider plugin:
 
 Python code
 ^^^^^^^^^^^
@@ -223,7 +228,7 @@ Each base class documents the functions, arguments and return types required for
 Example: custom pygeoapi raster data provider
 ---------------------------------------------
 
-Lets consider the steps for a raster data provider plugin:
+Let's consider the steps for a raster data provider plugin:
 
 Python code
 ^^^^^^^^^^^
@@ -278,6 +283,51 @@ Each base class documents the functions, arguments and return types required for
 
 .. _example-custom-pygeoapi-processing-plugin:
 
+Example: custom pygeoapi EDR data provider
+------------------------------------------
+
+Let's consider the steps for an EDR data provider plugin:
+
+Python code
+^^^^^^^^^^^
+
+The below template provides a minimal example (let's call the file ``mycooledrdata.py``:
+
+.. code-block:: python
+
+   from pygeoapi.provider.base_edr import BaseEDRProvider
+
+   class MyCoolEDRDataProvider(BaseEDRProvider):
+
+       def __init__(self, provider_def):
+           """Inherit from the parent class"""
+
+           super().__init__(provider_def)
+
+           self.covjson = {...}
+
+       def get_instances(self):
+           return ['foo', 'bar']
+
+       def get_instance(self, instance):
+           return instance in get_instances()
+
+       def position(self, **kwargs):
+           return self.covjson
+
+       def trajectory(self, **kwargs):
+           return self.covjson
+
+
+For brevity, the ``position`` function returns ``self.covjson`` which is a
+dictionary of a CoverageJSON representation.  ``get_instances`` returns a list
+of instances associated with the collection/plugin, and ``get_instance`` returns
+a boolean of whether a given instance exists/is valid.  EDR query types are subject
+to the query functions defined in the plugin.  In the example above, the plugin
+implements ``position`` and ``trajectory`` queries, which will be advertised as
+supported query types.
+
+
 Example: custom pygeoapi processing plugin
 ------------------------------------------
 
@@ -360,6 +410,7 @@ Below is a sample process definition as a Python dictionary:
                       'it back as output. Intended to demonstrate a simple '
                       'process with a single literal input.',
        'jobControlOptions': ['sync-execute', 'async-execute'],  # whether the process can be executed in sync or async mode
+       'outputTransmission': ['value', 'reference'],  # whether the process can return inline data or URL references
        'keywords': ['hello world', 'example', 'echo'],  # keywords associated with the process
        'links': [{  # a list of 1..n  # link objects relevant to the process
            'type': 'text/html',

docs/source/publishing/ogcapi-coverages.rst

@@ -89,11 +89,20 @@ The `Xarray`_ provider plugin reads and extracts `NetCDF`_ and `Zarr`_ data.
          format:
             name: zarr
             mimetype: application/zip
+         options:
+             zarr:
+                 consolidated: true
+             squeeze: true
+
 
 .. note::
    `Zarr`_ files are directories with files and subdirectories.  Therefore
    a zip file is returned upon request for said format.
 
+.. note::
+
+   ``options.zarr`` is a custom property that can be used to set `Zarr-specific open options`_.
+
 .. note::
    When referencing `NetCDF`_ or `Zarr`_ data stored in an S3 bucket, 
    be sure to provide the full S3 URL. Any parameters required to open the dataset
@@ -155,3 +164,4 @@ Data access examples
 .. _`Zarr`: https://zarr.readthedocs.io/en/stable
 .. _`GDAL raster driver short name`: https://gdal.org/drivers/raster/index.html
 .. _`pyproj.CRS.from_user_input`: https://pyproj4.github.io/pyproj/stable/api/crs/coordinate_system.html#pyproj.crs.CoordinateSystem.from_user_input
+.. _`Zarr-specific open options`: https://docs.xarray.dev/en/stable/generated/xarray.open_zarr.html