Bitbucket Cloud: Add branches and tags repository endpoints (#921)

Note that this currently does not support the generic
refs endpoint.

Signed-off-by: Frank Lichtenheld <frank@lichtenheld.com>

Author: flichtenheld

atlassian/bitbucket/cloud/repositories/__init__.py

@@ -7,6 +7,7 @@
 from .defaultReviewers import DefaultReviewers
 from .pipelines import Pipelines
 from .pullRequests import PullRequests
+from .refs import Branches, Tags
 
 
 class RepositoriesBase(BitbucketCloudBase):
@@ -225,10 +226,12 @@ def __init__(self, data, *args, **kwargs):
         self.__branch_restrictions = BranchRestrictions(
             "{}/branch-restrictions".format(self.url), **self._new_session_args
         )
+        self.__branches = Branches("{}/refs/branches".format(self.url), **self._new_session_args)
         self.__default_reviewers = DefaultReviewers("{}/default-reviewers".format(self.url), **self._new_session_args)
         self.__issues = Issues("{}/issues".format(self.url), **self._new_session_args)
         self.__pipelines = Pipelines("{}/pipelines".format(self.url), **self._new_session_args)
         self.__pullrequests = PullRequests("{}/pullrequests".format(self.url), **self._new_session_args)
+        self.__tags = Tags("{}/refs/tags".format(self.url), **self._new_session_args)
 
     def update(self, **kwargs):
         """
@@ -329,6 +332,11 @@ def branch_restrictions(self):
         """The repository branch restrictions"""
         return self.__branch_restrictions
 
+    @property
+    def branches(self):
+        """The repository branches."""
+        return self.__branches
+
     @property
     def default_reviewers(self):
         """The repository default reviewers"""
@@ -348,3 +356,8 @@ def pipelines(self):
     def pullrequests(self):
         """The repository pull requests"""
         return self.__pullrequests
+
+    @property
+    def tags(self):
+        """The repository tags."""
+        return self.__tags

atlassian/bitbucket/cloud/repositories/refs.py

@@ -0,0 +1,137 @@
+# coding=utf-8
+
+from ..base import BitbucketCloudBase
+from ..common.users import User
+
+
+class Refs(BitbucketCloudBase):
+    """
+    Bitbucket Cloud Refs.
+
+    Generic base object for any type of ref list.
+    """
+
+    def __init__(self, url, *args, **kwargs):
+        """See BitbucketCloudBase."""
+        super(Refs, self).__init__(url, *args, **kwargs)
+
+    def create(
+        self,
+        name,
+        commit,
+    ):
+        """
+        Creates a ref with the given target commit
+
+        :param name: string: name
+        :param commit: string: commit hash
+
+        :return: Ref
+        """
+
+        data = {"name": name, "target": {"hash": commit}}
+
+        return self._get_object(self.post(None, data))
+
+    def each(self, q=None, sort=None):
+        """
+        Returns the list of refs in this repository.
+
+        :param q: string: Query string to narrow down the response.
+                          See https://developer.atlassian.com/bitbucket/api/2/reference/meta/filtering for details.
+        :param sort: string: Name of a response property to sort results.
+                             See https://developer.atlassian.com/bitbucket/api/2/reference/meta/filtering for details.
+
+        :return: A generator for the Ref objects
+        """
+        params = {}
+        if sort is not None:
+            params["sort"] = sort
+        if q is not None:
+            params["q"] = q
+        for ref in self._get_paged(None, trailing=True, params=params):
+            yield self._get_object(super(Refs, self).get(ref.get("name")))
+
+        return
+
+    def get(self, name):
+        """
+        Returns the Ref with the requested name in the repository.
+
+        :param name: string: The requested name
+
+        :return: The requested Ref object
+        """
+        return self._get_object(super(Refs, self).get(name))
+
+
+class Branches(Refs):
+    """
+    BitBucket Cloud branches endpoint.
+
+    See https://developer.atlassian.com/cloud/bitbucket/rest/api-group-refs/#api-repositories-workspace-repo-slug-refs-branches-get
+    """
+
+    def _get_object(self, data):
+        return Branch(data, **self._new_session_args)
+
+
+class Tags(Refs):
+    """
+    BitBucket Cloud tags endpoint.
+
+    See https://developer.atlassian.com/cloud/bitbucket/rest/api-group-refs/#api-repositories-workspace-repo-slug-refs-tags-get
+    """
+
+    def _get_object(self, data):
+        return Tag(data, **self._new_session_args)
+
+
+class Ref(BitbucketCloudBase):
+    """
+    Base object for individual refs.
+    """
+
+    @property
+    def name(self):
+        """Ref name."""
+        return self.get_data("name")
+
+    @property
+    def hash(self):
+        """Commit hash."""
+        return self.get_data("target")["hash"]
+
+
+class Branch(Ref):
+    """
+    Bitbucket Cloud branch endpoint.
+
+    See https://developer.atlassian.com/cloud/bitbucket/rest/api-group-refs/#api-repositories-workspace-repo-slug-refs-branches-name-get
+    """
+
+    def __init__(self, data, *args, **kwargs):
+        """See BitbucketCloudBase."""
+        super(Branch, self).__init__(None, *args, data=data, expected_type="branch", **kwargs)
+
+    @property
+    def author(self):
+        """User object of the author."""
+        return User(None, self.get_data("author"))
+
+
+class Tag(Ref):
+    """
+    Bitbucket Cloud tags endpoint.
+
+    See https://developer.atlassian.com/cloud/bitbucket/rest/api-group-refs/#api-repositories-workspace-repo-slug-refs-tags-name-get
+    """
+
+    def __init__(self, data, *args, **kwargs):
+        """See BitbucketCloudBase."""
+        super(Tag, self).__init__(None, *args, data=data, expected_type="tag", **kwargs)
+
+    @property
+    def author(self):
+        """User object of the author."""
+        return User(None, self.get_data("tagger"))