237 update and refactor examples

examples/README.md

@@ -1,41 +1,44 @@
 # 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.
 
 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

@@ -23,7 +23,7 @@
 # Host address of QuantumLeap
 QL_URL = "http://localhost:8668"
 #
-# 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))

examples/ngsi_v2/e01_ngsi_v2_context_basics.py

@@ -1,5 +1,5 @@
 """
-# Example how to use Entity-models and interact with teh orion ContextBroker
+# Example how to use Entity-models and interact with the Orion ContextBroker
 """
 
 # ## Import packages
@@ -13,27 +13,27 @@
 
 # ## Parameters
 #
-# To run this example you need a working Fiware v2 setup with a context-broker
-# You can here set the address:
+# To run this example, you need a working Fiware v2 setup with a context-broker
+# You can set the address here:
 #
 # Host address of Context Broker
 CB_URL = "http://localhost:1026"
 
-# You can here also change the used Fiware service
+# You can also change the used Fiware service
 # FIWARE-Service
 SERVICE = 'filip'
-# FIWARE-Servicepath
+# FIWARE-Service path
 SERVICE_PATH = '/example'
 
 # Setting up logging
 logging.basicConfig(
     level='INFO',
-    format='%(asctime)s %(name)s %(levelname)s: %(message)s')
+    format='%(asctime)s %(name)s %(levelname)s: %(message)s',
+    datefmt='%d-%m-%Y %H:%M:%S')
 logger = logging.getLogger(__name__)
 
-
 if __name__ == "__main__":
-   
+
     # # 1 Setup Client
     #
     # create the client, for more details view the example: e01_http_clients.py
@@ -43,8 +43,8 @@
                                     fiware_header=fiware_header)
     # View version
     for key, value in cb_client.get_version().items():
-        logger.info("Context broker version" + value["version"] + " at url " +
-                    cb_client.base_url)
+        logger.info(f"Context broker version: {value['version']} at url: "
+                    f"{cb_client.base_url}")
 
     # # 2 Create Entities
     #
@@ -54,18 +54,18 @@
     #
     # ### 2.1.1 Passing a dict:
     #
-    room1 = {"id": "Room1",
-             "type": "Room",
-             "temperature": {"value": 11,
-                             "type": "Float"},
-             "pressure": {"value": 111,
-                          "type": "Integer"}
-             }
-    room1_entity = ContextEntity(**room1)
+    room1_dictionary = {"id": "urn:ngsi-ld:Room:001",
+                        "type": "Room",
+                        "temperature": {"value": 11,
+                                        "type": "Float"},
+                        "pressure": {"value": 111,
+                                     "type": "Integer"}
+                        }
+    room1_entity = ContextEntity(**room1_dictionary)
 
     # ### 2.1.2 Using the constructor and interfaces
     #
-    room2_entity = ContextEntity(id="Room2", type="Room")
+    room2_entity = ContextEntity(id="urn:ngsi-ld:Room:002", type="Room")
     temp_attr = NamedContextAttribute(name="temperature", value=22,
                                       type=DataType.FLOAT)
     pressure_attr = NamedContextAttribute(name="pressure", value=222,
@@ -74,33 +74,37 @@
 
     # ## 2.2 Post Entities
     #
-    print(cb_client.get_entity_list())
+    logger.info(f'Entity list before posting to CB: {cb_client.get_entity_list()}')
     cb_client.post_entity(entity=room1_entity)
     cb_client.post_entity(entity=room2_entity)
 
     # # 3 Access entities in Fiware
     #
     # Get all entities from context broker
-    logger.info(cb_client.get_entity_list())
+    logger.info(f'Entity list after posting to CB: {cb_client.get_entity_list()}')
 
     # Get entities by id
-    logger.info(cb_client.get_entity_list(entity_ids=["Room1"]))
+    logger.info(f'Entities with ID "urn:ngsi-ld:Room:001": '
+                f'{cb_client.get_entity_list(entity_ids=["urn:ngsi-ld:Room:001"])}')
 
     # Get entities by type
-    logger.info(cb_client.get_entity_list(entity_types=["Room"]))
+    logger.info(f'Entities by type "Room": {cb_client.get_entity_list(entity_types=["Room"])}')
 
     # Get entities by id pattern
-    logger.info(cb_client.get_entity_list(id_pattern="^Room[2-5]"))
+    # The regular expression filters the rooms that have the id number 2 through 5
+    # with the prefix 'urn:ngsi-ld:Room:'
+    logger.info(f'Entities with id pattern "^urn:ngsi-ld:Room:00[2-5]": '
+                f'{cb_client.get_entity_list(id_pattern="^urn:ngsi-ld:Room:00[2-5]")}')
 
     # Get entities by query expression
-    query = QueryString(qs=[('temperature', '>', 22)])
-    logger.info(cb_client.get_entity_list(q=query))
+    query = QueryString(qs=[('temperature', '>=', 22)])
+    logger.info(f'Entities with temperature >= 22: {cb_client.get_entity_list(q=query)}')
 
     # Get attributes of entities
-    logger.info(cb_client.get_entity_attributes(entity_id="Room1"))
+    logger.info(f'Attributes of entities: {cb_client.get_entity_attributes(entity_id="urn:ngsi-ld:Room:001")}')
 
-    # Accessing non existing ids or attributes will always throw an request
-    # error
+    # Trying to access non-existing ids or attributes will always throw
+    # a request error
 
     # # 4 Changing Entities
     #
@@ -112,8 +116,8 @@
     # ### 4.1.1 Updating directly
     #
     # Using the Filip interface, we can update different properties of our
-    # entity directly in the live version in FIWARE, here are listed a few
-    # examples of what is possible:
+    # entity directly in the live version in FIWARE. A few examples of what 
+    # is possible are listed here:
 
     # Updating value of an attribute of an entity
     logger.info(cb_client.update_attribute_value(entity_id=room1_entity.id,
@@ -130,7 +134,7 @@
     # Hereby it is tried to only make changes that were done locally,
     # keeping as much of the current live state as possible
 
-    # when accessing an attribute a new object is created. We need to
+    # When accessing an attribute a new object is created. We need to
     # manually transmit the made changes.
     temp_attr = room2_entity.get_attribute("temperature")
     temp_attr.value = 15
@@ -146,5 +150,5 @@
     # To delete an entry in Fiware, we can call:
     cb_client.delete_entity(entity_id=room2_entity.id,
                             entity_type=room2_entity.type)
-    # cb_client.delete_entity(entity_id=room1_entity.id,
-    #                         entity_type=room1_entity.type)
+    cb_client.delete_entity(entity_id=room1_entity.id,
+                            entity_type=room1_entity.type)