Add basic example about framework usage.

Author: david-woelfle

.vscode/settings.json

@@ -8,21 +8,29 @@
         "autouse",
         "bemcom",
         "caplog",
+        "cecinverter",
         "dataframe",
         "datapoint",
         "datapoints",
         "docstrings",
         "dotenv",
+        "fooc",
+        "iloc",
         "instrumentator",
         "jwks",
         "JWTs",
         "Keycloak",
         "levelname",
+        "meteo",
+        "modelchain",
         "MQTT",
         "oidc",
         "oneshot",
+        "pvlib",
+        "pvsystem",
         "pyjwt",
         "redoc",
+        "Sandia",
         "Setpoint",
         "setpoints",
         "UNVALIDATED",

build-docker-images.sh

@@ -0,0 +1,39 @@
+#!/bin/bash
+# USAGE:
+#
+# Build `latest` images with:
+# bash build-docker-images.sh 
+#
+# Build specific version, e.g. 0.1.0 with:
+# bash build-docker-images.sh 0.1.0
+set -euo pipefail
+
+IMAGE_NAME="energy_service_generics"
+SOURCE_PATH="./source"
+IMAGE_TAG_BASE=${1:-latest}
+
+
+# Build each of the four versions of the image and check directly 
+# afterwards if the image works as expected by executing the tests.
+# This way the script should fail faster if it doesn't make sense to
+# build another version, as the tests will fail anyway to the problems
+# already present in the the previous build.
+# NOTE: The builds are in such an order that as much as possible of layers
+#       can be reused to keep build times low.
+docker build --target esg-base -t $IMAGE_NAME:${IMAGE_TAG_BASE} $SOURCE_PATH
+docker run --rm -t $IMAGE_NAME:$IMAGE_TAG_BASE pytest
+docker build --target esg-service -t $IMAGE_NAME:${IMAGE_TAG_BASE}-service $SOURCE_PATH
+docker run --rm -t $IMAGE_NAME:${IMAGE_TAG_BASE}-service pytest
+docker build --target esg-pandas -t $IMAGE_NAME:${IMAGE_TAG_BASE}-pandas $SOURCE_PATH
+docker run --rm -t $IMAGE_NAME:${IMAGE_TAG_BASE}-pandas pytest
+docker build --target esg-service-pandas -t $IMAGE_NAME:${IMAGE_TAG_BASE}-service-pandas $SOURCE_PATH
+docker run --rm -t $IMAGE_NAME:${IMAGE_TAG_BASE}-service-pandas pytest
+
+printf "\033[0;32m\n" # Make text green
+printf "Success! "
+printf "\033[0m" # Make text normal again.
+printf "Built these images:\n"
+echo $IMAGE_NAME:$IMAGE_TAG_BASE
+echo $IMAGE_NAME:${IMAGE_TAG_BASE}-service
+echo $IMAGE_NAME:${IMAGE_TAG_BASE}-pandas
+echo $IMAGE_NAME:${IMAGE_TAG_BASE}-service-pandas

docs/examples/basic_example/docker-compose.yml

@@ -0,0 +1,31 @@
+# Copyright 2024 FZI Research Center for Information Technology
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# SPDX-FileCopyrightText: 2024 FZI Research Center for Information Technology
+# SPDX-License-Identifier: Apache-2.0
+
+services:
+  energy-service-generics-basic-example-autotest:
+    container_name: energy-service-generics-basic-example-autotest
+    build:
+      context: ./source
+      dockerfile: Dockerfile-worker
+    init: true # Faster shutdown.
+    entrypoint: [ "auto-pytest" ]
+    command: [ "/source/service/" ]
+    tty: true # Colorize output.
+    restart: unless-stopped
+    volumes:
+      - ./source/service:/source/service/
+    user: "${USER_ID:-1000}:${GROUP_ID:-1000}"

docs/examples/basic_example/source/Dockerfile-API

@@ -0,0 +1,5 @@
+FROM energy_service_generics:latest-service
+
+COPY api.py data_model.py worker.py /source/service/
+
+CMD ["/source/service/api.py"]

docs/examples/basic_example/source/Dockerfile-worker

@@ -0,0 +1,7 @@
+FROM energy_service_generics:latest-service-pandas
+
+RUN pip install pvlib scipy
+COPY service/ /source/service/
+
+ENTRYPOINT [ "celery" ]
+CMD [ "--app", "worker", "worker", "--loglevel=INFO" ]

docs/examples/basic_example/source/service/__init__.py

@@ -0,0 +1,20 @@
+"""
+Tests for content of fooc.py
+
+Copyright 2024 FZI Research Center for Information Technology
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+SPDX-FileCopyrightText: 2024 FZI Research Center for Information Technology
+SPDX-License-Identifier: Apache-2.0
+"""

docs/examples/basic_example/source/service/api.py

@@ -0,0 +1,42 @@
+"""
+Copyright 2024 FZI Research Center for Information Technology
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+SPDX-FileCopyrightText: 2024 FZI Research Center for Information Technology
+SPDX-License-Identifier: Apache-2.0
+"""
+
+from packaging.version import Version
+
+from esg.service.api import API
+
+from data_model import RequestArguments, RequestOutput
+from data_model import FittedParameters, Observations
+from data_model import FitParameterArguments
+from worker import request_task, fit_parameters_task
+
+api = API(
+    RequestArguments=RequestArguments,
+    RequestOutput=RequestOutput,
+    FittedParameters=FittedParameters,
+    Observations=Observations,
+    FitParameterArguments=FitParameterArguments,
+    request_task=request_task,
+    fit_parameters_task=fit_parameters_task,
+    title="PV Power Prediction Example Service",
+    version=Version("0.0.1"),
+)
+
+if __name__ == "__main__":
+    api.run()

docs/examples/basic_example/source/service/data_model.py

@@ -0,0 +1,49 @@
+"""
+Definition of the data models for de-/serializing data and the docs.
+
+Copyright 2024 FZI Research Center for Information Technology
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+SPDX-FileCopyrightText: 2024 FZI Research Center for Information Technology
+SPDX-License-Identifier: Apache-2.0
+"""
+
+from esg.models.base import _BaseModel
+from esg.models.datapoint import ValueMessageList
+from esg.models.metadata import GeographicPosition, PVSystem
+from pydantic import Field
+
+
+class RequestArguments(_BaseModel):
+    geographic_position: GeographicPosition
+
+
+class RequestOutput(_BaseModel):
+    power_prediction: ValueMessageList = Field(
+        description="Prediction of power production in W"
+    )
+
+
+class FittedParameters(_BaseModel):
+    pv_system: PVSystem
+
+
+class Observations(_BaseModel):
+    measured_power: ValueMessageList = Field(
+        description="Measured power production in W"
+    )
+
+
+class FitParameterArguments(_BaseModel):
+    geographic_position: GeographicPosition