fix: improving children and parent retrive docstring and creating a private generic method for then

Author: LucasAlvws

pydoll/elements/web_element.py

@@ -147,58 +147,50 @@ async def get_parent_element(self) -> 'WebElement':
     async def get_children_elements(
         self, max_depth: int = 1, tag_filter: list[str] = []
     ) -> list['WebElement']:
-        """Element's child elements."""
-        result = await self.execute_script(
-            Scripts.GET_CHILDREN_NODE.format(max_depth=max_depth, tag_filter=tag_filter)
-        )
-        if not self._has_object_id_key(result):
-            raise ElementNotFound(f'Child element not found for element: {self}')
-
-        array_object_id = result['result']['result']['objectId']
+        """
+        Retrieve all direct and nested child elements of this element.
 
-        get_properties_command = RuntimeCommands.get_properties(object_id=array_object_id)
-        properties_response: GetPropertiesResponse = await self._execute_command(
-            get_properties_command
-        )
+        Args:
+            max_depth (int, optional): Maximum depth to traverse when finding children.
+                Defaults to 1 for direct children only.
+            tag_filter (list[str], optional): List of HTML tag names to filter results.
+                If empty, returns all child elements regardless of tag. Defaults to [].
 
-        children_elements: list['WebElement'] = []
-        for prop in properties_response['result']['result']:
-            if prop['name'].isdigit() and 'objectId' in prop['value']:
-                child_object_id = prop['value']['objectId']
-                attributes = await self._get_object_attributes(object_id=child_object_id)
-                children_elements.append(
-                    WebElement(
-                        child_object_id, self._connection_handler, attributes_list=attributes
-                    )
-                )
+        Returns:
+            list[WebElement]: List of child WebElement objects found within the specified
+                depth and matching the tag filter criteria.
 
-        return children_elements
+        Raises:
+            ElementNotFound: If no child elements are found for this element.
+        """
+        try:
+            return await self._get_family_elements(
+                script=Scripts.GET_CHILDREN_NODE, max_depth=max_depth, tag_filter=tag_filter
+            )
+        except ElementNotFound:
+            raise ElementNotFound(f'Child element not found for element: {self}')
 
     async def get_siblings_elements(self, tag_filter: list[str] = []) -> list['WebElement']:
-        """Element's siblings elements."""
-        result = await self.execute_script(Scripts.GET_SIBLINGS_NODE.format(tag_filter=tag_filter))
-        if not self._has_object_id_key(result):
-            raise ElementNotFound(f'Sibling element not found for element: {self}')
+        """
+        Retrieve all sibling elements of this element (elements at the same DOM level).
 
-        array_object_id = result['result']['result']['objectId']
+        Args:
+            tag_filter (list[str], optional): List of HTML tag names to filter results.
+                If empty, returns all sibling elements regardless of tag. Defaults to [].
 
-        get_properties_command = RuntimeCommands.get_properties(object_id=array_object_id)
-        properties_response: GetPropertiesResponse = await self._execute_command(
-            get_properties_command
-        )
+        Returns:
+            list[WebElement]: List of sibling WebElement objects that share the same
+                parent as this element and match the tag filter criteria.
 
-        siblings_elements: list['WebElement'] = []
-        for prop in properties_response['result']['result']:
-            if prop['name'].isdigit() and 'objectId' in prop['value']:
-                child_object_id = prop['value']['objectId']
-                attributes = await self._get_object_attributes(object_id=child_object_id)
-                siblings_elements.append(
-                    WebElement(
-                        child_object_id, self._connection_handler, attributes_list=attributes
-                    )
-                )
-
-        return siblings_elements
+        Raises:
+            ElementNotFound: If no sibling elements are found for this element.
+        """
+        try:
+            return await self._get_family_elements(
+                script=Scripts.GET_SIBLINGS_NODE, tag_filter=tag_filter
+            )
+        except ElementNotFound:
+            raise ElementNotFound(f'Sibling element not found for element: {self}')
 
     async def take_screenshot(self, path: str, quality: int = 100):
         """
@@ -492,6 +484,49 @@ async def execute_script(self, script: str, return_by_value: bool = False):
             )
         )
 
+    async def _get_family_elements(
+        self, script: str, max_depth: int = 1, tag_filter: list[str] = []
+    ) -> list['WebElement']:
+        """
+        Retrieve all family elements of this element (elements at the same DOM level).
+
+        Args:
+            script (str): CDP script to execute for retrieving family elements.
+            tag_filter (list[str], optional): List of HTML tag names to filter results.
+                If empty, returns all family elements regardless of tag. Defaults to [].
+
+        Returns:
+            list[WebElement]: List of family WebElement objects that share the same
+                parent as this element and match the tag filter criteria.
+
+        Raises:
+            ElementNotFound: If no family elements are found for this element.
+        """
+        result = await self.execute_script(
+            script.format(tag_filter=tag_filter, max_depth=max_depth)
+        )
+        if not self._has_object_id_key(result):
+            raise ElementNotFound(f'Family element not found for element: {self}')
+
+        array_object_id = result['result']['result']['objectId']
+
+        get_properties_command = RuntimeCommands.get_properties(object_id=array_object_id)
+        properties_response: GetPropertiesResponse = await self._execute_command(
+            get_properties_command
+        )
+
+        family_elements: list['WebElement'] = []
+        for prop in properties_response['result']['result']:
+            if not (prop['name'].isdigit() and 'objectId' in prop['value']):
+                continue
+            child_object_id = prop['value']['objectId']
+            attributes = await self._get_object_attributes(object_id=child_object_id)
+            family_elements.append(
+                WebElement(child_object_id, self._connection_handler, attributes_list=attributes)
+            )
+
+        return family_elements
+
     def _def_attributes(self, attributes_list: list[str]):
         """Process flat attribute list into dictionary (renames 'class' to 'class_name')."""
         for i in range(0, len(attributes_list), 2):