[jira] new feature added scrap_regex_from_issue + docs + example (#1325)

* [jira] new feature added scrap_regex_from_issue + docs + example

Author: gkowalc

atlassian/jira.py

@@ -1409,7 +1409,7 @@ def issue_get_watchers(self, issue_key):
 
     def assign_issue(self, issue, account_id=None):
         """Assign an issue to a user. None will set it to unassigned. -1 will set it to Automatic.
-        :param issue: the issue ID or key to assign
+        :param issue : the issue ID or key to assign
         :type issue: int or str
         :param account_id: the account ID of the user to assign the issue to;
                 for jira server the value for account_id should be a valid jira username
@@ -1531,6 +1531,44 @@ def issue_edit_comment(self, issue_key, comment_id, comment, visibility=None, no
         params = {"notifyUsers": "true" if notify_users else "false"}
         return self.put(url, data=data, params=params)
 
+    def scrap_regex_from_issue(self, issue, regex):
+        """
+        This function scrapes the output of the given regex matches from the issue's description and comments.
+
+        Parameters:
+        issue (str): jira issue ide.
+        regex (str): The regex to match.
+
+        Returns:
+        list: A list of matches.
+        """
+        regex_output = []
+        issue_output = self.get_issue(issue)
+        description = issue_output["fields"]["description"]
+        comments = issue_output["fields"]["comment"]["comments"]
+
+        try:
+            description_matches = [x.group(0) for x in re.finditer(regex, description)]
+            if description_matches:
+                regex_output.extend(description_matches)
+
+            for comment in comments:
+                comment_html = comment["body"]
+                comment_matches = [x.group(0) for x in re.finditer(regex, comment_html)]
+                if comment_matches:
+                    regex_output.extend(comment_matches)
+
+            return regex_output
+        except HTTPError as e:
+            if e.response.status_code == 404:
+                # Raise ApiError as the documented reason is ambiguous
+                log.error("couldn't find issue: ", issue["key"])
+                raise ApiNotFoundError(
+                    "There is no content with the given issue ud,"
+                    "or the calling user does not have permission to view the issue",
+                    reason=e,
+                )
+
     def get_issue_remotelinks(self, issue_key, global_id=None, internal_id=None):
         """
         Compatibility naming method with get_issue_remote_links()

docs/jira.rst

@@ -363,6 +363,8 @@ Manage issues
     # started is a date string in the format %Y-%m-%dT%H:%M:%S.000+0000%z
     jira.issue_worklog(issue_key, started, time_in_sec)
 
+    # Scrap regex matches from issue description and comments:
+    jira.scrap_regex_from_issue(issue_key, regex)
 
 
 Epic Issues

examples/jira/jira_get_comment.py

@@ -1,5 +1,6 @@
 """ Example: Get Comments on a Jira Issue
 """
+
 # coding=utf-8
 from atlassian import Jira
 

examples/jira/jira_oauth2.py

@@ -5,6 +5,7 @@
     token and Using access token, Jira cloud ID is identified and
     the available projects are returned.
 """
+
 from requests_oauthlib import OAuth2Session
 from atlassian.jira import Jira
 from flask import Flask, request, redirect, session

examples/jira/jira_scrap_regex_from_issue.py

@@ -0,0 +1,8 @@
+from atlassian import Jira
+
+# This feature can be useful if you need to scrap some data from issue description or comments.
+jira = Jira(url="http://localhost:8080", username="admin", password="admin")
+regex = r"((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\[?\.\]?){3}(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)"  # regex for ipv4 address + ipv4 with [.] instead of dot
+issue = "TEST-1"  # id of the jira issue
+result = jira.scrap_regex_from_issue(issue, regex)
+# scrap_regex_from_issue will return results of positive regexes matches from issue description and issue comments.