fix: clarify func name, fix typo

Author: lindsay-stevens

pyxform/survey.py

@@ -77,28 +77,33 @@ def register_nsmap():
 register_nsmap()
 
 
-def share_same_repeat_parent(
+def get_path_relative_to_lcar(
     target: SurveyElement,
     source: SurveyElement,
     lcar_steps_source: int,
     lcar: SurveyElement,
     reference_parent: bool = False,
-):
+) -> tuple[int, str]:
     """
-    Returns a tuple of the number of steps from the source xpath to the lowest common
-    ancestor repeat, and the xpath to the target xpath from the LCAR.
+    Get the number of steps from the source to the LCAR, and the path to the target.
 
-    Function only called if target and source share a ancestor repeat.
+    Implementation assumes that it is only called if target and source have an LCAR.
 
-    For example,
-        xpath =         /data/repeat_a/group_a/name
-        context_xpath = /data/repeat_a/group_b/age
+    Example:
+        target = /data/repeat_a/group_a/name
+        source = /data/repeat_a/group_b/age
+        return = (2, "/group_a/name")
 
-        returns (2, '/group_a/name')'
+    :param target: The reference target, like "/data/repeat/q1" for "${q1}"
+    :param source: The reference source, where the reference is located.
+    :param lcar_steps_source: The number of path segments from the source to the LCAR.
+    :param lcar: The lowest common ancestor repeat.
+    :param reference_parent: If True, calculate to the LCAR parent rather than the LCAR.
+      This may not be actually honoured depending on the topography.
     """
 
-    def is_repeat(i: SurveyElement) -> bool:
-        return isinstance(i, Section) and i.type == constants.REPEAT
+    def is_repeat(e: SurveyElement) -> bool:
+        return isinstance(e, Section) and e.type == constants.REPEAT
 
     # Currently reference_parent only used for itemsets containing a pyxform variable,
     # i.e. `select_one ${ref}`. In that case, an extra step up the reference path may be
@@ -1092,7 +1097,7 @@ def _relative_path(ref_name: str, _use_current: bool) -> str | None:
                 other=target, group_type=constants.REPEAT
             )
             if relation[0] == "Common Ancestor":
-                steps, ref_path = share_same_repeat_parent(
+                steps, ref_path = get_path_relative_to_lcar(
                     target=target,
                     source=context,
                     lcar_steps_source=relation[1],

…tures/share_same_repeat_parent_cases.csv …ures/get_path_relative_to_lcar_cases.csvtests/fixtures/share_same_repeat_parent_cases.csv renamed to tests/fixtures/get_path_relative_to_lcar_cases.csv tests/fixtures/share_same_repeat_parent_cases.csv renamed to tests/fixtures/get_path_relative_to_lcar_cases.csv

@@ -165,7 +165,7 @@ def assertPyxformXform(
         odk_validate_error__contains = coalesce(odk_validate_error__contains, [])
         survey_valid = True
         result = None
-        # Some tests explicitly turn off ODK Validate because they not valid forms, so
+        # Some tests explicitly turn off ODK Validate because they are not valid forms, so
         # use the setting if any before applying the environment variable default.
         run_odk_validate = coalesce(run_odk_validate, PYXFORM_TESTS_RUN_ODK_VALIDATE)
 

tests/pyxform_test_case.py

@@ -5,7 +5,7 @@
 from pyxform import constants as const
 from pyxform.question import InputQuestion
 from pyxform.section import GroupedSection, RepeatingSection
-from pyxform.survey import Survey, share_same_repeat_parent
+from pyxform.survey import Survey, get_path_relative_to_lcar
 
 from tests.pyxform_test_case import PYXFORM_TESTS_RUN_ODK_VALIDATE, PyxformTestCase
 
@@ -181,9 +181,9 @@ def build_survey_from_path_spec(
     return survey, target, source
 
 
-class TestShareSameRepeatParent(TestCase):
+class TestGetPathRelativeToLCAR(TestCase):
     """
-    Tests of pyxform.survey.share_same_repeat_parent
+    Tests of pyxform.survey.get_path_relative_to_lcar
     """
 
     def assert_relative_path(
@@ -217,7 +217,7 @@ def assert_relative_path(
             relation = source.lowest_common_ancestor(
                 other=target, group_type=const.REPEAT
             )
-            observed = share_same_repeat_parent(
+            observed = get_path_relative_to_lcar(
                 target=target,
                 source=source,
                 lcar_steps_source=relation[1],
@@ -232,7 +232,7 @@ def assert_relative_path(
 
     def test_relative_paths__combinations_max_inner_depth_of_2(self):
         """Should find relative XPath and steps are calculated accurately."""
-        path = Path(__file__).parent / "fixtures" / "share_same_repeat_parent_cases.csv"
+        path = Path(__file__).parent / "fixtures" / "get_path_relative_to_lcar_cases.csv"
         with open(path) as f:
             for case in DictReader(f):
                 self.assert_relative_path(