PyELSSA 0.1.0__py3-none-any.whl

PyELSSA/master.py

@@ -0,0 +1,87 @@
+#
+# -*- coding: utf-8  -*-
+#=================================================================
+# Created by: Jieming Ye
+# Created on: Aug 2026
+# Last Modified: Aug 2026
+#=================================================================
+# Copyright (c) 2026 [Jieming Ye]
+#
+# This Python source code is licensed under the 
+# Open Source Non-Commercial License (OSNCL) v1.0
+# See LICENSE for details.
+#=================================================================
+"""
+Pre-requisite: 
+N/A
+Used Input:
+N/A
+Expected Output:
+Start GUI
+Description:
+This module is the package entry.
+This module is the only module to be called from User End script directly.
+It ensures GUI is only created in the main process while allowing subprocesses
+to be spawned for other tasks.
+"""
+#=================================================================
+# VERSION CONTROL
+# V1.0 - 2026.08.20 - Jieming Ye - Initial Version
+#=================================================================
+
+import multiprocessing
+import sys
+
+def is_main_process():
+    """Check if current process is the main process."""
+    return multiprocessing.current_process().name == 'MainProcess'
+
+def initialize_gui():
+    """Initialize the GUI if license check passes."""
+    try:
+        # STAGE 1: license check
+        from PyELSSA import licensing
+        if not licensing.main():
+            input("Press any key to exit.....")
+            return False
+
+        # STAGE 2: Release message
+        from PyELSSA import release_update
+        if not release_update.main():
+            input("Press any key to exit.....")
+            return False    
+
+        # STAGE 3: configuration check
+        from PyELSSA import configuration
+        if not configuration.main():
+            input("Press any key to exit.....")
+            return False
+        
+        # STAGE 4: Launch the GUI
+        from PyELSSA.gui import gui_start
+        app = gui_start.SampleApp()
+        app.mainloop()
+        return True
+    
+    except Exception as e:
+        print(f"FATAL ERROR: {e}")
+        input("Press any key to exit.....")
+        return False
+
+def main():
+    """Main entry point for the application."""
+    if not is_main_process():
+        # If this is a subprocess, just return without creating GUI
+        # have this under this main as this master is usually called from another entering script
+        return
+    
+    # Set up multiprocessing to work with frozen executables if needed
+    if getattr(sys, 'frozen', False):
+        multiprocessing.freeze_support()
+        
+    print('Loading Application...')
+    # Initialize GUI in main process only
+    initialize_gui()
+
+if __name__ == '__main__':
+    main()

PyELSSA/release_update.py

@@ -0,0 +1,59 @@
+#=================================================================
+# Created by: Jieming Ye
+# Created on: June 2026
+# Last Modified: June 2026
+#=================================================================
+# Copyright (c) 2026 [Jieming Ye]
+#
+# This Python source code is licensed under the 
+# Open Source Non-Commercial License (OSNCL) v1.0
+# See LICENSE for details.
+#=================================================================
+"""
+only run first time after user update the software
+
+# migrate_old_settings()
+# rebuild_cache()
+# show_release_notes()
+
+"""
+#=================================================================
+# VERSION CONTROL
+# V1.0 (Jieming Ye) - Initial Version
+#=================================================================
+# Set Information Variable
+# N/A
+#=================================================================
+
+import os
+import json
+from datetime import date
+
+from PyELSSA.shared_contents import SharedVariables, SharedMethods
+from PyELSSA import configuration
+
+def main():
+    # REQUIRE CHANGE FOR EACH VERSION
+    expiry_date = date(2026,8,21)
+
+    if date.today() <= expiry_date or configuration.version_updated():
+        SharedMethods.print_message(f"#############################################################\n","33")
+        SharedMethods.print_message(f"Welcome to the new version of ELSSA on Python tool\n","32")
+
+        # SharedMethods.print_message(f"New features in this version {SharedVariables.installed_version} include:", "32")
+        # SharedMethods.print_message(f"* XXXXXXXXXXXXXXX.", "32")
+
+        # SharedMethods.print_message("Fixed bugs and others include:", "32")
+        # SharedMethods.print_message("* Fixed an issue of ....... ", "32")
+
+        # SharedMethods.print_message(f"This version fixed multiple bugs reported by the user...", "32")
+        SharedMethods.print_message(f"\n#############################################################","33")
+
+    if configuration.version_updated():
+        # specific requirement for version update only
+        return True
+
+    return True
+
+if __name__ == "__main__":
+    main()

PyELSSA/shared_contents.py

@@ -0,0 +1,491 @@
+#
+# -*- coding: utf-8  -*-
+#=================================================================
+# Created by: Jieming Ye
+# Created on: Aug 2026
+# Last Modified: Aug 2026
+#=================================================================
+# Copyright (c) 2026 [Jieming Ye]
+#
+# This Python source code is licensed under the 
+# Open Source Non-Commercial License (OSNCL) v1.0
+# See LICENSE for details.
+#=================================================================
+"""
+DataFilenames:
+- Database filename lists
+
+Common Variable:
+- Global variable to be used among all scripts
+
+Common Methods:
+- Global methods to be used among all scripts
+
+Internet Validation:
+- For NR Internet configuration checking only
+
+Tee:
+- Consolo control
+
+"""
+#=================================================================
+# VERSION CONTROL
+# V1.0 (Jieming Ye) - Initial Version
+#
+#
+#=================================================================
+# Set Information Variable
+# N/A
+#=================================================================
+
+
+#import tkinter as tk
+import os
+import shutil
+import importlib
+import importlib.resources
+import importlib.metadata
+import csv
+import subprocess
+import sys
+import tempfile
+import requests
+import platform
+from datetime import datetime
+from contextlib import contextmanager
+
+from collections import Counter
+
+class SharedVariables:
+    '''
+    This class will hold all shared varibles
+    '''
+    # this class will store all shared varibles
+    sim_variable = None # get when be called
+    elssa_version = 1 # default update at gui.gui_start.py
+    used_database_path = 2 # default update at gui.gui_start.py (would be string either database_path_user or databse_path_default)
+    
+    # varible to be updated following version upgrade:
+    # Replace 'your_package_name' with the actual name of your package
+    package_name = 'PyELSSA'
+    support_name = 'support'
+    private_data_name = 'data'
+    package_path = importlib.resources.files(package_name)
+    elssa_core_path = os.path.join(package_path,"core")
+    try:
+        installed_version = importlib.metadata.version(package_name)
+    except:
+        installed_version = '0.0.0'
+    public_data_path = "https://github.com/NR-ESTractionPower/public_database"
+    raw_data_url_begin = "https://raw.githubusercontent.com/NR-ESTractionPower/public_database/refs/heads/main/"
+    
+    lastupdate = 'Aug / 2026' # date of checking all links below
+    copyright = 'CopyRight @ 2026, All Rights Reserved.'
+    status_note = '(Beta) PyELSSA is under active development. User is expected to see big changes with this package.'
+
+    # bhtpbank_path = 'C:\\Users\\Public\\Documents\\VISION\\Resources\\bhtpbank'
+    database_path_user = 'C:\\Users\\Public\\Documents\\PyELSSA\\user_data' # This is user controlled library
+    database_path_default = 'C:\\Users\\Public\\Documents\\PyELSSA\\default_data' # This is forced default data library
+    configuration_path = 'C:\\Users\\Public\\Documents\\PyELSSA\\user_config' # This is configuration data library
+
+    contacts = "Email: 'traction.power@networkrail.co.uk'"
+    license_online = "https://raw.githubusercontent.com/NR-ESTractionPower/vo_addin/refs/heads/main/vision_oslo_extension_license.txt"
+    # support_online = "https://github.com/NR-ESTractionPower/vo_addin"
+    issue_online = "https://github.com/NR-ESTractionPower/ELSSA_python/issues"
+
+    license_file = os.path.join(configuration_path, "license.json")
+    config_file = os.path.join(configuration_path, "config.json")
+    current_path = None # get current path
+    admin_password = "passwordS3F3" # this is the Mac password
+
+class DataFilenames:
+    '''
+    This class holds the database file name as in two lists.
+    These two list will be checked at the very beginning of application lauching
+    Any new dataset added in the future needs to be added to this comprehensive data list.
+    public_file list are files hold on the GitHub public repository
+    private_file list are files hold locally in data folder
+
+    This class also contains the default configuration settings
+    '''
+    public_file = {
+        'tiploc_library': 'TestFile.txt'
+    }
+
+    private_file = {
+        'private_file1': 'TestFile1.csv',
+        'private_file2': 'TestFile2.csv'
+    }
+
+    default_config = {
+        'package_version_number': SharedVariables.installed_version,
+        'default_database_updated': False,
+        'elssa_core_updated': False,
+        'elssa_version': 1, # default to 1
+        'database_location': 2 # default to user location
+    }
+
+    # Define a dictionary mapping import_option to module names
+    module_mapping = {
+        "cif_prepare.py": "cif_prepare",
+        "cif_duplicates.py": "cif_duplicates",
+        "model_check.py": "model_check",
+        "oslo_extraction.py": "oslo_extraction",
+    }
+
+class SharedMethods:
+    '''
+    This class will hold all shared methods
+    '''
+    # check if the script running in debug mode or not
+    @staticmethod
+    def is_debug_mode():
+        # Checks if the debugger is attached by inspecting system flags
+        return (sys.gettrace() is not None or "debugpy" in sys.modules)
+    
+    # context manager to change working directory and revert back
+    @contextmanager
+    def pushd(path):
+        prev = os.getcwd()
+        os.chdir(path)
+        try:
+            yield
+        finally:
+            os.chdir(prev)
+
+    # copy files from source folder to active entry
+    @staticmethod
+    def copy_example_files(filename):
+        distribution = importlib.resources.files(SharedVariables.package_name)
+        # Get the path to the package
+        #package_path = distribution.location + "\\" + SharedVariables.package_name
+        package_path = os.path.join(str(distribution), SharedVariables.support_name)
+
+        # Get the absolute path of the file in the package location
+        file_in_package = os.path.join(package_path, filename)
+        current_path = os.getcwd() # get current path
+
+        check_file = os.path.join(current_path, filename)
+
+        if os.path.exists(check_file):
+            print(f"File '{filename}' already exists in the current working directory. Skipping copy...")
+        else:
+            # Copy the file to the current working directory
+            shutil.copy(file_in_package,current_path)
+            print(f"File '{filename}' copied to the current working directory. Config as required...")
+
+    # check data library files, return full path if found
+    @staticmethod
+    def check_data_files(filename):
+        # Get the absolute path of the file in the package location
+        if not SharedVariables.used_database_path:
+            SharedVariables.used_database_path = SharedVariables.database_path_default
+            SharedMethods.print_message(f"WARNING: Database file path not set. Refer to Default. Contact support to report the issue...","33")
+        file_in_package = os.path.join(SharedVariables.used_database_path, filename)
+
+        if os.path.exists(file_in_package):
+            print(f"Data file '{filename}' exist in the Data library. Reading will be done.")
+            return file_in_package
+        else:
+            SharedMethods.print_message(f"WARNING: Data file '{filename}' does NOT exist in the Data library. Reading will be skipped.","33")
+            SharedMethods.print_message(f"ATTENTION: You can add data file '{filename}' to {SharedVariables.used_database_path} and report it to support.","33")
+            return False
+
+    # check if a file is in use or not
+    @staticmethod
+    def can_write_file(filename):
+        """Return True if the file can be opened for writing; False if Excel has it open."""
+        filepath = os.path.join(os.getcwd(), filename)
+        if not os.path.exists(filepath):
+            # File doesn't exist → safe to write
+            return True
+        try:
+            # Try opening in append+binary mode (does not read file)
+            with open(filepath, "r+b"):
+                pass
+            SharedMethods.print_message(f"WARNING: File {filename} could be overwritten at a later stage...", "33")
+            return True
+        except (OSError, PermissionError):
+            # File is locked by Excel or another process
+            return False
+
+    #check existing file
+    @staticmethod
+    def check_existing_file(filename,printing = True):
+        """
+        Check if a specific file exists.
+        Returns True if the file exists, False otherwise.
+        if printing is True, it will print message information.
+        """
+        print(f"Checking File {filename}...")
+
+        first = filename.split('.')[0]
+        if first == "":
+            SharedMethods.print_message("ERROR: Select the simulation or required file to continue...","31")
+            return False
+
+        current_path = os.getcwd() # get current path
+        file_path = os.path.join(current_path,filename) # join the file path
+        if not os.path.isfile(file_path): # if the oof file does not exist
+            if printing:
+                SharedMethods.print_message(f"ERROR: Required file {filename} does not exist. Checking required...","31")
+            return False
+        return True
+
+    # check the folder and file for summary
+    @staticmethod
+    def folder_file_check(subfolder,filename=None,required=True):
+        """
+        Check if a specific file exists in a given subfolder.
+        Returns True if the file exists, False otherwise.
+        if required is True, it will print an error message and exit if the file does not exist.
+        """
+        print(f"Checking File {filename} in {subfolder}...")
+        current_path = os.getcwd() # get current path
+
+        # Create the complete folder path
+        folder_path = os.path.join(current_path, subfolder)
+        
+        # Check if the folder exists
+        if not os.path.exists(folder_path):
+            if required:
+                SharedMethods.print_message(f"ERROR: Required folder {subfolder} does not exist. Check your Input. Exiting...","31")
+            return False
+        
+        if filename != None: #if filename is not None, check the file existance in the folder
+            # file path
+            file_path = os.path.join(folder_path,filename) # join the file path
+            # print(file_path)
+            if not os.path.isfile(file_path):
+                if required:
+                    SharedMethods.print_message(f"ERROR: Required file {filename} does not exist at {subfolder}. Check your Input. Exiting...","31")
+                return False
+            
+        return True
+
+    # copy the file to a subfolder / if not exist, create the subfolder
+    @staticmethod
+    def copy_file_to_subfolder(subfolder, filename, new_filename=None):
+        print(f"Copying File {filename} to {subfolder}...")
+        current_path = os.getcwd()  # Get current path
+        folder_path = os.path.join(current_path, subfolder)
+
+        # Create the folder if it doesn't exist
+        if not os.path.exists(folder_path):
+            try:
+                os.makedirs(folder_path)
+                print(f"Folder '{subfolder}' created.")
+            except Exception as e:
+                SharedMethods.print_message(f"ERROR: Error creating folder {subfolder}: {e}. Check your Input...", "31")
+                return False
+
+        # Determine the target file name
+        target_filename = new_filename if new_filename else filename
+        file_path = os.path.join(folder_path, target_filename)
+
+        # Warn if the target file already exists
+        if os.path.isfile(file_path):
+            SharedMethods.print_message(f"WARNING: File {target_filename} already exists in {subfolder}. Overwriting...", "33")
+            os.remove(file_path)
+
+        # Copy the file
+        try:
+            shutil.copy(filename, file_path)
+            print(f"File '{filename}' copied to subfolder successfully'.")
+        except Exception as e:
+            SharedMethods.print_message(f"ERROR: Error copying file {filename} to {file_path}: {e}. Check your Input...", "31")
+            return False
+
+        return True
+
+    # open a file in support folder
+    @staticmethod
+    def open_support_file(filename):
+        distribution = importlib.resources.files(SharedVariables.package_name)
+        package_path = os.path.join(str(distribution), SharedVariables.support_name)
+        # Get the absolute path of the file in the package location
+        file_in_package = os.path.join(package_path, filename)
+
+        # create a temp directory and copy the file there
+        temp_dir = tempfile.gettempdir()
+        temp_file = os.path.join(temp_dir, filename)
+
+        try:
+            shutil.copy(file_in_package, temp_file) # copy the file to temp directory
+            subprocess.Popen(['start', '', temp_file], shell=True,close_fds=True)
+        except Exception as e:
+            SharedMethods.print_message(f"ERROR: Error opening file with default app: {e}","31")
+
+        return
+
+    # add unique key to a ditionary type
+    @staticmethod
+    def add_unique_key(dictionary, key, value):
+        original_key = key
+        counter = 1
+        while key in dictionary:
+            key = f"{original_key}_{counter}"
+            counter += 1
+            SharedMethods.print_message(f"WARNING: Name {original_key} already exists. Trying to rename to {key}...","33")
+        dictionary[key] = value
+        return dictionary
+
+    # delete all simulation result:
+    def clean_up_simulation_folder():
+        '''
+        This function deletes all files in the current working directory except those with specific suffixes.
+        '''
+        reserved_file_suffix = ['.vvw','.ocl','.vcn','extra.oslo','extra.bat.oslo','pdv.csv','.xlsx','xlsm']
+        # delete all files in current working directory if file name not ending as in the list
+        current_path = os.getcwd() # get current path
+        for filename in os.listdir(current_path):
+            if not any(filename.endswith(suffix) for suffix in reserved_file_suffix):
+                file_path = os.path.join(current_path, filename)
+                try:
+                    if os.path.isfile(file_path) or os.path.islink(file_path):
+                        os.remove(file_path)  # remove the file or link
+                    elif os.path.isdir(file_path):
+                        shutil.rmtree(file_path)  # remove the directory and its contents
+                    print(f"INFO: File '{filename}' been deleted.")
+                except Exception as e:
+                    SharedMethods.print_message(f"ERROR: Failed to delete {file_path}. Reason: {e}", "31")
+        print("INFO: Simulation Folder Clean Up Completed.")
+
+    # define the running in thread mechanism    
+    def launch_new_thread_or_process(import_option,
+                                     text_input1, text_input2, option_input1, option_input2, time_input1, time_input2, add_text, add_input1, add_input2,config_input,
+                                     cwd=None):
+        '''
+        This function launches a new thread or process to run the specified module's main function.
+        '''
+
+        if cwd:
+            # Change the current working directory to the specified path
+            # this is compolsory for new process
+            os.chdir(cwd)
+
+        # Get the module name corresponding to import_option
+        module_name = DataFilenames.module_mapping.get(import_option)
+
+        # Import the module
+        if module_name:
+            fc = importlib.import_module(f"{SharedVariables.package_name}.{module_name}")
+            #from vision_oslo_extension import module_name as fc
+        else:
+            # Handle the case when import_option doesn't match any module
+            SharedMethods.print_message(f"ERROR: Invalid import_option: {import_option}", "31")
+        
+        try:
+            print(f"\nLauching module in new thread (same console): {module_name}\n")
+            continue_process = fc.main(text_input1,text_input2,option_input1,option_input2,time_input1,time_input2,add_text,add_input1,add_input2,config_input)
+            if not continue_process:
+                # Do something if the process should not continue
+                # Print error message in red
+                SharedMethods.print_message("ERROR: Process terminated due to captured issue. "
+                                            "Please check the error history above or contact support. "
+                                            "You can continue using other options...", "31")
+                return False
+
+            else:
+                # Do something if the process should continue
+                # Print success message in green
+                SharedMethods.print_message("Action successfully completed. "
+                                            "Check monitor history above and result files in your folder.", "32")
+        
+        except Exception as e:
+            SharedMethods.print_message(f"ERROR: UNEXPECTED! PLEASE REPORT BUG AND CONTACT SUPPORT... ", "31")
+            SharedMethods.print_message(f"ERROR: source code module - {import_option}: {e}","31")
+            return False
+        
+        return True
+    
+    def print_message(message: str, color_code: str):
+        '''
+        print out message in color in front end
+        color_code following ANSI color code
+        '''
+        color_start = f'\033[1;{color_code}m'   # Start color
+        color_reset = '\033[1;0m'               # Reset color
+        print(color_start + message + color_reset)
+
+class InternetValidation:
+    '''
+    This class contains methods to validate internet connection and check for restricted networks.
+    '''
+    def internet_check(url):
+        '''Check if a handshake with internet can be established or not. To decide if an upgrade is possible or not'''
+
+        # check connected network to see if it is NR network or not
+        if InternetValidation.check_restricted_network():
+            SharedMethods.print_message(f"WARNING: Abort internet connection due to Network Rail private network detected.","33")
+            return False
+
+        try:
+            # Send a HEAD request using requests with a timeout of 5 seconds
+            response = requests.get(url, timeout=5)
+            return True
+
+        except requests.exceptions.Timeout:
+            SharedMethods.print_message("ERROR: Request timed out after 5 seconds. POOR INTERNET...", "31")
+            return False
+        
+        except Exception as e:
+            SharedMethods.print_message(f"ERROR: Unexpected connection: {e}. Please contact the support...","31")
+            return False
+
+    def check_restricted_network():
+        '''Return TRUE if connected to the NR Office Environment'''
+        system = platform.system()
+        try:
+            if system == "Windows":
+                # WIFI Network Check
+                result = subprocess.run(["netsh", "wlan", "show", "interfaces"],
+                                        capture_output=True, text=True, check=True)
+                for line in result.stdout.splitlines():
+                    if "SSID" in line and "BSSID" not in line:
+                        ssid = line.split(":", 1)[1].strip()
+                        if ssid == "14":
+                            # print("NR CORP WIFI 14 DETECTED.")
+                            return True
+                        else:
+                            break
+                # Ehternet Network Check
+                block = False
+                result = subprocess.run(["ipconfig", "/all"],
+                                        capture_output=True, text=True, check=True)
+                for line in result.stdout.splitlines():
+                    if "adapter" in line.lower() and "Ethernet" in line:
+                        block = True
+                    if block:
+                        # skip the check if the ethernet cable is not used
+                        if "media disconnected" in line.lower():
+                            # this means WIFI not 14 and Ethernet cable is not connected
+                            return False
+                        type = line.split(":", 1)[0].strip().lower()
+                        if "default gateway" in type:
+                            gatewayip = line.split(":", 1)[1].strip()
+                            if gatewayip.startswith("10.176."): # This IP is only used for small private network
+                                # print("NR CORP ETHERNET CONNECTION DETECTED.")
+                                return True
+                            else:
+                                return False
+            else: # not ready for other operating system yet
+                return False
+        except Exception as e:
+            SharedMethods.print_message(f"ERROR: Unexpected error: {e}. Please contact the support...","31")
+            return False
+        return False
+    
+class Tee:
+    """Write to multiple streams (console + file)."""
+    def __init__(self, *streams):
+        self.streams = streams
+
+    def write(self, data):
+        for stream in self.streams:
+            stream.write(data)
+            stream.flush()
+
+    def flush(self):
+        for stream in self.streams:
+            stream.flush()