summaryrefslogtreecommitdiff
path: root/README.rst
blob: cce2ad0e36d20fc349f27c412fbf0f38692c7079 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
.. image:: https://travis-ci.org/python-gitlab/python-gitlab.svg?branch=master
   :target: https://travis-ci.org/python-gitlab/python-gitlab

.. image:: https://badge.fury.io/py/python-gitlab.svg
   :target: https://badge.fury.io/py/python-gitlab

.. image:: https://readthedocs.org/projects/python-gitlab/badge/?version=latest
   :target: https://python-gitlab.readthedocs.org/en/latest/?badge=latest

Python GitLab
=============

``python-gitlab`` is a Python package providing access to the GitLab server API.

It supports the v3 and v4 APIs of GitLab, and provides a CLI tool (``gitlab``).

Installation
============

Requirements
------------

python-gitlab depends on:

* `python-requests <http://docs.python-requests.org/en/latest/>`_
* `six <https://pythonhosted.org/six/>`_

Install with pip
----------------

.. code-block:: console

   pip install python-gitlab

Bug reports
===========

Please report bugs and feature requests at
https://github.com/python-gitlab/python-gitlab/issues.


Documentation
=============

The full documentation for CLI and API is available on `readthedocs
<http://python-gitlab.readthedocs.org/en/stable/>`_.


Contributing
============

You can contribute to the project in multiple ways:

* Write documentation
* Implement features
* Fix bugs
* Add unit and functional tests
* Everything else you can think of

Provide your patches as github pull requests. Thanks!

Running unit tests
------------------

Before submitting a pull request make sure that the tests still succeed with
your change. Unit tests will run using the travis service and passing tests are
mandatory.

You need to install ``tox`` to run unit tests and documentation builds:

.. code-block:: bash

   # run the unit tests for python 2/3, and the pep8 tests:
   tox

   # run tests in one environment only:
   tox -epy35

   # build the documentation, the result will be generated in
   # build/sphinx/html/
   tox -edocs

Running integration tests
-------------------------

Two scripts run tests against a running gitlab instance, using a docker
container. You need to have docker installed on the test machine, and your user
must have the correct permissions to talk to the docker daemon.

To run these tests:

.. code-block:: bash

   # run the CLI tests:
   ./tools/functional_tests.sh

   # run the python API tests:
   ./tools/py_functional_tests.sh

You can also build a test environment using the following command:

.. code-block:: bash

   ./tools/build_test_env.sh

A freshly configured gitlab container will be available at
http://localhost:8080 (login ``root`` / password ``5iveL!fe``). A configuration
for python-gitlab will be written in ``/tmp/python-gitlab.cfg``.

To cleanup the environment delete the container:

.. code-block:: bash

   docker rm -f gitlab-test