fix(api): avoid parameter conflicts with python and gitlabno-param-conflicts

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

6 files changed, 64 insertions, 3 deletions

diff --git a/RELEASE_NOTES.rst b/RELEASE_NOTES.rst
index 1e53a88..6abb980 100644
--- a/RELEASE_NOTES.rst
+++ b/RELEASE_NOTES.rst
@@ -4,6 +4,25 @@ Release notes
 
 This page describes important changes between python-gitlab releases.
 
+Changes from 1.7 to 1.8
+=======================
+
+* You can now use the ``query_parameters`` argument in method calls to define
+  arguments to send to the GitLab server. This allows to avoid conflicts
+  between python-gitlab and GitLab server variables, and allows to use the
+  python reserved keywords as GitLab arguments.
+
+  The following examples make the same GitLab request with the 2 syntaxes::
+
+     projects = gl.projects.list(owned=True, starred=True)
+     projects = gl.projects.list(query_parameters={'owned': True, 'starred': True})
+
+  The following example only works with the new parameter::
+
+     activities = gl.user_activities.list(
+                    query_parameters={'from': '2019-01-01'},
+                    all=True)
+
 Changes from 1.5 to 1.6
 =======================
 
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)
diff --git a/gitlab/__init__.py b/gitlab/__init__.py
index c280974..4f00603 100644
--- a/gitlab/__init__.py
+++ b/gitlab/__init__.py
@@ -445,7 +445,20 @@ class Gitlab(object):
 
         params = {}
         utils.copy_dict(params, query_data)
-        utils.copy_dict(params, kwargs)
+
+        # Deal with kwargs: by default a user uses kwargs to send data to the
+        # gitlab server, but this generates problems (python keyword conflicts
+        # and python-gitlab/gitlab conflicts).
+        # So we provide a `query_parameters` key: if it's there we use its dict
+        # value as arguments for the gitlab server, and ignore the other
+        # arguments, except pagination ones (per_page and page)
+        if 'query_parameters' in kwargs:
+            utils.copy_dict(params, kwargs['query_parameters'])
+            for arg in ('per_page', 'page'):
+                if arg in kwargs:
+                    params[arg] = kwargs[arg]
+        else:
+            utils.copy_dict(params, kwargs)
 
         opts = self._get_session_opts(content_type='application/json')
 
diff --git a/tools/python_test_v4.py b/tools/python_test_v4.py
index aacb3e7..958e350 100644
--- a/tools/python_test_v4.py
+++ b/tools/python_test_v4.py
@@ -773,7 +773,7 @@ snippets = gl.snippets.list(all=True)
 assert(len(snippets) == 0)
 
 # user activities
-gl.user_activities.list()
+gl.user_activities.list(query_parameters={'from': '2019-01-01'})
 
 # events
 gl.events.list()