FazBrowse GitHub Viewer | Trending |
URL:
| Home
Tools: [Download Repo ZIP]   [Original HTTPS Page]

docs(api): describe use of lower-level methods · python-gitlab/python-gitlab@b7a6874 · GitHub

  1. python-gitlab
  2. python-gitlab

Repository navigation

Commit b7a6874

Browse files
nejch
authored and
JohnVillalovos
committed
docs(api): describe use of lower-level methods
1 parent 97cae38 commit b7a6874

3 files changed

Lines changed: 105 additions & 0 deletions

File tree

‎README.rst‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,14 @@ python-gitlab
2929

3030
It supports the v4 API of GitLab, and provides a CLI tool (``gitlab``).
3131

32+
The client aims to let you write clean Python code when managing GitLab resources.
33+
You can pass arbitrary parameters to the GitLab API - so you only need to
34+
follow GitLab's current documentation on what parameters are available.
35+
36+
It also provides lower-level API methods giving you a degree of control and
37+
usability for any endpoint the moment it is available on GitLab.com or your
38+
GitLab instance.
39+
3240
Installation
3341
------------
3442

‎docs/api-levels.rst‎

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
################
2+
Lower-level APIs
3+
################
4+
5+
``python-gitlab``'s API levels provide different degrees of convenience, control and stability.
6+
7+
Main interface - ``Gitlab``, managers and objects
8+
=================================================
9+
10+
As shown in previous sections and examples, the high-level API interface wraps GitLab's API
11+
endpoints and makes them available from the ``Gitlab`` instance via managers that create
12+
objects you can manipulate.
13+
14+
This is what most users will want to use, as it covers most of GitLab's API endpoints, and
15+
allows you to write idiomatic Python code when interacting with the API.
16+
17+
Lower-level API - HTTP methods
18+
==============================
19+
20+
.. danger::
21+
22+
At this point, python-gitlab will no longer take care of URL-encoding and other transformations
23+
needed to correctly pass API parameter types. You have to construct these correctly yourself.
24+
25+
.. important::
26+
27+
If you've found yourself at this section because of an endpoint not yet implemented in
28+
the library - please consider opening a pull request implementing the resource or at
29+
least filing an issue so we can track progress.
30+
31+
High-quality pull requests for standard endpoints that pass CI and include unit tests and
32+
documentation are easy to review, and can land quickly with monthly releases. If you ask,
33+
we can also trigger a new release, so you and everyone benefits from the contribution right away!
34+
35+
Managers and objects call specific HTTP methods to fetch or send data to the server. These methods
36+
can be invoked directly to access endpoints not currently implemented by the client. This essentially
37+
gives you some level of usability for any endpoint the moment it is available on your GitLab instance.
38+
39+
These methods can be accessed directly via the ``Gitlab`` instance (e.g. ``gl.http_get()``), or via an
40+
object's manager (e.g. ``project.manager.gitlab.http_get()``), if the ``Gitlab`` instance is not available
41+
in the current context.
42+
43+
For example, if you'd like to access GitLab's `undocumented latest pipeline endpoint
44+
<https://gitlab.com/gitlab-org/gitlab/-/blob/5e2a61166d2a033d3fd1eb4c09d896ed19a57e60/lib/api/ci/pipelines.rb#L97>`__,
45+
you can do so by calling ``http_get()`` with the path to the endpoint:
46+
47+
.. code-block:: python
48+
49+
>>> gl = gitlab.Gitlab(private_token=private_token)
50+
>>>
51+
>>> pipeline = gl.http_get("/projects/gitlab-org%2Fgitlab/pipelines/latest")
52+
>>> pipeline["id"]
53+
449070256
54+
55+
The available methods are:
56+
57+
* ``http_get()``
58+
* ``http_post()``
59+
* ``http_put()``
60+
* ``http_delete()``
61+
* ``http_list()`` (a wrapper around ``http_get`` handling pagination, including with lazy generators)
62+
* ``http_head()`` (only returns the header dictionary)
63+
64+
Lower-lower-level API - HTTP requests
65+
=====================================
66+
67+
.. important::
68+
69+
This is mostly intended for internal use in python-gitlab and may have a less stable interface than
70+
higher-level APIs. To lessen the chances of a change to the interface impacting your code, we
71+
recommend using keyword arguments when calling the interfaces.
72+
73+
At the lowest level, HTTP methods call ``http_request()``, which performs the actual request and takes
74+
care of details such as timeouts, retries, and handling rate-limits.
75+
76+
This method can be invoked directly to or customize this behavior for a single request, or to call custom
77+
HTTP methods not currently implemented in the library - while still making use of all of the client's
78+
options and authentication methods.
79+
80+
For example, if for whatever reason you want to fetch allowed methods for an endpoint at runtime:
81+
82+
.. code-block:: python
83+
84+
>>> gl = gitlab.Gitlab(private_token=private_token)
85+
>>>
86+
>>> response = gl.http_request("OPTIONS", "/projects")
87+
>>> response.headers["Allow"]
88+
'OPTIONS, GET, POST, HEAD'
89+
90+
Or get the total number of a user's events with a customized HEAD request:
91+
92+
.. code-block:: python
93+
94+
>>> response = gl.http_request("HEAD", "/events", query_params={"sudo": "some-user"}, timeout=10)
95+
>>> response.headers["X-Total"]
96+
'123'

‎docs/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@
1111
api-objects
1212
api/gitlab
1313
cli-objects
14+
api-levels
1415
changelog
1516
release-notes
1617
faq

0 commit comments

Comments
 (0)
Back | FazBrowse Home | New Git URL