From dd825dba3aed3bef855e9cea6d47f5e438c94081 Mon Sep 17 00:00:00 2001
From: lukas leufen <l.leufen@fz-juelich.de>
Date: Tue, 28 Apr 2020 16:20:05 +0200
Subject: [PATCH] docstrings for run environment
---
src/run_modules/run_environment.py | 86 +++++++++++++++++++++++++++---
src/run_modules/training.py | 2 +-
2 files changed, 80 insertions(+), 8 deletions(-)
diff --git a/src/run_modules/run_environment.py b/src/run_modules/run_environment.py
index ab42efaa..b47c76d0 100644
--- a/src/run_modules/run_environment.py
+++ b/src/run_modules/run_environment.py
@@ -1,3 +1,5 @@
+"""Implementation of run environment."""
+
__author__ = "Lukas Leufen"
__date__ = '2019-11-25'
@@ -14,38 +16,107 @@ from src.helpers import TimeTracking
class RunEnvironment(object):
"""
- basic run class to measure execution time. Either call this class calling it by 'with' or delete the class instance
- after finishing the measurement. The duration result is logged.
+ Basic run class to measure execution time.
+
+ Either call this class by 'with' statement or delete the class instance after finishing the measurement. The
+ duration result is logged.
+
+ .. code-block:: python
+
+ >>> with RunEnvironment():
+ <your code>
+ INFO: RunEnvironment started
+ ...
+ INFO: RunEnvironment finished after 00:00:04 (hh:mm:ss)
+
+ If you want to embed your custom module in a RunEnvironment, you can easily call it inside the with statement. If
+ you want to exchange between different modules in addition, create your module as inheritance of the RunEnvironment
+ and call it after you initialised the RunEnvironment itself.
+
+ .. code-block:: python
+
+ class CustomClass(RunEnvironment):
+
+ def __init__(self):
+ super().__init__()
+ ...
+ ...
+
+
+ >>> with RunEnvironment():
+ CustomClass()
+ INFO: RunEnvironment started
+ INFO: CustomClass started
+ INFO: CustomClass finished after 00:00:04 (hh:mm:ss)
+ INFO: RunEnvironment finished after 00:00:04 (hh:mm:ss)
+
+ All data that is stored in the data store will be available for all other modules that inherit from RunEnvironment
+ as long the RunEnvironemnt base class is running. If the base class is deleted either by hand or on exit of the with
+ statement, this storage is cleared.
+
+ .. code-block:: python
+
+ class CustomClassA(RunEnvironment):
+
+ def __init__(self):
+ super().__init__()
+ self.data_store.set("testVar", 12)
+
+
+ class CustomClassB(RunEnvironment):
+
+ def __init__(self):
+ super().__init__()
+ self.test_var = self.data_store.get("testVar")
+ logging.info(f"testVar = {self.test_var}")
+
+
+ >>> with RunEnvironment():
+ CustomClassA()
+ CustomClassB()
+ INFO: RunEnvironment started
+ INFO: CustomClassA started
+ INFO: CustomClassA finished after 00:00:01 (hh:mm:ss)
+ INFO: CustomClassB started
+ INFO: testVar = 12
+ INFO: CustomClassB finished after 00:00:02 (hh:mm:ss)
+ INFO: RunEnvironment finished after 00:00:03 (hh:mm:ss)
+
"""
+ # set data store and logger (both are mutable!)
del_by_exit = False
data_store = DataStoreObject()
logger = Logger()
def __init__(self):
- """
- Starts time tracking automatically and logs as info.
- """
+ """Start time tracking automatically and logs as info."""
self.time = TimeTracking()
logging.info(f"{self.__class__.__name__} started")
def __del__(self):
"""
- This is the class finalizer. The code is not executed if already called by exit method to prevent duplicated
- logging (__exit__ is always executed before __del__) it this class was used in a with statement.
+ Finalise class.
+
+ Only stop time tracking, if not already called by exit method to prevent duplicated logging (__exit__ is always
+ executed before __del__) it this class was used in a with statement. If instance is called as base class and
+ not as inheritance from this class, log file is copied and data store is cleared.
"""
if not self.del_by_exit:
self.time.stop()
logging.info(f"{self.__class__.__name__} finished after {self.time}")
self.del_by_exit = True
+ # copy log file and clear data store only if called as base class and not as super class
if self.__class__.__name__ == "RunEnvironment":
self.__copy_log_file()
self.data_store.clear_data_store()
def __enter__(self):
+ """Enter run environment."""
return self
def __exit__(self, exc_type, exc_val, exc_tb):
+ """Exit run environment."""
if exc_type:
logging.error(exc_val, exc_info=(exc_type, exc_val, exc_tb))
self.__del__()
@@ -65,4 +136,5 @@ class RunEnvironment(object):
@staticmethod
def do_stuff(length=2):
+ """Just a placeholder method for testing without any sense."""
time.sleep(length)
diff --git a/src/run_modules/training.py b/src/run_modules/training.py
index 389e0eb4..d54f0c6d 100644
--- a/src/run_modules/training.py
+++ b/src/run_modules/training.py
@@ -31,7 +31,7 @@ class Training(RunEnvironment):
* `batch_size` [model]
* `epochs` [model]
* `callbacks` [model]
- * `model_name* [model]
+ * `model_name` [model]
* `experiment_name` [.]
* `experiment_path` [.]
* `trainable` [.]
--
GitLab