correcting an import error for 'evaluate_shipcall_state', updating misc/Deployment to describe the creation of a virtual environment, Python installation and running tests (pytest and pytest-coverage).

misc/Deployment.md

@@ -41,3 +41,70 @@ git checkout
 ```
 
 6) Database credentials are stored outside the web root, we are using /var/www/secure. Here the file ```connection_data.json``` is placed, a different named copy for each instance.
+
+
+### Installing Requirements
+Python 3.11 & Pip3.11 installation (linux), virtualenv package
+
+Optional, Step 0: Python source installation
+Windows (untested): 
+	Python 3.11: https://www.geeksforgeeks.org/download-and-install-python-3-latest-version/
+	PIP package manager (in command window): py -m ensurepip --upgrade
+	Virtual Environment 'virtualenv': https://mothergeo-py.readthedocs.io/en/latest/development/how-to/venv-win.html
+
+Linux: 
+	Python 3.11 & the PIP package manager: https://tecadmin.net/how-to-install-python-3-11-on-ubuntu-22-04/
+
+Virtual Environment 'virtualenv' 
+
+### Building the Virtual Environment
+Create a virtualenv called '.venv' with a specified python version, such as python3.11
+All python packages will be installed in the virtual environment. Upon running the application,
+make sure to activate the virtual environment before starting it.
+
+Windows: # on windows, provide the full path, as obtained by "where python"
+1.) Relocate to the 'brecal' directory
+	cd brecal
+	
+2.) create a virtual environment with the name '.venv'
+	where python
+	virtualenv --python {python_path} .venv	
+	
+3.) activate the virtual environment and install
+	.venv\Scripts\activate
+	cd ./src/server
+	pip install -r requirements.txt
+
+
+Linux:
+1.) Relocate to the 'brecal' directory
+	cd brecal
+2.) create a virtual environment with the name '.venv'
+	virtualenv --python python311 .venv	
+3.) activate the virtual environment and install
+	source .venv/bin/activate
+	cd ./src/server
+	pip install -r requirements.txt
+
+
+### Testing (using 'pytest')
+All tests in the directory brecal/src/server/tests can be run automatically with the 'pytest' module It recognizes any function within these
+scripts, as these use 'test_'-prefixes. The module can be used to run the tests or even to create coverage reports, which show, what portions
+of the directory are still untested. When the pytest module is installed, one can use a single line of code to run all tests. 
+
+1.) Relocate to the application's directory
+	cd brecal/src/server
+2.) activate the virtual environment
+Windows:
+	source .venv\Scripts\activate
+Linux:
+	source .venv\bin\activate
+3.) run the tests
+	option1: run pytest as a standalone
+	pytest tests/
+	
+	option2: run pytest & coverage report (inspects coverage for the folder 'BreCal' by running each test in 'tests/'
+	this creates a folder with the name 'coverage_reports', where .html files are created and can be observed by a developer.
+	the coverage files are typically ignored by .gitignore
+	pytest --cov BreCal tests/
+

src/server/BreCal/database/update_database.py

@@ -60,13 +60,13 @@ def update_all_shipcalls_in_mysql_database(sql_connection, sql_handler:SQLHandle
         update_shipcall_in_mysql_database(sql_connection, shipcall=shipcall, relevant_keys = ["evaluation", "evaluation_message"])
     return
 
-def run_validation_rules(mysql_connector_instance, shipcall_id:int=None, debug=False)->pd.DataFrame:
+def evaluate_shipcall_state(mysql_connector_instance, shipcall_id:int=None, debug=False)->pd.DataFrame:
     """
     options: 
         mysql_connector_instance: an instance created by the mysql.connector.connect() call. It is advised to use Python's context manager to close the connection after finished.
         e.g.,
             with mysql.connector.connect(**mysql_connection_data) as mysql_connector_instance:
-                run_validation_rules(mysql_connector_instance)
+                evaluate_shipcall_state(mysql_connector_instance)
     returns None
 
     """
@@ -98,6 +98,5 @@ def update_shipcall_evaluation_state(mysql_connection_data:dict, shipcall_id:int
         shipcall_id: int. ID of the shipcall to be updated. Defaults to 'None'. When providing 'None', all shipcalls are updated.
     """
     with mysql.connector.connect(**mysql_connection_data) as mysql_connector_instance:
-        shipcall_df = run_validation_rules(mysql_connector_instance=mysql_connector_instance, shipcall_id=shipcall_id, debug=False)
+        shipcall_df = evaluate_shipcall_state(mysql_connector_instance=mysql_connector_instance, shipcall_id=shipcall_id, debug=False)
     return shipcall_df
-

src/server/BreCal/local_db.py

@@ -16,6 +16,7 @@ def initPool(instancePath):
 
         if not os.path.exists(config_path):
             print ('cannot find ' + config_path)
+            print("instance path", instancePath)
             exit(1)
 
         f = open(config_path);

src/server/tests/test_create_app.py

@@ -13,7 +13,7 @@ def test_create_app():
     sys.path.append(lib_location)
 
     from BreCal import create_app
-    os.chdir(project_root) # set the current directory to ~/brecal, so the config is found
+    os.chdir(os.path.join(lib_location,"BreCal")) # set the current directory to ~/brecal/src/server/BreCal, so the config is found
     application = create_app()
     return