Merge branch 'rework_api'

8 files changed, 222 insertions, 166 deletions

diff --git a/docs/api/gitlab.rst b/docs/api/gitlab.rst
index d34d56f..e75f843 100644
--- a/docs/api/gitlab.rst
+++ b/docs/api/gitlab.rst
@@ -1,55 +1,48 @@
 gitlab package
 ==============
 
-Module contents
----------------
+Subpackages
+-----------
 
-.. automodule:: gitlab
+.. toctree::
+
+    gitlab.v3
+    gitlab.v4
+
+Submodules
+----------
+
+gitlab.base module
+------------------
+
+.. automodule:: gitlab.base
     :members:
     :undoc-members:
     :show-inheritance:
-    :exclude-members: Hook, UserProject, Group, Issue, Team, User,
-                      all_projects, owned_projects, search_projects
 
-gitlab.base
------------
+gitlab.cli module
+-----------------
 
-.. automodule:: gitlab.base
+.. automodule:: gitlab.cli
     :members:
     :undoc-members:
     :show-inheritance:
 
-gitlab.v3.objects module
-------------------------
+gitlab.config module
+--------------------
 
-.. automodule:: gitlab.v3.objects
+.. automodule:: gitlab.config
     :members:
     :undoc-members:
     :show-inheritance:
-    :exclude-members: Branch, Commit, Content, Event, File, Hook, Issue, Key,
-                      Label, Member, MergeRequest, Milestone, Note, Snippet,
-                      Tag, canGet, canList, canUpdate, canCreate, canDelete,
-                      requiredUrlAttrs, requiredListAttrs, optionalListAttrs,
-                      optionalGetAttrs, requiredGetAttrs, requiredDeleteAttrs,
-                      requiredCreateAttrs, optionalCreateAttrs,
-                      requiredUpdateAttrs, optionalUpdateAttrs, getRequiresId,
-                      shortPrintAttr, idAttr
 
-gitlab.v4.objects module
-------------------------
+gitlab.const module
+-------------------
 
-.. automodule:: gitlab.v4.objects
+.. automodule:: gitlab.const
     :members:
     :undoc-members:
     :show-inheritance:
-    :exclude-members: Branch, Commit, Content, Event, File, Hook, Issue, Key,
-                      Label, Member, MergeRequest, Milestone, Note, Snippet,
-                      Tag, canGet, canList, canUpdate, canCreate, canDelete,
-                      requiredUrlAttrs, requiredListAttrs, optionalListAttrs,
-                      optionalGetAttrs, requiredGetAttrs, requiredDeleteAttrs,
-                      requiredCreateAttrs, optionalCreateAttrs,
-                      requiredUpdateAttrs, optionalUpdateAttrs, getRequiresId,
-                      shortPrintAttr, idAttr
 
 gitlab.exceptions module
 ------------------------
@@ -58,3 +51,28 @@ gitlab.exceptions module
     :members:
     :undoc-members:
     :show-inheritance:
+
+gitlab.mixins module
+--------------------
+
+.. automodule:: gitlab.mixins
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+gitlab.utils module
+-------------------
+
+.. automodule:: gitlab.utils
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
+Module contents
+---------------
+
+.. automodule:: gitlab
+    :members:
+    :undoc-members:
+    :show-inheritance:
diff --git a/docs/api/gitlab.v3.rst b/docs/api/gitlab.v3.rst
new file mode 100644
index 0000000..61879bc
--- /dev/null
+++ b/docs/api/gitlab.v3.rst
@@ -0,0 +1,22 @@
+gitlab.v3 package
+=================
+
+Submodules
+----------
+
+gitlab.v3.objects module
+------------------------
+
+.. automodule:: gitlab.v3.objects
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
+Module contents
+---------------
+
+.. automodule:: gitlab.v3
+    :members:
+    :undoc-members:
+    :show-inheritance:
diff --git a/docs/api/gitlab.v4.rst b/docs/api/gitlab.v4.rst
new file mode 100644
index 0000000..70358c1
--- /dev/null
+++ b/docs/api/gitlab.v4.rst
@@ -0,0 +1,22 @@
+gitlab.v4 package
+=================
+
+Submodules
+----------
+
+gitlab.v4.objects module
+------------------------
+
+.. automodule:: gitlab.v4.objects
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
+Module contents
+---------------
+
+.. automodule:: gitlab.v4
+    :members:
+    :undoc-members:
+    :show-inheritance:
diff --git a/docs/api/modules.rst b/docs/api/modules.rst
deleted file mode 100644
index 3ec5a68..0000000
--- a/docs/api/modules.rst
+++ /dev/null
@@ -1,7 +0,0 @@
-API documentation
-=================
-
-.. toctree::
-   :maxdepth: 4
-
-   gitlab
diff --git a/docs/ext/docstrings.py b/docs/ext/docstrings.py
index fc95eeb..32c5da1 100644
--- a/docs/ext/docstrings.py
+++ b/docs/ext/docstrings.py
@@ -10,6 +10,8 @@ from sphinx.ext.napoleon.docstring import GoogleDocstring
 
 
 def classref(value, short=True):
+    return value
+
     if not inspect.isclass(value):
         return ':class:%s' % value
     tilde = '~' if short else ''
@@ -46,8 +48,13 @@ class GitlabDocstring(GoogleDocstring):
 
         return output.split('\n')
 
-    def __init__(self, *args, **kwargs):
-        super(GitlabDocstring, self).__init__(*args, **kwargs)
+    def __init__(self, docstring, config=None, app=None, what='', name='',
+                 obj=None, options=None):
+        super(GitlabDocstring, self).__init__(docstring, config, app, what,
+                                              name, obj, options)
+
+        if name and name.startswith('gitlab.v4.objects'):
+            return
 
         if getattr(self._obj, '__name__', None) == 'Gitlab':
             mgrs = []
@@ -57,9 +64,12 @@ class GitlabDocstring(GoogleDocstring):
                     mgrs.append(item)
             self._parsed_lines.extend(self._build_doc('gl_tmpl.j2',
                                                       mgrs=sorted(mgrs)))
+
+        # BaseManager
         elif hasattr(self._obj, 'obj_cls') and self._obj.obj_cls is not None:
             self._parsed_lines.extend(self._build_doc('manager_tmpl.j2',
                                                       cls=self._obj.obj_cls))
+        # GitlabObject
         elif hasattr(self._obj, 'canUpdate') and self._obj.canUpdate:
             self._parsed_lines.extend(self._build_doc('object_tmpl.j2',
                                                       obj=self._obj))
diff --git a/docs/index.rst b/docs/index.rst
index 2198025..7805fcf 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -14,9 +14,9 @@ Contents:
    install
    cli
    api-usage
+   switching-to-v4
    api-objects
-   upgrade-from-0.10
-   api/modules
+   api/gitlab
    release_notes
    changelog
 
diff --git a/docs/switching-to-v4.rst b/docs/switching-to-v4.rst
new file mode 100644
index 0000000..84181ff
--- /dev/null
+++ b/docs/switching-to-v4.rst
@@ -0,0 +1,116 @@
+##########################
+Switching to GtiLab API v4
+##########################
+
+GitLab provides a new API version (v4) since its 9.0 release. ``python-gitlab``
+provides support for this new version, but the python API has been modified to
+solve some problems with the existing one.
+
+GitLab will stop supporting the v3 API soon, and you should consider switching
+to v4 if you use a recent version of GitLab (>= 9.0), or if you use
+http://gitlab.com.
+
+The new v4 API is available in the `rework_api branch on github
+<https://github.com/python-gitlab/python-gitlab/tree/rework_api>`_, and will be
+released soon.
+
+
+Using the v4 API
+================
+
+To use the new v4 API, explicitly use it in the ``Gitlab`` constructor:
+
+.. code-block:: python
+
+   gl = gitlab.Gitlab(..., api_version=4)
+
+
+If you use the configuration file, also explicitly define the version:
+
+.. code-block:: ini
+
+   [my_gitlab]
+   ...
+   api_version = 4
+
+
+Changes between v3 and v4 API
+=============================
+
+For a list of GtiLab (upstream) API changes, see
+https://docs.gitlab.com/ce/api/v3_to_v4.html.
+
+The ``python-gitlab`` API reflects these changes. But also consider the
+following important changes in the python API:
+
+* managers and objects don't inherit from ``GitlabObject`` and ``BaseManager``
+  anymore. They inherit from :class:`~gitlab.base.RESTManager` and
+  :class:`~gitlab.base.RESTObject`.
+
+* You should only use the managers to perform CRUD operations.
+
+  The following v3 code:
+
+  .. code-block:: python
+
+     gl = gitlab.Gitlab(...)
+     p = Project(gl, project_id)
+
+  Should be replaced with:
+
+  .. code-block:: python
+
+     gl = gitlab.Gitlab(...)
+     p = gl.projects.get(project_id)
+
+* Listing methods (``manager.list()`` for instance) can now return generators
+  (:class:`~gitlab.base.RESTObjectList`). They handle the calls to the API when
+  needed to fetch new items.
+
+  By default you will still get lists. To get generators use ``as_list=False``:
+
+  .. code-block:: python
+
+     all_projects_g = gl.projects.list(as_list=False)
+
+* The "nested" managers (for instance ``gl.project_issues`` or
+  ``gl.group_members``) are not available anymore. Their goal was to provide a
+  direct way to manage nested objects, and to limit the number of needed API
+  calls.
+
+  To limit the number of API calls, you can now use ``get()`` methods with the
+  ``lazy=True`` parameter.  This creates shallow objects that provide usual
+  managers.
+
+  The following v3 code:
+
+  .. code-block:: python
+
+     issues = gl.project_issues.list(project_id=project_id)
+
+  Should be replaced with:
+
+  .. code-block:: python
+
+     issues = gl.projects.get(project_id, lazy=True).issues.list()
+
+  This will make only one API call, instead of two if ``lazy`` is not used.
+
+* The :class:`~gitlab.Gitlab` folowwing methods should not be used anymore for
+  v4:
+
+  + ``list()``
+  + ``get()``
+  + ``create()``
+  + ``update()``
+  + ``delete()``
+
+* If you need to perform HTTP requests to the GitLab server (which you
+  shouldn't), you can use the following :class:`~gitlab.Gitlab` methods:
+
+  + :attr:`~gitlab.Gitlab.http_request`
+  + :attr:`~gitlab.Gitlab.http_get`
+  + :attr:`~gitlab.Gitlab.http_list`
+  + :attr:`~gitlab.Gitlab.http_post`
+  + :attr:`~gitlab.Gitlab.http_put`
+  + :attr:`~gitlab.Gitlab.http_delete`
diff --git a/docs/upgrade-from-0.10.rst b/docs/upgrade-from-0.10.rst
deleted file mode 100644
index 7ff80ab..0000000
--- a/docs/upgrade-from-0.10.rst
+++ /dev/null
@@ -1,125 +0,0 @@
-#############################################
-Upgrading from python-gitlab 0.10 and earlier
-#############################################
-
-``python-gitlab`` 0.11 introduces new objects which make the API cleaner and
-easier to use. The feature set is unchanged but some methods have been
-deprecated in favor of the new manager objects.
-
-Deprecated methods will be remove in a future release.
-
-Gitlab object migration
-=======================
-
-The objects constructor methods are deprecated:
-
-* ``Hook()``
-* ``Project()``
-* ``UserProject()``
-* ``Group()``
-* ``Issue()``
-* ``User()``
-* ``Team()``
-
-Use the new managers objects instead. For example:
-
-.. code-block:: python
-
-   # Deprecated syntax
-   p1 = gl.Project({'name': 'myCoolProject'})
-   p1.save()
-   p2 = gl.Project(id=1)
-   p_list = gl.Project()
-
-   # New syntax
-   p1 = gl.projects.create({'name': 'myCoolProject'})
-   p2 = gl.projects.get(1)
-   p_list = gl.projects.list()
-
-The following methods are also deprecated:
-
-* ``search_projects()``
-* ``owned_projects()``
-* ``all_projects()``
-
-Use the ``projects`` manager instead:
-
-.. code-block:: python
-
-   # Deprecated syntax
-   l1 = gl.search_projects('whatever')
-   l2 = gl.owned_projects()
-   l3 = gl.all_projects()
-
-   # New syntax
-   l1 = gl.projects.search('whatever')
-   l2 = gl.projects.owned()
-   l3 = gl.projects.all()
-
-GitlabObject objects migration
-==============================
-
-The following constructor methods are deprecated in favor of the matching
-managers:
-
-.. list-table::
-   :header-rows: 1
-
-   * - Deprecated method
-     - Matching manager
-   * - ``User.Key()``
-     - ``User.keys``
-   * - ``CurrentUser.Key()``
-     - ``CurrentUser.keys``
-   * - ``Group.Member()``
-     - ``Group.members``
-   * - ``ProjectIssue.Note()``
-     - ``ProjectIssue.notes``
-   * - ``ProjectMergeRequest.Note()``
-     - ``ProjectMergeRequest.notes``
-   * - ``ProjectSnippet.Note()``
-     - ``ProjectSnippet.notes``
-   * - ``Project.Branch()``
-     - ``Project.branches``
-   * - ``Project.Commit()``
-     - ``Project.commits``
-   * - ``Project.Event()``
-     - ``Project.events``
-   * - ``Project.File()``
-     - ``Project.files``
-   * - ``Project.Hook()``
-     - ``Project.hooks``
-   * - ``Project.Key()``
-     - ``Project.keys``
-   * - ``Project.Issue()``
-     - ``Project.issues``
-   * - ``Project.Label()``
-     - ``Project.labels``
-   * - ``Project.Member()``
-     - ``Project.members``
-   * - ``Project.MergeRequest()``
-     - ``Project.mergerequests``
-   * - ``Project.Milestone()``
-     - ``Project.milestones``
-   * - ``Project.Note()``
-     - ``Project.notes``
-   * - ``Project.Snippet()``
-     - ``Project.snippets``
-   * - ``Project.Tag()``
-     - ``Project.tags``
-   * - ``Team.Member()``
-     - ``Team.members``
-   * - ``Team.Project()``
-     - ``Team.projects``
-
-For example:
-
-.. code-block:: python
-
-   # Deprecated syntax
-   p = gl.Project(id=2)
-   issues = p.Issue()
-
-   # New syntax
-   p = gl.projects.get(2)
-   issues = p.issues.list()