237 update and refactor examples

.env.filip.EXAMPLE

@@ -0,0 +1,8 @@
+# Global settings for filip
+# If needed (for example for running examples) copy the content to another
+# local file `.env.filip` in the root folder, i.e., ".../FiLiP/.env.filip"
+# Do not add the created `.env.filip` to the git
+CB_URL="http://localhost:1026"
+IOTA_URL="http://localhost:4041/"
+QL_URL="http://localhost:8668"
+MQTT_BROKER_URL="mqtt://localhost:1883"

.gitignore

@@ -44,3 +44,4 @@ venv
 /examples/ngsi_v2/data_models/
 /tests/semantics/models.py
 /tests/semantics/models2.py
+/.env.filip

examples/README.md

@@ -1,41 +1,46 @@
 # Examples
 
-This directory contains examples to support to teach you how to use FiLiP to 
-build smart solutions based on FIWARE. 
+This directory contains examples to support you how to use FiLiP to 
+build smart solutions based on FIWARE.  
+In order to execute the examples you need a working FIWARE instance. For more details
+look into the [required prerequisites](https://github.com/RWTH-EBC/FiLiP?tab=readme-ov-file#prerequisites) of the
+library.  
 Each example should be executable with only small adjustments according to 
-your FIWARE instance, e.g. URL settings
+your FIWARE instance, e.g. URL settings. To do so, you can create a copy of the 
+``.env.filip.EXAMPLE`` file in the **root folder (i.e., ``.../FiLiP``)** and name it ``.env.filip``. By default,
+we assume that the FIWARE instance is running on localhost.
 
 The following topics are covered:
 
 #### How to use the clients and use general settings?
 
-- [http-clients](https://github.com/RWTH-EBC/FiLiP/blob/master/examples/basics/e01_http_clients.py) 
-- [logging](https://github.com/RWTH-EBC/FiLiP/blob/master/examples/basics/e11_logging.py) 
-- [settings-management](https://github.com/RWTH-EBC/FiLiP/blob/master/examples/basics/e11_logging.py)
+- [http-clients](./basics/e01_http_clients.py) 
+- [logging](./basics/e11_logging.py) 
+- [settings-management](./basics/e12_settings.py)
 
-#### How to model context and interact with context broker Orion?
+#### How to model context and interact with Orion Context Broker?
 
-- [Context Basics](https://github.com/RWTH-EBC/FiLiP/blob/master/examples/ngsi_v2/e01_ngsi_v2_context_basics.py) 
-- [Context Relationships](https://github.com/RWTH-EBC/FiLiP/blob/master/examples/ngsi_v2/e02_ngsi_v2_context_relationships.py)
-- [Context HTTP Subscriptions](https://github.com/RWTH-EBC/FiLiP/blob/master/examples/ngsi_v2/e03_ngsi_v2_context_subscriptions_http.py)
-- [Context MQTT Subscriptions](https://github.com/RWTH-EBC/FiLiP/blob/master/examples/ngsi_v2/e03_ngsi_v2_context_subscriptions_mqtt.py)
-- [Context Registrations](https://github.com/RWTH-EBC/FiLiP/blob/master/examples/ngsi_v2/e05_ngsi_v2_context_registrations.py)
-- [Context Model Generation](https://github.com/RWTH-EBC/FiLiP/blob/master/examples/ngsi_v2/e06_ngsi_v2_autogenerate_context_data_models.py)
+- [Context Basics](./ngsi_v2/e01_ngsi_v2_context_basics.py) 
+- [Context Relationships](./ngsi_v2/e02_ngsi_v2_context_relationships.py)
+- [Context HTTP Subscriptions](./ngsi_v2/e03_ngsi_v2_context_subscriptions_http.py)
+- [Context MQTT Subscriptions](./ngsi_v2/e04_ngsi_v2_context_subscriptions_mqtt.py)
+- [Context Registrations](./ngsi_v2/e05_ngsi_v2_context_registrations.py)
+- [Context Model Generation](./ngsi_v2/e06_ngsi_v2_autogenerate_context_data_models.py)
 
 #### How to interact with IoT-Agent?
 
-- [IoT Basics](https://github.com/RWTH-EBC/FiLiP/blob/master/examples/ngsi_v2/e07_ngsi_v2_iota_basics.py)
-- [IoT Paho MQTT](https://github.com/RWTH-EBC/FiLiP/blob/master/examples/ngsi_v2/e08_ngsi_v2_iota_paho_mqtt.py)
-- [IoT FiLiP MQTT](https://github.com/RWTH-EBC/FiLiP/blob/master/examples/ngsi_v2/e09_ngsi_v2_iota_filip_mqtt.py)
+- [IoT Basics](./ngsi_v2/e07_ngsi_v2_iota_basics.py)
+- [IoT Paho MQTT](./ngsi_v2/e08_ngsi_v2_iota_paho_mqtt.py)
+- [IoT FiLiP MQTT](./ngsi_v2/e09_ngsi_v2_iota_filip_mqtt.py)
   (We implemented this for magic MQTT-Topic handling)
 
 #### How to handle time series data and interact with QuantumLeap?
 
-- [Time Series Data](https://github.com/RWTH-EBC/FiLiP/blob/master/examples/ngsi_v2/e10_ngsi_v2_quantumleap.py)
+- [Time Series Data](./ngsi_v2/e10_ngsi_v2_quantumleap.py)
   with QuantumLeap
 
 #### How to use ontologies for semantic system modelling?
 
-- [Semantics](https://github.com/RWTH-EBC/FiLiP/tree/master/examples/ngsi_v2/e11_ngsi_v2_semantics)
-- [Use-case specific data modeling](https://github.com/RWTH-EBC/FiLiP/tree/master/examples/ngsi_v2/e12_ngsi_v2_use_case_models.py)
+- [Semantics](./ngsi_v2/e11_ngsi_v2_semantics)
+- [Use-case specific data modeling](./ngsi_v2/e12_ngsi_v2_use_case_models.py)
 

examples/basics/e01_http_clients.py

@@ -11,19 +11,19 @@
     IoTAClient, \
     QuantumLeapClient
 from filip.models.base import FiwareHeader
-
+from filip.config import settings
 # ## Parameters
 #
 # Note: This example also reads parameters from the '.env.filip'-file
 #
 # Host address of Context Broker
-CB_URL = "http://localhost:1026"
+CB_URL = settings.CB_URL
 # Host address of IoT-Agent
-IOTA_URL = "http://localhost:4041"
+IOTA_URL = settings.IOTA_URL
 # Host address of QuantumLeap
-QL_URL = "http://localhost:8668"
+QL_URL = settings.QL_URL
 #
-# You can here also change the used Fiware service
+# Here you can also change the used Fiware service
 # FIWARE-Service
 service = 'filip'
 # FIWARE-Servicepath
@@ -34,40 +34,40 @@
 
     # # 1 FiwareHeader
     #
-    # First a create a fiware header that you want to work with
+    # First create a fiware header that you want to work with
     # For more details on the headers check the official documentation:
     # https://fiware-orion.readthedocs.io/en/master/user/multitenancy/index.html
     #
-    # In short a fiware header specifies a location in Fiware where the
+    # In short, a fiware header specifies a location in Fiware where the
     # created entities will be saved and requests are executed.
-    # It can be thought of as a separated subdirectory where you work in.
+    # It can be thought of as a separate subdirectory where you work in.
     fiware_header = FiwareHeader(service='filip',
                                  service_path='/example')
 
     # # 2 Client modes
     # You can run the clients in different modes:
     #
-    # ## 2.1 Run it as pure python object.
+    # ## 2.1 Run it as a pure python object.
     #
     # This will open and close a connection each time you use a function.
-    cb_client = ContextBrokerClient(url="http://134.130.166.184:1026",
+    cb_client = ContextBrokerClient(url=CB_URL,
                                     fiware_header=fiware_header)
     print(f"OCB Version: {cb_client.get_version()}")
 
-    # ## 2.2 Run the client via the python's context protocol.
+    # ## 2.2 Run the client via python's context protocol.
     #
     # This will initialize requests.session that the client will reuse for
     # each function.
-    # Formally, this usually lead to an performance boost because the
-    # connection was reused reused. The client and its connection will be
-    # closed after the end of the with-statement. However, thanks to urllib3
-    # the keep-alive and session reuse is handled totally automatically.
+    # Formerly, this usually lead to a performance boost because the
+    # connection was reused. The client and its connection are
+    # closed after the end of the with-statement. However, thanks to urllib3,
+    # the keep-alive and session reuse are handled totally automatically.
     with ContextBrokerClient(fiware_header=fiware_header) as cb_client:
         print(f"OCB Version: {cb_client.get_version()}")
 
     # ## 2.3 Run the client with an externally provided requests.Session object
     #
-    # This mode is recommend when you want to reuse requests.Session and mix
+    # This mode is recommended when you want to reuse requests.Session and mix
     # different clients. It is also useful in combination with OAuth2Session
     # objects that handle authentication mechanisms and third party libraries.
     # Please be aware that you need to do the session handling yourself.
@@ -88,12 +88,12 @@
 
     # # 4 URL
     #
-    # Additional to the FiwareHeader each client needs an URL, that points
+    # Additional to the FiwareHeader each client needs a URL that points
     # to the Fiware-server.
     #
     # ## 4.1 Environment variables
     #
-    # As shown above the client does not need to be given explicitly. If no URL
+    # As shown above, the client does not need to be given explicitly. If no URL
     # is given to the client, it is extracted from the environment variables
     #
     # ## 4.2 Direct Provision
@@ -109,7 +109,7 @@
     # # 5 Combined Client
     #
     # The library also contains a client (HttpClient) that contains all the
-    # particular clients as bundle.
+    # particular clients as a bundle.
     # It works almost the same as the other agents but takes a config. This
     # can be either a dict or the path to a json file:
 
@@ -128,4 +128,4 @@
     # Close client
     iota_client.close()
     cb_client.close()
-    ql_client.close()
+    ql_client.close()

examples/basics/e11_logging.py

@@ -6,16 +6,16 @@
 # therefore reuses the streams of the root logger.
 """
 
-# import python's build in logging implementation
+# import python's built-in logging implementation
 import logging
 # import an api client from filip as example
 from filip.clients.ngsi_v2 import ContextBrokerClient
 # setting up the basic configuration of the logging system. Please check the
 # official documentation and the functions docstrings for more details.
 # Handling for 'handlers' in the logging system is not trivial.
-# It is also import to know that this function should only be called once in
+# It is also important to know that this function should only be called once in
 # your application. Since FiLiP is an SDK that should help to implement other
-# services we do not call this function anywhere in our code.
+# services, we do not call this function anywhere in our code.
 # Hence, it is up to the user to configure the logging system.
 
 # In this example we will simply change the log level and the log format.

examples/basics/e12_settings.py

@@ -3,21 +3,16 @@
 # configuration settings. Using *.json config-files or environment
 # variables. You can also use the .env.filip file to provide the variables
 #
-# Feel free to play around with the settings and the check how
+# Feel free to play around with the settings and see how
 # the urls and header parameter will be checked and/or automatically
 # guessed based on the provided information.
 
-# Note: Although Urls are also guessed the safest is to set the service url
+# Note: Although URLs are also guessed, the safest option is to set the service url
 # directly
  """
 import os
 
 
-
-
-
-
-
 if __name__ == '__main__':
 
     # # 1 Example using environment variables
@@ -27,4 +22,4 @@
     os.environ["IOTA_URL"] = "http://localhost:4041"
 
     from filip import settings
-    print(settings.json(indent=2))
+    print(settings.model_dump_json(indent=2))