diff --git a/README.rst b/README.rst index 683332f54..6462bb6b2 100644 --- a/README.rst +++ b/README.rst @@ -29,6 +29,25 @@ python-gitlab It supports the v4 API of GitLab, and provides a CLI tool (``gitlab``). +.. _features: + +Features +-------- + +``python-gitlab`` enables you to: + +* write Pythonic code to manage your GitLab resources. +* pass arbitrary parameters to the GitLab API. Simply follow GitLab's docs + on what parameters are available. +* access arbitrary endpoints as soon as they are available on GitLab, by using + lower-level API methods. +* use persistent requests sessions for authentication, proxy and certificate handling. +* handle smart retries on network and server errors, with rate-limit handling. +* flexible handling of paginated responses, including lazy iterators. +* automatically URL-encode paths and parameters where needed. +* automatically convert some complex data structures to API attribute types +* merge configuration from config files, environment variables and arguments. + Installation ------------ @@ -55,7 +74,6 @@ From GitLab: $ pip install git+https://gitlab.com/python-gitlab/python-gitlab.git - Using the docker images ----------------------- diff --git a/docs/api-levels.rst b/docs/api-levels.rst new file mode 100644 index 000000000..5a52b78b4 --- /dev/null +++ b/docs/api-levels.rst @@ -0,0 +1,104 @@ +################ +Lower-level APIs +################ + +``python-gitlab``'s API levels provide different degrees of convenience, control and stability. + +Main interface - ``Gitlab``, managers and objects +================================================= + +As shown in previous sections and examples, the high-level API interface wraps GitLab's API +endpoints and makes them available from the ``Gitlab`` instance via managers that create +objects you can manipulate. + +This is what most users will want to use, as it covers most of GitLab's API endpoints, and +allows you to write idiomatic Python code when interacting with the API. + +Lower-level API - HTTP methods +============================== + +.. danger:: + + At this point, python-gitlab will no longer take care of URL-encoding and other transformations + needed to correctly pass API parameter types. You have to construct these correctly yourself. + + However, you still benefit from many of the client's :ref:`features` such as authentication, + requests and retry handling. + +.. important:: + + If you've found yourself at this section because of an endpoint not yet implemented in + the library - please consider opening a pull request implementing the resource or at + least filing an issue so we can track progress. + + High-quality pull requests for standard endpoints that pass CI and include unit tests and + documentation are easy to review, and can land quickly with monthly releases. If you ask, + we can also trigger a new release, so you and everyone benefits from the contribution right away! + +Managers and objects call specific HTTP methods to fetch or send data to the server. These methods +can be invoked directly to access endpoints not currently implemented by the client. This essentially +gives you some level of usability for any endpoint the moment it is available on your GitLab instance. + +These methods can be accessed directly via the ``Gitlab`` instance (e.g. ``gl.http_get()``), or via an +object's manager (e.g. ``project.manager.gitlab.http_get()``), if the ``Gitlab`` instance is not available +in the current context. + +For example, if you'd like to access GitLab's `undocumented latest pipeline endpoint +`__, +you can do so by calling ``http_get()`` with the path to the endpoint: + +.. code-block:: python + + >>> gl = gitlab.Gitlab(private_token=private_token) + >>> + >>> pipeline = gl.http_get("/projects/gitlab-org%2Fgitlab/pipelines/latest") + >>> pipeline["id"] + 449070256 + +The available methods are: + +* ``http_get()`` +* ``http_post()`` +* ``http_put()`` +* ``http_delete()`` +* ``http_list()`` (a wrapper around ``http_get`` handling pagination, including with lazy generators) +* ``http_head()`` (only returns the header dictionary) + +Lower-lower-level API - HTTP requests +===================================== + +.. important:: + + This is mostly intended for internal use in python-gitlab and may have a less stable interface than + higher-level APIs. To lessen the chances of a change to the interface impacting your code, we + recommend using keyword arguments when calling the interfaces. + +At the lowest level, HTTP methods call ``http_request()``, which performs the actual request and takes +care of details such as timeouts, retries, and handling rate-limits. + +This method can be invoked directly to or customize this behavior for a single request, or to call custom +HTTP methods not currently implemented in the library - while still making use of all of the client's +options and authentication methods. + +For example, if for whatever reason you want to fetch allowed methods for an endpoint at runtime: + +.. code-block:: python + + >>> gl = gitlab.Gitlab(private_token=private_token) + >>> + >>> response = gl.http_request(verb="OPTIONS", path="/projects") + >>> response.headers["Allow"] + 'OPTIONS, GET, POST, HEAD' + +Or get the total number of a user's events with a customized HEAD request: + +.. code-block:: python + + >>> response = gl.http_request( + verb="HEAD", + path="/events", + query_params={"sudo": "some-user"}, + timeout=10 + ) + >>> response.headers["X-Total"] + '123' diff --git a/docs/index.rst b/docs/index.rst index 86ae17c2b..ca0c83fb6 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -11,6 +11,7 @@ api-objects api/gitlab cli-objects + api-levels changelog release-notes faq