Refactor: Extract and exclude common content from README

This commit refactors the code that handles common content in README files for assignments. It introduces two functions:

- `assignment_instruction()`: This function takes a README file path and returns the assignment-specific instructions, excluding any common content. It uses configurable markers to identify the common content.
- `exclude_common_contents()`: This function takes a string containing README content and returns a new string with the common content removed.

This refactoring improves code organization, readability, and maintainability. It also makes the code more flexible by allowing the common content markers to be configured.

Additionally, this commit adds comprehensive docstrings to both functions, enhancing the documentation and making the code easier to understand.

Author: beachdweller

ai_tutor.py

@@ -2,8 +2,8 @@
 import json
 import logging
 import pathlib
+import re
 import time
-
 from typing import Dict, List, Tuple
 
 import requests
@@ -238,8 +238,65 @@ def assignment_code(student_files:Tuple[pathlib.Path]) -> str:
 
 
 @functools.lru_cache
-def assignment_instruction(readme_file:pathlib.Path) -> str:
-    return readme_file.read_text()
+def assignment_instruction(
+    readme_file: pathlib.Path,
+    common_content_start_marker: str = r"``From here is common to all assignments\.``",
+    common_content_end_marker: str = r"``Until here is common to all assignments\.``",
+) -> str:
+    """Extracts assignment-specific instructions from a README.md file.
+
+    This function reads a README.md file and removes content marked as common
+    to all assignments, returning only the assignment-specific instructions.
+
+    Args:
+        readme_file: Path to the README.md file.
+        common_content_start_marker: The marker indicating the start of common content.
+        common_content_end_marker: The marker indicating the end of common content.
+
+    Returns:
+        A string containing the assignment-specific instructions.
+    """
+   
+    return exclude_common_contents(
+        readme_file.read_text(),
+        common_content_start_marker,
+        common_content_end_marker,
+    )  # Single exit point
+
+
+def exclude_common_contents(
+    readme_content:str,
+    common_content_start_marker: str = r"``From here is common to all assignments\.``",
+    common_content_end_marker: str = r"``Until here is common to all assignments\.``",
+) -> str:
+    """Removes common content from a string.
+
+    This function takes a string and removes the content between the specified
+    start and end markers.
+
+    Args:
+        readme_content: The input string containing the README content.
+        common_content_start_marker: The marker indicating the start of common content.
+        common_content_end_marker: The marker indicating the end of common content.
+
+    Returns:
+        A string with the common content removed.
+    """
+    # Include the markers in the pattern itself
+    pattern = rf"(.*?){common_content_start_marker}\s*(.*?)\s*{common_content_end_marker}(.*?)"
+    match = re.search(pattern, readme_content, re.DOTALL | re.IGNORECASE)
+
+    if match:
+        # Extract the parts before and after the common content
+        before_common = match.group(1).strip()
+        after_common = match.group(3).strip()
+        # Combine them to get the final instructions
+        instruction = (before_common + after_common).strip()
+    else:
+        logging.warning(f"Common content markers '{common_content_start_marker}' and '{common_content_end_marker}' not found in README.md. Returning entire file.")
+        instruction = readme_content.strip()  # Single exit point
+
+    return instruction
 
 
 @functools.lru_cache(maxsize=None)

tests/test_ai_tutor.py

@@ -280,5 +280,44 @@ def test_load_locale(explanation_in:str, homework:Tuple[str]):
     )
 
 
+def test__exclude_common_contents__single():
+    start_marker = '``From here is common to all assignments.``'
+    end_marker = '``Until here is common to all assignments.``'
+
+    common_line_0 = "def subtract(a, b):"
+    common_line_1 = "return a - b"
+
+    common_content = start_marker + (
+        '``\n'
+        "\n"
+        f"{common_line_0}\n"
+        f"    {common_line_1}\n"
+    ) + end_marker + '\n'
+
+    specific_line_0 = "def add(a, b):"
+    specific_line_1 = "return a + b"
+
+    content = (
+        "Write a function that returns the sum of two numbers.\n"
+        "\n"
+        f"{specific_line_0}\n"
+        f"    {specific_line_1}\n"
+    ) + common_content
+
+    result = ai_tutor.exclude_common_contents(
+        readme_content=content,
+        common_content_start_marker=start_marker,
+        common_content_end_marker=end_marker,
+    )
+
+    assert specific_line_0 in result
+    assert specific_line_1 in result
+
+    assert common_line_0 not in result
+    assert common_line_1 not in result
+    assert start_marker not in result
+    assert end_marker not in result
+
+
 if '__main__' == __name__:
     pytest.main([__file__])