Python code documented

app/config.py

@@ -2,6 +2,21 @@
 
 
 class Config:
+    """
+    Config class containing the configuration variables for the application.
+
+    Attributes:
+        APP_HOST (str): The host of the application. Default is "0.0.0.0".
+        APP_PORT (int): The port of the application. Default is 5000.
+        DEBUG (bool): The debug mode of the application. Default is True.
+        API_KEY (str): The API key for the Google Maps API. Retrieved from the environment variable "MAPS_API_KEY".
+        GEOCODE_API_URL (str): The URL for the geocode API of Google Maps.
+        DISTANCE_MATRIX_API_URL (str): The URL for the distance matrix API of Google Maps.
+        BABEL_DEFAULT_TIMEZONE (str): The default timezone for babel translations. Default is "en".
+        BABEL_TRANSLATION_DIRECTORIES (str): The translation directories for babel translations. Default is "app/translations".
+        LANGUAGES (dict): The supported languages for translations and their corresponding names.
+    """
+
     APP_HOST = "0.0.0.0"
     APP_PORT = 5000
     DEBUG = True

app/routes/addresses.py

@@ -6,12 +6,18 @@
 addresses_blueprint = Blueprint("addresses_blueprint", __name__)
 
 
-# TODO: Add node
+# TODO: CHECK THIS FUNCTION
 @addresses_blueprint.route("/handle-address", methods=["POST", "GET"])
 def register_address():
     """
     Register an address based on the provided form data. The address can be either a depot or a regular address.
     It converts the all the addresses to coordinates (if necessary).
+
+    Args:
+        None
+
+    Returns:
+        dict: A dictionary containing the success status, a message, the coordinates, and the index of the registered address.
     """
     if request.method == "POST":
         address = request.form["address"]
@@ -53,6 +59,17 @@ def register_address():
 
 
 def update_problem_when_deleted(index):
+    """
+    Updates the problem data when a node is deleted.
+
+    This function removes the given index from the 'start_nodes' and 'end_nodes' lists,
+    and removes the corresponding address from the 'addresses' dictionary in the current_app.problem_data.
+
+    Args:
+        index (int): The index of the node to be deleted.
+
+    Returns:
+        None"""
     if index in current_app.problem_data["start_nodes"]:
         current_app.problem_data["start_nodes"].remove(index)
     if index in current_app.problem_data["end_nodes"]:
@@ -64,7 +81,15 @@ def update_problem_when_deleted(index):
 def delete_address():
     """
     Delete an address based on the provided form data. The address is identified by its index.
-    """
+
+    Args:
+        None
+
+    Returns:
+        dict: A dictionary with the following keys:
+            - success (bool): Indicates whether the address was deleted successfully.
+            - message (str): A success message.
+            - problem_data (obj): The updated problem data."""
     if request.method == "POST":
         index = int(request.form["index"])
         update_problem_when_deleted(index)

app/routes/loaders.py

@@ -11,7 +11,12 @@
 def load_yaml_problem():
     """
     Load problem definition data from a YAML file, convert the addresses to coordinates, and store them in the application context.
-    """
+
+    Args:
+        None
+
+    Returns:
+        None"""
     coord_inds = []
     if request.method == "POST":
         current_app.problem_data = load_problem_definiton()
@@ -49,7 +54,12 @@ def load_yaml_problem():
 def load_yaml_solver():
     """
     Load solver configuration data from a YAML file and store them in the application context.
-    """
+
+    Args:
+        None
+
+    Returns:
+        None"""
     if request.method == "POST":
         file = request.form["file"]
         current_app.solver_data = load_solver_configuration(file)

app/routes/routes.py

@@ -18,6 +18,9 @@ def generate_route():
     """
     Generate a route based on the provided form data and the problem and solver data stored in the application context.
     This includes generating a distance matrix if it doesn't exist, finding routes using OR-Tools, and generating a solution.
+
+    Returns:
+        JSON object: A JSON object containing the success status, a message, the generated routes, and the problem data.
     """
     if request.method == "POST":
         if not current_app.solver_data:

app/routes/save.py

@@ -12,8 +12,10 @@ def save_nodes(file="output/nodes2visit.yaml"):
     Save the list of addresses (nodes) to visit to a YAML file.
 
     Parameters:
-    file (str, optional): The path of the file to save to. Default is "output/nodes2visit.yaml".
-    """
+        file (str, optional): The path of the file to save to. Default is "output/nodes2visit.yaml".
+
+    Returns:
+        type: Description of the return param."""
     if request.method == "POST":
         ensure_folder_exist("/".join(file.split("/")[:-1]))
         data = {"addresses": current_app.problem_data["addresses"]}
@@ -27,8 +29,10 @@ def save_routes(file="output/routes.yaml"):
     Save the generated routes to a YAML file.
 
     Parameters:
-    file (str, optional): The path of the file to save to. Default is "output/routes.yaml".
-    """
+        file (str, optional): The path of the file to save to. Default is "output/routes.yaml".
+
+    Returns:
+        None"""
     if request.method == "POST":
         ensure_folder_exist("/".join(file.split("/")[:-1]))
         data = {"routes": current_app.routes}

app/routes/simulation.py

@@ -11,7 +11,9 @@
 def start_simulation():
     """
     Start a simulation of the vehicle routing problem.
-    """
+
+    Returns:
+        Response: A response object containing the simulated data."""
 
     def stream(simulation, simulation_path):
         while simulation:
@@ -39,8 +41,7 @@ def stream(simulation, simulation_path):
 @simulation_blueprint.route("/stop-simulation", methods=["POST"])
 def stop_simulation():
     """
-    Activate the flag to end the ongoing simulation of the vehicles.
-    """
+    Activate the flag to end the ongoing simulation of the vehicles."""
     if request.method == "POST":
         current_app.simulation = False
         return jsonify(success=True, message=gettext("Ending simulation..."))

main.py

@@ -21,6 +21,13 @@
 
 # To get the best matching language
 def get_locale():
+    """
+    Get the locale that best matches the user's preferred language.
+
+    This function uses the `accept_languages` attribute from the `request` object to determine the best matching locale based on the user's preferred language. It compares the user's preferred language against the available languages defined in the `LANGUAGES` configuration dictionary.
+
+    Returns:
+        str: The locale that best matches the user's preferred language."""
     return request.accept_languages.best_match(app.config["LANGUAGES"].keys())
 
 
@@ -44,11 +51,31 @@ def get_locale():
 
 @app.route("/images/<filename>")
 def custom_image(filename):
+    """
+    This function retrieves and returns a custom image file from the "app/static/images" directory.
+
+    Args:
+        filename (str): The name of the image file to be retrieved.
+
+    Returns:
+        str: The retrieved custom image file.
+
+    Example:
+        >>> custom_image("image.jpg")"""
     return send_from_directory("app/static/images", filename)
 
 
 @app.route("/reset", methods=["POST"])
 def reset():
+    """
+    Resets the problem definition, solver definiton, and routes.
+
+    This function resets the problem definition, solver definition, and routes by clearing the respective data structures.
+    It sets the 'addresses', 'start_nodes', 'end_nodes' to empty lists, and 'n_vehicles' to 1.
+    It also sets the 'simulation' flag to False.
+
+    Returns:
+        jsonify: A JSON response indicating the success of the reset operation."""
     current_app.problem_data = {}  # Reset problem definition
     current_app.solver_data = {}  # Reset solver definiton
     current_app.routes = {}  # Reset the routes
@@ -62,7 +89,19 @@ def reset():
 
 @app.route("/", methods=["POST", "GET"])
 def main():
-    # Initialize variables global to the app context
+    """
+    Initialize the main function of the app.
+
+    This function initializes variables global to the app context, sets the map center coordinates,
+    sets up an AddressFormatConversion object, and calls the reset function to initialize variables.
+    When a POST request is made, the function redirects to the root URL. If an error occurs, it returns an error message.
+    Otherwise, it renders the index.html template with the map center coordinates and the API key.
+
+    Args:
+        None
+
+    Returns:
+        None"""
     current_app.map_center = [
         [37.38602323347123, -5.99311606343879]
     ]  # Center of the map