Merge branch 'master' of https://github.com/AstroMatt/atlassian-python-api

Author: Gonchik Tsymzhitov

README.rst

@@ -1,14 +1,14 @@
 ============================
 Atlassian Python API wrapper
 ============================
-|Build Status| |PyPI version| |PyPI - Downloads| |License| |Codacy Badge|
+|Build Status| |PyPI version| |PyPI - Downloads| |License| |Codacy Badge| |Docs|
 
 Documentation
 -------------
 
-`Documentation (beta)`_
+`Documentation`_
 
-.. _Documentation (beta): https://atlassian-python-api.readthedocs.io/en/latest/index.html
+.. _Documentation: https://atlassian-python-api.readthedocs.io/en/latest/index.html
 
 Examples
 --------
@@ -109,6 +109,9 @@ See the `Contribution guidelines for this project`_ for details on how to make c
    :alt: Codacy Badge
 .. |PyPI - Downloads| image:: https://pepy.tech/badge/atlassian-python-api/month
    :alt: PyPI - Downloads
+.. |Docs| image:: https://readthedocs.org/projects/atlassian-python-api/badge/?version=latest
+   :target: https://atlassian-python-api.readthedocs.io/en/latest/?badge=latest
+   :alt: Documentation Status
 
 
 Credits

atlassian/VERSION

@@ -1 +1 @@
-1.13.23
+1.13.28

atlassian/bamboo.py

@@ -61,6 +61,15 @@ def base_list_call(self, resource, expand, favourite, clover_enabled, max_result
         params['start-index'] = start_index
         return self.get(self.resource_url(resource), flags=flags, params=params)
 
+    def get_custom_expiry(self, limit=25):
+        """
+        Get list of all plans where user has admin permission and which override global expiry settings. 
+        If global expiry is not enabled it returns empty response.
+        :param limit:
+        """
+        url = "rest/api/latest/admin/expiry/custom/plan?limit={}".format(limit)
+        return self.get(url)
+
     def plan_directory_info(self, plan_key):
         """
         Returns information about the directories where artifacts, build logs, and build results will be stored. 
@@ -95,7 +104,7 @@ def plans(self, expand=None, favourite=False, clover_enabled=False, start_index=
                                    elements_key='plans', element_key='plan')
 
     def results(self, project_key=None, plan_key=None, job_key=None, build_number=None, expand=None, favourite=False,
-                clover_enabled=False, issue_key=None, label=None, start_index=0, max_results=25):
+                clover_enabled=False, issue_key=None, label=None, start_index=0, max_results=25, include_all_states=False):
         """
         Get results as generic method
         :param project_key:
@@ -109,6 +118,7 @@ def results(self, project_key=None, plan_key=None, job_key=None, build_number=No
         :param label:
         :param start_index:
         :param max_results:
+        :param include_all_states:
         :return:
         """
         resource = "result"
@@ -124,12 +134,14 @@ def results(self, project_key=None, plan_key=None, job_key=None, build_number=No
         params = {}
         if issue_key:
             params['issueKey'] = issue_key
+        if include_all_states:
+            params['includeAllStates'] = include_all_states
         return self.base_list_call(resource, expand=expand, favourite=favourite, clover_enabled=clover_enabled,
                                    start_index=start_index, max_results=max_results,
                                    elements_key='results', element_key='result', label=label, **params)
 
     def latest_results(self, expand=None, favourite=False, clover_enabled=False, label=None, issue_key=None,
-                       start_index=0, max_results=25):
+                       start_index=0, max_results=25, include_all_states=False):
         """
         Get latest Results
         :param expand:
@@ -139,13 +151,14 @@ def latest_results(self, expand=None, favourite=False, clover_enabled=False, lab
         :param issue_key:
         :param start_index:
         :param max_results:
+        :param include_all_states:
         :return:
         """
         return self.results(expand=expand, favourite=favourite, clover_enabled=clover_enabled,
-                            label=label, issue_key=issue_key, start_index=start_index, max_results=max_results)
+                            label=label, issue_key=issue_key, start_index=start_index, max_results=max_results, include_all_states=include_all_states)
 
     def project_latest_results(self, project_key, expand=None, favourite=False, clover_enabled=False, label=None,
-                               issue_key=None, start_index=0, max_results=25):
+                               issue_key=None, start_index=0, max_results=25, include_all_states=False):
         """
         Get latest Project Results
         :param project_key:
@@ -156,13 +169,14 @@ def project_latest_results(self, project_key, expand=None, favourite=False, clov
         :param issue_key:
         :param start_index:
         :param max_results:
+        :param include_all_states:
         :return:
         """
         return self.results(project_key, expand=expand, favourite=favourite, clover_enabled=clover_enabled,
-                            label=label, issue_key=issue_key, start_index=start_index, max_results=max_results)
+                            label=label, issue_key=issue_key, start_index=start_index, max_results=max_results, include_all_states=include_all_states)
 
     def plan_results(self, project_key, plan_key, expand=None, favourite=False, clover_enabled=False, label=None,
-                     issue_key=None, start_index=0, max_results=25):
+                     issue_key=None, start_index=0, max_results=25, include_all_states=False):
         """
         Get Plan results
         :param project_key:
@@ -174,12 +188,13 @@ def plan_results(self, project_key, plan_key, expand=None, favourite=False, clov
         :param issue_key:
         :param start_index:
         :param max_results:
+        :param include_all_states:
         :return:
         """
         return self.results(project_key, plan_key, expand=expand, favourite=favourite, clover_enabled=clover_enabled,
-                            label=label, issue_key=issue_key, start_index=start_index, max_results=max_results)
+                            label=label, issue_key=issue_key, start_index=start_index, max_results=max_results, include_all_states=include_all_states)
 
-    def build_result(self, build_key, expand=None):
+    def build_result(self, build_key, expand=None, include_all_states=False):
         """
         Returns details of a specific build result
         :param expand: expands build result details on request. Possible values are: artifacts, comments, labels,
@@ -192,22 +207,23 @@ def build_result(self, build_key, expand=None):
             int(build_key.split('-')[-1])
             resource = "result/{}".format(build_key)
             return self.base_list_call(resource, expand, favourite=False, clover_enabled=False,
-                                       start_index=0, max_results=25)
+                                       start_index=0, max_results=25, include_all_states=include_all_states)
         except ValueError:
             raise ValueError('The key "{}" does not correspond to a build result'.format(build_key))
 
-    def build_latest_result(self, plan_key, expand=None):
+    def build_latest_result(self, plan_key, expand=None, include_all_states=False):
         """
         Returns details of a latest build result
         :param expand: expands build result details on request. Possible values are: artifacts, comments, labels,
         Jira Issues, stages. stages expand is available only for top level plans. It allows to drill down to job results
         using stages.stage.results.result. All expand parameters should contain results.result prefix.
         :param plan_key: Should be in the form XX-YY[-ZZ]
+        :param include_all_states:
         """
         try:
             resource = "result/{}/latest.json".format(plan_key)
             return self.base_list_call(resource, expand, favourite=False, clover_enabled=False,
-                                       start_index=0, max_results=25)
+                                       start_index=0, max_results=25, include_all_states=include_all_states)
         except ValueError:
             raise ValueError('The key "{}" does not correspond to the latest build result'.format(plan_key))
 

atlassian/bitbucket.py

@@ -24,7 +24,7 @@ def project(self, key):
         :return:
         """
         url = 'rest/api/1.0/projects/{0}'.format(key)
-        return (self.get(url) or {}).get('values')
+        return (self.get(url) or {})
 
     def create_project(self, key, name, description=""):
         """
@@ -669,6 +669,25 @@ def add_pull_request_comment(self, project, repository, pull_request_id, text):
         body = {'text': text}
         return self.post(url, data=body)
 
+    def get_pull_request_comment(self, project, repository, pull_request_id, comment_id):
+        """
+        Retrieves a pull request comment.
+        The authenticated user must have REPO_READ permission
+        for the repository that this pull request targets to call this resource.
+        :param project:
+        :param repository:
+        :param pull_request_id: the ID of the pull request within the repository
+        :param comment_id: the ID of the comment to retrieve
+        :return:
+        """
+        url = ('rest/api/1.0/projects/{project}/repos/{repository}'
+               '/pull-requests/{pullRequestId}/comments/{comment_id}').format(
+            project=project,
+            repository=repository,
+            pullRequestId=pull_request_id,
+            comment_id=comment_id)
+        return self.get(url)
+
     def get_pullrequest(self, project, repository, pull_request_id):
         """
         Retrieve a pull request.

atlassian/confluence.py

@@ -84,6 +84,16 @@ def get_page_id(self, space, title):
         """
         return (self.get_page_by_title(space, title) or {}).get('id')
 
+    def get_parent_content_id(self, page_id):
+        """
+        Provide parent content id from page id
+        :type page_id: str
+        :return:
+        """
+        parent_content_id = ((self.get_page_by_id(page_id=page_id, expand='ancestors').get('ancestors') or {})[-1].get(
+            'id') or None)
+        return parent_content_id
+
     def get_page_space(self, page_id):
         """
         Provide space key from content id
@@ -124,7 +134,11 @@ def get_page_by_id(self, page_id, expand=None):
         """
         Get page by ID
         :param page_id: Content ID
-        :param expand: OPTIONAL: expand e.g. history
+        :param expand: OPTIONAL: A comma separated list of properties to expand on the content.
+                       Default value: history,space,version We can also specify some extensions
+                       such as extensions.inlineProperties
+                       (for getting inline comment-specific properties) or extensions.resolution
+                       for the resolution status of each comment in the results
         :return:
         """
         params = {}
@@ -202,7 +216,7 @@ def get_all_pages_by_label(self, label, start=0, limit=50):
         url = 'rest/api/content/search'
         params = {}
         if label:
-            params['cql'] = 'type={type}%20AND%20label={label}'.format(type='page',
+            params['cql'] = 'type={type} AND label={label}'.format(type='page',
                                                                        label=label)
         if start:
             params['start'] = start
@@ -364,19 +378,22 @@ def create_page(self, space, title, body, parent_id=None, type='page',
             data['ancestors'] = [{'type': type, 'id': parent_id}]
         return self.post(url, data=data)
 
-    def get_all_spaces(self, start=0, limit=500):
+    def get_all_spaces(self, start=0, limit=500, expand=None):
         """
         Get all spaces with provided limit
         :param start: OPTIONAL: The start point of the collection to return. Default: None (0).
         :param limit: OPTIONAL: The limit of the number of pages to return, this may be restricted by
                             fixed system limits. Default: 500
+        :param expand: OPTIONAL: additional info, e.g. metadata, icon, description, homepage
         """
         url = 'rest/api/space'
         params = {}
-        if limit:
-            params['limit'] = limit
         if start:
             params['start'] = start
+        if limit:
+            params['limit'] = limit
+        if expand:
+            params['expand'] = expand
         return (self.get(url, params=params) or {}).get('results')
 
     def add_comment(self, page_id, text):
@@ -671,10 +688,10 @@ def update_page(self, page_id, title, body, parent_id=None, type='page', represe
                     minor_edit=False):
         """
         Update page if already exist
-        :param parent_id:
         :param page_id:
         :param title:
         :param body:
+        :param parent_id:
         :param type:
         :param representation: OPTIONAL: either Confluence 'storage' or 'wiki' markup format
         :param minor_edit: Indicates whether to notify watchers about changes.
@@ -702,7 +719,7 @@ def update_page(self, page_id, title, body, parent_id=None, type='page', represe
 
             return self.put('rest/api/content/{0}'.format(page_id), data=data)
 
-    def append_page(self, parent_id, page_id, title, append_body, type='page', representation='storage',
+    def append_page(self, page_id, title, append_body, parent_id=None, type='page', representation='storage',
                     minor_edit=False):
         """
         Append body to page if already exist
@@ -741,21 +758,23 @@ def append_page(self, parent_id, page_id, title, append_body, type='page', repre
 
             return self.put('rest/api/content/{0}'.format(page_id), data=data)
 
-    def update_or_create(self, parent_id, title, body, representation='storage'):
+    def update_or_create(self, parent_id, title, body, representation='storage', minor_edit=False):
         """
         Update page or create a page if it is not exists
         :param parent_id:
         :param title:
         :param body:
         :param representation: OPTIONAL: either Confluence 'storage' or 'wiki' markup format
+        :param minor_edit: Update page without notification
         :return:
         """
         space = self.get_page_space(parent_id)
 
         if self.page_exists(space, title):
             page_id = self.get_page_id(space, title)
+            parent_id = self.get_parent_content_id(page_id)
             result = self.update_page(parent_id=parent_id, page_id=page_id, title=title, body=body,
-                                      representation=representation)
+                                      representation=representation, minor_edit=minor_edit)
         else:
             result = self.create_page(space=space, parent_id=parent_id, title=title, body=body,
                                       representation=representation)
@@ -1200,3 +1219,56 @@ def audit(self, start_date=None, end_date=None, start=None, limit=None, search_s
         if search_string:
             params['searchString'] = search_string
         return self.get(url, params=params)
+
+    """
+    ##############################################################################################
+    #   Team Calendars REST API implements  (https://jira.atlassian.com/browse/CONFSERVER-51003) #
+    ##############################################################################################
+    """
+
+    def team_calendars_get_sub_calendars(self, include=None, viewing_space_key=None, calendar_context=None):
+        """
+        Get subscribed calendars
+        :param include:
+        :param viewing_space_key:
+        :param calendar_context:
+        :return:
+        """
+        url = 'rest/calendar-services/1.0/calendar/subcalendars'
+        params = {}
+        if include:
+            params['include'] = include
+        if viewing_space_key:
+            params['viewingSpaceKey'] = viewing_space_key
+        if calendar_context:
+            params['calendarContext'] = calendar_context
+        return self.get(url, params=params)
+
+    def team_calendars_get_sub_calendars_watching_status(self, include=None):
+        url = 'rest/calendar-services/1.0/calendar/subcalendars/watching/status'
+        params = {}
+        if include:
+            params['include'] = include
+        return self.get(url, params=params)
+
+    def team_calendar_events(self, sub_calendar_id, start, end, user_time_zone_id=None):
+        """
+        Get calendar event status
+        :param sub_calendar_id:
+        :param start:
+        :param end:
+        :param user_time_zone_id:
+        :return:
+        """
+        url = 'rest/calendar-services/1.0/calendar/events'
+        params = {}
+        if sub_calendar_id:
+            params['subCalendarId'] = sub_calendar_id
+        if user_time_zone_id:
+            params['userTimeZoneId'] = user_time_zone_id
+        if start:
+            params['start'] = start
+        if end:
+            params['start'] = end
+        return self.get(url, params=params)
+