From e9506d15a971888a9af72b37d3e7dbce55e49126 Mon Sep 17 00:00:00 2001 From: Gauvain Pocentek Date: Sat, 25 Aug 2018 15:46:27 +0200 Subject: Minor doc updates --- docs/api-usage.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/api-usage.rst') diff --git a/docs/api-usage.rst b/docs/api-usage.rst index ede2d47..fa6e0b0 100644 --- a/docs/api-usage.rst +++ b/docs/api-usage.rst @@ -7,7 +7,7 @@ python-gitlab supports both GitLab v3 and v4 APIs. To use the v3 make sure to .. note:: To use the v3 make sure to install python-gitlab 1.4. Only the v4 API is - documented here. See the documentation of earlier version for the v3 API. + documented here. See the documentation of earlier versions for the v3 API. ``gitlab.Gitlab`` class ======================= @@ -88,7 +88,7 @@ Examples: You can list the mandatory and optional attributes for object creation and update with the manager's ``get_create_attrs()`` and ``get_update_attrs()`` methods. They return 2 tuples, the first one is the list of mandatory -attributes, the second one the list of optional attribute: +attributes, the second one is the list of optional attribute: .. code-block:: python @@ -206,7 +206,7 @@ through a large number of items: for item in items: print(item.attributes) -The generator exposes extra listing information as received by the server: +The generator exposes extra listing information as received from the server: * ``current_page``: current page number (first page is 1) * ``prev_page``: if ``None`` the current page is the first one @@ -249,7 +249,7 @@ properly closed when you exit a ``with`` block: .. warning:: The context manager will also close the custom ``Session`` object you might - have used to build a ``Gitlab`` instance. + have used to build the ``Gitlab`` instance. Proxy configuration ------------------- -- cgit v1.2.1 From ccf0c2ad35d4dd1af4f36e411027286a0be0f49f Mon Sep 17 00:00:00 2001 From: Gauvain Pocentek Date: Tue, 4 Sep 2018 16:36:34 +0200 Subject: [docs] Fix the owned/starred usage documentation Closes #579 --- docs/api-usage.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/api-usage.rst') diff --git a/docs/api-usage.rst b/docs/api-usage.rst index fa6e0b0..44df385 100644 --- a/docs/api-usage.rst +++ b/docs/api-usage.rst @@ -187,7 +187,7 @@ parameter to get all the items when using listing methods: .. code-block:: python all_groups = gl.groups.list(all=True) - all_owned_projects = gl.projects.owned(all=True) + all_owned_projects = gl.projects.list(owned=True, all=True) You can define the ``per_page`` value globally to avoid passing it to every ``list()`` method call: -- cgit v1.2.1 From b02c30f8b1829e87e2cc28ae7fdf8bb458a4b1c7 Mon Sep 17 00:00:00 2001 From: Gauvain Pocentek Date: Wed, 5 Sep 2018 18:01:07 +0200 Subject: [docs] fix cut and paste leftover --- docs/api-usage.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/api-usage.rst') diff --git a/docs/api-usage.rst b/docs/api-usage.rst index 44df385..c2d50c4 100644 --- a/docs/api-usage.rst +++ b/docs/api-usage.rst @@ -2,7 +2,7 @@ Getting started with the API ############################ -python-gitlab supports both GitLab v3 and v4 APIs. To use the v3 make sure to +python-gitlab supports both GitLab v3 and v4 APIs. .. note:: -- cgit v1.2.1 From 042b706238810fa3b4fde92d298a709ebdb3a925 Mon Sep 17 00:00:00 2001 From: Gauvain Pocentek Date: Wed, 5 Sep 2018 18:04:15 +0200 Subject: [docs] add a warning about https:// http to https redirection cause problems. Make notes of this in the docs. --- docs/api-usage.rst | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'docs/api-usage.rst') diff --git a/docs/api-usage.rst b/docs/api-usage.rst index c2d50c4..73d1377 100644 --- a/docs/api-usage.rst +++ b/docs/api-usage.rst @@ -43,6 +43,11 @@ You can also use configuration files to create ``gitlab.Gitlab`` objects: See the :ref:`cli_configuration` section for more information about configuration files. +.. warning:: + + If the GitLab server you are using redirects requests from http to https, + make sure to use the ``https://`` protocol in the URL definition. + Note on password authentication ------------------------------- -- cgit v1.2.1 From 7a3724f3fca93b4f55aed5132cf46d3718c4f594 Mon Sep 17 00:00:00 2001 From: Srikanth Chelluri Date: Tue, 8 Jan 2019 20:58:26 -0500 Subject: fix: handle empty 'Retry-After' header from GitLab When requests are throttled (HTTP response code 429), python-gitlab assumed that 'Retry-After' existed in the response headers. This is not always the case and so the request fails due to a KeyError. The change in this commit adds a rudimentary exponential backoff to the 'http_request' method, which defaults to 10 retries but can be set to -1 to retry without bound. --- docs/api-usage.rst | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) (limited to 'docs/api-usage.rst') diff --git a/docs/api-usage.rst b/docs/api-usage.rst index 73d1377..a5afbda 100644 --- a/docs/api-usage.rst +++ b/docs/api-usage.rst @@ -299,7 +299,9 @@ Rate limits python-gitlab obeys the rate limit of the GitLab server by default. On receiving a 429 response (Too Many Requests), python-gitlab sleeps for the -amount of time in the Retry-After header that GitLab sends back. +amount of time in the Retry-After header that GitLab sends back. If GitLab +does not return a response with the Retry-After header, python-gitlab will +perform an exponential backoff. If you don't want to wait, you can disable the rate-limiting feature, by supplying the ``obey_rate_limit`` argument. @@ -312,6 +314,18 @@ supplying the ``obey_rate_limit`` argument. gl = gitlab.gitlab(url, token, api_version=4) gl.projects.list(all=True, obey_rate_limit=False) +If you do not disable the rate-limiting feature, you can supply a custom value +for ``max_retries``; by default, this is set to 10. To retry without bound when +throttled, you can set this parameter to -1. This parameter is ignored if +``obey_rate_limit`` is set to ``False``. + +.. code-block:: python + + import gitlab + import requests + + gl = gitlab.gitlab(url, token, api_version=4) + gl.projects.list(all=True, max_retries=12) .. warning:: -- cgit v1.2.1 From 4bd027aac41c41f7e22af93c7be0058d2faf7fb4 Mon Sep 17 00:00:00 2001 From: Gauvain Pocentek Date: Sun, 13 Jan 2019 13:12:17 +0100 Subject: fix(api): avoid parameter conflicts with python and gitlab Provide another way to send data to gitlab with a new `query_parameters` argument. This parameter can be used to explicitly define the dict of items to send to the server, so that **kwargs are only used to specify python-gitlab specific parameters. Closes #566 Closes #629 --- docs/api-usage.rst | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) (limited to 'docs/api-usage.rst') diff --git a/docs/api-usage.rst b/docs/api-usage.rst index a5afbda..8ab252c 100644 --- a/docs/api-usage.rst +++ b/docs/api-usage.rst @@ -118,6 +118,25 @@ Some objects also provide managers to access related GitLab resources: project = gl.projects.get(1) issues = project.issues.list() +python-gitlab allows to send any data to the GitLab server when making queries. +In case of invalid or missing arguments python-gitlab will raise an exception +with the GitLab server error message: + +.. code-block:: python + + >>> gl.projects.list(sort='invalid value') + ... + GitlabListError: 400: sort does not have a valid value + +You can use the ``query_parameters`` argument to send arguments that would +conflict with python or python-gitlab when using them as kwargs: + +.. code-block:: python + + gl.user_activities.list(from='2019-01-01') ## invalid + + gl.user_activities.list(query_parameters={'from': '2019-01-01'}) # OK + Gitlab Objects ============== -- cgit v1.2.1