python-gitlab 5.3.1__tar.gz → 5.4.0__tar.gz

{python_gitlab-5.3.1 → python_gitlab-5.4.0}/CHANGELOG.md

@@ -1,6 +1,149 @@
 # CHANGELOG
 
 
+## v5.4.0 (2025-01-28)
+
+### Bug Fixes
+
+- **api**: Make type ignores more specific where possible
+  ([`e3cb806`](https://github.com/python-gitlab/python-gitlab/commit/e3cb806dc368af0a495087531ee94892d3f240ce))
+
+Instead of using absolute ignore `# type: ignore` use a more specific ignores like `# type:
+  ignore[override]`. This might help in the future where a new bug might be introduced and get
+  ignored by a general ignore comment but not a more specific one.
+
+Signed-off-by: Igor Ponomarev <igor.ponomarev@collabora.com>
+
+- **api**: Return the new commit when calling cherry_pick
+  ([`de29503`](https://github.com/python-gitlab/python-gitlab/commit/de29503262b7626421f3bffeea3ff073e63e3865))
+
+- **files**: Add optional ref parameter for cli project-file raw (python-gitlab#3032)
+  ([`22f03bd`](https://github.com/python-gitlab/python-gitlab/commit/22f03bdc2bac92138225563415f5cf6fa36a5644))
+
+The ef parameter was removed in python-gitlab v4.8.0. This will add ef back as an optional parameter
+  for the project-file raw cli command.
+
+### Chores
+
+- Fix missing space in deprecation message
+  ([`ba75c31`](https://github.com/python-gitlab/python-gitlab/commit/ba75c31e4d13927b6a3ab0ce427800d94e5eefb4))
+
+- Fix pytest deprecation
+  ([`95db680`](https://github.com/python-gitlab/python-gitlab/commit/95db680d012d73e7e505ee85db7128050ff0db6e))
+
+pytest has changed the function argument name to `start_path`
+
+- Fix warning being generated
+  ([`0eb5eb0`](https://github.com/python-gitlab/python-gitlab/commit/0eb5eb0505c5b837a2d767cfa256a25b64ceb48b))
+
+The CI shows a warning. Use `get_all=False` to resolve issue.
+
+- Resolve DeprecationWarning message in CI run
+  ([`accd5aa`](https://github.com/python-gitlab/python-gitlab/commit/accd5aa757ba5215497c278da50d48f10ea5a258))
+
+Catch the DeprecationWarning in our test, as we expect it.
+
+- **ci**: Set a 30 minute timeout for 'functional' tests
+  ([`e8d6953`](https://github.com/python-gitlab/python-gitlab/commit/e8d6953ec06dbbd817852207abbbc74eab8a27cf))
+
+Currently the functional API test takes around 17 minutes to run. And the functional CLI test takes
+  around 12 minutes to run.
+
+Occasionally a job gets stuck and will sit until the default 360 minutes job timeout occurs.
+
+Now have a 30 minute timeout for the 'functional' tests.
+
+- **deps**: Update all non-major dependencies
+  ([`939505b`](https://github.com/python-gitlab/python-gitlab/commit/939505b9c143939ba1e52c5cb920d8aa36596e19))
+
+- **deps**: Update all non-major dependencies
+  ([`cbd4263`](https://github.com/python-gitlab/python-gitlab/commit/cbd4263194fcbad9d6c11926862691f8df0dea6d))
+
+- **deps**: Update gitlab ([#3088](https://github.com/python-gitlab/python-gitlab/pull/3088),
+  [`9214b83`](https://github.com/python-gitlab/python-gitlab/commit/9214b8371652be2371823b6f3d531eeea78364c7))
+
+Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
+
+- **deps**: Update gitlab/gitlab-ee docker tag to v17.7.1-ee.0
+  ([#3082](https://github.com/python-gitlab/python-gitlab/pull/3082),
+  [`1e95944`](https://github.com/python-gitlab/python-gitlab/commit/1e95944119455875bd239752cdf0fe5cc27707ea))
+
+Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
+
+- **deps**: Update mypy to 1.14 and resolve issues
+  ([`671e711`](https://github.com/python-gitlab/python-gitlab/commit/671e711c341d28ae0bc61ccb12d2e986353473fd))
+
+mypy 1.14 has a change to Enum Membership Semantics:
+  https://mypy.readthedocs.io/en/latest/changelog.html
+
+Resolve the issues with Enum and typing, and update mypy to 1.14
+
+- **test**: Prevent 'job_with_artifact' fixture running forever
+  ([`e4673d8`](https://github.com/python-gitlab/python-gitlab/commit/e4673d8aeaf97b9ad5d2500e459526b4cf494547))
+
+Previously the 'job_with_artifact' fixture could run forever. Now give it up to 60 seconds to
+  complete before failing.
+
+### Continuous Integration
+
+- Use gitlab-runner:v17.7.1 for the CI
+  ([`2dda9dc`](https://github.com/python-gitlab/python-gitlab/commit/2dda9dc149668a99211daaa1981bb1f422c63880))
+
+The `latest` gitlab-runner image does not have the `gitlab-runner` user and it causes our tests to
+  fail.
+
+Closes: #3091
+
+### Features
+
+- **api**: Add argument that appends extra HTTP headers to a request
+  ([`fb07b5c`](https://github.com/python-gitlab/python-gitlab/commit/fb07b5cfe1d986c3a7cd7879b11ecc43c75542b7))
+
+Currently the only way to manipulate the headers for a request is to use `Gitlab.headers` attribute.
+  However, this makes it very concurrently unsafe because the `Gitlab` object can be shared between
+  multiple requests at the same time.
+
+Instead add a new keyword argument `extra_headers` which will update the headers dictionary with new
+  values just before the request is sent.
+
+For example, this can be used to download a part of a artifacts file using the `Range` header:
+  https://developer.mozilla.org/en-US/docs/Web/HTTP/Range_requests
+
+Signed-off-by: Igor Ponomarev <igor.ponomarev@collabora.com>
+
+- **api**: Add support for external status check
+  ([`175b355`](https://github.com/python-gitlab/python-gitlab/commit/175b355d84d54a71f15fe3601c5275dc35984b9b))
+
+- **api**: Narrow down return type of download methods using typing.overload
+  ([`44fd9dc`](https://github.com/python-gitlab/python-gitlab/commit/44fd9dc1176a2c5529c45cc3186c0e775026175e))
+
+Currently the download methods such as `ProjectJob.artifacts` have return type set to
+  `Optional[Union[bytes, Iterator[Any]]]` which means they return either `None` or `bytes` or
+  `Iterator[Any]`.
+
+However, the actual return type is determined by the passed `streamed` and `iterator` arguments.
+  Using `@typing.overload` decorator it is possible to return a single type based on the passed
+  arguments.
+
+Add overloads in the following order to all download methods:
+
+1. If `streamed=False` and `iterator=False` return `bytes`. This is the default argument values
+  therefore it should be first as it will be used to lookup default arguments. 2. If `iterator=True`
+  return `Iterator[Any]`. This can be combined with both `streamed=True` and `streamed=False`. 3. If
+  `streamed=True` and `iterator=False` return `None`. In this case `action` argument can be set to a
+  callable that accepts `bytes`.
+
+Signed-off-by: Igor Ponomarev <igor.ponomarev@collabora.com>
+
+- **api**: Narrow down return type of ProjectFileManager.raw using typing.overload
+  ([`36d9b24`](https://github.com/python-gitlab/python-gitlab/commit/36d9b24ff27d8df514c1beebd0fff8ad000369b7))
+
+This is equivalent to the changes in 44fd9dc1176a2c5529c45cc3186c0e775026175e but for
+  `ProjectFileManager.raw` method that I must have missed in the original commit.
+
+Signed-off-by: Igor Ponomarev <igor.ponomarev@collabora.com>
+
+
 ## v5.3.1 (2025-01-07)
 
 ### Bug Fixes

{python_gitlab-5.3.1 → python_gitlab-5.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.2
 Name: python-gitlab
-Version: 5.3.1
+Version: 5.4.0
 Summary: The python wrapper for the GitLab REST and GraphQL APIs.
 Author-email: Gauvain Pocentek <gauvain@pocentek.net>
 Maintainer-email: John Villalovos <john@sodarock.com>, Max Wittig <max.wittig@siemens.com>, Nejc Habjan <nejc.habjan@siemens.com>, Roger Meier <r.meier@siemens.com>

{python_gitlab-5.3.1 → python_gitlab-5.4.0}/docs/api-objects.rst

@@ -63,6 +63,7 @@ API examples
    gl_objects/settings
    gl_objects/snippets
    gl_objects/statistics
+   gl_objects/status_checks
    gl_objects/system_hooks
    gl_objects/templates
    gl_objects/todos

{python_gitlab-5.3.1 → python_gitlab-5.4.0}/docs/api-usage-advanced.rst

@@ -211,3 +211,20 @@ on your own, such as for nested API responses and ``Union`` return types. For ex
 
    if TYPE_CHECKING:
       assert isinstance(license["plan"], str)
+
+Per request HTTP headers override
+---------------------------------
+
+The ``extra_headers`` keyword argument can be used to add and override
+the HTTP headers for a specific request. For example, it can be used do add ``Range``
+header to download a part of artifacts archive:
+
+.. code-block:: python
+
+   import gitlab
+
+   gl = gitlab.Gitlab(url, token)
+   project = gl.projects.get(1)
+   job = project.jobs.get(123)
+
+   artifacts = job.artifacts(extra_headers={"Range": "bytes=0-9"})

python_gitlab-5.4.0/docs/gl_objects/status_checks.rst

@@ -0,0 +1,57 @@
+#######################
+External Status Checks
+#######################
+
+Manage external status checks for projects and merge requests.
+
+
+Project external status checks
+===============================
+
+Reference
+---------
+
+* v4 API:
+
+  + :class:`gitlab.v4.objects.ProjectExternalStatusCheck`
+  + :class:`gitlab.v4.objects.ProjectExternalStatusCheckManager`
+  + :attr:`gitlab.v4.objects.Project.external_status_checks`
+
+* GitLab API: https://docs.gitlab.com/ee/api/status_checks.html
+
+Examples
+---------
+
+List external status checks for a project::
+
+    status_checks = project.external_status_checks.list()
+
+Create an external status check with shared secret::
+
+    status_checks = project.external_status_checks.create({
+        "name": "mr_blocker",
+        "external_url": "https://example.com/mr-status-check",
+        "shared_secret": "secret-string"
+    })
+
+Create an external status check with shared secret for protected branches::
+
+    protected_branch = project.protectedbranches.get('main')
+
+    status_check = project.external_status_checks.create({
+        "name": "mr_blocker",
+        "external_url": "https://example.com/mr-status-check",
+        "shared_secret": "secret-string",
+        "protected_branch_ids": [protected_branch.id]
+    })
+
+
+Update an external status check::
+
+    status_check.external_url = "https://example.com/mr-blocker"
+    status_check.save()
+
+Delete an external status check::
+
+    status_check.delete(status_check_id)
+

{python_gitlab-5.3.1 → python_gitlab-5.4.0}/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.4.0"

{python_gitlab-5.3.1 → python_gitlab-5.4.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,

{python_gitlab-5.3.1 → python_gitlab-5.4.0}/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"

{python_gitlab-5.3.1 → python_gitlab-5.4.0}/gitlab/mixins.py

@@ -6,7 +6,9 @@ from typing import (
     Dict,
     Iterator,
     List,
+    Literal,
     Optional,
+    overload,
     Tuple,
     Type,
     TYPE_CHECKING,
@@ -612,6 +614,39 @@ 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], None]] = 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(

{python_gitlab-5.3.1 → python_gitlab-5.4.0}/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 *

{python_gitlab-5.3.1 → python_gitlab-5.4.0}/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], None]] = None,
+        chunk_size: int = 1024,
+        *,
+        iterator: Literal[False] = False,
+        **kwargs: Any,
+    ) -> None: ...
+
     @cli.register_custom_action(
         cls_names="ProjectArtifactManager",
         required=("ref_name", "job"),
@@ -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], None]] = 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"),

{python_gitlab-5.3.1 → python_gitlab-5.4.0}/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)