chore: enhance function documentation and add PR comment automation (#21)

* chore: add pr comment after issue is create

Also, update all functions documentations

* fix: typo github integration

* chore: update package builder

* chore: add pr comment function

* chore: add uv to build requirements

* chore: typo fix on add_pr_comments

* chore: removed redundant section

Author: saidsef

github_integration.py

@@ -29,36 +29,69 @@
 logging.getLogger(__name__)
 logging.basicConfig(level=logging.WARNING)
 
-class GutHubIntegration:
+class GitHubIntegration:
     def __init__(self):
-        # Initialize GitHub token
+        """
+        Initialize the GitHubIntegration class.
+
+        Returns:
+            None
+
+        Raises:
+            ValueError: If the GitHub token is not found in environment variables.
+        """
         self.github_token = GITHUB_TOKEN
         if not self.github_token:
             raise ValueError("Missing GitHub GITHUB_TOKEN in environment variables")
 
         logging.info("GitHub Integration initialized")
 
     def _get_headers(self):
-        """Get headers for GitHub API requests."""
+        """
+        Return the headers required for GitHub API requests.
+
+        Returns:
+            dict: A dictionary containing the required HTTP headers.
+
+        Raises:
+            ValueError: If the GitHub token is missing.
+
+        Error Handling:
+            Raises ValueError if the GitHub token is not set.
+        """
+        if not self.github_token:
+            raise ValueError("GitHub token is missing for API requests")
         return {
             'Authorization': f'token {self.github_token}',
             'Accept': 'application/vnd.github.v3+json'
         }
 
     def _get_pr_url(self, repo_owner: str, repo_name: str, pr_number: int) -> str:
-        """Construct the URL for a specific pull request."""
+        """
+        Generates the GitHub API URL for a specific pull request in a given repository.
+        Args:
+            repo_owner (str): The owner of the GitHub repository.
+            repo_name (str): The name of the GitHub repository.
+            pr_number (int): The pull request number.
+        Returns:
+            str: The formatted GitHub API URL for the specified pull request.
+        Raises:
+            ValueError: If any of the arguments are empty or if pr_number is not a positive integer.
+        """
+        
         return f"https://api.github.com/repos/{repo_owner}/{repo_name}/pulls/{pr_number}"
 
     def get_pr_diff(self, repo_owner: str, repo_name: str, pr_number: int) -> str:
-        """Fetch the diff/patch of a pull request.
-        
+        """
+        Fetches the diff/patch of a pull request from a GitHub repository.
         Args:
-            repo_owner: The owner of the GitHub repository
-            repo_name: The name of the GitHub repository
-            pr_number: The number of the pull request to analyze
-            
+            repo_owner (str): The owner of the GitHub repository.
+            repo_name (str): The name of the GitHub repository.
+            pr_number (int): The pull request number.
         Returns:
-            A string containing the raw patch of the pull request
+            str: The raw patch/diff text of the pull request if successful, otherwise None.
+        Error Handling:
+            Logs an error message and prints the traceback if the request fails or an exception occurs.
         """
         logging.info(f"Fetching PR diff for {repo_owner}/{repo_name}#{pr_number}")
 
@@ -77,15 +110,17 @@ def get_pr_diff(self, repo_owner: str, repo_name: str, pr_number: int) -> str:
             return None
 
     def get_pr_content(self, repo_owner: str, repo_name: str, pr_number: int) -> Dict[str, Any]:
-        """Fetch the content of a pull request.
-        
+        """
+        Fetches the content of a specific pull request from a GitHub repository.
         Args:
-            repo_owner: The owner of the GitHub repository
-            repo_name: The name of the GitHub repository
-            pr_number: The number of the pull request to analyze
-            
+            repo_owner (str): The owner of the repository.
+            repo_name (str): The name of the repository.
+            pr_number (int): The pull request number.
         Returns:
-            A dictionary containing PR metadata and file changes
+            Dict[str, Any]: A dictionary containing the pull request's title, description, author, creation and update timestamps, and state.
+            Returns None if an error occurs during the fetch operation.
+        Error Handling:
+            Logs an error message and prints the traceback if the request fails or an exception is raised during processing.
         """
         logging.info(f"Fetching PR content for {repo_owner}/{repo_name}#{pr_number}")
 
@@ -117,16 +152,18 @@ def get_pr_content(self, repo_owner: str, repo_name: str, pr_number: int) -> Dic
             return None
 
     def add_pr_comments(self, repo_owner: str, repo_name: str, pr_number: int, comment: str) -> Dict[str, Any]:
-        """Add a comment to a pull request.
-
+        """
+        Adds a comment to a specified pull request on GitHub.
         Args:
-            repo_owner: The owner of the GitHub repository
-            repo_name: The name of the GitHub repository
-            pr_number: The number of the pull request to comment on
-            comment: The content of the comment
-
+            repo_owner (str): The owner of the repository.
+            repo_name (str): The name of the repository.
+            pr_number (int): The pull request number to which the comment will be added.
+            comment (str): The content of the comment to add.
         Returns:
-            A dictionary containing the added comment's metadata
+            Dict[str, Any]: The JSON response from the GitHub API containing the comment data if successful.
+            None: If an error occurs while adding the comment.
+        Error Handling:
+            Logs an error message and prints the traceback if the request fails or an exception is raised.
         """
         logging.info(f"Adding comment to PR {repo_owner}/{repo_name}#{pr_number}")
 
@@ -148,17 +185,19 @@ def add_pr_comments(self, repo_owner: str, repo_name: str, pr_number: int, comme
             return None
 
     def update_pr_description(self, repo_owner: str, repo_name: str, pr_number: int, new_title: str, new_description: str) -> Dict[str, Any]:
-        """Update the description of a pull request.
-
+        """
+        Updates the title and description of a pull request on GitHub.
         Args:
-            repo_owner: The owner of the GitHub repository
-            repo
-            repo_name: The name of the GitHub repository
-            pr_number: The number of the pull request to update
-            new_title: The new title for the pull request
-            new_description: The new description for the pull request
+            repo_owner (str): The owner of the repository.
+            repo_name (str): The name of the repository.
+            pr_number (int): The pull request number to update.
+            new_title (str): The new title for the pull request.
+            new_description (str): The new description (body) for the pull request.
         Returns:
-            A dictionary containing the updated pull request's metadata
+            Dict[str, Any]: The updated pull request data as returned by the GitHub API if the update is successful.
+            None: If an error occurs during the update process.
+        Error Handling:
+            Logs an error message and prints the traceback if the update fails due to an exception (e.g., network issues, invalid credentials, or API errors).
         """
         logging.info(f"Updating PR description for {repo_owner}/{repo_name}#{pr_number}")
 
@@ -181,17 +220,20 @@ def update_pr_description(self, repo_owner: str, repo_name: str, pr_number: int,
             return None
 
     def create_issue(self, repo_owner: str, repo_name: str, title: str, body: str, labels: list[str]) -> Dict[str, Any]:
-        """Create a new issue in the specified GitHub repository.
-        
+        """
+        Creates a new issue in the specified GitHub repository.
+        When issue is created add comment to PR with "Resolves: #<issue_number>" using add_pr_comments function.
         Args:
-            repo_owner: The owner of the GitHub repository
-            repo_name: The name of the GitHub repository
-            title: The title of the issue
-            body: The body content of the issue, this should include description, why, details, references
-                  if there is a PR number, add resolve by PR number
-            labels: A list of labels to apply to the issue
+            repo_owner (str): The owner of the repository.
+            repo_name (str): The name of the repository.
+            title (str): The title of the issue to be created.
+            body (str): The body content of the issue.
+            labels (list[str]): A list of labels to assign to the issue. The label 'mcp' will always be included.
         Returns:
-            A dictionary containing the created issue's metadata
+            Dict[str, Any]: A dictionary containing the created issue's data if successful.
+            None: If an error occurs during issue creation.
+        Error Handling:
+            Logs errors and prints the traceback if the issue creation fails, returning None.
         """
         logging.info(f"Creating issue in {repo_owner}/{repo_name}")
 
@@ -218,18 +260,21 @@ def create_issue(self, repo_owner: str, repo_name: str, title: str, body: str, l
             return None
 
     def update_issue(self, repo_owner: str, repo_name: str, issue_number: int, title: str, body: str, labels: list[str] = [], state: str = 'open') -> Dict[str, Any]:
-        """Update an existing issue in the specified GitHub repository.
-
+        """
+        Updates an existing GitHub issue with the specified parameters.
         Args:
-            repo_owner: The owner of the GitHub repository
-            repo_name: The name of the GitHub repository
-            issue_number: The number of the issue to update
-            title: The new title of the issue
-            body: The new body content of the issue
-            labels: A list of labels to apply to the issue
-            state: The new state of the issue (open/closed)
+            repo_owner (str): The owner of the repository.
+            repo_name (str): The name of the repository.
+            issue_number (int): The number of the issue to update.
+            title (str): The new title for the issue.
+            body (str): The new body content for the issue.
+            labels (list[str], optional): A list of labels to assign to the issue. Defaults to an empty list.
+            state (str, optional): The state of the issue ('open' or 'closed'). Defaults to 'open'.
         Returns:
-            A dictionary containing the updated issue's metadata
+            Dict[str, Any]: The updated issue data as returned by the GitHub API if the update is successful.
+            None: If an error occurs during the update process.
+        Error Handling:
+            Logs an error message and prints the traceback if the request fails or an exception is raised.
         """
         logging.info(f"Updating issue {issue_number} in {repo_owner}/{repo_name}")
 
@@ -254,13 +299,16 @@ def update_issue(self, repo_owner: str, repo_name: str, issue_number: int, title
             return None
 
     def get_latest_sha(self, repo_owner: str, repo_name: str) -> Optional[str]:
-        """Fetch the latest commit SHA from the specified GitHub repository.
-
+        """
+        Fetches the latest commit SHA from a specified GitHub repository.
         Args:
-            repo_owner: The owner of the GitHub repository
-            repo_name: The name of the GitHub repository
+            repo_owner (str): The owner of the GitHub repository.
+            repo_name (str): The name of the GitHub repository.
         Returns:
-            The latest commit SHA as a string, or None if no commits are found
+            Optional[str]: The SHA string of the latest commit if found, otherwise None.
+        Error Handling:
+            Logs errors and warnings if the request fails, the response is invalid, or no commits are found.
+            Returns None in case of exceptions or if the repository has no commits.
         """
         logging.info(f"Fetching latest commit SHA for {repo_owner}/{repo_name}")
 
@@ -287,15 +335,18 @@ def get_latest_sha(self, repo_owner: str, repo_name: str) -> Optional[str]:
             return None
 
     def create_tag(self, repo_owner: str, repo_name: str, tag_name: str, message: str) -> Dict[str, Any]:
-        """Create a new tag in the specified GitHub repository.
-
+        """
+        Creates a new tag in the specified GitHub repository.
         Args:
-            repo_owner: The owner of the GitHub repository
-            repo_name: The name of the GitHub repository
-            tag_name: The name of the new tag
-            message: The message for the tag
+            repo_owner (str): The owner of the repository.
+            repo_name (str): The name of the repository.
+            tag_name (str): The name of the tag to create.
+            message (str): The message associated with the tag.
         Returns:
-            A dictionary containing the created tag's metadata
+            Dict[str, Any]: The response data from the GitHub API if the tag is created successfully.
+            None: If an error occurs during the tag creation process.
+        Error Handling:
+            Logs errors and prints the traceback if fetching the latest commit SHA fails or if the GitHub API request fails.
         """
         logging.info(f"Creating tag {tag_name} in {repo_owner}/{repo_name}")
         # Construct the tags URL
@@ -324,16 +375,19 @@ def create_tag(self, repo_owner: str, repo_name: str, tag_name: str, message: st
             return None
 
     def create_release(self, repo_owner: str, repo_name: str, tag_name: str, release_name: str, body: str) -> Dict[str, Any]:
-        """Create a new release in the specified GitHub repository.
-
+        """
+        Creates a new release in the specified GitHub repository.
         Args:
-            repo_owner: The owner of the GitHub repository
-            repo_name: The name of the GitHub repository
-            tag_name: The name of the tag for the release
-            release_name: The name of the release
-            body: The body content of the release
+            repo_owner (str): The owner of the repository.
+            repo_name (str): The name of the repository.
+            tag_name (str): The tag name for the release.
+            release_name (str): The name of the release.
+            body (str): The description or body content of the release.
         Returns:
-            A dictionary containing the created release's metadata
+            Dict[str, Any]: The JSON response from the GitHub API containing release information if successful.
+            None: If an error occurs during the release creation process.
+        Error Handling:
+            Logs errors and prints the traceback if the release creation fails, returning None.
         """
         logging.info(f"Creating release {release_name} in {repo_owner}/{repo_name}")
 

ip_integration.py

@@ -32,8 +32,12 @@ class IPIntegration:
   def __init__(self, ipv4_api_url: str = None, ipv6_api_url: str = None) -> None:
     """
     Initialize the IPIntegration class.
-    :param ip_api_url: The URL of the IP API to use. If None, defaults to "https://ipinfo.io/json".
+
+    :param ipv4_api_url: Optional custom API URL for IPv4 information.
+    :param ipv6_api_url: Optional custom API URL for IPv6 information.
     """
+    self.ipv4_api_url = None
+    self.ipv6_api_url = None
     if ipv4_api_url is None or ipv6_api_url is None:
         self.ipv4_api_url = "https://ipinfo.io/json"
         self.ipv6_api_url = "https://v6.ipinfo.io/json"
@@ -42,19 +46,25 @@ def __init__(self, ipv4_api_url: str = None, ipv6_api_url: str = None) -> None:
         self.ipv6_api_url = ipv6_api_url
 
   def get_info(self, url: str) -> Dict[str, Any]:
-      """
-      Get information about an IP address.
-      :param url: The URL of the IP API to use.
-      :return: A dictionary containing the IP information.
-      """
-      try:
-          response = requests.get(url)
-          response.raise_for_status()
-          return response.json()
-      except requests.RequestException as e:
-          logging.error(f"Error fetching IP info: {e}")
-          logging.debug(traceback.format_exc())
-          return {}
+    """
+    Fetches information from the specified URL using an HTTP GET request.
+    Args:
+        url (str): The URL to send the GET request to.
+    Returns:
+        Dict[str, Any]: The JSON response parsed into a dictionary if the request is successful.
+        Returns an empty dictionary if the request fails or an exception occurs.
+    Error Handling:
+        Logs an error message and stack trace if a requests.RequestException is raised during the HTTP request.
+    """
+      
+    try:
+        response = requests.get(url)
+        response.raise_for_status()
+        return response.json()
+    except requests.RequestException as e:
+        logging.error(f"Error fetching IP info: {e}")
+        logging.debug(traceback.format_exc())
+        return {}
 
   def get_ipv4_info(self) -> Dict[str, Any]:
       """
@@ -73,21 +83,28 @@ def get_ipv4_info(self) -> Dict[str, Any]:
           return {}
 
   def get_ipv6_info(self) -> Dict[str, Any]:
-      """
-      Get information about an IPv6 address.
-      :return: A dictionary containing the IPv6 information.
-      """
-      # Override the allowed_gai_family method to use IPv6
-      def allowed_gai_family():
-          return socket.AF_INET6
-      urllib3_connection.allowed_gai_family = allowed_gai_family
-      try:
-          ipv6 = self.get_info(self.ipv6_api_url)
-          if not ipv6:
-              logging.error("No IPv6 information found.")
-              return {}
-          return ipv6
-      except requests.RequestException as e:
-          logging.error(f"Error fetching IPv6 info: {e}")
-          logging.debug(traceback.format_exc())
-          return {}
+    """
+    Retrieves IPv6 information from a specified API endpoint.
+    This method temporarily overrides the `allowed_gai_family` method to force the use of IPv6 when making network requests.
+    It then attempts to fetch IPv6-related information from the configured API URL.
+    Returns:
+        dict: A dictionary containing IPv6 information if the request is successful.
+              Returns an empty dictionary if no information is found or if an error occurs.
+    Error Handling:
+        Logs an error message and returns an empty dictionary if a `requests.RequestException` is raised during the fetch operation.
+        Also logs the full traceback at the debug level for troubleshooting.
+    """
+    # Override the allowed_gai_family method to use IPv6
+    def allowed_gai_family():
+        return socket.AF_INET6
+    urllib3_connection.allowed_gai_family = allowed_gai_family
+    try:
+        ipv6 = self.get_info(self.ipv6_api_url)
+        if not ipv6:
+            logging.error("No IPv6 information found.")
+            return {}
+        return ipv6
+    except requests.RequestException as e:
+        logging.error(f"Error fetching IPv6 info: {e}")
+        logging.debug(traceback.format_exc())
+        return {}