Merge pull request #5 from itk-dev-rpa/release-v1

Release v1

Author: ghbm-itk

.github/workflows/pylint.yml

@@ -1,4 +1,4 @@
-name: Pylint
+name: Linting
 
 on: [push]
 
@@ -14,10 +14,18 @@ jobs:
       uses: actions/setup-python@v3
       with:
         python-version: ${{ matrix.python-version }}
+
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
         pip install pylint
+        pip install flake8
+        pip install .
+
     - name: Analysing the code with pylint
       run: |
         pylint --rcfile=.pylintrc $(git ls-files '*.py')
+
+    - name: Analysing the code with flake8
+      run: |
+        flake8 --extend-ignore=E501,E251 $(git ls-files '*.py')

README.md

@@ -6,7 +6,7 @@ This repo is meant to be used as a template for robots made for [OpenOrchestrato
 
 1. To use the template simply use the repo as a template as shown [here](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-repository-from-a-template).
 
-2. Fill out the requirements.txt file with all packages needed by the robot.
+2. Fill out the dependencies in the pyproject.toml file with all packages needed by the robot.
 
 3. Implement all functions in the files:
 * src/initialize.py
@@ -15,12 +15,12 @@ This repo is meant to be used as a template for robots made for [OpenOrchestrato
 * src/process.py
 * Feel free to add more files as needed.
 
-4. Make sure the smtp setup in error_screenshot.py is set up to your needs.
+4. Change config.py to your needs.
 
-When the robot is run from OpenOrchestrator the main.bat file is run.
-main.bat does a few things:
+When the robot is run from OpenOrchestrator the main.py file is run.
+main.py does a few things:
 1. A virtual environment is automatically setup with the required packages.
-2. The framework is called passing on all arguments needed by [OpenOrchestratorConnection](https://github.com/itk-dev-rpa/OpenOrchestratorConnection).
+2. The framework is called passing on all arguments needed by [OpenOrchestrator](https://github.com/itk-dev-rpa/OpenOrchestrator).
 
 ## Requirements
 Minimum python version 3.10

Robot-Framework.drawio

@@ -0,0 +1,17 @@
+"""The main file of the robot which will install all requirements in
+a virtual environment and then start the actual process.
+"""
+
+import subprocess
+import os
+import sys
+
+script_directory = os.path.dirname(os.path.realpath(__file__))
+os.chdir(script_directory)
+
+subprocess.run("python -m venv .venv", check=True)
+subprocess.run(r'.venv\Scripts\pip install .', check=True)
+
+command_args = [r".venv\Scripts\python", "-m", "robot_framework"] + sys.argv[1:]
+
+subprocess.run(command_args, check=True)

main.bat

@@ -0,0 +1,21 @@
+[build-system]
+requires = ["setuptools>=65.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "robot_framework"
+version = "0.0.1"
+authors = [
+  { name="ITK Development", email="[email protected]" },
+]
+readme = "README.md"
+requires-python = ">=3.11"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: Microsoft :: Windows",
+]
+dependencies = [
+    "OpenOrchestrator == 1.*",
+    "Pillow == 9.5.0",
+]

main.py

@@ -0,0 +1,4 @@
+"""The entry point of the process."""
+
+from robot_framework.framework import main
+main()

pyproject.toml

@@ -0,0 +1,9 @@
+"""This module contains configuration constants used across the framework"""
+
+# The number of times the robot retries on an error before terminating.
+MAX_RETRY_COUNT = 3
+
+# Error screenshot config
+SMTP_SERVER = "smtp.aarhuskommune.local"
+SMTP_PORT = 25
+SCREENSHOT_SENDER = "[email protected]"

requirements.txt

@@ -0,0 +1,53 @@
+"""This module has functionality to send error screenshots via smtp."""
+
+import smtplib
+from email.message import EmailMessage
+import base64
+import traceback
+from io import BytesIO
+
+from PIL import ImageGrab
+
+from robot_framework import config
+
+
+def send_error_screenshot(to_address: str | list[str], exception: Exception, process_name: str):
+    """Sends an email with an error report, including a screenshot, when an exception occurs.
+    Configuration details such as SMTP server, port, sender email, etc., should be set in 'config' module.
+
+    Args:
+        to_address: Email address or list of addresses to send the error report.
+        exception: The exception that triggered the error.
+        process_name: Name of the process from OpenOrchestrator.
+    """
+    # Create message
+    msg = EmailMessage()
+    msg['to'] = to_address
+    msg['from'] = config.SCREENSHOT_SENDER
+    msg['subject'] = f"Error screenshot: {process_name}"
+
+    # Take screenshot and convert to base64
+    screenshot = ImageGrab.grab()
+    buffer = BytesIO()
+    screenshot.save(buffer, format='PNG')
+    screenshot_base64 = base64.b64encode(buffer.getvalue()).decode('utf-8')
+
+    # Create an HTML message with the exception and screenshot
+    html_message = f"""
+    <html>
+        <body>
+            <p>Error type: {type(exception).__name__}</p>
+            <p>Error message: {exception}</p>
+            <p>{traceback.format_exc()}</p>
+            <img src="data:image/png;base64,{screenshot_base64}" alt="Screenshot">
+        </body>
+    </html>
+    """
+
+    msg.set_content("Please enable HTML to view this message.")
+    msg.add_alternative(html_message, subtype='html')
+
+    # Send message
+    with smtplib.SMTP(config.SMTP_SERVER, config.SMTP_PORT) as smtp:
+        smtp.starttls()
+        smtp.send_message(msg)

robot_framework/__init__.py

@@ -0,0 +1,66 @@
+"""This module is the primary module of the robot framework. It collects the functionality of the rest of the framework."""
+
+import traceback
+import sys
+
+from OpenOrchestrator.orchestrator_connection.connection import OrchestratorConnection
+
+from robot_framework import initialize
+from robot_framework import get_constants
+from robot_framework import reset
+from robot_framework import error_screenshot
+from robot_framework import process
+from robot_framework import config
+
+
+def main():
+    """The entry point for the framework. Should be called as the first thing when running the robot."""
+    orchestrator_connection = OrchestratorConnection.create_connection_from_args()
+    sys.excepthook = log_exception(orchestrator_connection)
+
+    orchestrator_connection.log_trace("Robot Framework started.")
+    initialize.initialize(orchestrator_connection)
+    constants = get_constants.get_constants(orchestrator_connection)
+
+    error_count = 0
+    for _ in range(config.MAX_RETRY_COUNT):
+        try:
+            reset.reset(orchestrator_connection)
+            process.process(orchestrator_connection)
+            break
+
+        # If any business rules are broken the robot should stop entirely.
+        except BusinessError as error:
+            orchestrator_connection.log_error(f"BusinessError: {error}\nTrace: {traceback.format_exc()}")
+            error_screenshot.send_error_screenshot(constants.error_email, error, orchestrator_connection.process_name)
+            break
+
+        # We actually want to catch all exceptions possible here.
+        # pylint: disable-next = broad-exception-caught
+        except Exception as error:
+            error_count += 1
+            error_type = type(error).__name__
+            orchestrator_connection.log_error(f"Error caught during process. Total number of errors caught: {error_count}. {error_type}: {error}\nTrace: {traceback.format_exc()}")
+            error_screenshot.send_error_screenshot(constants.error_email, error, orchestrator_connection.process_name)
+
+    reset.clean_up(orchestrator_connection)
+    reset.close_all(orchestrator_connection)
+    reset.kill_all(orchestrator_connection)
+
+
+def log_exception(orchestrator_connection: OrchestratorConnection) -> callable:
+    """Creates a function to be used as an exception hook that logs any uncaught exception in OpenOrchestrator.
+
+    Args:
+        orchestrator_connection: The connection to OpenOrchestrator.
+
+    Returns:
+        callable: A function that can be assigned to sys.excepthook.
+    """
+    def inner(exception_type, value, traceback_string):
+        orchestrator_connection.log_error(f"Uncaught Exception:\nType: {exception_type}\nValue: {value}\nTrace: {traceback_string}")
+    return inner
+
+
+class BusinessError(Exception):
+    """An empty exception used to identify errors caused by breaking business rules"""

robot_framework/__main__.py

@@ -0,0 +1,22 @@
+"""This module defines how the robot should receive and store constants/credentials from OpenOrchestrator."""
+
+from dataclasses import dataclass
+
+from OpenOrchestrator.orchestrator_connection.connection import OrchestratorConnection
+
+
+@dataclass(kw_only=True)
+class Constants:
+    """An object for holding any robot specific constants. Expand as needed"""
+    error_email: str
+
+
+def get_constants(orchestrator_connection: OrchestratorConnection) -> Constants:
+    """Get all constants used by the robot."""
+    orchestrator_connection.log_trace("Getting constants.")
+
+    constants = Constants(
+        error_email = orchestrator_connection.get_constant("Error Email").value
+    )
+
+    return constants

robot_framework/config.py

@@ -0,0 +1,8 @@
+"""This module defines any initial processes to run when the robot starts."""
+
+from OpenOrchestrator.orchestrator_connection.connection import OrchestratorConnection
+
+
+def initialize(orchestrator_connection: OrchestratorConnection) -> None:
+    """Do all custom startup initializations of the robot."""
+    orchestrator_connection.log_trace("Initializing.")

robot_framework/error_screenshot.py

@@ -0,0 +1,8 @@
+"""This module contains the main process of the robot."""
+
+from OpenOrchestrator.orchestrator_connection.connection import OrchestratorConnection
+
+
+def process(orchestrator_connection: OrchestratorConnection) -> None:
+    """Do the primary process of the robot."""
+    orchestrator_connection.log_trace("Running process.")

robot_framework/framework.py

@@ -0,0 +1,32 @@
+"""This module handles resetting the state of the computer so the robot can work with a clean slate."""
+
+from OpenOrchestrator.orchestrator_connection.connection import OrchestratorConnection
+
+
+def reset(orchestrator_connection: OrchestratorConnection) -> None:
+    """Clean up, close/kill all programs and start them again. """
+    orchestrator_connection.log_trace("Resetting.")
+    clean_up(orchestrator_connection)
+    close_all(orchestrator_connection)
+    kill_all(orchestrator_connection)
+    open_all(orchestrator_connection)
+
+
+def clean_up(orchestrator_connection: OrchestratorConnection) -> None:
+    """Do any cleanup needed to leave a blank slate."""
+    orchestrator_connection.log_trace("Doing cleanup.")
+
+
+def close_all(orchestrator_connection: OrchestratorConnection) -> None:
+    """Gracefully close all applications used by the robot."""
+    orchestrator_connection.log_trace("Closing all applications.")
+
+
+def kill_all(orchestrator_connection: OrchestratorConnection) -> None:
+    """Forcefully close all applications used by the robot."""
+    orchestrator_connection.log_trace("Killing all applications.")
+
+
+def open_all(orchestrator_connection: OrchestratorConnection) -> None:
+    """Open all programs used by the robot."""
+    orchestrator_connection.log_trace("Opening all applications.")