Merge pull request JdeRobot#3637 from Kunal-Somani/docs/fix-typo-and-improve-backend-documentation

docs(academy): fix typo in InvalidPath and improve documentation across backend modules

Author: javizqh

academy/exceptions.py

@@ -2,7 +2,7 @@ class InvalidPath(Exception):
     """Exception raised when a path is not valid."""
 
     def __init__(self, msg):
-        self.message = f"Pat: {msg} is invalid."
+        self.message = f"Path: {msg} is invalid."
         super().__init__(self.message)
         self.error_code = 403
 

academy/file_access.py

@@ -13,47 +13,63 @@
 
 
 class FAL(ABC):
-    """File Abstraction Layer"""
+    """
+    Abstract base class defining the File Abstraction Layer (FAL) interface.
+
+    Provides a unified API for file and directory operations used by
+    RoboticsAcademy exercises. Concrete implementations handle different
+    storage backends (local filesystem, remote, etc.).
+    """
 
     def __init__(self, academy="", helper=""):
         self.academy = academy
         self.helper = helper
         self.user = None
 
     def set_user(self, user):
+        """Set the current user context for file operations."""
         self.user = user
 
     @abstractmethod
     def academy_path(self) -> str:
+        """Return the root path for all academy exercise files."""
         pass
 
     def exercise_path(self, exercise_id) -> str:
+        """Return the full path for a specific exercise directory."""
         return self.path_join(self.academy_path(), exercise_id)
 
     def helpers_path(self, exercise_id) -> str:
+        """Return the path to the helpers directory for an exercise."""
         return self.path_join(self.helper, exercise_id)
 
     def exercise_helper_path(self, project_id, language) -> str:
+        """Return the path to the language-specific template directory for an exercise."""
         return self.path_join(self.helpers_path(project_id), f"{language}_template/")
 
     @abstractmethod
     def path_join(self, a: str, b: str) -> str:
+        """Join two path components and return the result."""
         pass
 
     @abstractmethod
     def exists(self, path: str) -> bool:
+        """Return file size if exists, 0 if directory, -1 if not found."""
         pass
 
     @abstractmethod
     def isdir(self, path: str) -> bool:
+        """Return True if path is an existing directory."""
         pass
 
     @abstractmethod
     def isfile(self, path: str) -> bool:
+        """Return True if path is an existing file."""
         pass
 
     @abstractmethod
     def create(self, path: str, content):
+        """Create a new text file at path with given content. Raises InvalidPath or ResourceAlreadyExists."""
         if ".." in path:
             raise InvalidPath(path)
 
@@ -62,6 +78,7 @@ def create(self, path: str, content):
 
     @abstractmethod
     def create_binary(self, path: str, content):
+        """Create a new binary file at path with given content. Raises InvalidPath or ResourceAlreadyExists."""
         if ".." in path:
             raise InvalidPath(path)
 
@@ -70,18 +87,21 @@ def create_binary(self, path: str, content):
 
     @abstractmethod
     def write(self, path: str, content):
+        """Overwrite an existing text file at path. Raises ResourceNotExists if missing."""
         size = self.exists(path)
         if size < 0:
             raise ResourceNotExists(path)
 
     @abstractmethod
     def write_binary(self, path: str, content):
+        """Overwrite an existing binary file at path. Raises ResourceNotExists if missing."""
         size = self.exists(path)
         if size < 0:
             raise ResourceNotExists(path)
 
     @abstractmethod
     def read(self, path: str):
+        """Read and return text content of file at path. Raises InvalidPath or ResourceNotExists."""
         if ".." in path:
             raise InvalidPath(path)
 
@@ -90,6 +110,7 @@ def read(self, path: str):
 
     @abstractmethod
     def read_binary(self, path: str):
+        """Read and return binary content of file at path. Raises InvalidPath or ResourceNotExists."""
         if ".." in path:
             raise InvalidPath(path)
 
@@ -98,6 +119,7 @@ def read_binary(self, path: str):
 
     @abstractmethod
     def listdirs(self, path: str):
+        """Return list of subdirectory names at path. Raises InvalidPath or ResourceNotExists."""
         if ".." in path:
             raise InvalidPath(path)
 
@@ -109,6 +131,7 @@ def listdirs(self, path: str):
 
     @abstractmethod
     def listfiles(self, path: str):
+        """Return list of file names at path. Raises InvalidPath or ResourceNotExists."""
         if ".." in path:
             raise InvalidPath(path)
 
@@ -120,6 +143,7 @@ def listfiles(self, path: str):
 
     @abstractmethod
     def list_formatted(self, path: str, base_group: str):
+        """Return formatted directory listing for the file explorer UI."""
         if ".." in path:
             raise InvalidPath(path)
 
@@ -131,6 +155,7 @@ def list_formatted(self, path: str, base_group: str):
 
     @abstractmethod
     def mkdir(self, path: str):
+        """Create a new directory at path. Raises InvalidPath or ResourceAlreadyExists."""
         if ".." in path:
             raise InvalidPath(path)
 
@@ -139,6 +164,7 @@ def mkdir(self, path: str):
 
     @abstractmethod
     def renamefile(self, old_path: str, new_path: str):
+        """Rename a file from old_path to new_path. Raises InvalidPath, ResourceNotExists, or ResourceAlreadyExists."""
         if ".." in new_path:
             raise InvalidPath(new_path)
 
@@ -150,6 +176,7 @@ def renamefile(self, old_path: str, new_path: str):
 
     @abstractmethod
     def renamedir(self, old_path: str, new_path: str):
+        """Rename a directory from old_path to new_path. Raises InvalidPath, ResourceNotExists, or ResourceAlreadyExists."""
         if ".." in new_path:
             raise InvalidPath(new_path)
 
@@ -161,6 +188,7 @@ def renamedir(self, old_path: str, new_path: str):
 
     @abstractmethod
     def removefile(self, path: str):
+        """Delete a file at path. Raises InvalidPath or ResourceNotExists."""
         if ".." in path:
             raise InvalidPath(path)
 
@@ -173,6 +201,7 @@ def removefile(self, path: str):
 
     @abstractmethod
     def removedir(self, path: str):
+        """Delete a directory and all its contents. Raises InvalidPath or ResourceNotExists."""
         if ".." in path:
             raise InvalidPath(path)
 
@@ -184,6 +213,7 @@ def removedir(self, path: str):
 
     @abstractmethod
     def dir_size(self, path):
+        """Return total size in bytes of all files under path. Raises InvalidPath or ResourceNotExists."""
         if ".." in path:
             raise InvalidPath(path)
 
@@ -196,11 +226,17 @@ def dir_size(self, path):
             raise ResourceNotExists(path)
 
     def filename(self, path: str) -> str:
+        """Return the filename without extension from a full path."""
         return os.path.splitext(os.path.basename(path))[0]
 
 
 class FAL_RA(FAL):
-    """File Abstraction Layer"""
+    """
+    Concrete FAL implementation for local RoboticsAcademy filesystem.
+
+    Stores exercise files under the academy filesystem directory and
+    uses standard Python os/shutil operations for all file access.
+    """
 
     def __init__(self, base, helper):
         FAL.__init__(self, base, helper)

academy/models.py

@@ -1,5 +1,8 @@
 """
-models.py
+Django ORM models for Robotics Academy.
+
+Defines the database schema for exercises, universes, worlds,
+robots, and tools used by the Robotics Academy platform.
 """
 
 from django.db import models
@@ -23,7 +26,11 @@
 
 class Tool(models.Model):
     """
-    Modelo Tool para Robotics Academy
+    Represents a tool available in the Robotics Academy platform.
+
+    Attributes:
+        name: Unique identifier and primary key for the tool.
+        base_config: Default configuration string for the tool.
     """
 
     name = models.CharField(max_length=50, blank=False, unique=True, primary_key=True)
@@ -38,7 +45,11 @@ class Meta:
 
 class Robot(models.Model):
     """
-    Modelo Robot para RoboticsAcademy
+    Represents a robot available in the Robotics Academy platform.
+
+    Attributes:
+        name: Unique name identifying the robot.
+        launch_file_path: Path to the ROS launch file for this robot.
     """
 
     name = models.CharField(max_length=100, blank=False, unique=True)
@@ -53,7 +64,15 @@ class Meta:
 
 class World(models.Model):
     """
-    Modelo World para RoboticsCademy
+    Represents a simulation world in the Robotics Academy platform.
+
+    Attributes:
+        name: Unique name identifying the world.
+        launch_file_path: Path to the ROS launch file for this world.
+        tools_config: JSON string with tool configuration overrides.
+        ros_version: ROS version used (ROS or ROS2).
+        type: Simulator type (none, gazebo, gz, physical).
+        start_pose: List of starting poses for robots in this world.
     """
 
     name = models.CharField(max_length=100, blank=False, unique=True)
@@ -81,7 +100,12 @@ class Meta:
 
 class Universe(models.Model):
     """
-    Modelo Universe para Robotics Academy
+    Represents a universe combining a world and a robot.
+
+    Attributes:
+        name: Unique name identifying the universe.
+        world: Associated World instance.
+        robot: Associated Robot instance.
     """
 
     name = models.CharField(max_length=100, blank=False, unique=True)
@@ -104,7 +128,17 @@ class Meta:
 
 class Exercise(models.Model):
     """
-    Robotics Academy Exercise model
+    Represents a Robotics Academy exercise.
+
+    Attributes:
+        exercise_id: Unique string identifier for the exercise.
+        name: Human-readable name of the exercise.
+        description: Short description of the exercise goals.
+        tags: JSON-encoded list of tags (e.g. MULTILANGUAGE).
+        status: Lifecycle status (ACTIVE, INACTIVE, PROTOTYPE).
+        universes: Associated Universe instances via ExerciseUniverses.
+        tools: Associated Tool instances.
+        url: Optional URL for additional exercise resources.
     """
 
     exercise_id = models.CharField(max_length=40, blank=False, unique=True)
@@ -126,6 +160,14 @@ class Meta:
 
 
 class ExerciseUniverses(models.Model):
+    """
+    Through model linking Exercise and Universe with a default flag.
+
+    Attributes:
+        exercise: Related Exercise instance.
+        universe: Related Universe instance.
+        is_default: Whether this universe is the default for the exercise.
+    """
     exercise = models.ForeignKey(Exercise, on_delete=models.CASCADE)
     universe = models.ForeignKey(Universe, on_delete=models.CASCADE)
     is_default = models.BooleanField()

academy/serializers.py

@@ -1,5 +1,16 @@
+"""
+Serializers for Robotics Academy API.
+"""
+
 from rest_framework import serializers
 
 
 class FileContentSerializer(serializers.Serializer):
+    """
+    Serializer for file content responses.
+
+    Fields:
+        content: The text content of the file as a string.
+    """
+
     content = serializers.CharField()