feat(api): support head() method for get and list endpoints

nejch · JohnVillalovos · commit ce9216ccc542 · 2022-06-25T09:30:03.000-07:00
diff --git a/gitlab/exceptions.py b/gitlab/exceptions.py
@@ -82,6 +82,10 @@ class GitlabGetError(GitlabOperationError):
     pass
 
 
+class GitlabHeadError(GitlabOperationError):
+    pass
+
+
 class GitlabCreateError(GitlabOperationError):
     pass
 
diff --git a/gitlab/mixins.py b/gitlab/mixins.py
@@ -68,7 +68,35 @@
     _RestObjectBase = object
 
 
-class GetMixin(_RestManagerBase):
+class HeadMixin(_RestManagerBase):
+    @exc.on_http_error(exc.GitlabHeadError)
+    def head(
+        self, id: Optional[Union[str, int]] = None, **kwargs: Any
+    ) -> requests.structures.CaseInsensitiveDict:
+        """Retrieve headers from an endpoint.
+
+        Args:
+            id: ID of the object to retrieve
+            **kwargs: Extra options to send to the server (e.g. sudo)
+
+        Returns:
+            A requests header object.
+
+        Raises:
+            GitlabAuthenticationError: If authentication is not correct
+            GitlabHeadError: If the server cannot perform the request
+        """
+        if TYPE_CHECKING:
+            assert self.path is not None
+
+        path = self.path
+        if id is not None:
+            path = f"{path}/{utils.EncodedId(id)}"
+
+        return self.gitlab.http_head(path, **kwargs)
+
+
+class GetMixin(HeadMixin, _RestManagerBase):
     _computed_path: Optional[str]
     _from_parent_attrs: Dict[str, Any]
     _obj_cls: Optional[Type[base.RESTObject]]
@@ -113,7 +141,7 @@ def get(
         return self._obj_cls(self, server_data)
 
 
-class GetWithoutIdMixin(_RestManagerBase):
+class GetWithoutIdMixin(HeadMixin, _RestManagerBase):
     _computed_path: Optional[str]
     _from_parent_attrs: Dict[str, Any]
     _obj_cls: Optional[Type[base.RESTObject]]
@@ -181,7 +209,7 @@ def refresh(self, **kwargs: Any) -> None:
         self._update_attrs(server_data)
 
 
-class ListMixin(_RestManagerBase):
+class ListMixin(HeadMixin, _RestManagerBase):
     _computed_path: Optional[str]
     _from_parent_attrs: Dict[str, Any]
     _list_filters: Tuple[str, ...] = ()
diff --git a/tests/functional/api/test_projects.py b/tests/functional/api/test_projects.py
@@ -6,6 +6,16 @@
 from gitlab.v4.objects.projects import ProjectStorage
 
 
+def test_projects_head(gl):
+    headers = gl.projects.head()
+    assert headers["x-total"]
+
+
+def test_project_head(gl, project):
+    headers = gl.projects.head(project.id)
+    assert headers["content-type"] == "application/json"
+
+
 def test_create_project(gl, user):
     # Moved from group tests chunk in legacy tests, TODO cleanup
     admin_project = gl.projects.create({"name": "admin_project"})
diff --git a/tests/functional/api/test_repository.py b/tests/functional/api/test_repository.py
@@ -40,6 +40,9 @@ def test_repository_files(project):
     # object method
     assert readme.decode().decode() == "Initial content"
 
+    headers = project.files.head("README.rst", ref="main")
+    assert headers["X-Gitlab-File-Path"] == "README.rst"
+
     blame = project.files.blame(file_path="README.rst", ref="main")
     assert blame
 
diff --git a/tests/unit/mixins/test_mixin_methods.py b/tests/unit/mixins/test_mixin_methods.py
@@ -1,4 +1,5 @@
 import pytest
+import requests
 import responses
 
 from gitlab import base
@@ -47,6 +48,26 @@ class M(GetMixin, FakeManager):
     assert responses.assert_call_count(url, 1) is True
 
 
+@responses.activate
+def test_head_mixin(gl):
+    class M(GetMixin, FakeManager):
+        pass
+
+    url = "http://localhost/api/v4/tests/42"
+    responses.add(
+        method=responses.HEAD,
+        url=url,
+        headers={"X-GitLab-Header": "test"},
+        status=200,
+        match=[responses.matchers.query_param_matcher({})],
+    )
+
+    manager = M(gl)
+    result = manager.head(42)
+    assert isinstance(result, requests.structures.CaseInsensitiveDict)
+    assert result["x-gitlab-header"] == "test"
+
+
 @responses.activate
 def test_refresh_mixin(gl):
     class TestClass(RefreshMixin, FakeObject):
