python-gitlab 4.9.0__tar.gz → 4.11.0__tar.gz

{python_gitlab-4.9.0 → python_gitlab-4.11.0}/CHANGELOG.md

@@ -1,5 +1,97 @@
 # CHANGELOG
 
+## v4.11.0 (2024-09-13)
+
+### Chore
+
+* chore(pre-commit): add deps ([`fe5e608`](https://github.com/python-gitlab/python-gitlab/commit/fe5e608bc6cc04863bd4d1d9dbe101fffd88e954))
+
+* chore(deps): update all non-major dependencies ([`fac8bf9`](https://github.com/python-gitlab/python-gitlab/commit/fac8bf9f3e2a0218f96337536d08dec9991bfc1a))
+
+* chore(deps): update dependency types-setuptools to v74 ([`bdfaddb`](https://github.com/python-gitlab/python-gitlab/commit/bdfaddb89ae7ba351bd3a21c6cecc528772db4de))
+
+* chore(deps): update all non-major dependencies ([`88c7529`](https://github.com/python-gitlab/python-gitlab/commit/88c75297377dd1f1106b5bc673946cebd563e0a1))
+
+### Documentation
+
+* docs(objects): fix typo in get latest pipeline ([`b9f5c12`](https://github.com/python-gitlab/python-gitlab/commit/b9f5c12d3ba6ca4e4321a81e7610d03fb4440c02))
+
+### Feature
+
+* feat(client): make retries configurable in GraphQL ([`145870e`](https://github.com/python-gitlab/python-gitlab/commit/145870e628ed3b648a0a29fc551a6f38469b684a))
+
+* feat(client): add retry handling to GraphQL client ([`8898c38`](https://github.com/python-gitlab/python-gitlab/commit/8898c38b97ed36d9ff8f2f20dee27ef1448b9f83))
+
+* feat(api): add exclusive GET attrs for /projects/:id/members ([`e637808`](https://github.com/python-gitlab/python-gitlab/commit/e637808bcb74498438109d7ed352071ebaa192d5))
+
+* feat: add a minimal GraphQL client ([`d6b1b0a`](https://github.com/python-gitlab/python-gitlab/commit/d6b1b0a962bbf0f4e0612067fc075dbdcbb772f8))
+
+* feat(api): add exclusive GET attrs for /groups/:id/members ([`d44ddd2`](https://github.com/python-gitlab/python-gitlab/commit/d44ddd2b00d78bb87ff6a4776e64e05e0c1524e1))
+
+### Refactor
+
+* refactor(client): move retry logic into utility ([`3235c48`](https://github.com/python-gitlab/python-gitlab/commit/3235c48328c2866f7d46597ba3c0c2488e6c375c))
+
+## v4.10.0 (2024-08-28)
+
+### Chore
+
+* chore(release): track tags for renovate ([`d600444`](https://github.com/python-gitlab/python-gitlab/commit/d6004449ad5aaaf2132318a78523818996ec3e21))
+
+* chore(deps): update python-semantic-release/upload-to-gh-release digest to 17c75b7 ([`12caaa4`](https://github.com/python-gitlab/python-gitlab/commit/12caaa496740cb15e6220511751b7a20e2d29d07))
+
+* chore(deps): update dependency types-setuptools to v73 ([`d55c045`](https://github.com/python-gitlab/python-gitlab/commit/d55c04502bee0fb42e2ef359cde3bc1b4b510b1a))
+
+* chore(deps): update all non-major dependencies ([`2ade0d9`](https://github.com/python-gitlab/python-gitlab/commit/2ade0d9f4922226143e2e3835a7449fde9c49d66))
+
+* chore(deps): update gitlab/gitlab-ee docker tag to v17.3.1-ee.0 ([`3fdd130`](https://github.com/python-gitlab/python-gitlab/commit/3fdd130a8e87137e5a048d5cb78e43aa476c8f34))
+
+* chore(deps): update all non-major dependencies ([`0578bf0`](https://github.com/python-gitlab/python-gitlab/commit/0578bf07e7903037ffef6558e914766b6cf6f545))
+
+* chore(deps): update gitlab/gitlab-ee docker tag to v17.3.0-ee.0 ([`e5a46f5`](https://github.com/python-gitlab/python-gitlab/commit/e5a46f57de166f94e01f5230eb6ad91f319791e4))
+
+* chore(deps): update dependency myst-parser to v4 ([`930d4a2`](https://github.com/python-gitlab/python-gitlab/commit/930d4a21b8afed833b4b2e6879606bbadaee19a1))
+
+* chore(deps): update dependency sphinx to v8 ([`cb65ffb`](https://github.com/python-gitlab/python-gitlab/commit/cb65ffb6957bf039f35926d01f15db559e663915))
+
+* chore(deps): update gitlab/gitlab-ee docker tag to v17.2.2-ee.0 ([`b2275f7`](https://github.com/python-gitlab/python-gitlab/commit/b2275f767dd620c6cb2c27b0470f4e8151c76550))
+
+* chore(deps): update all non-major dependencies ([`31786a6`](https://github.com/python-gitlab/python-gitlab/commit/31786a60da4b9a10dec0eab3a0b078aa1e94d809))
+
+### Documentation
+
+* docs(faq): correct the attribute fetching example
+
+There is an example about object attributes in the FAQ. It shows how to
+properly fetch all attributes of all projects, by using list() followed
+by a get(id) call.
+
+Unfortunately this example used a wrong variable name, which caused it
+not to work and which could have made it slightly confusing to readers.
+This commit fixes that, by changing the variable name.
+
+Now the example uses one variable for two Python objects. As they
+correspond to the same GitLab object and the intended behavior is to
+obtain that very object, just with all attributes, this is fine and is
+probably what readers will find most useful in this context. ([`43a16ac`](https://github.com/python-gitlab/python-gitlab/commit/43a16ac17ce78cf18e0fc10fa8229f052eed3946))
+
+### Feature
+
+* feat(api): project/group hook test triggering
+
+Add the ability to trigger tests of project and group hooks.
+
+Fixes #2924 ([`9353f54`](https://github.com/python-gitlab/python-gitlab/commit/9353f5406d6762d09065744bfca360ccff36defe))
+
+### Test
+
+* test(cli): allow up to 30 seconds for a project export
+
+Before we allowed a maximum of around 15 seconds for the
+project-export. Often times the CI was failing with this value.
+
+Change it to a maximum of around 30 seconds. ([`bdc155b`](https://github.com/python-gitlab/python-gitlab/commit/bdc155b716ef63ef1398ee1e6f5ca67da1109c13))
+
 ## v4.9.0 (2024-08-06)
 
 ### Chore

{python_gitlab-4.9.0 → python_gitlab-4.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: python-gitlab
-Version: 4.9.0
+Version: 4.11.0
 Summary: A python wrapper for the GitLab API
 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>
@@ -34,6 +34,8 @@ Provides-Extra: autocompletion
 Requires-Dist: argcomplete<3,>=1.10.0; extra == "autocompletion"
 Provides-Extra: yaml
 Requires-Dist: PyYaml>=6.0.1; extra == "yaml"
+Provides-Extra: graphql
+Requires-Dist: gql[httpx]<4,>=3.5.0; extra == "graphql"
 
 python-gitlab
 =============

python_gitlab-4.11.0/docs/api-usage-graphql.rst

@@ -0,0 +1,52 @@
+############################
+Using the GraphQL API (beta)
+############################
+
+python-gitlab provides basic support for executing GraphQL queries and mutations.
+
+.. danger::
+
+   The GraphQL client is experimental and only provides basic support.
+   It does not currently support pagination, obey rate limits,
+   or attempt complex retries. You can use it to build simple queries and mutations.
+
+   It is currently unstable and its implementation may change. You can expect a more
+   mature client in one of the upcoming versions.
+
+The ``gitlab.GraphQL`` class
+==================================
+
+As with the REST client, you connect to a GitLab instance by creating a ``gitlab.GraphQL`` object:
+
+.. code-block:: python
+
+   import gitlab
+
+   # anonymous read-only access for public resources (GitLab.com)
+   gq = gitlab.GraphQL()
+
+   # anonymous read-only access for public resources (self-hosted GitLab instance)
+   gq = gitlab.GraphQL('https://gitlab.example.com')
+
+   # personal access token or OAuth2 token authentication (GitLab.com)
+   gq = gitlab.GraphQL(token='glpat-JVNSESs8EwWRx5yDxM5q')
+
+   # personal access token or OAuth2 token authentication (self-hosted GitLab instance)
+   gq = gitlab.GraphQL('https://gitlab.example.com', token='glpat-JVNSESs8EwWRx5yDxM5q')
+
+Sending queries
+===============
+
+Get the result of a query:
+
+.. code-block:: python
+
+    query = """{
+        query {
+          currentUser {
+            name
+          }
+        }
+    """
+
+    result = gq.execute(query)

{python_gitlab-4.9.0 → python_gitlab-4.11.0}/docs/api-usage.rst

@@ -1,8 +1,8 @@
-############################
-Getting started with the API
-############################
+##################
+Using the REST API
+##################
 
-python-gitlab only supports GitLab API v4.
+python-gitlab currently only supports v4 of the GitLab REST API.
 
 ``gitlab.Gitlab`` class
 =======================

{python_gitlab-4.9.0 → python_gitlab-4.11.0}/docs/cli-usage.rst

@@ -1,6 +1,6 @@
-############################
-Getting started with the CLI
-############################
+#############
+Using the CLI
+#############
 
 ``python-gitlab`` provides a :command:`gitlab` command-line tool to interact
 with GitLab servers.

{python_gitlab-4.9.0 → python_gitlab-4.11.0}/docs/faq.rst

@@ -58,7 +58,7 @@ To retrieve an object with all attributes, use a ``get()`` call.
 
 Example with projects::
 
-    for projects in gl.projects.list():
+    for project in gl.projects.list():
         # Retrieve project object with all attributes
         project = gl.projects.get(project.id)
 

{python_gitlab-4.9.0 → python_gitlab-4.11.0}/docs/gl_objects/groups.rst

@@ -89,7 +89,7 @@ Remove a group::
     group.delete()
 
 Restore a Group marked for deletion (Premium only):::
-    
+
     group.restore()
 
 
@@ -368,9 +368,9 @@ SAML group links
 
 Add a SAML group link to an existing GitLab group::
 
-    saml_link = group.saml_group_links.create({ 
-        "saml_group_name": "<your_saml_group_name>", 
-        "access_level": <chosen_access_level> 
+    saml_link = group.saml_group_links.create({
+        "saml_group_name": "<your_saml_group_name>",
+        "access_level": <chosen_access_level>
     })
 
 List a group's SAML group links::
@@ -419,6 +419,10 @@ Update a group hook::
     hook.push_events = 0
     hook.save()
 
+Test a group hook::
+
+    hook.test("push_events")
+
 Delete a group hook::
 
     group.hooks.delete(hook_id)

{python_gitlab-4.9.0 → python_gitlab-4.11.0}/docs/gl_objects/pipelines_and_jobs.rst

@@ -51,7 +51,7 @@ Delete a pipeline::
 
 Get latest pipeline::
 
-    projet.pipelines.latest(ref="main")
+    project.pipelines.latest(ref="main")
 
 
 Triggers

{python_gitlab-4.9.0 → python_gitlab-4.11.0}/docs/gl_objects/projects.rst

@@ -353,7 +353,7 @@ Import the project using file stored on a remote URL::
     output = gl.projects.remote_import(
         url="https://whatever.com/url/file.tar.gz",
         path="my_new_remote_project",
-        name="My New Remote Project", 
+        name="My New Remote Project",
         namespace="my-group",
         override_params={'visibility': 'private'},
     )
@@ -367,7 +367,7 @@ Import the project using file stored on AWS S3::
         file_key="aws-file-key",
         access_key_id="aws-access-key-id",
         secret_access_key="secret-access-key",
-        name="My New Remote Project", 
+        name="My New Remote Project",
         namespace="my-group",
         override_params={'visibility': 'private'},
     )
@@ -449,7 +449,7 @@ Get file details from headers, without fetching its entire content::
     print(headers["X-Gitlab-Size"])
 
 Get a raw file::
-    
+
     raw_content = project.files.raw(file_path='README.rst', ref='main')
     print(raw_content)
     with open('/tmp/raw-download.txt', 'wb') as f:
@@ -689,6 +689,10 @@ Update a project hook::
     hook.push_events = 0
     hook.save()
 
+Test a project hook::
+
+    hook.test("push_events")
+
 Delete a project hook::
 
     project.hooks.delete(hook_id)

{python_gitlab-4.9.0 → python_gitlab-4.11.0}/docs/index.rst

@@ -7,6 +7,7 @@
    cli-usage
    api-usage
    api-usage-advanced
+   api-usage-graphql
    cli-examples
    api-objects
    api/gitlab

{python_gitlab-4.9.0 → python_gitlab-4.11.0}/gitlab/__init__.py

@@ -27,7 +27,7 @@ from gitlab._version import (  # noqa: F401
     __title__,
     __version__,
 )
-from gitlab.client import Gitlab, GitlabList  # noqa: F401
+from gitlab.client import Gitlab, GitlabList, GraphQL  # noqa: F401
 from gitlab.exceptions import *  # noqa: F401,F403
 
 warnings.filterwarnings("default", category=DeprecationWarning, module="^gitlab")
@@ -42,5 +42,6 @@ __all__ = [
     "__version__",
     "Gitlab",
     "GitlabList",
+    "GraphQL",
 ]
 __all__.extend(gitlab.exceptions.__all__)

python_gitlab-4.11.0/gitlab/_backends/graphql.py

@@ -0,0 +1,24 @@
+from typing import Any
+
+import httpx
+from gql.transport.httpx import HTTPXTransport
+
+
+class GitlabTransport(HTTPXTransport):
+    """A gql httpx transport that reuses an existing httpx.Client.
+    By default, gql's transports do not have a keep-alive session
+    and do not enable providing your own session that's kept open.
+    This transport lets us provide and close our session on our own
+    and provide additional auth.
+    For details, see https://github.com/graphql-python/gql/issues/91.
+    """
+
+    def __init__(self, *args: Any, client: httpx.Client, **kwargs: Any):
+        super().__init__(*args, **kwargs)
+        self.client = client
+
+    def connect(self) -> None:
+        pass
+
+    def close(self) -> None:
+        pass

{python_gitlab-4.9.0 → python_gitlab-4.11.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__ = "4.9.0"
+__version__ = "4.11.0"

{python_gitlab-4.9.0 → python_gitlab-4.11.0}/gitlab/client.py

@@ -2,7 +2,6 @@
 
 import os
 import re
-import time
 from typing import (
     Any,
     BinaryIO,
@@ -25,6 +24,19 @@ import gitlab.const
 import gitlab.exceptions
 from gitlab import _backends, utils
 
+try:
+    import gql
+    import gql.transport.exceptions
+    import graphql
+    import httpx
+
+    from ._backends.graphql import GitlabTransport
+
+    _GQL_INSTALLED = True
+except ImportError:  # pragma: no cover
+    _GQL_INSTALLED = False
+
+
 REDIRECT_MSG = (
     "python-gitlab detected a {status_code} ({reason!r}) redirection. You must update "
     "your GitLab URL to the correct URL to avoid issues. The redirection was from: "
@@ -89,7 +101,7 @@ class Gitlab:
         self._api_version = str(api_version)
         self._server_version: Optional[str] = None
         self._server_revision: Optional[str] = None
-        self._base_url = self._get_base_url(url)
+        self._base_url = utils.get_base_url(url)
         self._url = f"{self._base_url}/api/v{api_version}"
         #: Timeout to use for requests to gitlab server
         self.timeout = timeout
@@ -557,18 +569,6 @@ class Gitlab:
             "verify": self.ssl_verify,
         }
 
-    @staticmethod
-    def _get_base_url(url: Optional[str] = None) -> str:
-        """Return the base URL with the trailing slash stripped.
-        If the URL is a Falsy value, return the default URL.
-        Returns:
-            The base URL
-        """
-        if not url:
-            return gitlab.const.DEFAULT_URL
-
-        return url.rstrip("/")
-
     def _build_url(self, path: str) -> str:
         """Returns the full url from path.
 
@@ -718,7 +718,12 @@ class Gitlab:
         send_data = self._backend.prepare_send_data(files, post_data, raw)
         opts["headers"]["Content-type"] = send_data.content_type
 
-        cur_retries = 0
+        retry = utils.Retry(
+            max_retries=max_retries,
+            obey_rate_limit=obey_rate_limit,
+            retry_transient_errors=retry_transient_errors,
+        )
+
         while True:
             try:
                 result = self._backend.http_request(
@@ -733,14 +738,8 @@ class Gitlab:
                     **opts,
                 )
             except (requests.ConnectionError, requests.exceptions.ChunkedEncodingError):
-                if retry_transient_errors and (
-                    max_retries == -1 or cur_retries < max_retries
-                ):
-                    wait_time = 2**cur_retries * 0.1
-                    cur_retries += 1
-                    time.sleep(wait_time)
+                if retry.handle_retry():
                     continue
-
                 raise
 
             self._check_redirects(result.response)
@@ -748,31 +747,10 @@ class Gitlab:
             if 200 <= result.status_code < 300:
                 return result.response
 
-            def should_retry() -> bool:
-                if result.status_code == 429 and obey_rate_limit:
-                    return True
-
-                if not retry_transient_errors:
-                    return False
-                if result.status_code in gitlab.const.RETRYABLE_TRANSIENT_ERROR_CODES:
-                    return True
-                if result.status_code == 409 and "Resource lock" in result.reason:
-                    return True
-
-                return False
-
-            if should_retry():
-                # Response headers documentation:
-                # https://docs.gitlab.com/ee/user/admin_area/settings/user_and_ip_rate_limits.html#response-headers
-                if max_retries == -1 or cur_retries < max_retries:
-                    wait_time = 2**cur_retries * 0.1
-                    if "Retry-After" in result.headers:
-                        wait_time = int(result.headers["Retry-After"])
-                    elif "RateLimit-Reset" in result.headers:
-                        wait_time = int(result.headers["RateLimit-Reset"]) - time.time()
-                    cur_retries += 1
-                    time.sleep(wait_time)
-                    continue
+            if retry.handle_retry_on_status(
+                result.status_code, result.headers, result.reason
+            ):
+                continue
 
             error_message = result.content
             try:
@@ -1296,3 +1274,94 @@ class GitlabList:
             return self.next()
 
         raise StopIteration
+
+
+class GraphQL:
+    def __init__(
+        self,
+        url: Optional[str] = None,
+        *,
+        token: Optional[str] = None,
+        ssl_verify: Union[bool, str] = True,
+        client: Optional[httpx.Client] = None,
+        timeout: Optional[float] = None,
+        user_agent: str = gitlab.const.USER_AGENT,
+        fetch_schema_from_transport: bool = False,
+        max_retries: int = 10,
+        obey_rate_limit: bool = True,
+        retry_transient_errors: bool = False,
+    ) -> None:
+        if not _GQL_INSTALLED:
+            raise ImportError(
+                "The GraphQL client could not be initialized because "
+                "the gql dependencies are not installed. "
+                "Install them with 'pip install python-gitlab[graphql]'"
+            )
+        self._base_url = utils.get_base_url(url)
+        self._timeout = timeout
+        self._token = token
+        self._url = f"{self._base_url}/api/graphql"
+        self._user_agent = user_agent
+        self._ssl_verify = ssl_verify
+        self._max_retries = max_retries
+        self._obey_rate_limit = obey_rate_limit
+        self._retry_transient_errors = retry_transient_errors
+
+        opts = self._get_client_opts()
+        self._http_client = client or httpx.Client(**opts)
+        self._transport = GitlabTransport(self._url, client=self._http_client)
+        self._client = gql.Client(
+            transport=self._transport,
+            fetch_schema_from_transport=fetch_schema_from_transport,
+        )
+        self._gql = gql.gql
+
+    def __enter__(self) -> "GraphQL":
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self._http_client.close()
+
+    def _get_client_opts(self) -> Dict[str, Any]:
+        headers = {"User-Agent": self._user_agent}
+
+        if self._token:
+            headers["Authorization"] = f"Bearer {self._token}"
+
+        return {
+            "headers": headers,
+            "timeout": self._timeout,
+            "verify": self._ssl_verify,
+        }
+
+    def execute(
+        self, request: Union[str, graphql.Source], *args: Any, **kwargs: Any
+    ) -> Any:
+        parsed_document = self._gql(request)
+        retry = utils.Retry(
+            max_retries=self._max_retries,
+            obey_rate_limit=self._obey_rate_limit,
+            retry_transient_errors=self._retry_transient_errors,
+        )
+
+        while True:
+            try:
+                result = self._client.execute(parsed_document, *args, **kwargs)
+            except gql.transport.exceptions.TransportServerError as e:
+                if retry.handle_retry_on_status(
+                    status_code=e.code, headers=self._transport.response_headers
+                ):
+                    continue
+
+                if e.code == 401:
+                    raise gitlab.exceptions.GitlabAuthenticationError(
+                        response_code=e.code,
+                        error_message=str(e),
+                    )
+
+                raise gitlab.exceptions.GitlabHttpError(
+                    response_code=e.code,
+                    error_message=str(e),
+                )
+
+            return result

{python_gitlab-4.9.0 → python_gitlab-4.11.0}/gitlab/exceptions.py

@@ -316,6 +316,10 @@ class GitlabDeploymentApprovalError(GitlabOperationError):
     pass
 
 
+class GitlabHookTestError(GitlabOperationError):
+    pass
+
+
 # For an explanation of how these type-hints work see:
 # https://mypy.readthedocs.io/en/stable/generics.html#declaring-decorators
 #
@@ -370,6 +374,7 @@ __all__ = [
     "GitlabGetError",
     "GitlabGroupTransferError",
     "GitlabHeadError",
+    "GitlabHookTestError",
     "GitlabHousekeepingError",
     "GitlabHttpError",
     "GitlabImportError",