Release da3d2c10abaf6d290e5d8087bf6bc170

_requirements_/specification.py

@@ -0,0 +1,208 @@
+def specification(req_spec):
+    req_spec.add_title("Caching Module")
+
+    #
+    # Section
+    #
+    sec_uuid = req_spec.add(
+        itemtype="SEC",
+        id=1,
+        heading="Cache generation (json / pickle)",
+    )
+
+    # Requirement
+    req_spec.add(
+        parent=sec_uuid,
+        itemtype="REQ",
+        id=3,
+        heading="Data generation from source instance, if no cache is available",
+        description="If the cache is not available, the data shall be generated from the source instance.",
+        reason="There shall be the posibility to create the cache on demand, so the fallback is to generate the data from the source instance.",
+        fitcriterion="Caching is called without previous cache generation and the data from the source instance is completely available.",
+    )
+
+    # Requirement
+    req_spec.add(
+        parent=sec_uuid,
+        itemtype="REQ",
+        id=1,
+        heading="Create complete cache from the given data instance",
+        description="There shall be a method caching all information from the given instance.",
+        reason="Independent usage of data generation and data usage (e.g. the user requesting the data is not able to create the data).",
+        fitcriterion="Caching is called twice with different data instances and the cached data from the first call is completely available.",
+    )
+
+    # Requirement
+    req_spec.add(
+        parent=sec_uuid,
+        itemtype="REQ",
+        id=5,
+        heading="Create cache partially from a given data instance by get method",
+        description="On getting data from the cached instance, the information shall be stored in the cache file.",
+        reason="There shall be the posibility to create the cache on demand, so the fallback is to generate the data from the source instance.",
+        fitcriterion="Caching is called twice with different data instances and the cached data from the first call is  available for all keys cached on the first run.",
+    )
+
+    # Requirement
+    req_spec.add(
+        parent=sec_uuid,
+        itemtype="REQ",
+        id=15,
+        heading="Ignore corrupt cache file",
+        description="Ignore corrupt cachefile, while loading cache.",
+        reason="Suppress exceptions while caching.",
+        fitcriterion="Loading cache results in no exception, when cache file is empty.",
+    )
+    #
+    # Section
+    #
+    sec_uuid = req_spec.add(
+        itemtype="SEC",
+        id=2,
+        heading="Load spreading for full update",
+    )
+
+    # Requirement
+    req_spec.add(
+        parent=sec_uuid,
+        itemtype="REQ",
+        id=4,
+        heading="Full update with delay between each data generation for the cache",
+        description="The full update method shall pause for a given time between every cached item.",
+        reason="Load spreading in case of cyclic called {\\tt .full\\_update()}.",
+        fitcriterion="The time consumption of the method {\\tt .full\\_update(\u003csleep\\_time\u003e)} shall consume $n$ times the given {\\tt sleep\\_time}. Where $n$ is the number of items which will be cahed from the source instance.",
+    )
+
+    # Requirement
+    req_spec.add(
+        parent=sec_uuid,
+        itemtype="REQ",
+        id=2,
+        heading="No cache generation if disabled",
+        description="The cache shall be generated by the {\\tt .get()} method, only if the cache instance parameter {\\tt store\\_on\\_get} is set to {\\tt True}.",
+        reason="Independent usage of data generation and data usage (e.g. the user requesting the data is not able to create the data).",
+        fitcriterion="Create a caching instance with {\\tt store\\_on\\_get} set to {\\tt False}. Get every item of the source instance with the {\\tt .get()} method and check that no cache file exists.",
+    )
+    #
+    # Section
+    #
+    sec_uuid = req_spec.add(
+        itemtype="SEC",
+        id=3,
+        heading="Dump cache conditions",
+    )
+
+    # Requirement
+    req_spec.add(
+        parent=sec_uuid,
+        itemtype="REQ",
+        id=6,
+        heading="Dump cache if time is expired",
+        description="Dump the cached item, if this item is older then the given expirery time.",
+        reason="Ensure, that the cache is updated from time to time. For example for items which do not change very often.",
+        fitcriterion="Create a cache instance, cache some data. Intialise a second caching instance with a different source instance and a expire time. Wait for longer than the given expiry time and check that the items from the second source instance are returned.",
+    )
+
+    # Requirement
+    req_spec.add(
+        parent=sec_uuid,
+        itemtype="REQ",
+        id=7,
+        heading="Dump cache if data version increases",
+        description="Dump the complete cache, if the \\emph{data version} of the source instance is increased.",
+        reason="The data version is part of the source instance. Increasing the data version indicates, that the source instance generates the data in another way or the structure of the data is changed. In that condition, the cache needs to be ignored.",
+        fitcriterion="Create a cached instance and cache some items. Generate a second cached instance with different source data and a increased  data version. Ensure, that the cache instance returns the values from the second source. It is required to set {\\tt load\\_all\\_on\\_init} to {\\tt False} and {\\tt store\\_on\\_get} to {\\tt True}.",
+    )
+
+    # Requirement
+    req_spec.add(
+        parent=sec_uuid,
+        itemtype="REQ",
+        id=8,
+        heading="Dump cache if data uid is changed",
+        description="Dump the complete cache, if the \\emph{data uid} of the source instance is changed.",
+        reason="The data uid is part of the source instance. Changing the data uid indicates, that the source of the data created by the source instance is changed  (e.g. the uid of a file or folder) and the cache needs to be ignored.",
+        fitcriterion="Create a cached instance and cache some items. Generate a second cached instance with different source data and a changed data uid. Ensure, that the cache instance returns the values from the second source. It is required to set {\\tt load\\_all\\_on\\_init} to {\\tt False} and {\\tt store\\_on\\_get} to {\\tt True}.",
+    )
+
+    # Requirement
+    req_spec.add(
+        parent=sec_uuid,
+        itemtype="REQ",
+        id=9,
+        heading="Dump cache if storage version is changed",
+        description="Dump the complete cache, if the \\emph{storage version} of the caching class is changed.",
+        reason="The storage version is part of the caching class. Changing the storage version indicates, that the previously stored cache is not compatible due to new data storage and the cache needs to be ignored.",
+        fitcriterion="Create a cached instance and cache some items. Generate a second cached instance with different source data and a changed storage version. Ensure, that the cache instance returns the values from the second source. It is required to set {\\tt load\\_all\\_on\\_init} to {\\tt False} and {\\tt store\\_on\\_get} to {\\tt True}.",
+    )
+
+    # Requirement
+    req_spec.add(
+        parent=sec_uuid,
+        itemtype="REQ",
+        id=14,
+        heading="Dump cache if stored value is \"None\"",
+        description="Dump the cached item, if the stored value is {\\tt None}.",
+        reason="If no information is stored in the cache, the data shall be generated by the source instance.",
+        fitcriterion="Create a cached instance and cache some items. One needs to have {\\tt None} as value. Generate a second cached instance with different source data (especially, the previous item with value {\\tt None} needs to have a not {\\tt None} value. Ensure, that the caching instance returns not {\\tt None} from the second source.",
+    )
+    #
+    # Section
+    #
+    sec_uuid = req_spec.add(
+        itemtype="SEC",
+        id=4,
+        heading="Definition of uncached data",
+    )
+
+    # Requirement
+    req_spec.add(
+        parent=sec_uuid,
+        itemtype="REQ",
+        id=10,
+        heading="Define uncached data",
+        description="It shall be possible to define items which are not cached.",
+        reason="If there is dynamic changed data in the source instance, it shall be possible to define these items as non cached to get them always from the source instance.",
+        fitcriterion="Create a cached instance and cache some items. Generate a second cached instance with different source data and set at least one item as source item. This item should be previously cached. Ensure, that the source item isis the one from the second source instance.",
+    )
+    #
+    # Section
+    #
+    sec_uuid = req_spec.add(
+        itemtype="SEC",
+        id=5,
+        heading="Callback on data storage",
+    )
+
+    # Requirement
+    req_spec.add(
+        parent=sec_uuid,
+        itemtype="REQ",
+        id=11,
+        heading="If no data is changed, no callback will be executed",
+        description="The store callback shall not be executed, if no cache is stored.",
+        reason="Do actions, if cache data is stored to disk.",
+        fitcriterion="Initialise the cache instance without storing cache data. Ensure, that the callback is never executed.",
+    )
+
+    # Requirement
+    req_spec.add(
+        parent=sec_uuid,
+        itemtype="REQ",
+        id=12,
+        heading="Callback execution in case of a full update",
+        description="The storage callback shall be called once on every {\\tt full\\_update()}.",
+        reason="Do actions, if cache data is stored to disk.",
+        fitcriterion="Initialise the cache instance and ensure, that the callback is executed as often as the {\\tt .full\\_update()} method is executed.",
+    )
+
+    # Requirement
+    req_spec.add(
+        parent=sec_uuid,
+        itemtype="REQ",
+        id=13,
+        heading="Callback execution in case of get function",
+        description="The storage callback, shall be called once on every {\\tt .get()}, if {\\tt storage\\_on\\_get} is set to {\\tt True}.",
+        reason="Do actions, if cache data is stored to disk.",
+        fitcriterion="Initialise the cache instance and ensure, that the callback is executed as often as the {\\tt .get()} method is executed.",
+    )