From 4bd027aac41c41f7e22af93c7be0058d2faf7fb4 Mon Sep 17 00:00:00 2001
From: Gauvain Pocentek <gauvain@pocentek.net>
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 +++++++++++++++++++
 docs/gl_objects/commits.rst |  8 ++++++++
 docs/gl_objects/users.rst   |  4 +++-
 3 files changed, 30 insertions(+), 1 deletion(-)

(limited to 'docs')

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
 ==============
 
diff --git a/docs/gl_objects/commits.rst b/docs/gl_objects/commits.rst
index 662d9c3..9f48c98 100644
--- a/docs/gl_objects/commits.rst
+++ b/docs/gl_objects/commits.rst
@@ -27,6 +27,14 @@ results::
     commits = project.commits.list(ref_name='my_branch')
     commits = project.commits.list(since='2016-01-01T00:00:00Z')
 
+.. note::
+
+   The available ``all`` listing argument conflicts with the python-gitlab
+   argument. Use ``query_parameters`` to avoid the conflict::
+
+       commits = project.commits.list(all=True,
+                                      query_parameters={'ref_name': 'my_branch'})
+
 Create a commit::
 
     # See https://docs.gitlab.com/ce/api/commits.html#create-a-commit-with-multiple-files-and-actions
diff --git a/docs/gl_objects/users.rst b/docs/gl_objects/users.rst
index d86d2ed..e66ef3a 100644
--- a/docs/gl_objects/users.rst
+++ b/docs/gl_objects/users.rst
@@ -312,4 +312,6 @@ Examples
 
 Get the users activities::
 
-    activities = gl.user_activities.list(all=True, as_list=False)
+    activities = gl.user_activities.list(
+        query_parameters={'from': '2018-07-01'},
+        all=True, as_list=False)
-- 
cgit v1.2.1