Skip to content

Commit fe89b94

Browse files
author
Gauvain Pocentek
committed
Drop API v3 support
Drop the code, the tests, and update the documentation.
1 parent 7011694 commit fe89b94

19 files changed

+60
-5838
lines changed

‎docs/api-usage.rst

Lines changed: 23 additions & 69 deletions
Original file line numberDiff line numberDiff line change
@@ -2,13 +2,12 @@
22
Getting started with the API
33
############################
44

5-
python-gitlab supports both GitLab v3 and v4 APIs.
5+
python-gitlab supports both GitLab v3 and v4 APIs. To use the v3 make sure to
66

7-
v3 being deprecated by GitLab, its support in python-gitlab will be minimal.
8-
The development team will focus on v4.
9-
10-
v4 is the default API used by python-gitlab since version 1.3.0.
7+
.. note::
118

9+
To use the v3 make sure to install python-gitlab 1.4. Only the v4 API is
10+
documented here. See the documentation of earlier version for the v3 API.
1211

1312
``gitlab.Gitlab`` class
1413
=======================
@@ -60,23 +59,6 @@ https://gist.github.com/gpocentek/bd4c3fbf8a6ce226ebddc4aad6b46c0a.
6059
See `issue 380 <https://github.com/python-gitlab/python-gitlab/issues/380>`_
6160
for a detailed discussion.
6261

63-
API version
64-
===========
65-
66-
``python-gitlab`` uses the v4 GitLab API by default. Use the ``api_version``
67-
parameter to switch to v3:
68-
69-
.. code-block:: python
70-
71-
import gitlab
72-
73-
gl = gitlab.Gitlab('http://10.0.0.1', 'JVNSESs8EwWRx5yDxM5q', api_version=3)
74-
75-
.. warning::
76-
77-
The python-gitlab API is not the same for v3 and v4. Make sure to read
78-
:ref:`switching_to_v4` if you are upgrading from v3.
79-
8062
Managers
8163
========
8264

@@ -103,10 +85,10 @@ Examples:
10385
user = gl.users.create(user_data)
10486
print(user)
10587
106-
You can list the mandatory and optional attributes for object creation
107-
with the manager's ``get_create_attrs()`` method. It returns 2 tuples, the
108-
first one is the list of mandatory attributes, the second one the list of
109-
optional attribute:
88+
You can list the mandatory and optional attributes for object creation and
89+
update with the manager's ``get_create_attrs()`` and ``get_update_attrs()``
90+
methods. They return 2 tuples, the first one is the list of mandatory
91+
attributes, the second one the list of optional attribute:
11092

11193
.. code-block:: python
11294
@@ -116,19 +98,11 @@ optional attribute:
11698
11799
The attributes of objects are defined upon object creation, and depend on the
118100
GitLab API itself. To list the available information associated with an object
119-
use the python introspection tools for v3, or the ``attributes`` attribute for
120-
v4:
101+
use the ``attributes`` attribute:
121102

122103
.. code-block:: python
123104
124105
project = gl.projects.get(1)
125-
126-
# v3
127-
print(vars(project))
128-
# or
129-
print(project.__dict__)
130-
131-
# v4
132106
print(project.attributes)
133107
134108
Some objects also provide managers to access related GitLab resources:
@@ -171,32 +145,21 @@ The ``gitlab`` package provides some base types.
171145

172146
* ``gitlab.Gitlab`` is the primary class, handling the HTTP requests. It holds
173147
the GitLab URL and authentication information.
174-
175-
For v4 the following types are defined:
176-
177148
* ``gitlab.base.RESTObject`` is the base class for all the GitLab v4 objects.
178149
These objects provide an abstraction for GitLab resources (projects, groups,
179150
and so on).
180151
* ``gitlab.base.RESTManager`` is the base class for v4 objects managers,
181152
providing the API to manipulate the resources and their attributes.
182153

183-
For v3 the following types are defined:
184-
185-
* ``gitlab.base.GitlabObject`` is the base class for all the GitLab v3 objects.
186-
These objects provide an abstraction for GitLab resources (projects, groups,
187-
and so on).
188-
* ``gitlab.base.BaseManager`` is the base class for v3 objects managers,
189-
providing the API to manipulate the resources and their attributes.
154+
Lazy objects
155+
============
190156

191-
Lazy objects (v4 only)
192-
======================
193-
194-
To avoid useless calls to the server API, you can create lazy objects. These
157+
To avoid useless API calls to the server you can create lazy objects. These
195158
objects are created locally using a known ID, and give access to other managers
196159
and methods.
197160

198161
The following example will only make one API call to the GitLab server to star
199-
a project:
162+
a project (the previous example used 2 API calls):
200163

201164
.. code-block:: python
202165
@@ -214,9 +177,9 @@ listing methods support the ``page`` and ``per_page`` parameters:
214177
215178
ten_first_groups = gl.groups.list(page=1, per_page=10)
216179
217-
.. note::
180+
.. warning::
218181

219-
The first page is page 1, not page 0, except for project commits in v3 API.
182+
The first page is page 1, not page 0.
220183

221184
By default GitLab does not return the complete list of items. Use the ``all``
222185
parameter to get all the items when using listing methods:
@@ -226,18 +189,9 @@ parameter to get all the items when using listing methods:
226189
all_groups = gl.groups.list(all=True)
227190
all_owned_projects = gl.projects.owned(all=True)
228191
229-
.. warning::
230-
231-
With API v3 python-gitlab will iterate over the list by calling the
232-
corresponding API multiple times. This might take some time if you have a
233-
lot of items to retrieve. This might also consume a lot of memory as all the
234-
items will be stored in RAM. If you're encountering the python recursion
235-
limit exception, use ``safe_all=True`` to stop pagination automatically if
236-
the recursion limit is hit.
237-
238-
With API v4, ``list()`` methods can also return a generator object which will
239-
handle the next calls to the API when required. This is the recommended way to
240-
iterate through a large number of items:
192+
``list()`` methods can also return a generator object which will handle the
193+
next calls to the API when required. This is the recommended way to iterate
194+
through a large number of items:
241195

242196
.. code-block:: python
243197
@@ -331,12 +285,12 @@ http://docs.python-requests.org/en/master/user/advanced/#client-side-certificate
331285
Rate limits
332286
-----------
333287

334-
python-gitlab will obey the rate limit of the GitLab server by default.
335-
On receiving a 429 response (Too Many Requests), python-gitlab will sleep for the amount of time
336-
in the Retry-After header, that GitLab sends back.
288+
python-gitlab obeys the rate limit of the GitLab server by default. On
289+
receiving a 429 response (Too Many Requests), python-gitlab sleeps for the
290+
amount of time in the Retry-After header that GitLab sends back.
337291

338-
If you don't want to wait, you can disable the rate-limiting feature, by supplying the
339-
``obey_rate_limit`` argument.
292+
If you don't want to wait, you can disable the rate-limiting feature, by
293+
supplying the ``obey_rate_limit`` argument.
340294

341295
.. code-block:: python
342296

‎docs/api/gitlab.rst

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,6 @@ Subpackages
66

77
.. toctree::
88

9-
gitlab.v3
109
gitlab.v4
1110

1211
Submodules

‎docs/api/gitlab.v3.rst

Lines changed: 0 additions & 22 deletions
This file was deleted.

0 commit comments

Comments
 (0)