diff options
| -rw-r--r-- | docs/api-usage.rst | 94 | ||||
| -rw-r--r-- | docs/cli.rst | 9 | ||||
| -rw-r--r-- | docs/switching-to-v4.rst | 11 |
3 files changed, 85 insertions, 29 deletions
diff --git a/docs/api-usage.rst b/docs/api-usage.rst index eae26db..ecb0e64 100644 --- a/docs/api-usage.rst +++ b/docs/api-usage.rst @@ -2,15 +2,38 @@ Getting started with the API ############################ -The ``gitlab`` package provides 3 base types: +python-gitlab supports both GitLab v3 and v4 APIs. + +v3 being deprecated by GitLab, its support in python-gitlab will be minimal. +The development team will focus on v4. + +v3 is still the default API used by python-gitlab, for compatibility reasons.. + + +Base types +========== + +The ``gitlab`` package provides some base types. * ``gitlab.Gitlab`` is the primary class, handling the HTTP requests. It holds the GitLab URL and authentication information. -* ``gitlab.GitlabObject`` is the base class for all the GitLab objects. These - objects provide an abstraction for GitLab resources (projects, groups, and so - on). -* ``gitlab.BaseManager`` is the base class for objects managers, providing the - API to manipulate the resources and their attributes. + +For v4 the following types are defined: + +* ``gitlab.base.RESTObject`` is the base class for all the GitLab v4 objects. + These objects provide an abstraction for GitLab resources (projects, groups, + and so on). +* ``gitlab.base.RESTManager`` is the base class for v4 objects managers, + providing the API to manipulate the resources and their attributes. + +For v3 the following types are defined: + +* ``gitlab.base.GitlabObject`` is the base class for all the GitLab v3 objects. + These objects provide an abstraction for GitLab resources (projects, groups, + and so on). +* ``gitlab.base.BaseManager`` is the base class for v3 objects managers, + providing the API to manipulate the resources and their attributes. + ``gitlab.Gitlab`` class ======================= @@ -40,7 +63,9 @@ You can also use configuration files to create ``gitlab.Gitlab`` objects: See the :ref:`cli_configuration` section for more information about configuration files. -**GitLab v4 support** + +API version +=========== ``python-gitlab`` uses the v3 GitLab API by default. Use the ``api_version`` parameter to switch to v4: @@ -53,15 +78,17 @@ parameter to switch to v4: .. warning:: - The v4 support is experimental. + The python-gitlab API is not the same for v3 and v4. Make sure to read + :ref:`switching_to_v4` before upgrading. + + v4 will become the default in python-gitlab. Managers ======== The ``gitlab.Gitlab`` class provides managers to access the GitLab resources. Each manager provides a set of methods to act on the resources. The available -methods depend on the resource type. Resources are represented as -``gitlab.GitlabObject``-derived objects. +methods depend on the resource type. Examples: @@ -84,17 +111,22 @@ Examples: The attributes of objects are defined upon object creation, and depend on the GitLab API itself. To list the available information associated with an object -use the python introspection tools: +use the python introspection tools for v3, or the ``attributes`` attribute for +v4: .. code-block:: python project = gl.projects.get(1) + + # v3 print(vars(project)) # or print(project.__dict__) -Some ``gitlab.GitlabObject`` classes also provide managers to access related -GitLab resources: + # v4 + print(project.attributes) + +Some objects also provide managers to access related GitLab resources: .. code-block:: python @@ -105,7 +137,7 @@ GitLab resources: Gitlab Objects ============== -You can update or delete an object when it exists as a ``GitlabObject`` object: +You can update or delete a remote object when it exists locally: .. code-block:: python @@ -119,8 +151,8 @@ You can update or delete an object when it exists as a ``GitlabObject`` object: project.delete() -Some ``GitlabObject``-derived classes provide additional methods, allowing more -actions on the GitLab resources. For example: +Some classes provide additional methods, allowing more actions on the GitLab +resources. For example: .. code-block:: python @@ -128,6 +160,22 @@ actions on the GitLab resources. For example: project = gl.projects.get(1) project.star() +Lazy objects (v4 only) +====================== + +To avoid useless calls to the server API, you can create lazy objects. These +objects are created locally using a known ID, and give access to other managers +and methods. + +The following exemple will only make one API call to the GitLab server to star +a project: + +.. code-block:: python + + # star a git repository + project = gl.projects.get(1, lazy=True) # no API call + project.star() # API call + Pagination ========== @@ -142,8 +190,7 @@ listing methods support the ``page`` and ``per_page`` parameters: The first page is page 1, not page 0. - -By default GitLab does not return the complete list of items. Use the ``all`` +By default GitLab does not return the complete list of items. Use the ``all`` parameter to get all the items when using listing methods: .. code-block:: python @@ -151,7 +198,7 @@ parameter to get all the items when using listing methods: all_groups = gl.groups.list(all=True) all_owned_projects = gl.projects.owned(all=True) -.. note:: +.. warning:: python-gitlab will iterate over the list by calling the corresponding API multiple times. This might take some time if you have a lot of items to @@ -160,6 +207,15 @@ parameter to get all the items when using listing methods: use ``safe_all=True`` instead to stop pagination automatically if the recursion limit is hit. +With v4, ``list()`` methods can also return a generator object which will +handle the next calls to the API when required: + +.. code-block:: python + + items = gl.groups.list(as_list=False) + for item in items: + print(item.attributes) + Sudo ==== diff --git a/docs/cli.rst b/docs/cli.rst index 349ee02..e4d3437 100644 --- a/docs/cli.rst +++ b/docs/cli.rst @@ -28,7 +28,8 @@ Content ------- The configuration file uses the ``INI`` format. It contains at least a -``[global]`` section, and a new section for each GitLab server. For example: +``[global]`` section, and a specific section for each GitLab server. For +example: .. code-block:: ini @@ -98,7 +99,7 @@ CLI Objects and actions ------------------- -The ``gitlab`` command expects two mandatory arguments. This first one is the +The ``gitlab`` command expects two mandatory arguments. The first one is the type of object that you want to manipulate. The second is the action that you want to perform. For example: @@ -140,8 +141,8 @@ These options must be defined before the mandatory arguments. Output format. Defaults to a custom format. Can also be ``yaml`` or ``json``. ``--fields``, ``-f`` - Comma-separated list of fields to display (``yaml`` and ``json`` formats - only). If not used, all the object fields are displayed. + Comma-separated list of fields to display (``yaml`` and ``json`` output + formats only). If not used, all the object fields are displayed. Example: diff --git a/docs/switching-to-v4.rst b/docs/switching-to-v4.rst index 84181ff..3415bc4 100644 --- a/docs/switching-to-v4.rst +++ b/docs/switching-to-v4.rst @@ -1,3 +1,5 @@ +.. _switching_to_v4: + ########################## Switching to GtiLab API v4 ########################## @@ -10,15 +12,12 @@ 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: +To use the new v4 API, explicitly define ``api_version` `in the ``Gitlab`` +constructor: .. code-block:: python @@ -79,7 +78,7 @@ following important changes in the python 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 + ``lazy=True`` parameter. This creates shallow objects that provide usual managers. The following v3 code: |