python-gitlab 5.3.1__py3-none-any.whl → 5.5.0__py3-none-any.whl

gitlab/_version.py

@@ -3,4 +3,4 @@ __copyright__ = "Copyright 2013-2019 Gauvain Pocentek, 2019-2023 python-gitlab t
 __email__ = "gauvainpocentek@gmail.com"
 __license__ = "LGPL3"
 __title__ = "python-gitlab"
-__version__ = "5.3.1"
+__version__ = "5.5.0"

gitlab/client.py

@@ -654,6 +654,7 @@ class Gitlab:
         obey_rate_limit: bool = True,
         retry_transient_errors: Optional[bool] = None,
         max_retries: int = 10,
+        extra_headers: Optional[Dict[str, Any]] = None,
         **kwargs: Any,
     ) -> requests.Response:
         """Make an HTTP request to the Gitlab server.
@@ -675,6 +676,7 @@ class Gitlab:
                 or 52x responses. Defaults to False.
             max_retries: Max retries after 429 or transient errors,
                                set to -1 to retry forever. Defaults to 10.
+            extra_headers: Add and override HTTP headers for the request.
             **kwargs: Extra options to send to the server (e.g. sudo)
 
         Returns:
@@ -721,6 +723,9 @@ class Gitlab:
         send_data = self._backend.prepare_send_data(files, post_data, raw)
         opts["headers"]["Content-type"] = send_data.content_type
 
+        if extra_headers is not None:
+            opts["headers"].update(extra_headers)
+
         retry = utils.Retry(
             max_retries=max_retries,
             obey_rate_limit=obey_rate_limit,

gitlab/const.py

@@ -9,83 +9,83 @@ class GitlabEnum(str, Enum):
 
 # https://gitlab.com/gitlab-org/gitlab/-/blob/e97357824bedf007e75f8782259fe07435b64fbb/lib/gitlab/access.rb#L12-18
 class AccessLevel(IntEnum):
-    NO_ACCESS: int = 0
-    MINIMAL_ACCESS: int = 5
-    GUEST: int = 10
-    PLANNER: int = 15
-    REPORTER: int = 20
-    DEVELOPER: int = 30
-    MAINTAINER: int = 40
-    OWNER: int = 50
-    ADMIN: int = 60
+    NO_ACCESS = 0
+    MINIMAL_ACCESS = 5
+    GUEST = 10
+    PLANNER = 15
+    REPORTER = 20
+    DEVELOPER = 30
+    MAINTAINER = 40
+    OWNER = 50
+    ADMIN = 60
 
 
 # https://gitlab.com/gitlab-org/gitlab/-/blob/e97357824bedf007e75f8782259fe07435b64fbb/lib/gitlab/visibility_level.rb#L23-25
 class Visibility(GitlabEnum):
-    PRIVATE: str = "private"
-    INTERNAL: str = "internal"
-    PUBLIC: str = "public"
+    PRIVATE = "private"
+    INTERNAL = "internal"
+    PUBLIC = "public"
 
 
 class NotificationLevel(GitlabEnum):
-    DISABLED: str = "disabled"
-    PARTICIPATING: str = "participating"
-    WATCH: str = "watch"
-    GLOBAL: str = "global"
-    MENTION: str = "mention"
-    CUSTOM: str = "custom"
+    DISABLED = "disabled"
+    PARTICIPATING = "participating"
+    WATCH = "watch"
+    GLOBAL = "global"
+    MENTION = "mention"
+    CUSTOM = "custom"
 
 
 # https://gitlab.com/gitlab-org/gitlab/-/blob/e97357824bedf007e75f8782259fe07435b64fbb/app/views/search/_category.html.haml#L10-37
 class SearchScope(GitlabEnum):
     # all scopes (global, group and  project)
-    PROJECTS: str = "projects"
-    ISSUES: str = "issues"
-    MERGE_REQUESTS: str = "merge_requests"
-    MILESTONES: str = "milestones"
-    WIKI_BLOBS: str = "wiki_blobs"
-    COMMITS: str = "commits"
-    BLOBS: str = "blobs"
-    USERS: str = "users"
+    PROJECTS = "projects"
+    ISSUES = "issues"
+    MERGE_REQUESTS = "merge_requests"
+    MILESTONES = "milestones"
+    WIKI_BLOBS = "wiki_blobs"
+    COMMITS = "commits"
+    BLOBS = "blobs"
+    USERS = "users"
 
     # specific global scope
-    GLOBAL_SNIPPET_TITLES: str = "snippet_titles"
+    GLOBAL_SNIPPET_TITLES = "snippet_titles"
 
     # specific project scope
-    PROJECT_NOTES: str = "notes"
+    PROJECT_NOTES = "notes"
 
 
 # https://docs.gitlab.com/ee/api/merge_requests.html#merge-status
 class DetailedMergeStatus(GitlabEnum):
     # possible values for the detailed_merge_status field of Merge Requests
-    BLOCKED_STATUS: str = "blocked_status"
-    BROKEN_STATUS: str = "broken_status"
-    CHECKING: str = "checking"
-    UNCHECKED: str = "unchecked"
-    CI_MUST_PASS: str = "ci_must_pass"
-    CI_STILL_RUNNING: str = "ci_still_running"
-    DISCUSSIONS_NOT_RESOLVED: str = "discussions_not_resolved"
-    DRAFT_STATUS: str = "draft_status"
-    EXTERNAL_STATUS_CHECKS: str = "external_status_checks"
-    MERGEABLE: str = "mergeable"
-    NOT_APPROVED: str = "not_approved"
-    NOT_OPEN: str = "not_open"
-    POLICIES_DENIED: str = "policies_denied"
+    BLOCKED_STATUS = "blocked_status"
+    BROKEN_STATUS = "broken_status"
+    CHECKING = "checking"
+    UNCHECKED = "unchecked"
+    CI_MUST_PASS = "ci_must_pass"
+    CI_STILL_RUNNING = "ci_still_running"
+    DISCUSSIONS_NOT_RESOLVED = "discussions_not_resolved"
+    DRAFT_STATUS = "draft_status"
+    EXTERNAL_STATUS_CHECKS = "external_status_checks"
+    MERGEABLE = "mergeable"
+    NOT_APPROVED = "not_approved"
+    NOT_OPEN = "not_open"
+    POLICIES_DENIED = "policies_denied"
 
 
 # https://docs.gitlab.com/ee/api/pipelines.html
 class PipelineStatus(GitlabEnum):
-    CREATED: str = "created"
-    WAITING_FOR_RESOURCE: str = "waiting_for_resource"
-    PREPARING: str = "preparing"
-    PENDING: str = "pending"
-    RUNNING: str = "running"
-    SUCCESS: str = "success"
-    FAILED: str = "failed"
-    CANCELED: str = "canceled"
-    SKIPPED: str = "skipped"
-    MANUAL: str = "manual"
-    SCHEDULED: str = "scheduled"
+    CREATED = "created"
+    WAITING_FOR_RESOURCE = "waiting_for_resource"
+    PREPARING = "preparing"
+    PENDING = "pending"
+    RUNNING = "running"
+    SUCCESS = "success"
+    FAILED = "failed"
+    CANCELED = "canceled"
+    SKIPPED = "skipped"
+    MANUAL = "manual"
+    SCHEDULED = "scheduled"
 
 
 DEFAULT_URL: str = "https://gitlab.com"

gitlab/mixins.py

@@ -6,7 +6,9 @@ from typing import (
     Dict,
     Iterator,
     List,
+    Literal,
     Optional,
+    overload,
     Tuple,
     Type,
     TYPE_CHECKING,
@@ -612,12 +614,45 @@ class DownloadMixin(_RestObjectBase):
     _updated_attrs: Dict[str, Any]
     manager: base.RESTManager
 
+    @overload
+    def download(
+        self,
+        streamed: Literal[False] = False,
+        action: None = None,
+        chunk_size: int = 1024,
+        *,
+        iterator: Literal[False] = False,
+        **kwargs: Any,
+    ) -> bytes: ...
+
+    @overload
+    def download(
+        self,
+        streamed: bool = False,
+        action: None = None,
+        chunk_size: int = 1024,
+        *,
+        iterator: Literal[True] = True,
+        **kwargs: Any,
+    ) -> Iterator[Any]: ...
+
+    @overload
+    def download(
+        self,
+        streamed: Literal[True] = True,
+        action: Optional[Callable[[bytes], Any]] = None,
+        chunk_size: int = 1024,
+        *,
+        iterator: Literal[False] = False,
+        **kwargs: Any,
+    ) -> None: ...
+
     @cli.register_custom_action(cls_names=("GroupExport", "ProjectExport"))
     @exc.on_http_error(exc.GitlabGetError)
     def download(
         self,
         streamed: bool = False,
-        action: Optional[Callable[[bytes], None]] = None,
+        action: Optional[Callable[[bytes], Any]] = None,
         chunk_size: int = 1024,
         *,
         iterator: bool = False,

gitlab/utils.py

@@ -77,7 +77,7 @@ class MaskingFormatter(logging.Formatter):
 def response_content(
     response: requests.Response,
     streamed: bool,
-    action: Optional[Callable[[bytes], None]],
+    action: Optional[Callable[[bytes], Any]],
     chunk_size: int,
     *,
     iterator: bool,

gitlab/v4/objects/__init__.py

@@ -68,6 +68,7 @@ from .settings import *
 from .sidekiq import *
 from .snippets import *
 from .statistics import *
+from .status_checks import *
 from .tags import *
 from .templates import *
 from .todos import *

gitlab/v4/objects/artifacts.py

@@ -3,7 +3,16 @@ GitLab API:
 https://docs.gitlab.com/ee/api/job_artifacts.html
 """
 
-from typing import Any, Callable, Iterator, Optional, TYPE_CHECKING, Union
+from typing import (
+    Any,
+    Callable,
+    Iterator,
+    Literal,
+    Optional,
+    overload,
+    TYPE_CHECKING,
+    Union,
+)
 
 import requests
 
@@ -43,6 +52,45 @@ class ProjectArtifactManager(RESTManager):
             assert path is not None
         self.gitlab.http_delete(path, **kwargs)
 
+    @overload
+    def download(
+        self,
+        ref_name: str,
+        job: str,
+        streamed: Literal[False] = False,
+        action: None = None,
+        chunk_size: int = 1024,
+        *,
+        iterator: Literal[False] = False,
+        **kwargs: Any,
+    ) -> bytes: ...
+
+    @overload
+    def download(
+        self,
+        ref_name: str,
+        job: str,
+        streamed: bool = False,
+        action: None = None,
+        chunk_size: int = 1024,
+        *,
+        iterator: Literal[True] = True,
+        **kwargs: Any,
+    ) -> Iterator[Any]: ...
+
+    @overload
+    def download(
+        self,
+        ref_name: str,
+        job: str,
+        streamed: Literal[True] = True,
+        action: Optional[Callable[[bytes], Any]] = None,
+        chunk_size: int = 1024,
+        *,
+        iterator: Literal[False] = False,
+        **kwargs: Any,
+    ) -> None: ...
+
     @cli.register_custom_action(
         cls_names="ProjectArtifactManager",
         required=("ref_name", "job"),
@@ -54,7 +102,7 @@ class ProjectArtifactManager(RESTManager):
         ref_name: str,
         job: str,
         streamed: bool = False,
-        action: Optional[Callable[[bytes], None]] = None,
+        action: Optional[Callable[[bytes], Any]] = None,
         chunk_size: int = 1024,
         *,
         iterator: bool = False,
@@ -94,6 +142,48 @@ class ProjectArtifactManager(RESTManager):
             result, streamed, action, chunk_size, iterator=iterator
         )
 
+    @overload
+    def raw(
+        self,
+        ref_name: str,
+        artifact_path: str,
+        job: str,
+        streamed: Literal[False] = False,
+        action: None = None,
+        chunk_size: int = 1024,
+        *,
+        iterator: Literal[False] = False,
+        **kwargs: Any,
+    ) -> bytes: ...
+
+    @overload
+    def raw(
+        self,
+        ref_name: str,
+        artifact_path: str,
+        job: str,
+        streamed: bool = False,
+        action: None = None,
+        chunk_size: int = 1024,
+        *,
+        iterator: Literal[True] = True,
+        **kwargs: Any,
+    ) -> Iterator[Any]: ...
+
+    @overload
+    def raw(
+        self,
+        ref_name: str,
+        artifact_path: str,
+        job: str,
+        streamed: Literal[True] = True,
+        action: Optional[Callable[[bytes], Any]] = None,
+        chunk_size: int = 1024,
+        *,
+        iterator: Literal[False] = False,
+        **kwargs: Any,
+    ) -> None: ...
+
     @cli.register_custom_action(
         cls_names="ProjectArtifactManager",
         required=("ref_name", "artifact_path", "job"),
@@ -105,7 +195,7 @@ class ProjectArtifactManager(RESTManager):
         artifact_path: str,
         job: str,
         streamed: bool = False,
-        action: Optional[Callable[[bytes], None]] = None,
+        action: Optional[Callable[[bytes], Any]] = None,
         chunk_size: int = 1024,
         *,
         iterator: bool = False,

gitlab/v4/objects/commits.py

@@ -48,7 +48,9 @@ class ProjectCommit(RESTObject):
 
     @cli.register_custom_action(cls_names="ProjectCommit", required=("branch",))
     @exc.on_http_error(exc.GitlabCherryPickError)
-    def cherry_pick(self, branch: str, **kwargs: Any) -> None:
+    def cherry_pick(
+        self, branch: str, **kwargs: Any
+    ) -> Union[Dict[str, Any], requests.Response]:
         """Cherry-pick a commit into a branch.
 
         Args:
@@ -58,10 +60,13 @@ class ProjectCommit(RESTObject):
         Raises:
             GitlabAuthenticationError: If authentication is not correct
             GitlabCherryPickError: If the cherry-pick could not be performed
+
+        Returns:
+            The new commit data (*not* a RESTObject)
         """
         path = f"{self.manager.path}/{self.encoded_id}/cherry_pick"
         post_data = {"branch": branch}
-        self.manager.gitlab.http_post(path, post_data=post_data, **kwargs)
+        return self.manager.gitlab.http_post(path, post_data=post_data, **kwargs)
 
     @cli.register_custom_action(cls_names="ProjectCommit", optional=("type",))
     @exc.on_http_error(exc.GitlabGetError)

gitlab/v4/objects/files.py

@@ -5,7 +5,9 @@ from typing import (
     Dict,
     Iterator,
     List,
+    Literal,
     Optional,
+    overload,
     Tuple,
     TYPE_CHECKING,
     Union,
@@ -51,7 +53,7 @@ class ProjectFile(SaveMixin, ObjectDeleteMixin, RESTObject):
 
     # NOTE(jlvillal): Signature doesn't match SaveMixin.save() so ignore
     # type error
-    def save(  # type: ignore
+    def save(  # type: ignore[override]
         self, branch: str, commit_message: str, **kwargs: Any
     ) -> None:
         """Save the changes made to the file to the server.
@@ -75,7 +77,7 @@ class ProjectFile(SaveMixin, ObjectDeleteMixin, RESTObject):
     @exc.on_http_error(exc.GitlabDeleteError)
     # NOTE(jlvillal): Signature doesn't match DeleteMixin.delete() so ignore
     # type error
-    def delete(  # type: ignore
+    def delete(  # type: ignore[override]
         self, branch: str, commit_message: str, **kwargs: Any
     ) -> None:
         """Delete the file from the server.
@@ -219,7 +221,7 @@ class ProjectFileManager(CreateMixin, UpdateMixin, DeleteMixin, RESTManager):
     @exc.on_http_error(exc.GitlabUpdateError)
     # NOTE(jlvillal): Signature doesn't match UpdateMixin.update() so ignore
     # type error
-    def update(  # type: ignore
+    def update(  # type: ignore[override]
         self, file_path: str, new_data: Optional[Dict[str, Any]] = None, **kwargs: Any
     ) -> Dict[str, Any]:
         """Update an object on the server.
@@ -254,7 +256,7 @@ class ProjectFileManager(CreateMixin, UpdateMixin, DeleteMixin, RESTManager):
     @exc.on_http_error(exc.GitlabDeleteError)
     # NOTE(jlvillal): Signature doesn't match DeleteMixin.delete() so ignore
     # type error
-    def delete(  # type: ignore
+    def delete(  # type: ignore[override]
         self, file_path: str, branch: str, commit_message: str, **kwargs: Any
     ) -> None:
         """Delete a file on the server.
@@ -274,9 +276,49 @@ class ProjectFileManager(CreateMixin, UpdateMixin, DeleteMixin, RESTManager):
         data = {"branch": branch, "commit_message": commit_message}
         self.gitlab.http_delete(path, query_data=data, **kwargs)
 
+    @overload
+    def raw(
+        self,
+        file_path: str,
+        ref: Optional[str] = None,
+        streamed: Literal[False] = False,
+        action: None = None,
+        chunk_size: int = 1024,
+        *,
+        iterator: Literal[False] = False,
+        **kwargs: Any,
+    ) -> bytes: ...
+
+    @overload
+    def raw(
+        self,
+        file_path: str,
+        ref: Optional[str] = None,
+        streamed: bool = False,
+        action: None = None,
+        chunk_size: int = 1024,
+        *,
+        iterator: Literal[True] = True,
+        **kwargs: Any,
+    ) -> Iterator[Any]: ...
+
+    @overload
+    def raw(
+        self,
+        file_path: str,
+        ref: Optional[str] = None,
+        streamed: Literal[True] = True,
+        action: Optional[Callable[[bytes], Any]] = None,
+        chunk_size: int = 1024,
+        *,
+        iterator: Literal[False] = False,
+        **kwargs: Any,
+    ) -> None: ...
+
     @cli.register_custom_action(
         cls_names="ProjectFileManager",
         required=("file_path",),
+        optional=("ref",),
     )
     @exc.on_http_error(exc.GitlabGetError)
     def raw(

gitlab/v4/objects/issues.py

@@ -302,7 +302,7 @@ class ProjectIssueLinkManager(ListMixin, CreateMixin, DeleteMixin, RESTManager):
     @exc.on_http_error(exc.GitlabCreateError)
     # NOTE(jlvillal): Signature doesn't match CreateMixin.create() so ignore
     # type error
-    def create(  # type: ignore
+    def create(  # type: ignore[override]
         self, data: Dict[str, Any], **kwargs: Any
     ) -> Tuple[RESTObject, RESTObject]:
         """Create a new object.

gitlab/v4/objects/jobs.py

@@ -1,4 +1,15 @@
-from typing import Any, Callable, cast, Dict, Iterator, Optional, TYPE_CHECKING, Union
+from typing import (
+    Any,
+    Callable,
+    cast,
+    Dict,
+    Iterator,
+    Literal,
+    Optional,
+    overload,
+    TYPE_CHECKING,
+    Union,
+)
 
 import requests
 
@@ -115,6 +126,39 @@ class ProjectJob(RefreshMixin, RESTObject):
         path = f"{self.manager.path}/{self.encoded_id}/artifacts"
         self.manager.gitlab.http_delete(path, **kwargs)
 
+    @overload
+    def artifacts(
+        self,
+        streamed: Literal[False] = False,
+        action: None = None,
+        chunk_size: int = 1024,
+        *,
+        iterator: Literal[False] = False,
+        **kwargs: Any,
+    ) -> bytes: ...
+
+    @overload
+    def artifacts(
+        self,
+        streamed: bool = False,
+        action: None = None,
+        chunk_size: int = 1024,
+        *,
+        iterator: Literal[True] = True,
+        **kwargs: Any,
+    ) -> Iterator[Any]: ...
+
+    @overload
+    def artifacts(
+        self,
+        streamed: Literal[True] = True,
+        action: Optional[Callable[[bytes], Any]] = None,
+        chunk_size: int = 1024,
+        *,
+        iterator: Literal[False] = False,
+        **kwargs: Any,
+    ) -> None: ...
+
     @cli.register_custom_action(cls_names="ProjectJob")
     @exc.on_http_error(exc.GitlabGetError)
     def artifacts(
@@ -156,6 +200,42 @@ class ProjectJob(RefreshMixin, RESTObject):
             result, streamed, action, chunk_size, iterator=iterator
         )
 
+    @overload
+    def artifact(
+        self,
+        path: str,
+        streamed: Literal[False] = False,
+        action: None = None,
+        chunk_size: int = 1024,
+        *,
+        iterator: Literal[False] = False,
+        **kwargs: Any,
+    ) -> bytes: ...
+
+    @overload
+    def artifact(
+        self,
+        path: str,
+        streamed: bool = False,
+        action: None = None,
+        chunk_size: int = 1024,
+        *,
+        iterator: Literal[True] = True,
+        **kwargs: Any,
+    ) -> Iterator[Any]: ...
+
+    @overload
+    def artifact(
+        self,
+        path: str,
+        streamed: Literal[True] = True,
+        action: Optional[Callable[[bytes], Any]] = None,
+        chunk_size: int = 1024,
+        *,
+        iterator: Literal[False] = False,
+        **kwargs: Any,
+    ) -> None: ...
+
     @cli.register_custom_action(cls_names="ProjectJob")
     @exc.on_http_error(exc.GitlabGetError)
     def artifact(
@@ -199,6 +279,39 @@ class ProjectJob(RefreshMixin, RESTObject):
             result, streamed, action, chunk_size, iterator=iterator
         )
 
+    @overload
+    def trace(
+        self,
+        streamed: Literal[False] = False,
+        action: None = None,
+        chunk_size: int = 1024,
+        *,
+        iterator: Literal[False] = False,
+        **kwargs: Any,
+    ) -> bytes: ...
+
+    @overload
+    def trace(
+        self,
+        streamed: bool = False,
+        action: None = None,
+        chunk_size: int = 1024,
+        *,
+        iterator: Literal[True] = True,
+        **kwargs: Any,
+    ) -> Iterator[Any]: ...
+
+    @overload
+    def trace(
+        self,
+        streamed: Literal[True] = True,
+        action: Optional[Callable[[bytes], Any]] = None,
+        chunk_size: int = 1024,
+        *,
+        iterator: Literal[False] = False,
+        **kwargs: Any,
+    ) -> None: ...
+
     @cli.register_custom_action(cls_names="ProjectJob")
     @exc.on_http_error(exc.GitlabGetError)
     def trace(

gitlab/v4/objects/labels.py

@@ -66,7 +66,7 @@ class GroupLabelManager(
     # Update without ID.
     # NOTE(jlvillal): Signature doesn't match UpdateMixin.update() so ignore
     # type error
-    def update(  # type: ignore
+    def update(  # type: ignore[override]
         self,
         name: Optional[str],
         new_data: Optional[Dict[str, Any]] = None,
@@ -132,7 +132,7 @@ class ProjectLabelManager(
     # Update without ID.
     # NOTE(jlvillal): Signature doesn't match UpdateMixin.update() so ignore
     # type error
-    def update(  # type: ignore
+    def update(  # type: ignore[override]
         self,
         name: Optional[str],
         new_data: Optional[Dict[str, Any]] = None,

gitlab/v4/objects/merge_requests.py

@@ -44,6 +44,7 @@ from .merge_request_approvals import (  # noqa: F401
 from .notes import ProjectMergeRequestNoteManager  # noqa: F401
 from .pipelines import ProjectMergeRequestPipelineManager  # noqa: F401
 from .reviewers import ProjectMergeRequestReviewerDetailManager
+from .status_checks import ProjectMergeRequestStatusCheckManager
 
 __all__ = [
     "MergeRequest",
@@ -167,6 +168,7 @@ class ProjectMergeRequest(
     resourcemilestoneevents: ProjectMergeRequestResourceMilestoneEventManager
     resourcestateevents: ProjectMergeRequestResourceStateEventManager
     reviewer_details: ProjectMergeRequestReviewerDetailManager
+    status_checks: ProjectMergeRequestStatusCheckManager
 
     @cli.register_custom_action(cls_names="ProjectMergeRequest")
     @exc.on_http_error(exc.GitlabMROnBuildSuccessError)