Merge pull request #971 from SuffolkLITLab/copilot/fix-853

Add optional `required` parameter to _fields() methods for granular field requirement control

Author: nonprofittechy

docassemble/AssemblyLine/al_general.py

@@ -1114,6 +1114,7 @@ def name_fields(
         maxlengths: Optional[Dict[str, int]] = None,
         suffix_choices: Optional[Union[List[str], Callable]] = None,
         title_options: Optional[Union[List[str], Callable]] = None,
+        required: Optional[Dict[str, bool]] = None,
     ) -> List[Dict[str, str]]:
         """
         Generates suitable field prompts for a name based on the type of entity (person or business)
@@ -1133,6 +1134,7 @@ def name_fields(
             maxlengths (Dict[str, int], optional): A dictionary of field names and their maximum lengths. Default is None.
             suffix_choices (Union[List[str], Callable], optional): A list of suffix options or a callable to generate suffix options, or overridden by value of global `al_name_suffixes`.
             title_options: (Union[List[str], Callable], optional): Deprecated parameter, use `title_choices` instead. If provided, it will be used to set the title choices.
+            required (Dict[str, bool], optional): A dictionary of field names and if they should be required. Default is None.
 
         Returns:
             List[Dict[str, str]]: A list of dictionaries where each dictionary contains field prompt details.
@@ -1196,6 +1198,17 @@ def name_fields(
             if show_if:
                 for field in fields:
                     field["show if"] = show_if
+
+            if maxlengths:
+                for field in fields:
+                    if field["field"] in maxlengths:
+                        field["maxlength"] = maxlengths[field["field"]]
+
+            if required:
+                for field in fields:
+                    if field["field"] in required:
+                        field["required"] = required[field["field"]]
+
             return fields
         elif person_or_business == "business":
             fields = [
@@ -1206,6 +1219,17 @@ def name_fields(
             ]
             if show_if:
                 fields[0]["show if"] = show_if
+
+            if maxlengths:
+                for field in fields:
+                    if field["field"] in maxlengths:
+                        field["maxlength"] = maxlengths[field["field"]]
+
+            if required:
+                for field in fields:
+                    if field["field"] in required:
+                        field["required"] = required[field["field"]]
+
             return fields
         else:
             # Note: the labels are template block objects: if they are keys,
@@ -1273,6 +1297,12 @@ def name_fields(
                 for field in fields:
                     if field["field"] in maxlengths:
                         field["maxlength"] = maxlengths[field["field"]]
+
+            if required:
+                for field in fields:
+                    if field["field"] in required:
+                        field["required"] = required[field["field"]]
+
             return fields
 
     def address_fields(
@@ -1324,6 +1354,7 @@ def gender_fields(
         show_if: Union[str, Dict[str, str], None] = None,
         maxlengths: Optional[Dict[str, int]] = None,
         choices: Optional[Union[List[Dict[str, str]], Callable]] = None,
+        required: Optional[Dict[str, bool]] = None,
     ) -> List[Dict[str, str]]:
         """
         Generate fields for capturing gender information, including a
@@ -1334,6 +1365,7 @@ def gender_fields(
             show_if (Union[str, Dict[str, str], None]): Condition to determine if the field should be shown. Defaults to None.
             maxlengths (Dict[str, int], optional): A dictionary of field names and their maximum lengths. Default is None.
             choices (Optional[Union[List[Dict[str, str]], Callable]]): A list of choices of genders to use in the prompts, or a callable that returns such a list. Default set of choices includes male, female, nonbinary, prefer-not-to-say, self-described, and unknown.
+            required (Dict[str, bool], optional): A dictionary of field names and if they should be required. Default is None.
 
         Returns:
             List[Dict[str, str]]: A list of dictionaries with field prompts for gender.
@@ -1377,13 +1409,18 @@ def gender_fields(
                 if field["field"] in maxlengths:
                     field["maxlength"] = maxlengths[field["field"]]
 
+        if required:
+            for field in fields:
+                if field["field"] in required:
+                    field["required"] = required[field["field"]]
+
         return fields
 
     def pronoun_fields(
         self,
         show_help=False,
         show_if: Union[str, Dict[str, str], None] = None,
-        required: bool = False,
+        required: Union[bool, Dict[str, bool]] = False,
         shuffle: bool = False,
         show_unknown: Optional[Union[Literal["guess"], bool]] = "guess",
         maxlengths: Optional[Dict[str, int]] = None,
@@ -1395,7 +1432,7 @@ def pronoun_fields(
         Args:
             show_help (bool): Whether to show additional help text. Defaults to False.
             show_if (Union[str, Dict[str, str], None]): Condition to determine if the field should be shown. Defaults to None.
-            required (bool): Whether the field is required. Defaults to False.
+            required (Union[bool, Dict[str, bool]]): Whether the field is required. Can be a boolean (applies to all fields) or a dictionary of field names and if they should be required. Defaults to False.
             shuffle (bool): Whether to shuffle the order of pronouns. Defaults to False.
             show_unknown (Union[Literal["guess"], bool]): Whether to show an "unknown" option. Can be "guess", True, or False. Defaults to "guess".
             maxlengths (Dict[str, int], optional): A dictionary of field names and their maximum lengths. Default is None.
@@ -1429,7 +1466,7 @@ def pronoun_fields(
                 "datatype": "checkboxes",
                 "choices": shuffled_choices + final_choices,
                 "none of the above": str(self.pronoun_prefer_not_to_say_label),
-                "required": required,
+                "required": required if isinstance(required, bool) else False,
             },
             self_described_input,
         ]
@@ -1444,6 +1481,12 @@ def pronoun_fields(
                 if field["field"] in maxlengths:
                     field["maxlength"] = maxlengths[field["field"]]
 
+        # Handle dictionary-based required parameter
+        if isinstance(required, dict):
+            for field in fields:
+                if field["field"] in required:
+                    field["required"] = required[field["field"]]
+
         return fields
 
     def get_pronouns(self) -> set:
@@ -1482,6 +1525,7 @@ def language_fields(
         style: str = "radio",
         show_if: Union[str, Dict[str, str], None] = None,
         maxlengths: Optional[Dict[str, int]] = None,
+        required: Optional[Dict[str, bool]] = None,
     ) -> List[Dict[str, str]]:
         """
         Generate fields for capturing language preferences.
@@ -1491,6 +1535,7 @@ def language_fields(
             style (str): The display style of choices. Defaults to "radio".
             show_if (Union[str, Dict[str, str], None]): Condition to determine if the field should be shown. Defaults to None.
             maxlengths (Dict[str, int], optional): A dictionary of field names and their maximum lengths. Default is None.
+            required (Dict[str, bool], optional): A dictionary of field names and if they should be required. Default is None.
 
         Returns:
             List[Dict[str, str]]: A list of dictionaries with field prompts for language preferences.
@@ -1525,6 +1570,12 @@ def language_fields(
             for field in fields:
                 if field["field"] in maxlengths:
                     field["maxlength"] = maxlengths[field["field"]]
+
+        if required:
+            for field in fields:
+                if field["field"] in required:
+                    field["required"] = required[field["field"]]
+
         return fields
 
     def language_name(self) -> str:

docassemble/AssemblyLine/test_al_general.py

@@ -462,6 +462,119 @@ def test_name_methods(self):
         self.assertEqual(self.individual.name_short(), "Johnny's Sandwiches")
         self.assertEqual(str(self.individual), "Johnny's Sandwiches")
 
+    def test_name_fields_required(self):
+        """Test the required parameter for name_fields method"""
+        self.individual.instanceName = "test_individual"
+
+        # Test without required parameter - middle name should default to False
+        fields = self.individual.name_fields(person_or_business="person")
+        middle_field = None
+        for field in fields:
+            if "middle" in field["field"]:
+                middle_field = field
+                break
+        self.assertIsNotNone(middle_field)
+        self.assertEqual(middle_field["required"], False)
+
+        # Test with required parameter making middle name required
+        fields = self.individual.name_fields(
+            person_or_business="person", required={"test_individual.name.middle": True}
+        )
+        middle_field = None
+        for field in fields:
+            if "middle" in field["field"]:
+                middle_field = field
+                break
+        self.assertIsNotNone(middle_field)
+        self.assertEqual(middle_field["required"], True)
+
+        # Test business case with required parameter
+        fields = self.individual.name_fields(
+            person_or_business="business", required={"test_individual.name.first": True}
+        )
+        business_field = fields[0]
+        self.assertEqual(business_field["required"], True)
+
+    def test_gender_fields_required(self):
+        """Test the required parameter for gender_fields method"""
+        self.individual.instanceName = "test_individual"
+
+        # Test without required parameter
+        fields = self.individual.gender_fields()
+        gender_field = fields[0]
+        self.assertNotIn(
+            "required", gender_field
+        )  # Should not have required by default
+
+        # Test with required parameter
+        fields = self.individual.gender_fields(
+            required={"test_individual.gender": True}
+        )
+        gender_field = fields[0]
+        self.assertEqual(gender_field["required"], True)
+
+        # Test key not in required dict - should not change default
+        fields = self.individual.gender_fields(required={"other_field": True})
+        gender_field = fields[0]
+        self.assertNotIn("required", gender_field)
+
+    def test_pronoun_fields_required(self):
+        """Test the required parameter for pronoun_fields method (both bool and dict)"""
+        self.individual.instanceName = "test_individual"
+
+        # Test with boolean required parameter (existing behavior)
+        fields = self.individual.pronoun_fields(required=True)
+        pronoun_field = fields[0]
+        self.assertEqual(pronoun_field["required"], True)
+
+        # Test with boolean required parameter = False
+        fields = self.individual.pronoun_fields(required=False)
+        pronoun_field = fields[0]
+        self.assertEqual(pronoun_field["required"], False)
+
+        # Test with dictionary required parameter (new behavior)
+        fields = self.individual.pronoun_fields(
+            required={"test_individual.pronouns": True}
+        )
+        pronoun_field = fields[0]
+        self.assertEqual(pronoun_field["required"], True)
+
+        # Test with dictionary required parameter for different field
+        fields = self.individual.pronoun_fields(
+            required={"test_individual.pronouns_self_described": True}
+        )
+        pronoun_field = fields[0]
+        self_described_field = fields[1]
+        self.assertEqual(
+            pronoun_field["required"], False
+        )  # First field should still be False
+        self.assertEqual(self_described_field["required"], True)
+
+    def test_language_fields_required(self):
+        """Test the required parameter for language_fields method"""
+        self.individual.instanceName = "test_individual"
+
+        # Test without required parameter
+        fields = self.individual.language_fields()
+        language_field = fields[0]
+        self.assertNotIn(
+            "required", language_field
+        )  # Should not have required by default
+
+        # Test with required parameter
+        fields = self.individual.language_fields(
+            required={"test_individual.language": True}
+        )
+        language_field = fields[0]
+        self.assertEqual(language_field["required"], True)
+
+        # Test other language field
+        fields = self.individual.language_fields(
+            required={"test_individual.language_other": False}
+        )
+        other_field = fields[1]
+        self.assertEqual(other_field["required"], False)
+
 
 class test_get_visible_al_nav_items(unittest.TestCase):
     def test_case_1(self):