diff options
| author | Nejc Habjan <hab.nejc@gmail.com> | 2021-12-01 01:04:53 +0100 |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2021-12-01 01:04:53 +0100 |
| commit | 8d76826fa64460e504acc5924f859f8dbc246b42 (patch) | |
| tree | 083fefada982c795e2415092794db429abb0c184 /docs | |
| parent | 5a1678f43184bd459132102cc13cf8426fe0449d (diff) | |
| parent | 86ab04e54ea4175f10053decfad5086cda7aa024 (diff) | |
| download | gitlab-master.tar.gz | |
Merge pull request #1723 from python-gitlab/jlvillal/dead_mastermaster
Close-out `master` branch
Diffstat (limited to 'docs')
70 files changed, 0 insertions, 7628 deletions
diff --git a/docs/Makefile b/docs/Makefile deleted file mode 100644 index a59769c..0000000 --- a/docs/Makefile +++ /dev/null @@ -1,177 +0,0 @@ -# Makefile for Sphinx documentation -# - -# You can set these variables from the command line. -SPHINXOPTS = -SPHINXBUILD = sphinx-build -PAPER = -BUILDDIR = _build - -# User-friendly check for sphinx-build -ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1) -$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/) -endif - -# Internal variables. -PAPEROPT_a4 = -D latex_paper_size=a4 -PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . -# the i18n builder cannot share the environment and doctrees with the others -I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . - -.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext - -help: - @echo "Please use \`make <target>' where <target> is one of" - @echo " html to make standalone HTML files" - @echo " dirhtml to make HTML files named index.html in directories" - @echo " singlehtml to make a single large HTML file" - @echo " pickle to make pickle files" - @echo " json to make JSON files" - @echo " htmlhelp to make HTML files and a HTML help project" - @echo " qthelp to make HTML files and a qthelp project" - @echo " devhelp to make HTML files and a Devhelp project" - @echo " epub to make an epub" - @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" - @echo " latexpdf to make LaTeX files and run them through pdflatex" - @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx" - @echo " text to make text files" - @echo " man to make manual pages" - @echo " texinfo to make Texinfo files" - @echo " info to make Texinfo files and run them through makeinfo" - @echo " gettext to make PO message catalogs" - @echo " changes to make an overview of all changed/added/deprecated items" - @echo " xml to make Docutils-native XML files" - @echo " pseudoxml to make pseudoxml-XML files for display purposes" - @echo " linkcheck to check all external links for integrity" - @echo " doctest to run all doctests embedded in the documentation (if enabled)" - -clean: - rm -rf $(BUILDDIR)/* - -html: - $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." - -dirhtml: - $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." - -singlehtml: - $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml - @echo - @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." - -pickle: - $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle - @echo - @echo "Build finished; now you can process the pickle files." - -json: - $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json - @echo - @echo "Build finished; now you can process the JSON files." - -htmlhelp: - $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp - @echo - @echo "Build finished; now you can run HTML Help Workshop with the" \ - ".hhp project file in $(BUILDDIR)/htmlhelp." - -qthelp: - $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp - @echo - @echo "Build finished; now you can run "qcollectiongenerator" with the" \ - ".qhcp project file in $(BUILDDIR)/qthelp, like this:" - @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/python-gitlab.qhcp" - @echo "To view the help file:" - @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/python-gitlab.qhc" - -devhelp: - $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp - @echo - @echo "Build finished." - @echo "To view the help file:" - @echo "# mkdir -p $$HOME/.local/share/devhelp/python-gitlab" - @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/python-gitlab" - @echo "# devhelp" - -epub: - $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub - @echo - @echo "Build finished. The epub file is in $(BUILDDIR)/epub." - -latex: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo - @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." - @echo "Run \`make' in that directory to run these through (pdf)latex" \ - "(use \`make latexpdf' here to do that automatically)." - -latexpdf: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo "Running LaTeX files through pdflatex..." - $(MAKE) -C $(BUILDDIR)/latex all-pdf - @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." - -latexpdfja: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo "Running LaTeX files through platex and dvipdfmx..." - $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja - @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." - -text: - $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text - @echo - @echo "Build finished. The text files are in $(BUILDDIR)/text." - -man: - $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man - @echo - @echo "Build finished. The manual pages are in $(BUILDDIR)/man." - -texinfo: - $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo - @echo - @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." - @echo "Run \`make' in that directory to run these through makeinfo" \ - "(use \`make info' here to do that automatically)." - -info: - $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo - @echo "Running Texinfo files through makeinfo..." - make -C $(BUILDDIR)/texinfo info - @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." - -gettext: - $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale - @echo - @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." - -changes: - $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes - @echo - @echo "The overview file is in $(BUILDDIR)/changes." - -linkcheck: - $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck - @echo - @echo "Link check complete; look for any errors in the above output " \ - "or in $(BUILDDIR)/linkcheck/output.txt." - -doctest: - $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest - @echo "Testing of doctests in the sources finished, look at the " \ - "results in $(BUILDDIR)/doctest/output.txt." - -xml: - $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml - @echo - @echo "Build finished. The XML files are in $(BUILDDIR)/xml." - -pseudoxml: - $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml - @echo - @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." diff --git a/docs/__init__.py b/docs/__init__.py deleted file mode 100644 index e69de29..0000000 --- a/docs/__init__.py +++ /dev/null diff --git a/docs/_templates/breadcrumbs.html b/docs/_templates/breadcrumbs.html deleted file mode 100644 index 68648fa..0000000 --- a/docs/_templates/breadcrumbs.html +++ /dev/null @@ -1,24 +0,0 @@ -{# Support for Sphinx 1.3+ page_source_suffix, but don't break old builds. #} - -{% if page_source_suffix %} -{% set suffix = page_source_suffix %} -{% else %} -{% set suffix = source_suffix %} -{% endif %} - -<div role="navigation" aria-label="breadcrumbs navigation"> - <ul class="wy-breadcrumbs"> - <li><a href="{{ pathto(master_doc) }}">Docs</a> »</li> - {% for doc in parents %} - <li><a href="{{ doc.link|e }}">{{ doc.title }}</a> »</li> - {% endfor %} - <li>{{ title }}</li> - <li class="wy-breadcrumbs-aside"> - {% if pagename != "search" %} - <a href="https://github.com/python-gitlab/python-gitlab/blob/master/{{ conf_py_path }}{{ pagename }}{{ suffix }}" class="fa fa-github"> Edit on GitHub</a> - | <a href="https://github.com/python-gitlab/python-gitlab/issues/new?title=Documentation+bug&body=%0A%0A------%0AIn+page:+{{ pagename }}{{ suffix }}">Report a bug</a> - {% endif %} - </li> - </ul> - <hr/> -</div> diff --git a/docs/api-objects.rst b/docs/api-objects.rst deleted file mode 100644 index 567344f..0000000 --- a/docs/api-objects.rst +++ /dev/null @@ -1,58 +0,0 @@ -############ -API examples -############ - -.. toctree:: - :maxdepth: 1 - - gl_objects/access_requests - gl_objects/appearance - gl_objects/applications - gl_objects/emojis - gl_objects/badges - gl_objects/branches - gl_objects/clusters - gl_objects/messages - gl_objects/commits - gl_objects/deploy_keys - gl_objects/deploy_tokens - gl_objects/deployments - gl_objects/discussions - gl_objects/environments - gl_objects/events - gl_objects/epics - gl_objects/features - gl_objects/geo_nodes - gl_objects/groups - gl_objects/issues - gl_objects/keys - gl_objects/boards - gl_objects/labels - gl_objects/notifications - gl_objects/mrs - gl_objects/mr_approvals - gl_objects/milestones - gl_objects/namespaces - gl_objects/notes - gl_objects/packages - gl_objects/pagesdomains - gl_objects/personal_access_tokens - gl_objects/pipelines_and_jobs - gl_objects/projects - gl_objects/project_access_tokens - gl_objects/protected_branches - gl_objects/releases - gl_objects/runners - gl_objects/remote_mirrors - gl_objects/repositories - gl_objects/repository_tags - gl_objects/search - gl_objects/settings - gl_objects/snippets - gl_objects/system_hooks - gl_objects/templates - gl_objects/todos - gl_objects/users - gl_objects/variables - gl_objects/sidekiq - gl_objects/wikis diff --git a/docs/api-usage.rst b/docs/api-usage.rst deleted file mode 100644 index f30ed03..0000000 --- a/docs/api-usage.rst +++ /dev/null @@ -1,458 +0,0 @@ -############################ -Getting started with the API -############################ - -python-gitlab only supports GitLab API v4. - -``gitlab.Gitlab`` class -======================= - -To connect to GitLab.com or another GitLab instance, create a ``gitlab.Gitlab`` object: - -.. code-block:: python - - import gitlab - - # anonymous read-only access for public resources (GitLab.com) - gl = gitlab.Gitlab() - - # anonymous read-only access for public resources (self-hosted GitLab instance) - gl = gitlab.Gitlab('https://gitlab.example.com') - - # private token or personal token authentication (GitLab.com) - gl = gitlab.Gitlab(private_token='JVNSESs8EwWRx5yDxM5q') - - # private token or personal token authentication (self-hosted GitLab instance) - gl = gitlab.Gitlab(url='https://gitlab.example.com', private_token='JVNSESs8EwWRx5yDxM5q') - - # oauth token authentication - gl = gitlab.Gitlab('https://gitlab.example.com', oauth_token='my_long_token_here') - - # job token authentication (to be used in CI) - # bear in mind the limitations of the API endpoints it supports: - # https://docs.gitlab.com/ee/ci/jobs/ci_job_token.html - import os - gl = gitlab.Gitlab('https://gitlab.example.com', job_token=os.environ['CI_JOB_TOKEN']) - - # Define your own custom user agent for requests - gl = gitlab.Gitlab('https://gitlab.example.com', user_agent='my-package/1.0.0') - - # make an API request to create the gl.user object. This is mandatory if you - # use the username/password authentication - not required for token authentication, - # and will not work with job tokens. - gl.auth() - -You can also use configuration files to create ``gitlab.Gitlab`` objects: - -.. code-block:: python - - gl = gitlab.Gitlab.from_config('somewhere', ['/tmp/gl.cfg']) - -See the :ref:`cli_configuration` section for more information about -configuration files. - -.. warning:: - - Note that a url that results in 301/302 redirects will raise an error, - so it is highly recommended to use the final destination in the ``url`` field. - For example, if the GitLab server you are using redirects requests from http - to https, make sure to use the ``https://`` protocol in the URL definition. - - A URL that redirects using 301/302 (rather than 307/308) will most likely - `cause malformed POST and PUT requests <https://github.com/psf/requests/blob/c45a4dfe6bfc6017d4ea7e9f051d6cc30972b310/requests/sessions.py#L324-L332>`_. - - python-gitlab will therefore raise a ``RedirectionError`` when it encounters - a redirect which it believes will cause such an error, to avoid confusion - between successful GET and failing POST/PUT requests on the same instance. - -Note on password authentication -------------------------------- - -The ``/session`` API endpoint used for username/password authentication has -been removed from GitLab in version 10.2, and is not available on gitlab.com -anymore. Personal token authentication is the preferred authentication method. - -If you need username/password authentication, you can use cookie-based -authentication. You can use the web UI form to authenticate, retrieve cookies, -and then use a custom ``requests.Session`` object to connect to the GitLab API. -The following code snippet demonstrates how to automate this: -https://gist.github.com/gpocentek/bd4c3fbf8a6ce226ebddc4aad6b46c0a. - -See `issue 380 <https://github.com/python-gitlab/python-gitlab/issues/380>`_ -for a detailed discussion. - -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. - -Examples: - -.. code-block:: python - - # list all the projects - projects = gl.projects.list() - for project in projects: - print(project) - - # get the group with id == 2 - group = gl.groups.get(2) - for project in group.projects.list(): - print(project) - - # create a new user - user_data = {'email': 'jen@foo.com', 'username': 'jen', 'name': 'Jen'} - user = gl.users.create(user_data) - print(user) - -You can list the mandatory and optional attributes for object creation and -update with the manager's ``get_create_attrs()`` and ``get_update_attrs()`` -methods. They return 2 tuples, the first one is the list of mandatory -attributes, the second one is the list of optional attribute: - -.. code-block:: python - - # v4 only - print(gl.projects.get_create_attrs()) - (('name',), ('path', 'namespace_id', ...)) - -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 ``attributes`` attribute: - -.. code-block:: python - - project = gl.projects.get(1) - print(project.attributes) - -Some objects also provide managers to access related GitLab resources: - -.. code-block:: python - - # list the issues for a project - project = gl.projects.get(1) - issues = project.issues.list() - -python-gitlab allows to send any data to the GitLab server when making queries. -In case of invalid or missing arguments python-gitlab will raise an exception -with the GitLab server error message: - -.. code-block:: python - - >>> gl.projects.list(sort='invalid value') - ... - GitlabListError: 400: sort does not have a valid value - -You can use the ``query_parameters`` argument to send arguments that would -conflict with python or python-gitlab when using them as kwargs: - -.. code-block:: python - - gl.user_activities.list(from='2019-01-01') ## invalid - - gl.user_activities.list(query_parameters={'from': '2019-01-01'}) # OK - -Gitlab Objects -============== - -You can update or delete a remote object when it exists locally: - -.. code-block:: python - - # update the attributes of a resource - project = gl.projects.get(1) - project.wall_enabled = False - # don't forget to apply your changes on the server: - project.save() - - # delete the resource - project.delete() - -Some classes provide additional methods, allowing more actions on the GitLab -resources. For example: - -.. code-block:: python - - # star a git repository - project = gl.projects.get(1) - project.star() - -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.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. - -Lazy objects -============ - -To avoid useless API calls to the server you can create lazy objects. These -objects are created locally using a known ID, and give access to other managers -and methods. - -The following example will only make one API call to the GitLab server to star -a project (the previous example used 2 API calls): - -.. code-block:: python - - # star a git repository - project = gl.projects.get(1, lazy=True) # no API call - project.star() # API call - -Pagination -========== - -You can use pagination to iterate over long lists. All the Gitlab objects -listing methods support the ``page`` and ``per_page`` parameters: - -.. code-block:: python - - ten_first_groups = gl.groups.list(page=1, per_page=10) - -.. warning:: - - The first page is page 1, not page 0. - -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 - - all_groups = gl.groups.list(all=True) - all_owned_projects = gl.projects.list(owned=True, all=True) - -You can define the ``per_page`` value globally to avoid passing it to every -``list()`` method call: - -.. code-block:: python - - gl = gitlab.Gitlab(url, token, per_page=50) - -Gitlab allows to also use keyset pagination. You can supply it to your project listing, -but you can also do so globally. Be aware that GitLab then also requires you to only use supported -order options. At the time of writing, only ``order_by="id"`` works. - -.. code-block:: python - - gl = gitlab.Gitlab(url, token, pagination="keyset", order_by="id", per_page=100) - gl.projects.list() - -Reference: -https://docs.gitlab.com/ce/api/README.html#keyset-based-pagination - -``list()`` methods can also return a generator object which will handle the -next calls to the API when required. This is the recommended way to iterate -through a large number of items: - -.. code-block:: python - - items = gl.groups.list(as_list=False) - for item in items: - print(item.attributes) - -The generator exposes extra listing information as received from the server: - -* ``current_page``: current page number (first page is 1) -* ``prev_page``: if ``None`` the current page is the first one -* ``next_page``: if ``None`` the current page is the last one -* ``per_page``: number of items per page -* ``total_pages``: total number of pages available -* ``total``: total number of items in the list - -Sudo -==== - -If you have the administrator status, you can use ``sudo`` to act as another -user. For example: - -.. code-block:: python - - p = gl.projects.create({'name': 'awesome_project'}, sudo='user1') - -Advanced HTTP configuration -=========================== - -python-gitlab relies on ``requests`` ``Session`` objects to perform all the -HTTP requests to the Gitlab servers. - -You can provide your own ``Session`` object with custom configuration when -you create a ``Gitlab`` object. - -Context manager ---------------- - -You can use ``Gitlab`` objects as context managers. This makes sure that the -``requests.Session`` object associated with a ``Gitlab`` instance is always -properly closed when you exit a ``with`` block: - -.. code-block:: python - - with gitlab.Gitlab(host, token) as gl: - gl.projects.list() - -.. warning:: - - The context manager will also close the custom ``Session`` object you might - have used to build the ``Gitlab`` instance. - -Proxy configuration -------------------- - -The following sample illustrates how to define a proxy configuration when using -python-gitlab: - -.. code-block:: python - - import gitlab - import requests - - session = requests.Session() - session.proxies = { - 'https': os.environ.get('https_proxy'), - 'http': os.environ.get('http_proxy'), - } - gl = gitlab.gitlab(url, token, api_version=4, session=session) - -Reference: -https://2.python-requests.org/en/master/user/advanced/#proxies - -SSL certificate verification ----------------------------- - -python-gitlab relies on the CA certificate bundle in the `certifi` package -that comes with the requests library. - -If you need python-gitlab to use your system CA store instead, you can provide -the path to the CA bundle in the `REQUESTS_CA_BUNDLE` environment variable. - -Reference: -https://2.python-requests.org/en/master/user/advanced/#ssl-cert-verification - -Client side certificate ------------------------ - -The following sample illustrates how to use a client-side certificate: - -.. code-block:: python - - import gitlab - import requests - - session = requests.Session() - session.cert = ('/path/to/client.cert', '/path/to/client.key') - gl = gitlab.gitlab(url, token, api_version=4, session=session) - -Reference: -https://2.python-requests.org/en/master/user/advanced/#client-side-certificates - -Rate limits ------------ - -python-gitlab obeys the rate limit of the GitLab server by default. On -receiving a 429 response (Too Many Requests), python-gitlab sleeps for the -amount of time in the Retry-After header that GitLab sends back. If GitLab -does not return a response with the Retry-After header, python-gitlab will -perform an exponential backoff. - -If you don't want to wait, you can disable the rate-limiting feature, by -supplying the ``obey_rate_limit`` argument. - -.. code-block:: python - - import gitlab - import requests - - gl = gitlab.gitlab(url, token, api_version=4) - gl.projects.list(all=True, obey_rate_limit=False) - -If you do not disable the rate-limiting feature, you can supply a custom value -for ``max_retries``; by default, this is set to 10. To retry without bound when -throttled, you can set this parameter to -1. This parameter is ignored if -``obey_rate_limit`` is set to ``False``. - -.. code-block:: python - - import gitlab - import requests - - gl = gitlab.gitlab(url, token, api_version=4) - gl.projects.list(all=True, max_retries=12) - -.. warning:: - - You will get an Exception, if you then go over the rate limit of your GitLab instance. - -Transient errors ----------------- - -GitLab server can sometimes return a transient HTTP error. -python-gitlab can automatically retry in such case, when -``retry_transient_errors`` argument is set to ``True``. When enabled, -HTTP error codes 500 (Internal Server Error), 502 (502 Bad Gateway), -503 (Service Unavailable), and 504 (Gateway Timeout) are retried. By -default an exception is raised for these errors. - -.. code-block:: python - - import gitlab - import requests - - gl = gitlab.gitlab(url, token, api_version=4) - gl.projects.list(all=True, retry_transient_errors=True) - -The default ``retry_transient_errors`` can also be set on the ``Gitlab`` object -and overridden by individual API calls. - -.. code-block:: python - - import gitlab - import requests - gl = gitlab.gitlab(url, token, api_version=4, retry_transient_errors=True) - gl.projects.list(all=True) # retries due to default value - gl.projects.list(all=True, retry_transient_errors=False) # does not retry - -Timeout -------- - -python-gitlab will by default use the ``timeout`` option from it's configuration -for all requests. This is passed downwards to the ``requests`` module at the -time of making the HTTP request. However if you would like to override the -global timeout parameter for a particular call, you can provide the ``timeout`` -parameter to that API invocation: - -.. code-block:: python - - import gitlab - - gl = gitlab.gitlab(url, token, api_version=4) - gl.projects.import_github(ACCESS_TOKEN, 123456, "root", timeout=120.0) - -.. _object_attributes: - -Attributes in updated objects -============================= - -When methods manipulate an existing object, such as with ``refresh()`` and ``save()``, -the object will only have attributes that were returned by the server. In some cases, -such as when the initial request fetches attributes that are needed later for additional -processing, this may not be desired: - -.. code-block:: python - - project = gl.projects.get(1, statistics=True) - project.statistics - - project.refresh() - project.statistics # AttributeError - -To avoid this, either copy the object/attributes before calling ``refresh()``/``save()`` -or subsequently perform another ``get()`` call as needed, to fetch the attributes you want. diff --git a/docs/api/gitlab.rst b/docs/api/gitlab.rst deleted file mode 100644 index c13ae53..0000000 --- a/docs/api/gitlab.rst +++ /dev/null @@ -1,87 +0,0 @@ -API reference (``gitlab`` package) -================================== - -Module contents ---------------- - -.. automodule:: gitlab - :members: - :undoc-members: - :show-inheritance: - -.. autoclass:: gitlab.Gitlab - :members: - :undoc-members: - :show-inheritance: - -.. autoclass:: gitlab.GitlabList - :members: - :undoc-members: - :show-inheritance: - - -Subpackages ------------ - -.. toctree:: - - gitlab.v4 - -Submodules ----------- - -gitlab.base module ------------------- - -.. automodule:: gitlab.base - :members: - :undoc-members: - :show-inheritance: - -gitlab.cli module ------------------ - -.. automodule:: gitlab.cli - :members: - :undoc-members: - :show-inheritance: - -gitlab.config module --------------------- - -.. automodule:: gitlab.config - :members: - :undoc-members: - :show-inheritance: - -gitlab.const module -------------------- - -.. automodule:: gitlab.const - :members: - :undoc-members: - :show-inheritance: - -gitlab.exceptions module ------------------------- - -.. automodule:: gitlab.exceptions - :members: - :undoc-members: - :show-inheritance: - -gitlab.mixins module --------------------- - -.. automodule:: gitlab.mixins - :members: - :undoc-members: - :show-inheritance: - -gitlab.utils module -------------------- - -.. automodule:: gitlab.utils - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/api/gitlab.v4.rst b/docs/api/gitlab.v4.rst deleted file mode 100644 index 70358c1..0000000 --- a/docs/api/gitlab.v4.rst +++ /dev/null @@ -1,22 +0,0 @@ -gitlab.v4 package -================= - -Submodules ----------- - -gitlab.v4.objects module ------------------------- - -.. automodule:: gitlab.v4.objects - :members: - :undoc-members: - :show-inheritance: - - -Module contents ---------------- - -.. automodule:: gitlab.v4 - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/changelog.md b/docs/changelog.md deleted file mode 100644 index 66efc0f..0000000 --- a/docs/changelog.md +++ /dev/null @@ -1,2 +0,0 @@ -```{include} ../CHANGELOG.md -``` diff --git a/docs/cli-objects.rst b/docs/cli-objects.rst deleted file mode 100644 index d6648f6..0000000 --- a/docs/cli-objects.rst +++ /dev/null @@ -1,17 +0,0 @@ -################################## -CLI reference (``gitlab`` command) -################################## - -.. warning:: - - The following is a complete, auto-generated list of subcommands available - via the :command:`gitlab` command-line tool. Some of the actions may - currently not work as expected or lack functionality available via the API. - - Please see the existing `list of CLI related issues`_, or open a new one if - it is not already listed there. - -.. _list of CLI related issues: https://github.com/python-gitlab/python-gitlab/issues?q=is%3Aopen+is%3Aissue+label%3Acli - -.. autoprogram:: gitlab.cli:docs() - :prog: gitlab diff --git a/docs/cli-usage.rst b/docs/cli-usage.rst deleted file mode 100644 index ea10f93..0000000 --- a/docs/cli-usage.rst +++ /dev/null @@ -1,484 +0,0 @@ -#################### -``gitlab`` CLI usage -#################### - -``python-gitlab`` provides a :command:`gitlab` command-line tool to interact -with GitLab servers. It uses a configuration file to define how to connect to -the servers. - -.. _cli_configuration: - -Configuration -============= - -Files ------ - -``gitlab`` looks up 3 configuration files by default: - -``PYTHON_GITLAB_CFG`` environment variable - An environment variable that contains the path to a configuration file - -``/etc/python-gitlab.cfg`` - System-wide configuration file - -``~/.python-gitlab.cfg`` - User configuration file - -You can use a different configuration file with the ``--config-file`` option. - -Content -------- - -The configuration file uses the ``INI`` format. It contains at least a -``[global]`` section, and a specific section for each GitLab server. For -example: - -.. code-block:: ini - - [global] - default = somewhere - ssl_verify = true - timeout = 5 - - [somewhere] - url = https://some.whe.re - private_token = vTbFeqJYCY3sibBP7BZM - api_version = 4 - - [elsewhere] - url = http://else.whe.re:8080 - private_token = helper: path/to/helper.sh - timeout = 1 - -The ``default`` option of the ``[global]`` section defines the GitLab server to -use if no server is explicitly specified with the ``--gitlab`` CLI option. - -The ``[global]`` section also defines the values for the default connection -parameters. You can override the values in each GitLab server section. - -.. list-table:: Global options - :header-rows: 1 - - * - Option - - Possible values - - Description - * - ``ssl_verify`` - - ``True``, ``False``, or a ``str`` - - Verify the SSL certificate. Set to ``False`` to disable verification, - though this will create warnings. Any other value is interpreted as path - to a CA_BUNDLE file or directory with certificates of trusted CAs. - * - ``timeout`` - - Integer - - Number of seconds to wait for an answer before failing. - * - ``api_version`` - - ``4`` - - The API version to use to make queries. Only ``4`` is available since 1.5.0. - * - ``per_page`` - - Integer between 1 and 100 - - The number of items to return in listing queries. GitLab limits the - value at 100. - * - ``user_agent`` - - ``str`` - - A string defining a custom user agent to use when ``gitlab`` makes requests. - -You must define the ``url`` in each GitLab server section. - -.. warning:: - - Note that a url that results in 301/302 redirects will raise an error, - so it is highly recommended to use the final destination in the ``url`` field. - For example, if the GitLab server you are using redirects requests from http - to https, make sure to use the ``https://`` protocol in the URL definition. - - A URL that redirects using 301/302 (rather than 307/308) will most likely - `cause malformed POST and PUT requests <https://github.com/psf/requests/blob/c45a4dfe6bfc6017d4ea7e9f051d6cc30972b310/requests/sessions.py#L324-L332>`_. - - python-gitlab will therefore raise a ``RedirectionError`` when it encounters - a redirect which it believes will cause such an error, to avoid confusion - between successful GET and failing POST/PUT requests on the same instance. - -Only one of ``private_token``, ``oauth_token`` or ``job_token`` should be -defined. If neither are defined an anonymous request will be sent to the Gitlab -server, with very limited permissions. - -We recommend that you use `Credential helpers`_ to securely store your tokens. - -.. list-table:: GitLab server options - :header-rows: 1 - - * - Option - - Description - * - ``url`` - - URL for the GitLab server. Do **NOT** use a URL which redirects. - * - ``private_token`` - - Your user token. Login/password is not supported. Refer to `the - official documentation - <https://docs.gitlab.com/ce/user/profile/personal_access_tokens.html>`__ - to learn how to obtain a token. - * - ``oauth_token`` - - An Oauth token for authentication. The Gitlab server must be configured - to support this authentication method. - * - ``job_token`` - - Your job token. See `the official documentation - <https://docs.gitlab.com/ce/api/jobs.html#get-job-artifacts>`__ - to learn how to obtain a token. - * - ``api_version`` - - GitLab API version to use. Only ``4`` is available since 1.5.0. - * - ``http_username`` - - Username for optional HTTP authentication - * - ``http_password`` - - Password for optional HTTP authentication - - -Credential helpers ------------------- - -For all configuration options that contain secrets (``http_password``, -``personal_token``, ``oauth_token``, ``job_token``), you can specify -a helper program to retrieve the secret indicated by a ``helper:`` -prefix. This allows you to fetch values from a local keyring store -or cloud-hosted vaults such as Bitwarden. Environment variables are -expanded if they exist and ``~`` expands to your home directory. - -It is expected that the helper program prints the secret to standard output. -To use shell features such as piping to retrieve the value, you will need -to use a wrapper script; see below. - -Example for a `keyring <https://github.com/jaraco/keyring>`_ helper: - -.. code-block:: ini - - [global] - default = somewhere - ssl_verify = true - timeout = 5 - - [somewhere] - url = http://somewhe.re - private_token = helper: keyring get Service Username - timeout = 1 - -Example for a `pass <https://www.passwordstore.org>`_ helper with a wrapper script: - -.. code-block:: ini - - [global] - default = somewhere - ssl_verify = true - timeout = 5 - - [somewhere] - url = http://somewhe.re - private_token = helper: /path/to/helper.sh - timeout = 1 - -In `/path/to/helper.sh`: - -.. code-block:: bash - - #!/bin/bash - pass show path/to/password | head -n 1 - -CLI -=== - -Objects and actions -------------------- - -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: - -.. code-block:: console - - $ gitlab project list - -Use the ``--help`` option to list the available object types and actions: - -.. code-block:: console - - $ gitlab --help - $ gitlab project --help - -Some actions require additional parameters. Use the ``--help`` option to -list mandatory and optional arguments for an action: - -.. code-block:: console - - $ gitlab project create --help - -Optional arguments ------------------- - -Use the following optional arguments to change the behavior of ``gitlab``. -These options must be defined before the mandatory arguments. - -``--verbose``, ``-v`` - Outputs detail about retrieved objects. Available for legacy (default) - output only. - -``--config-file``, ``-c`` - Path to a configuration file. - -``--gitlab``, ``-g`` - ID of a GitLab server defined in the configuration file. - -``--output``, ``-o`` - Output format. Defaults to a custom format. Can also be ``yaml`` or ``json``. - - **Notice:** - - The `PyYAML package <https://pypi.org/project/PyYAML/>`_ is required to use the yaml output option. - You need to install it explicitly using ``pip install python-gitlab[yaml]`` - -``--fields``, ``-f`` - Comma-separated list of fields to display (``yaml`` and ``json`` output - formats only). If not used, all the object fields are displayed. - -Example: - -.. code-block:: console - - $ gitlab -o yaml -f id,permissions -g elsewhere -c /tmp/gl.cfg project list - -Examples -======== - - **Notice:** - - For a complete list of objects and actions available, see :doc:`/cli-objects`. - -List the projects (paginated): - -.. code-block:: console - - $ gitlab project list - -List all the projects: - -.. code-block:: console - - $ gitlab project list --all - -List all projects of a group: - -.. code-block:: console - - $ gitlab group-project list --all --group-id 1 - -List all projects of a group and its subgroups: - -.. code-block:: console - - $ gitlab group-project list --all --include-subgroups true --group-id 1 - -Limit to 5 items per request, display the 1st page only - -.. code-block:: console - - $ gitlab project list --page 1 --per-page 5 - -Get a specific project (id 2): - -.. code-block:: console - - $ gitlab project get --id 2 - -Get a specific user by id: - -.. code-block:: console - - $ gitlab user get --id 3 - -Create a deploy token for a project: - -.. code-block:: console - - $ gitlab -v project-deploy-token create --project-id 2 \ - --name bar --username root --expires-at "2021-09-09" --scopes "read_repository" - -List deploy tokens for a group: - -.. code-block:: console - - $ gitlab -v group-deploy-token list --group-id 3 - -List packages for a project: - -.. code-block:: console - - $ gitlab -v project-package list --project-id 3 - -List packages for a group: - -.. code-block:: console - - $ gitlab -v group-package list --group-id 3 - -Get a specific project package by id: - -.. code-block:: console - - $ gitlab -v project-package get --id 1 --project-id 3 - -Delete a specific project package by id: - -.. code-block:: console - - $ gitlab -v project-package delete --id 1 --project-id 3 - -Upload a generic package to a project: - -.. code-block:: console - - $ gitlab generic-package upload --project-id 1 --package-name hello-world \ - --package-version v1.0.0 --file-name hello.tar.gz --path /path/to/hello.tar.gz - -Download a project's generic package: - -.. code-block:: console - - $ gitlab generic-package download --project-id 1 --package-name hello-world \ - --package-version v1.0.0 --file-name hello.tar.gz > /path/to/hello.tar.gz - -Get a list of issues for this project: - -.. code-block:: console - - $ gitlab project-issue list --project-id 2 - -Delete a snippet (id 3): - -.. code-block:: console - - $ gitlab project-snippet delete --id 3 --project-id 2 - -Update a snippet: - -.. code-block:: console - - $ gitlab project-snippet update --id 4 --project-id 2 \ - --code "My New Code" - -Create a snippet: - -.. code-block:: console - - $ gitlab project-snippet create --project-id 2 - Impossible to create object (Missing attribute(s): title, file-name, code) - $ # oops, let's add the attributes: - $ gitlab project-snippet create --project-id 2 --title "the title" \ - --file-name "the name" --code "the code" - -Get a specific project commit by its SHA id: - -.. code-block:: console - - $ gitlab project-commit get --project-id 2 --id a43290c - -Get the signature (e.g. GPG or x509) of a signed commit: - -.. code-block:: console - - $ gitlab project-commit signature --project-id 2 --id a43290c - -Define the status of a commit (as would be done from a CI tool for example): - -.. code-block:: console - - $ gitlab project-commit-status create --project-id 2 \ - --commit-id a43290c --state success --name ci/jenkins \ - --target-url http://server/build/123 \ - --description "Jenkins build succeeded" - -Download the artifacts zip archive of a job: - -.. code-block:: console - - $ gitlab project-job artifacts --id 10 --project-id 1 > artifacts.zip - -Use sudo to act as another user (admin only): - -.. code-block:: console - - $ gitlab project create --name user_project1 --sudo username - -List values are comma-separated: - -.. code-block:: console - - $ gitlab issue list --labels foo,bar - -Reading values from files -------------------------- - -You can make ``gitlab`` read values from files instead of providing them on the -command line. This is handy for values containing new lines for instance: - -.. code-block:: console - - $ cat > /tmp/description << EOF - This is the description of my project. - - It is obviously the best project around - EOF - $ gitlab project create --name SuperProject --description @/tmp/description - -Enabling shell autocompletion -============================= - -To get autocompletion, you'll need to install the package with the extra -"autocompletion": - -.. code-block:: console - - pip install python_gitlab[autocompletion] - - -Add the appropriate command below to your shell's config file so that it is run on -startup. You will likely have to restart or re-login for the autocompletion to -start working. - -Bash ----- - -.. code-block:: console - - eval "$(register-python-argcomplete gitlab)" - -tcsh ----- - -.. code-block:: console - - eval `register-python-argcomplete --shell tcsh gitlab` - -fish ----- - -.. code-block:: console - - register-python-argcomplete --shell fish gitlab | . - -Zsh ---- - -.. warning:: - - Zsh autocompletion support is broken right now in the argcomplete python - package. Perhaps it will be fixed in a future release of argcomplete at - which point the following instructions will enable autocompletion in zsh. - -To activate completions for zsh you need to have bashcompinit enabled in zsh: - -.. code-block:: console - - autoload -U bashcompinit - bashcompinit - -Afterwards you can enable completion for gitlab: - -.. code-block:: console - - eval "$(register-python-argcomplete gitlab)" diff --git a/docs/conf.py b/docs/conf.py deleted file mode 100644 index 9e0ad83..0000000 --- a/docs/conf.py +++ /dev/null @@ -1,295 +0,0 @@ -#!/usr/bin/env python3 -# -*- coding: utf-8 -*- -# -# python-gitlab documentation build configuration file, created by -# sphinx-quickstart on Mon Dec 8 15:17:39 2014. -# -# This file is execfile()d with the current directory set to its -# containing dir. -# -# Note that not all possible configuration values are present in this -# autogenerated file. -# -# All configuration values have a default; values that are commented out -# serve to show the default. - -from __future__ import unicode_literals - -import os -import sys - -sys.path.append("../") -sys.path.append(os.path.dirname(__file__)) -import gitlab # noqa: E402. Needed purely for readthedocs' build - -on_rtd = os.environ.get("READTHEDOCS", None) == "True" - -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. -sys.path.insert(0, os.path.abspath("..")) - -# -- General configuration ------------------------------------------------ - -# If your documentation needs a minimal Sphinx version, state it here. -# needs_sphinx = '1.0' - -# Add any Sphinx extension module names here, as strings. They can be -# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom -# ones. -extensions = [ - "myst_parser", - "sphinx.ext.autodoc", - "sphinx.ext.autosummary", - "ext.docstrings", - "sphinxcontrib.autoprogram", -] - -# Add any paths that contain templates here, relative to this directory. -templates_path = ["_templates"] - -# The suffix of source filenames. -source_suffix = {".rst": "restructuredtext", ".md": "markdown"} - -# The encoding of source files. -# source_encoding = 'utf-8-sig' - -# The master toctree document. -master_doc = "index" - -# General information about the project. -project = "python-gitlab" -copyright = "2013-2018, Gauvain Pocentek, Mika Mäenpää" - -# The version info for the project you're documenting, acts as replacement for -# |version| and |release|, also used in various other places throughout the -# built documents. -# -# The short X.Y version. -version = gitlab.__version__ -# The full version, including alpha/beta/rc tags. -release = version - -# The language for content autogenerated by Sphinx. Refer to documentation -# for a list of supported languages. -# language = None - -# There are two options for replacing |today|: either, you set today to some -# non-false value, then it is used: -# today = '' -# Else, today_fmt is used as the format for a strftime call. -# today_fmt = '%B %d, %Y' - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -exclude_patterns = ["_build"] - -# The reST default role (used for this markup: `text`) to use for all -# documents. -# default_role = None - -# If true, '()' will be appended to :func: etc. cross-reference text. -# add_function_parentheses = True - -# If true, the current module name will be prepended to all description -# unit titles (such as .. function::). -# add_module_names = True - -# If true, sectionauthor and moduleauthor directives will be shown in the -# output. They are ignored by default. -# show_authors = False - -# The name of the Pygments (syntax highlighting) style to use. -pygments_style = "sphinx" - -# A list of ignored prefixes for module index sorting. -# modindex_common_prefix = [] - -# If true, keep warnings as "system message" paragraphs in the built documents. -# keep_warnings = False - - -# -- Options for HTML output ---------------------------------------------- - -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -html_theme = "default" -if not on_rtd: # only import and set the theme if we're building docs locally - try: - import sphinx_rtd_theme - - html_theme = "sphinx_rtd_theme" - html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] - except ImportError: # Theme not found, use default - pass - -# Theme options are theme-specific and customize the look and feel of a theme -# further. For a list of options available for each theme, see the -# documentation. -# html_theme_options = {} - -# Add any paths that contain custom themes here, relative to this directory. -# html_theme_path = [] - -# The name for this set of Sphinx documents. If None, it defaults to -# "<project> v<release> documentation". -# html_title = None - -# A shorter title for the navigation bar. Default is the same as html_title. -# html_short_title = None - -# The name of an image file (relative to this directory) to place at the top -# of the sidebar. -# html_logo = None - -# The name of an image file (within the static path) to use as favicon of the -# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 -# pixels large. -# html_favicon = None - -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". -# html_static_path = ['_static'] - -# Add any extra paths that contain custom files (such as robots.txt or -# .htaccess) here, relative to this directory. These files are copied -# directly to the root of the documentation. -# html_extra_path = [] - -# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, -# using the given strftime format. -# html_last_updated_fmt = '%b %d, %Y' - -# If true, SmartyPants will be used to convert quotes and dashes to -# typographically correct entities. -# html_use_smartypants = True - -# Custom sidebar templates, maps document names to template names. -# html_sidebars = {} - -# Additional templates that should be rendered to pages, maps page names to -# template names. -# html_additional_pages = {} - -# If false, no module index is generated. -# html_domain_indices = True - -# If false, no index is generated. -# html_use_index = True - -# If true, the index is split into individual pages for each letter. -# html_split_index = False - -# If true, links to the reST sources are added to the pages. -# html_show_sourcelink = True - -# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. -# html_show_sphinx = True - -# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. -# html_show_copyright = True - -# If true, an OpenSearch description file will be output, and all pages will -# contain a <link> tag referring to it. The value of this option must be the -# base URL from which the finished HTML is served. -# html_use_opensearch = '' - -# This is the file name suffix for HTML files (e.g. ".xhtml"). -# html_file_suffix = None - -# Output file base name for HTML help builder. -htmlhelp_basename = "python-gitlabdoc" - - -# -- Options for LaTeX output --------------------------------------------- - -latex_elements = { - # The paper size ('letterpaper' or 'a4paper'). - # 'papersize': 'letterpaper', - # The font size ('10pt', '11pt' or '12pt'). - # 'pointsize': '10pt', - # Additional stuff for the LaTeX preamble. - # 'preamble': '', -} - -# Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, -# author, documentclass [howto, manual, or own class]). -latex_documents = [ - ( - "index", - "python-gitlab.tex", - "python-gitlab Documentation", - "Gauvain Pocentek, Mika Mäenpää", - "manual", - ) -] - -# The name of an image file (relative to this directory) to place at the top of -# the title page. -# latex_logo = None - -# For "manual" documents, if this is true, then toplevel headings are parts, -# not chapters. -# latex_use_parts = False - -# If true, show page references after internal links. -# latex_show_pagerefs = False - -# If true, show URL addresses after external links. -# latex_show_urls = False - -# Documents to append as an appendix to all manuals. -# latex_appendices = [] - -# If false, no module index is generated. -# latex_domain_indices = True - - -# -- Options for manual page output --------------------------------------- - -# One entry per manual page. List of tuples -# (source start file, name, description, authors, manual section). -man_pages = [ - ( - "index", - "python-gitlab", - "python-gitlab Documentation", - ["Gauvain Pocentek, Mika Mäenpää"], - 1, - ) -] - -# If true, show URL addresses after external links. -# man_show_urls = False - - -# -- Options for Texinfo output ------------------------------------------- - -# Grouping the document tree into Texinfo files. List of tuples -# (source start file, target name, title, author, -# dir menu entry, description, category) -texinfo_documents = [ - ( - "index", - "python-gitlab", - "python-gitlab Documentation", - "Gauvain Pocentek, Mika Mäenpää", - "python-gitlab", - "One line description of project.", - "Miscellaneous", - ) -] - -# Documents to append as an appendix to all manuals. -# texinfo_appendices = [] - -# If false, no module index is generated. -# texinfo_domain_indices = True - -# How to display URL addresses: 'footnote', 'no', or 'inline'. -# texinfo_show_urls = 'footnote' - -# If true, do not generate a @detailmenu in the "Top" node's menu. -# texinfo_no_detailmenu = False diff --git a/docs/ext/__init__.py b/docs/ext/__init__.py deleted file mode 100644 index e69de29..0000000 --- a/docs/ext/__init__.py +++ /dev/null diff --git a/docs/ext/docstrings.py b/docs/ext/docstrings.py deleted file mode 100644 index fc1c10b..0000000 --- a/docs/ext/docstrings.py +++ /dev/null @@ -1,56 +0,0 @@ -import inspect -import os - -import jinja2 -import sphinx -import sphinx.ext.napoleon as napoleon -from sphinx.ext.napoleon.docstring import GoogleDocstring - - -def classref(value, short=True): - return value - - if not inspect.isclass(value): - return ":class:%s" % value - tilde = "~" if short else "" - return ":class:`%sgitlab.objects.%s`" % (tilde, value.__name__) - - -def setup(app): - app.connect("autodoc-process-docstring", _process_docstring) - app.connect("autodoc-skip-member", napoleon._skip_member) - - conf = napoleon.Config._config_values - - for name, (default, rebuild) in conf.items(): - app.add_config_value(name, default, rebuild) - return {"version": sphinx.__display_version__, "parallel_read_safe": True} - - -def _process_docstring(app, what, name, obj, options, lines): - result_lines = lines - docstring = GitlabDocstring(result_lines, app.config, app, what, name, obj, options) - result_lines = docstring.lines() - lines[:] = result_lines[:] - - -class GitlabDocstring(GoogleDocstring): - def _build_doc(self, tmpl, **kwargs): - env = jinja2.Environment( - loader=jinja2.FileSystemLoader(os.path.dirname(__file__)), trim_blocks=False - ) - env.filters["classref"] = classref - template = env.get_template(tmpl) - output = template.render(**kwargs) - - return output.split("\n") - - def __init__( - self, docstring, config=None, app=None, what="", name="", obj=None, options=None - ): - super(GitlabDocstring, self).__init__( - docstring, config, app, what, name, obj, options - ) - - if name.startswith("gitlab.v4.objects") and name.endswith("Manager"): - self._parsed_lines.extend(self._build_doc("manager_tmpl.j2", cls=self._obj)) diff --git a/docs/ext/manager_tmpl.j2 b/docs/ext/manager_tmpl.j2 deleted file mode 100644 index 6e71c0c..0000000 --- a/docs/ext/manager_tmpl.j2 +++ /dev/null @@ -1,38 +0,0 @@ -{% if cls._list_filters %} -**Object listing filters** -{% for item in cls._list_filters %} -- ``{{ item }}`` -{% endfor %} -{% endif %} - -{% if cls._create_attrs %} -**Object Creation** -{% if cls._create_attrs[0] %} -Mandatory attributes: -{% for item in cls._create_attrs[0] %} -- ``{{ item }}`` -{% endfor %} -{% endif %} -{% if cls._create_attrs[1] %} -Optional attributes: -{% for item in cls._create_attrs[1] %} -- ``{{ item }}`` -{% endfor %} -{% endif %} -{% endif %} - -{% if cls._update_attrs %} -**Object update** -{% if cls._update_attrs[0] %} -Mandatory attributes for object update: -{% for item in cls._update_attrs[0] %} -- ``{{ item }}`` -{% endfor %} -{% endif %} -{% if cls._update_attrs[1] %} -Optional attributes for object update: -{% for item in cls._update_attrs[1] %} -- ``{{ item }}`` -{% endfor %} -{% endif %} -{% endif %} diff --git a/docs/faq.rst b/docs/faq.rst deleted file mode 100644 index 0f914ed..0000000 --- a/docs/faq.rst +++ /dev/null @@ -1,38 +0,0 @@ -### -FAQ -### - -I cannot edit the merge request / issue I've just retrieved - It is likely that you used a ``MergeRequest``, ``GroupMergeRequest``, - ``Issue`` or ``GroupIssue`` object. These objects cannot be edited. But you - can create a new ``ProjectMergeRequest`` or ``ProjectIssue`` object to - apply changes. For example:: - - issue = gl.issues.list()[0] - project = gl.projects.get(issue.project_id, lazy=True) - editable_issue = project.issues.get(issue.iid, lazy=True) - # you can now edit the object - - See the :ref:`merge requests example <merge_requests_examples>` and the - :ref:`issues examples <issues_examples>`. - -How can I clone the repository of a project? - python-gitlab doesn't provide an API to clone a project. You have to use a - git library or call the ``git`` command. - - The git URI is exposed in the ``ssh_url_to_repo`` attribute of ``Project`` - objects. - - Example:: - - import subprocess - - project = gl.projects.create(data) # or gl.projects.get(project_id) - print(project.attributes) # displays all the attributes - git_url = project.ssh_url_to_repo - subprocess.call(['git', 'clone', git_url]) - -I get an ``AttributeError`` when accessing attributes after ``save()`` or ``refresh()``. - You are most likely trying to access an attribute that was not returned - by the server on the second request. Please look at the documentation in - :ref:`object_attributes` to see how to avoid this. diff --git a/docs/gl_objects/access_requests.rst b/docs/gl_objects/access_requests.rst deleted file mode 100644 index 467c3e5..0000000 --- a/docs/gl_objects/access_requests.rst +++ /dev/null @@ -1,53 +0,0 @@ -############### -Access requests -############### - -Users can request access to groups and projects. - -When access is granted the user should be given a numerical access level. The -following constants are provided to represent the access levels: - -* ``gitlab.GUEST_ACCESS``: ``10`` -* ``gitlab.REPORTER_ACCESS``: ``20`` -* ``gitlab.DEVELOPER_ACCESS``: ``30`` -* ``gitlab.MAINTAINER_ACCESS``: ``40`` -* ``gitlab.OWNER_ACCESS``: ``50`` - -References ----------- - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectAccessRequest` - + :class:`gitlab.v4.objects.ProjectAccessRequestManager` - + :attr:`gitlab.v4.objects.Project.accessrequests` - + :class:`gitlab.v4.objects.GroupAccessRequest` - + :class:`gitlab.v4.objects.GroupAccessRequestManager` - + :attr:`gitlab.v4.objects.Group.accessrequests` - -* GitLab API: https://docs.gitlab.com/ce/api/access_requests.html - -Examples --------- - -List access requests from projects and groups:: - - p_ars = project.accessrequests.list() - g_ars = group.accessrequests.list() - -Create an access request:: - - p_ar = project.accessrequests.create() - g_ar = group.accessrequests.create() - -Approve an access request:: - - ar.approve() # defaults to DEVELOPER level - ar.approve(access_level=gitlab.MAINTAINER_ACCESS) # explicitly set access level - -Deny (delete) an access request:: - - project.accessrequests.delete(user_id) - group.accessrequests.delete(user_id) - # or - ar.delete() diff --git a/docs/gl_objects/appearance.rst b/docs/gl_objects/appearance.rst deleted file mode 100644 index 0c05268..0000000 --- a/docs/gl_objects/appearance.rst +++ /dev/null @@ -1,26 +0,0 @@ -########## -Appearance -########## - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.ApplicationAppearance` - + :class:`gitlab.v4.objects.ApplicationAppearanceManager` - + :attr:`gitlab.Gitlab.appearance` - -* GitLab API: https://docs.gitlab.com/ce/api/appearance.html - -Examples --------- - -Get the appearance:: - - appearance = gl.appearance.get() - -Update the appearance:: - - appearance.title = "Test" - appearance.save() diff --git a/docs/gl_objects/applications.rst b/docs/gl_objects/applications.rst deleted file mode 100644 index 146b6e8..0000000 --- a/docs/gl_objects/applications.rst +++ /dev/null @@ -1,31 +0,0 @@ -############ -Applications -############ - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.Applications` - + :class:`gitlab.v4.objects.ApplicationManager` - + :attr:`gitlab.Gitlab.applications` - -* GitLab API: https://docs.gitlab.com/ce/api/applications.html - -Examples --------- - -List all OAuth applications:: - - applications = gl.applications.list() - -Create an application:: - - gl.applications.create({'name': 'your_app', 'redirect_uri': 'http://application.url', 'scopes': ['api']}) - -Delete an applications:: - - gl.applications.delete(app_id) - # or - application.delete() diff --git a/docs/gl_objects/badges.rst b/docs/gl_objects/badges.rst deleted file mode 100644 index 2a26bb3..0000000 --- a/docs/gl_objects/badges.rst +++ /dev/null @@ -1,52 +0,0 @@ -###### -Badges -###### - -Badges can be associated with groups and projects. - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.GroupBadge` - + :class:`gitlab.v4.objects.GroupBadgeManager` - + :attr:`gitlab.v4.objects.Group.badges` - + :class:`gitlab.v4.objects.ProjectBadge` - + :class:`gitlab.v4.objects.ProjectBadgeManager` - + :attr:`gitlab.v4.objects.Project.badges` - -* GitLab API: - - + https://docs.gitlab.com/ce/api/group_badges.html - + https://docs.gitlab.com/ce/api/project_badges.html - -Examples --------- - -List badges:: - - badges = group_or_project.badges.list() - -Get a badge:: - - badge = group_or_project.badges.get(badge_id) - -Create a badge:: - - badge = group_or_project.badges.create({'link_url': link, 'image_url': image_link}) - -Update a badge:: - - badge.image_link = new_link - badge.save() - -Delete a badge:: - - badge.delete() - -Render a badge (preview the generate URLs):: - - output = group_or_project.badges.render(link, image_link) - print(output['rendered_link_url']) - print(output['rendered_image_url']) diff --git a/docs/gl_objects/boards.rst b/docs/gl_objects/boards.rst deleted file mode 100644 index 3bdbb51..0000000 --- a/docs/gl_objects/boards.rst +++ /dev/null @@ -1,104 +0,0 @@ -############ -Issue boards -############ - -Boards -====== - -Boards are a visual representation of existing issues for a project or a group. -Issues can be moved from one list to the other to track progress and help with -priorities. - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectBoard` - + :class:`gitlab.v4.objects.ProjectBoardManager` - + :attr:`gitlab.v4.objects.Project.boards` - + :class:`gitlab.v4.objects.GroupBoard` - + :class:`gitlab.v4.objects.GroupBoardManager` - + :attr:`gitlab.v4.objects.Group.boards` - -* GitLab API: - - + https://docs.gitlab.com/ce/api/boards.html - + https://docs.gitlab.com/ce/api/group_boards.html - -Examples --------- - -Get the list of existing boards for a project or a group:: - - # item is a Project or a Group - boards = project_or_group.boards.list() - -Get a single board for a project or a group:: - - board = project_or_group.boards.get(board_id) - -Create a board:: - - board = project_or_group.boards.create({'name': 'new-board'}) - -.. note:: Board creation is not supported in the GitLab CE edition. - -Delete a board:: - - board.delete() - # or - project_or_group.boards.delete(board_id) - -.. note:: Board deletion is not supported in the GitLab CE edition. - -Board lists -=========== - -Boards are made of lists of issues. Each list is associated to a label, and -issues tagged with this label automatically belong to the list. - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectBoardList` - + :class:`gitlab.v4.objects.ProjectBoardListManager` - + :attr:`gitlab.v4.objects.ProjectBoard.lists` - + :class:`gitlab.v4.objects.GroupBoardList` - + :class:`gitlab.v4.objects.GroupBoardListManager` - + :attr:`gitlab.v4.objects.GroupBoard.lists` - -* GitLab API: - - + https://docs.gitlab.com/ce/api/boards.html - + https://docs.gitlab.com/ce/api/group_boards.html - -Examples --------- - -List the issue lists for a board:: - - b_lists = board.lists.list() - -Get a single list:: - - b_list = board.lists.get(list_id) - -Create a new list:: - - # First get a ProjectLabel - label = get_or_create_label() - # Then use its ID to create the new board list - b_list = board.lists.create({'label_id': label.id}) - -Change a list position. The first list is at position 0. Moving a list will -set it at the given position and move the following lists up a position:: - - b_list.position = 2 - b_list.save() - -Delete a list:: - - b_list.delete() diff --git a/docs/gl_objects/branches.rst b/docs/gl_objects/branches.rst deleted file mode 100644 index aeba8ea..0000000 --- a/docs/gl_objects/branches.rst +++ /dev/null @@ -1,42 +0,0 @@ -######## -Branches -######## - -References ----------- - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectBranch` - + :class:`gitlab.v4.objects.ProjectBranchManager` - + :attr:`gitlab.v4.objects.Project.branches` - -* GitLab API: https://docs.gitlab.com/ce/api/branches.html - -Examples --------- - -Get the list of branches for a repository:: - - branches = project.branches.list() - -Get a single repository branch:: - - branch = project.branches.get('master') - -Create a repository branch:: - - branch = project.branches.create({'branch': 'feature1', - 'ref': 'master'}) - -Delete a repository branch:: - - project.branches.delete('feature1') - # or - branch.delete() - -Delete the merged branches for a project:: - - project.delete_merged_branches() - -To manage protected branches, see :doc:`/gl_objects/protected_branches`. diff --git a/docs/gl_objects/clusters.rst b/docs/gl_objects/clusters.rst deleted file mode 100644 index 96edd82..0000000 --- a/docs/gl_objects/clusters.rst +++ /dev/null @@ -1,82 +0,0 @@ -############ -Clusters -############ - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectCluster` - + :class:`gitlab.v4.objects.ProjectClusterManager` - + :attr:`gitlab.v4.objects.Project.clusters` - + :class:`gitlab.v4.objects.GroupCluster` - + :class:`gitlab.v4.objects.GroupClusterManager` - + :attr:`gitlab.v4.objects.Group.clusters` - -* GitLab API: https://docs.gitlab.com/ee/api/project_clusters.html -* GitLab API: https://docs.gitlab.com/ee/api/group_clusters.html - -Examples --------- - -List clusters for a project:: - - clusters = project.clusters.list() - -Create an cluster for a project:: - - cluster = project.clusters.create( - { - "name": "cluster1", - "platform_kubernetes_attributes": { - "api_url": "http://url", - "token": "tokenval", - }, - }) - -Retrieve a specific cluster for a project:: - - cluster = project.clusters.get(cluster_id) - -Update an cluster for a project:: - - cluster.platform_kubernetes_attributes = {"api_url": "http://newurl"} - cluster.save() - -Delete an cluster for a project:: - - cluster = project.clusters.delete(cluster_id) - # or - cluster.delete() - - -List clusters for a group:: - - clusters = group.clusters.list() - -Create an cluster for a group:: - - cluster = group.clusters.create( - { - "name": "cluster1", - "platform_kubernetes_attributes": { - "api_url": "http://url", - "token": "tokenval", - }, - }) - -Retrieve a specific cluster for a group:: - - cluster = group.clusters.get(cluster_id) - -Update an cluster for a group:: - - cluster.platform_kubernetes_attributes = {"api_url": "http://newurl"} - cluster.save() - -Delete an cluster for a group:: - - cluster = group.clusters.delete(cluster_id) - # or - cluster.delete() diff --git a/docs/gl_objects/commits.rst b/docs/gl_objects/commits.rst deleted file mode 100644 index a1d878c..0000000 --- a/docs/gl_objects/commits.rst +++ /dev/null @@ -1,147 +0,0 @@ -####### -Commits -####### - -Commits -======= - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectCommit` - + :class:`gitlab.v4.objects.ProjectCommitManager` - + :attr:`gitlab.v4.objects.Project.commits` - -Examples --------- - -List the commits for a project:: - - commits = project.commits.list() - -You can use the ``ref_name``, ``since`` and ``until`` filters to limit the -results:: - - commits = project.commits.list(ref_name='my_branch') - commits = project.commits.list(since='2016-01-01T00:00:00Z') - -.. note:: - - The available ``all`` listing argument conflicts with the python-gitlab - argument. Use ``query_parameters`` to avoid the conflict:: - - commits = project.commits.list(all=True, - query_parameters={'ref_name': 'my_branch'}) - -Create a commit:: - - # See https://docs.gitlab.com/ce/api/commits.html#create-a-commit-with-multiple-files-and-actions - # for actions detail - data = { - 'branch': 'master', - 'commit_message': 'blah blah blah', - 'actions': [ - { - 'action': 'create', - 'file_path': 'README.rst', - 'content': open('path/to/file.rst').read(), - }, - { - # Binary files need to be base64 encoded - 'action': 'create', - 'file_path': 'logo.png', - 'content': base64.b64encode(open('logo.png').read()), - 'encoding': 'base64', - } - ] - } - - commit = project.commits.create(data) - -Get a commit detail:: - - commit = project.commits.get('e3d5a71b') - -Get the diff for a commit:: - - diff = commit.diff() - -Cherry-pick a commit into another branch:: - - commit.cherry_pick(branch='target_branch') - -Revert a commit on a given branch:: - - commit.revert(branch='target_branch') - -Get the references the commit has been pushed to (branches and tags):: - - commit.refs() # all references - commit.refs('tag') # only tags - commit.refs('branch') # only branches - -Get the signature of the commit (if the commit was signed, e.g. with GPG or x509):: - - commit.signature() - -List the merge requests related to a commit:: - - commit.merge_requests() - -Commit comments -=============== - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectCommitComment` - + :class:`gitlab.v4.objects.ProjectCommitCommentManager` - + :attr:`gitlab.v4.objects.ProjectCommit.comments` - -* GitLab API: https://docs.gitlab.com/ce/api/commits.html - -Examples --------- - -Get the comments for a commit:: - - comments = commit.comments.list() - -Add a comment on a commit:: - - # Global comment - commit = commit.comments.create({'note': 'This is a nice comment'}) - # Comment on a line in a file (on the new version of the file) - commit = commit.comments.create({'note': 'This is another comment', - 'line': 12, - 'line_type': 'new', - 'path': 'README.rst'}) - -Commit status -============= - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectCommitStatus` - + :class:`gitlab.v4.objects.ProjectCommitStatusManager` - + :attr:`gitlab.v4.objects.ProjectCommit.statuses` - -* GitLab API: https://docs.gitlab.com/ce/api/commits.html - -Examples --------- - -List the statuses for a commit:: - - statuses = commit.statuses.list() - -Change the status of a commit:: - - commit.statuses.create({'state': 'success'}) diff --git a/docs/gl_objects/deploy_keys.rst b/docs/gl_objects/deploy_keys.rst deleted file mode 100644 index 31e31a9..0000000 --- a/docs/gl_objects/deploy_keys.rst +++ /dev/null @@ -1,70 +0,0 @@ -########### -Deploy keys -########### - -Deploy keys -=========== - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.DeployKey` - + :class:`gitlab.v4.objects.DeployKeyManager` - + :attr:`gitlab.Gitlab.deploykeys` - -* GitLab API: https://docs.gitlab.com/ce/api/deploy_keys.html - -Examples --------- - -List the deploy keys:: - - keys = gl.deploykeys.list() - -Deploy keys for projects -======================== - -Deploy keys can be managed on a per-project basis. - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectKey` - + :class:`gitlab.v4.objects.ProjectKeyManager` - + :attr:`gitlab.v4.objects.Project.keys` - -* GitLab API: https://docs.gitlab.com/ce/api/deploy_keys.html - -Examples --------- - -List keys for a project:: - - keys = project.keys.list() - -Get a single deploy key:: - - key = project.keys.get(key_id) - -Create a deploy key for a project:: - - key = project.keys.create({'title': 'jenkins key', - 'key': open('/home/me/.ssh/id_rsa.pub').read()}) - -Delete a deploy key for a project:: - - key = project.keys.list(key_id) - # or - key.delete() - -Enable a deploy key for a project:: - - project.keys.enable(key_id) - -Disable a deploy key for a project:: - - project_key.delete() diff --git a/docs/gl_objects/deploy_tokens.rst b/docs/gl_objects/deploy_tokens.rst deleted file mode 100644 index 302cb9c..0000000 --- a/docs/gl_objects/deploy_tokens.rst +++ /dev/null @@ -1,137 +0,0 @@ -############# -Deploy tokens -############# - -Deploy tokens allow read-only access to your repository and registry images -without having a user and a password. - -Deploy tokens -============= - -This endpoint requires admin access. - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.DeployToken` - + :class:`gitlab.v4.objects.DeployTokenManager` - + :attr:`gitlab.Gitlab.deploytokens` - -* GitLab API: https://docs.gitlab.com/ce/api/deploy_tokens.html - -Examples --------- - -Use the ``list()`` method to list all deploy tokens across the GitLab instance. - -:: - - # List deploy tokens - deploy_tokens = gl.deploytokens.list() - -Project deploy tokens -===================== - -This endpoint requires project maintainer access or higher. - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectDeployToken` - + :class:`gitlab.v4.objects.ProjectDeployTokenManager` - + :attr:`gitlab.v4.objects.Project.deploytokens` - -* GitLab API: https://docs.gitlab.com/ce/api/deploy_tokens.html#project-deploy-tokens - -Examples --------- - -List the deploy tokens for a project:: - - deploy_tokens = project.deploytokens.list() - -Create a new deploy token to access registry images of a project: - -In addition to required parameters ``name`` and ``scopes``, this method accepts -the following parameters: - -* ``expires_at`` Expiration date of the deploy token. Does not expire if no value is provided. -* ``username`` Username for deploy token. Default is ``gitlab+deploy-token-{n}`` - - -:: - - deploy_token = project.deploytokens.create({'name': 'token1', 'scopes': ['read_registry'], 'username':'', 'expires_at':''}) - # show its id - print(deploy_token.id) - # show the token value. Make sure you save it, you won't be able to access it again. - print(deploy_token.token) - -.. warning:: - - With GitLab 12.9, even though ``username`` and ``expires_at`` are not required, they always have to be passed to the API. - You can set them to empty strings, see: https://gitlab.com/gitlab-org/gitlab/-/issues/211878. - Also, the ``username``'s value is ignored by the API and will be overridden with ``gitlab+deploy-token-{n}``, - see: https://gitlab.com/gitlab-org/gitlab/-/issues/211963 - These issues were fixed in GitLab 12.10. - -Remove a deploy token from the project:: - - deploy_token.delete() - # or - project.deploytokens.delete(deploy_token.id) - - -Group deploy tokens -=================== - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.GroupDeployToken` - + :class:`gitlab.v4.objects.GroupDeployTokenManager` - + :attr:`gitlab.v4.objects.Group.deploytokens` - -* GitLab API: https://docs.gitlab.com/ce/api/deploy_tokens.html#group-deploy-tokens - -Examples --------- - -List the deploy tokens for a group:: - - deploy_tokens = group.deploytokens.list() - -Create a new deploy token to access all repositories of all projects in a group: - -In addition to required parameters ``name`` and ``scopes``, this method accepts -the following parameters: - -* ``expires_at`` Expiration date of the deploy token. Does not expire if no value is provided. -* ``username`` Username for deploy token. Default is ``gitlab+deploy-token-{n}`` - -:: - - deploy_token = group.deploytokens.create({'name': 'token1', 'scopes': ['read_repository'], 'username':'', 'expires_at':''}) - # show its id - print(deploy_token.id) - -.. warning:: - - With GitLab 12.9, even though ``username`` and ``expires_at`` are not required, they always have to be passed to the API. - You can set them to empty strings, see: https://gitlab.com/gitlab-org/gitlab/-/issues/211878. - Also, the ``username``'s value is ignored by the API and will be overridden with ``gitlab+deploy-token-{n}``, - see: https://gitlab.com/gitlab-org/gitlab/-/issues/211963 - These issues were fixed in GitLab 12.10. - -Remove a deploy token from the group:: - - deploy_token.delete() - # or - group.deploytokens.delete(deploy_token.id) - diff --git a/docs/gl_objects/deployments.rst b/docs/gl_objects/deployments.rst deleted file mode 100644 index 945ad41..0000000 --- a/docs/gl_objects/deployments.rst +++ /dev/null @@ -1,63 +0,0 @@ -########### -Deployments -########### - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectDeployment` - + :class:`gitlab.v4.objects.ProjectDeploymentManager` - + :attr:`gitlab.v4.objects.Project.deployments` - -* GitLab API: https://docs.gitlab.com/ce/api/deployments.html - -Examples --------- - -List deployments for a project:: - - deployments = project.deployments.list() - -Get a single deployment:: - - deployment = project.deployments.get(deployment_id) - -Create a new deployment:: - - deployment = project.deployments.create({ - "environment": "Test", - "sha": "1agf4gs", - "ref": "master", - "tag": False, - "status": "created", - }) - -Update a deployment:: - - deployment = project.deployments.get(42) - deployment.status = "failed" - deployment.save() - -Merge requests associated with a deployment -=========================================== - -Reference ----------- - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectDeploymentMergeRequest` - + :class:`gitlab.v4.objects.ProjectDeploymentMergeRequestManager` - + :attr:`gitlab.v4.objects.ProjectDeployment.mergerequests` - -* GitLab API: https://docs.gitlab.com/ee/api/deployments.html#list-of-merge-requests-associated-with-a-deployment - -Examples --------- - -List the merge requests associated with a deployment:: - - deployment = project.deployments.get(42, lazy=True) - mrs = deployment.mergerequests.list() diff --git a/docs/gl_objects/discussions.rst b/docs/gl_objects/discussions.rst deleted file mode 100644 index 444d883..0000000 --- a/docs/gl_objects/discussions.rst +++ /dev/null @@ -1,107 +0,0 @@ -########### -Discussions -########### - -Discussions organize the notes in threads. See the :ref:`project-notes` chapter -for more information about notes. - -Discussions are available for project issues, merge requests, snippets and -commits. - -Reference -========= - -* v4 API: - - Issues: - - + :class:`gitlab.v4.objects.ProjectIssueDiscussion` - + :class:`gitlab.v4.objects.ProjectIssueDiscussionManager` - + :class:`gitlab.v4.objects.ProjectIssueDiscussionNote` - + :class:`gitlab.v4.objects.ProjectIssueDiscussionNoteManager` - + :attr:`gitlab.v4.objects.ProjectIssue.notes` - - MergeRequests: - - + :class:`gitlab.v4.objects.ProjectMergeRequestDiscussion` - + :class:`gitlab.v4.objects.ProjectMergeRequestDiscussionManager` - + :class:`gitlab.v4.objects.ProjectMergeRequestDiscussionNote` - + :class:`gitlab.v4.objects.ProjectMergeRequestDiscussionNoteManager` - + :attr:`gitlab.v4.objects.ProjectMergeRequest.notes` - - Snippets: - - + :class:`gitlab.v4.objects.ProjectSnippetDiscussion` - + :class:`gitlab.v4.objects.ProjectSnippetDiscussionManager` - + :class:`gitlab.v4.objects.ProjectSnippetDiscussionNote` - + :class:`gitlab.v4.objects.ProjectSnippetDiscussionNoteManager` - + :attr:`gitlab.v4.objects.ProjectSnippet.notes` - -* GitLab API: https://docs.gitlab.com/ce/api/discussions.html - -Examples -======== - -List the discussions for a resource (issue, merge request, snippet or commit):: - - discussions = resource.discussions.list() - -Get a single discussion:: - - discussion = resource.discussions.get(discussion_id) - -You can access the individual notes in the discussion through the ``notes`` -attribute. It holds a list of notes in chronological order:: - - # ``resource.notes`` is a DiscussionNoteManager, so we need to get the - # object notes using ``attributes`` - for note in discussion.attributes['notes']: - print(note['body']) - -.. note:: - - The notes are dicts, not objects. - -You can add notes to existing discussions:: - - new_note = discussion.notes.create({'body': 'Episode IV: A new note'}) - -You can get and update a single note using the ``*DiscussionNote`` resources:: - - discussion = resource.discussions.get(discussion_id) - # Get the latest note's id - note_id = discussion.attributes['note'][-1]['id'] - last_note = discussion.notes.get(note_id) - last_note.body = 'Updated comment' - last_note.save() - -Create a new discussion:: - - discussion = resource.discussions.create({'body': 'First comment of discussion'}) - -You can comment on merge requests and commit diffs. Provide the ``position`` -dict to define where the comment should appear in the diff:: - - mr_diff = mr.diffs.get(diff_id) - mr.discussions.create({'body': 'Note content', - 'position': { - 'base_sha': mr_diff.base_commit_sha, - 'start_sha': mr_diff.start_commit_sha, - 'head_sha': mr_diff.head_commit_sha, - 'position_type': 'text', - 'new_line': 1, - 'old_path': 'README.rst', - 'new_path': 'README.rst'} - }) - -Resolve / unresolve a merge request discussion:: - - mr_d = mr.discussions.get(d_id) - mr_d.resolved = True # True to resolve, False to unresolve - mr_d.save() - -Delete a comment:: - - discussions.notes.delete(note_id) - # or - note.delete() diff --git a/docs/gl_objects/emojis.rst b/docs/gl_objects/emojis.rst deleted file mode 100644 index 179141f..0000000 --- a/docs/gl_objects/emojis.rst +++ /dev/null @@ -1,45 +0,0 @@ -############ -Award Emojis -############ - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectIssueAwardEmoji` - + :class:`gitlab.v4.objects.ProjectIssueNoteAwardEmoji` - + :class:`gitlab.v4.objects.ProjectMergeRequestAwardEmoji` - + :class:`gitlab.v4.objects.ProjectMergeRequestNoteAwardEmoji` - + :class:`gitlab.v4.objects.ProjectSnippetAwardEmoji` - + :class:`gitlab.v4.objects.ProjectSnippetNoteAwardEmoji` - + :class:`gitlab.v4.objects.ProjectIssueAwardEmojiManager` - + :class:`gitlab.v4.objects.ProjectIssueNoteAwardEmojiManager` - + :class:`gitlab.v4.objects.ProjectMergeRequestAwardEmojiManager` - + :class:`gitlab.v4.objects.ProjectMergeRequestNoteAwardEmojiManager` - + :class:`gitlab.v4.objects.ProjectSnippetAwardEmojiManager` - + :class:`gitlab.v4.objects.ProjectSnippetNoteAwardEmojiManager` - - -* GitLab API: https://docs.gitlab.com/ce/api/award_emoji.html - -Examples --------- - -List emojis for a resource:: - - emojis = obj.awardemojis.list() - -Get a single emoji:: - - emoji = obj.awardemojis.get(emoji_id) - -Add (create) an emoji:: - - emoji = obj.awardemojis.create({'name': 'tractor'}) - -Delete an emoji:: - - emoji.delete - # or - obj.awardemojis.delete(emoji_id) diff --git a/docs/gl_objects/environments.rst b/docs/gl_objects/environments.rst deleted file mode 100644 index 6edde12..0000000 --- a/docs/gl_objects/environments.rst +++ /dev/null @@ -1,44 +0,0 @@ -############ -Environments -############ - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectEnvironment` - + :class:`gitlab.v4.objects.ProjectEnvironmentManager` - + :attr:`gitlab.v4.objects.Project.environments` - -* GitLab API: https://docs.gitlab.com/ce/api/environments.html - -Examples --------- - -List environments for a project:: - - environments = project.environments.list() - -Create an environment for a project:: - - environment = project.environments.create({'name': 'production'}) - -Retrieve a specific environment for a project:: - - environment = project.environments.get(112) - -Update an environment for a project:: - - environment.external_url = 'http://foo.bar.com' - environment.save() - -Delete an environment for a project:: - - environment = project.environments.delete(environment_id) - # or - environment.delete() - -Stop an environments:: - - environment.stop() diff --git a/docs/gl_objects/epics.rst b/docs/gl_objects/epics.rst deleted file mode 100644 index 2b1e23e..0000000 --- a/docs/gl_objects/epics.rst +++ /dev/null @@ -1,79 +0,0 @@ -##### -Epics -##### - -Epics -===== - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.GroupEpic` - + :class:`gitlab.v4.objects.GroupEpicManager` - + :attr:`gitlab.Gitlab.Group.epics` - -* GitLab API: https://docs.gitlab.com/ee/api/epics.html (EE feature) - -Examples --------- - -List the epics for a group:: - - epics = groups.epics.list() - -Get a single epic for a group:: - - epic = group.epics.get(epic_iid) - -Create an epic for a group:: - - epic = group.epics.create({'title': 'My Epic'}) - -Edit an epic:: - - epic.title = 'New title' - epic.labels = ['label1', 'label2'] - epic.save() - -Delete an epic:: - - epic.delete() - -Epics issues -============ - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.GroupEpicIssue` - + :class:`gitlab.v4.objects.GroupEpicIssueManager` - + :attr:`gitlab.Gitlab.GroupEpic.issues` - -* GitLab API: https://docs.gitlab.com/ee/api/epic_issues.html (EE feature) - -Examples --------- - -List the issues associated with an issue:: - - ei = epic.issues.list() - -Associate an issue with an epic:: - - # use the issue id, not its iid - ei = epic.issues.create({'issue_id': 4}) - -Move an issue in the list:: - - ei.move_before_id = epic_issue_id_1 - # or - ei.move_after_id = epic_issue_id_2 - ei.save() - -Delete an issue association:: - - ei.delete() diff --git a/docs/gl_objects/events.rst b/docs/gl_objects/events.rst deleted file mode 100644 index 5dc03c7..0000000 --- a/docs/gl_objects/events.rst +++ /dev/null @@ -1,83 +0,0 @@ -###### -Events -###### - -Events -====== - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.Event` - + :class:`gitlab.v4.objects.EventManager` - + :attr:`gitlab.Gitlab.events` - + :class:`gitlab.v4.objects.ProjectEvent` - + :class:`gitlab.v4.objects.ProjectEventManager` - + :attr:`gitlab.v4.objects.Project.events` - + :class:`gitlab.v4.objects.UserEvent` - + :class:`gitlab.v4.objects.UserEventManager` - + :attr:`gitlab.v4.objects.User.events` - -* GitLab API: https://docs.gitlab.com/ce/api/events.html - -Examples --------- - -You can list events for an entire Gitlab instance (admin), users and projects. -You can filter you events you want to retrieve using the ``action`` and -``target_type`` attributes. The possible values for these attributes are -available on `the gitlab documentation -<https://docs.gitlab.com/ce/api/events.html>`_. - -List all the events (paginated):: - - events = gl.events.list() - -List the issue events on a project:: - - events = project.events.list(target_type='issue') - -List the user events:: - - events = project.events.list() - -Resource state events -===================== - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectIssueResourceStateEvent` - + :class:`gitlab.v4.objects.ProjectIssueResourceStateEventManager` - + :attr:`gitlab.v4.objects.ProjectIssue.resourcestateevents` - + :class:`gitlab.v4.objects.ProjectMergeRequestResourceStateEvent` - + :class:`gitlab.v4.objects.ProjectMergeRequestResourceStateEventManager` - + :attr:`gitlab.v4.objects.ProjectMergeRequest.resourcestateevents` - -* GitLab API: https://docs.gitlab.com/ee/api/resource_state_events.html - -Examples --------- - -You can list and get specific resource state events (via their id) for project issues -and project merge requests. - -List the state events of a project issue (paginated):: - - state_events = issue.resourcestateevents.list() - -Get a specific state event of a project issue by its id:: - - state_event = issue.resourcestateevents.get(1) - -List the state events of a project merge request (paginated):: - - state_events = mr.resourcestateevents.list() - -Get a specific state event of a project merge request by its id:: - - state_event = mr.resourcestateevents.get(1) diff --git a/docs/gl_objects/features.rst b/docs/gl_objects/features.rst deleted file mode 100644 index 2344895..0000000 --- a/docs/gl_objects/features.rst +++ /dev/null @@ -1,32 +0,0 @@ -############## -Features flags -############## - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.Feature` - + :class:`gitlab.v4.objects.FeatureManager` - + :attr:`gitlab.Gitlab.features` - -* GitLab API: https://docs.gitlab.com/ce/api/features.html - -Examples --------- - -List features:: - - features = gl.features.list() - -Create or set a feature:: - - feature = gl.features.set(feature_name, True) - feature = gl.features.set(feature_name, 30) - feature = gl.features.set(feature_name, True, user=filipowm) - feature = gl.features.set(feature_name, 40, group=mygroup) - -Delete a feature:: - - feature.delete() diff --git a/docs/gl_objects/geo_nodes.rst b/docs/gl_objects/geo_nodes.rst deleted file mode 100644 index 181ec91..0000000 --- a/docs/gl_objects/geo_nodes.rst +++ /dev/null @@ -1,43 +0,0 @@ -######### -Geo nodes -######### - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.GeoNode` - + :class:`gitlab.v4.objects.GeoNodeManager` - + :attr:`gitlab.Gitlab.geonodes` - -* GitLab API: https://docs.gitlab.com/ee/api/geo_nodes.html (EE feature) - -Examples --------- - -List the geo nodes:: - - nodes = gl.geonodes.list() - -Get the status of all the nodes:: - - status = gl.geonodes.status() - -Get a specific node and its status:: - - node = gl.geonodes.get(node_id) - node.status() - -Edit a node configuration:: - - node.url = 'https://secondary.mygitlab.domain' - node.save() - -Delete a node:: - - node.delete() - -List the sync failure on the current node:: - - failures = gl.geonodes.current_failures() diff --git a/docs/gl_objects/groups.rst b/docs/gl_objects/groups.rst deleted file mode 100644 index 549fe53..0000000 --- a/docs/gl_objects/groups.rst +++ /dev/null @@ -1,378 +0,0 @@ -###### -Groups -###### - -Groups -====== - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.Group` - + :class:`gitlab.v4.objects.GroupManager` - + :attr:`gitlab.Gitlab.groups` - -* GitLab API: https://docs.gitlab.com/ce/api/groups.html - -Examples --------- - -List the groups:: - - groups = gl.groups.list() - -Get a group's detail:: - - group = gl.groups.get(group_id) - -List a group's projects:: - - projects = group.projects.list() - -.. note:: - - ``GroupProject`` objects returned by this API call are very limited, and do - not provide all the features of ``Project`` objects. If you need to - manipulate projects, create a new ``Project`` object:: - - first_group_project = group.projects.list()[0] - manageable_project = gl.projects.get(first_group_project.id, lazy=True) - -You can filter and sort the result using the following parameters: - -* ``archived``: limit by archived status -* ``visibility``: limit by visibility. Allowed values are ``public``, - ``internal`` and ``private`` -* ``search``: limit to groups matching the given value -* ``order_by``: sort by criteria. Allowed values are ``id``, ``name``, ``path``, - ``created_at``, ``updated_at`` and ``last_activity_at`` -* ``sort``: sort order: ``asc`` or ``desc`` -* ``ci_enabled_first``: return CI enabled groups first -* ``include_subgroups``: include projects in subgroups - -Create a group:: - - group = gl.groups.create({'name': 'group1', 'path': 'group1'}) - -Create a subgroup under an existing group:: - - subgroup = gl.groups.create({'name': 'subgroup1', 'path': 'subgroup1', 'parent_id': parent_group_id}) - -Update a group:: - - group.description = 'My awesome group' - group.save() - -Set the avatar image for a group:: - - # the avatar image can be passed as data (content of the file) or as a file - # object opened in binary mode - group.avatar = open('path/to/file.png', 'rb') - group.save() - -Remove a group:: - - gl.groups.delete(group_id) - # or - group.delete() - -Share/unshare the group with a group:: - - group.share(group2.id, gitlab.DEVELOPER_ACCESS) - group.unshare(group2.id) - -Import / Export -=============== - -You can export groups from gitlab, and re-import them to create new groups. - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.GroupExport` - + :class:`gitlab.v4.objects.GroupExportManager` - + :attr:`gitlab.v4.objects.Group.exports` - + :class:`gitlab.v4.objects.GroupImport` - + :class:`gitlab.v4.objects.GroupImportManager` - + :attr:`gitlab.v4.objects.Group.imports` - + :attr:`gitlab.v4.objects.GroupManager.import_group` - -* GitLab API: https://docs.gitlab.com/ce/api/group_import_export.html - -Examples --------- - -A group export is an asynchronous operation. To retrieve the archive -generated by GitLab you need to: - -#. Create an export using the API -#. Wait for the export to be done -#. Download the result - -.. warning:: - - Unlike the Project Export API, GitLab does not provide an export_status - for Group Exports. It is up to the user to ensure the export is finished. - - However, Group Exports only contain metadata, so they are much faster - than Project Exports. - -:: - - # Create the export - group = gl.groups.get(my_group) - export = group.exports.create() - - # Wait for the export to finish - time.sleep(3) - - # Download the result - with open('/tmp/export.tgz', 'wb') as f: - export.download(streamed=True, action=f.write) - -Import the group:: - - with open('/tmp/export.tgz', 'rb') as f: - gl.groups.import_group(f, path='imported-group', name="Imported Group") - -Subgroups -========= - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.GroupSubgroup` - + :class:`gitlab.v4.objects.GroupSubgroupManager` - + :attr:`gitlab.v4.objects.Group.subgroups` - -Examples --------- - -List the subgroups for a group:: - - subgroups = group.subgroups.list() - -.. note:: - - The ``GroupSubgroup`` objects don't expose the same API as the ``Group`` - objects. If you need to manipulate a subgroup as a group, create a new - ``Group`` object:: - - real_group = gl.groups.get(subgroup_id, lazy=True) - real_group.issues.list() - -Descendant Groups -================= - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.GroupDescendantGroup` - + :class:`gitlab.v4.objects.GroupDescendantGroupManager` - + :attr:`gitlab.v4.objects.Group.descendant_groups` - -Examples --------- - -List the descendant groups of a group:: - - descendant_groups = group.descendant_groups.list() - -.. note:: - - Like the ``GroupSubgroup`` objects described above, ``GroupDescendantGroup`` - objects do not expose the same API as the ``Group`` objects. Create a new - ``Group`` object instead if needed, as shown in the subgroup example. - -Group custom attributes -======================= - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.GroupCustomAttribute` - + :class:`gitlab.v4.objects.GroupCustomAttributeManager` - + :attr:`gitlab.v4.objects.Group.customattributes` - -* GitLab API: https://docs.gitlab.com/ce/api/custom_attributes.html - -Examples --------- - -List custom attributes for a group:: - - attrs = group.customattributes.list() - -Get a custom attribute for a group:: - - attr = group.customattributes.get(attr_key) - -Set (create or update) a custom attribute for a group:: - - attr = group.customattributes.set(attr_key, attr_value) - -Delete a custom attribute for a group:: - - attr.delete() - # or - group.customattributes.delete(attr_key) - -Search groups by custom attribute:: - - group.customattributes.set('role': 'admin') - gl.groups.list(custom_attributes={'role': 'admin'}) - -Group members -============= - -The following constants define the supported access levels: - -* ``gitlab.GUEST_ACCESS = 10`` -* ``gitlab.REPORTER_ACCESS = 20`` -* ``gitlab.DEVELOPER_ACCESS = 30`` -* ``gitlab.MAINTAINER_ACCESS = 40`` -* ``gitlab.OWNER_ACCESS = 50`` - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.GroupMember` - + :class:`gitlab.v4.objects.GroupMemberManager` - + :class:`gitlab.v4.objects.GroupMemberAllManager` - + :class:`gitlab.v4.objects.GroupBillableMember` - + :class:`gitlab.v4.objects.GroupBillableMemberManager` - + :attr:`gitlab.v4.objects.Group.members` - + :attr:`gitlab.v4.objects.Group.members_all` - + :attr:`gitlab.v4.objects.Group.billable_members` - -* GitLab API: https://docs.gitlab.com/ce/api/members.html - -Billable group members are only available in GitLab EE. - -Examples --------- - -List only direct group members:: - - members = group.members.list() - -List the group members recursively (including inherited members through -ancestor groups):: - - members = group.members_all.list(all=True) - -Get only direct group member:: - - members = group.members.get(member_id) - -Get a member of a group, including members inherited through ancestor groups:: - - members = group.members_all.get(member_id) - -Add a member to the group:: - - member = group.members.create({'user_id': user_id, - 'access_level': gitlab.GUEST_ACCESS}) - -Update a member (change the access level):: - - member.access_level = gitlab.DEVELOPER_ACCESS - member.save() - -Remove a member from the group:: - - group.members.delete(member_id) - # or - member.delete() - -List billable members of a group (top-level groups only):: - - billable_members = group.billable_members.list() - -Remove a billable member from the group:: - - group.billable_members.delete(member_id) - # or - billable_member.delete() - -List memberships of a billable member:: - - billable_member.memberships.list() - -LDAP group links -================ - -Add an LDAP group link to an existing GitLab group:: - - group.add_ldap_group_link(ldap_group_cn, gitlab.DEVELOPER_ACCESS, 'ldapmain') - -Remove a link:: - - group.delete_ldap_group_link(ldap_group_cn, 'ldapmain') - -Sync the LDAP groups:: - - group.ldap_sync() - -You can use the ``ldapgroups`` manager to list available LDAP groups:: - - # listing (supports pagination) - ldap_groups = gl.ldapgroups.list() - - # filter using a group name - ldap_groups = gl.ldapgroups.list(search='foo') - - # list the groups for a specific LDAP provider - ldap_groups = gl.ldapgroups.list(search='foo', provider='ldapmain') - -Groups hooks -============ - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.GroupHook` - + :class:`gitlab.v4.objects.GroupHookManager` - + :attr:`gitlab.v4.objects.Group.hooks` - -* GitLab API: https://docs.gitlab.com/ce/api/groups.html#hooks - -Examples --------- - -List the group hooks:: - - hooks = group.hooks.list() - -Get a group hook:: - - hook = group.hooks.get(hook_id) - -Create a group hook:: - - hook = group.hooks.create({'url': 'http://my/action/url', 'push_events': 1}) - -Update a group hook:: - - hook.push_events = 0 - hook.save() - -Delete a group hook:: - - group.hooks.delete(hook_id) - # or - hook.delete() diff --git a/docs/gl_objects/issues.rst b/docs/gl_objects/issues.rst deleted file mode 100644 index dfb1ff7..0000000 --- a/docs/gl_objects/issues.rst +++ /dev/null @@ -1,279 +0,0 @@ -.. _issues_examples: - -###### -Issues -###### - -Reported issues -=============== - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.Issue` - + :class:`gitlab.v4.objects.IssueManager` - + :attr:`gitlab.Gitlab.issues` - -* GitLab API: https://docs.gitlab.com/ce/api/issues.html - -Examples --------- - -List the issues:: - - issues = gl.issues.list() - -Use the ``state`` and ``label`` parameters to filter the results. Use the -``order_by`` and ``sort`` attributes to sort the results:: - - open_issues = gl.issues.list(state='opened') - closed_issues = gl.issues.list(state='closed') - tagged_issues = gl.issues.list(labels=['foo', 'bar']) - -.. note:: - - It is not possible to edit or delete Issue objects. You need to create a - ProjectIssue object to perform changes:: - - issue = gl.issues.list()[0] - project = gl.projects.get(issue.project_id, lazy=True) - editable_issue = project.issues.get(issue.iid, lazy=True) - editable_issue.title = updated_title - editable_issue.save() - -Group issues -============ - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.GroupIssue` - + :class:`gitlab.v4.objects.GroupIssueManager` - + :attr:`gitlab.v4.objects.Group.issues` - -* GitLab API: https://docs.gitlab.com/ce/api/issues.html - -Examples --------- - -List the group issues:: - - issues = group.issues.list() - # Filter using the state, labels and milestone parameters - issues = group.issues.list(milestone='1.0', state='opened') - # Order using the order_by and sort parameters - issues = group.issues.list(order_by='created_at', sort='desc') - -.. note:: - - It is not possible to edit or delete GroupIssue objects. You need to create - a ProjectIssue object to perform changes:: - - issue = group.issues.list()[0] - project = gl.projects.get(issue.project_id, lazy=True) - editable_issue = project.issues.get(issue.iid, lazy=True) - editable_issue.title = updated_title - editable_issue.save() - -Project issues -============== - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectIssue` - + :class:`gitlab.v4.objects.ProjectIssueManager` - + :attr:`gitlab.v4.objects.Project.issues` - -* GitLab API: https://docs.gitlab.com/ce/api/issues.html - -Examples --------- - -List the project issues:: - - issues = project.issues.list() - # Filter using the state, labels and milestone parameters - issues = project.issues.list(milestone='1.0', state='opened') - # Order using the order_by and sort parameters - issues = project.issues.list(order_by='created_at', sort='desc') - -Get a project issue:: - - issue = project.issues.get(issue_iid) - -Create a new issue:: - - issue = project.issues.create({'title': 'I have a bug', - 'description': 'Something useful here.'}) - -Update an issue:: - - issue.labels = ['foo', 'bar'] - issue.save() - -Close / reopen an issue:: - - # close an issue - issue.state_event = 'close' - issue.save() - # reopen it - issue.state_event = 'reopen' - issue.save() - -Delete an issue (admin or project owner only):: - - project.issues.delete(issue_id) - # pr - issue.delete() - -Subscribe / unsubscribe from an issue:: - - issue.subscribe() - issue.unsubscribe() - -Move an issue to another project:: - - issue.move(other_project_id) - -Make an issue as todo:: - - issue.todo() - -Get time tracking stats:: - - issue.time_stats() - -On recent versions of Gitlab the time stats are also returned as an issue -object attribute:: - - issue = project.issue.get(iid) - print(issue.attributes['time_stats']) - -Set a time estimate for an issue:: - - issue.time_estimate('3h30m') - -Reset a time estimate for an issue:: - - issue.reset_time_estimate() - -Add spent time for an issue:: - - issue.add_spent_time('3h30m') - -Reset spent time for an issue:: - - issue.reset_spent_time() - -Get user agent detail for the issue (admin only):: - - detail = issue.user_agent_detail() - -Get the list of merge requests that will close an issue when merged:: - - mrs = issue.closed_by() - -Get the merge requests related to an issue:: - - mrs = issue.related_merge_requests() - -Get the list of participants:: - - users = issue.participants() - -Issue links -=========== - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectIssueLink` - + :class:`gitlab.v4.objects.ProjectIssueLinkManager` - + :attr:`gitlab.v4.objects.ProjectIssue.links` - -* GitLab API: https://docs.gitlab.com/ee/api/issue_links.html (EE feature) - -Examples --------- - -List the issues linked to ``i1``:: - - links = i1.links.list() - -Link issue ``i1`` to issue ``i2``:: - - data = { - 'target_project_id': i2.project_id, - 'target_issue_iid': i2.iid - } - src_issue, dest_issue = i1.links.create(data) - -.. note:: - - The ``create()`` method returns the source and destination ``ProjectIssue`` - objects, not a ``ProjectIssueLink`` object. - -Delete a link:: - - i1.links.delete(issue_link_id) - -Issues statistics -========================= - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.IssuesStatistics` - + :class:`gitlab.v4.objects.IssuesStatisticsManager` - + :attr:`gitlab.issues_statistics` - + :class:`gitlab.v4.objects.GroupIssuesStatistics` - + :class:`gitlab.v4.objects.GroupIssuesStatisticsManager` - + :attr:`gitlab.v4.objects.Group.issues_statistics` - + :class:`gitlab.v4.objects.ProjectIssuesStatistics` - + :class:`gitlab.v4.objects.ProjectIssuesStatisticsManager` - + :attr:`gitlab.v4.objects.Project.issues_statistics` - - -* GitLab API: https://docs.gitlab.com/ce/api/issues_statistics.htm - -Examples ---------- - -Get statistics of all issues created by the current user:: - - statistics = gl.issues_statistics.get() - -Get statistics of all issues the user has access to:: - - statistics = gl.issues_statistics.get(scope='all') - -Get statistics of issues for the user with ``foobar`` in the ``title`` or the ``description``:: - - statistics = gl.issues_statistics.get(search='foobar') - -Get statistics of all issues in a group:: - - statistics = group.issues_statistics.get() - -Get statistics of issues in a group with ``foobar`` in the ``title`` or the ``description``:: - - statistics = group.issues_statistics.get(search='foobar') - -Get statistics of all issues in a project:: - - statistics = project.issues_statistics.get() - -Get statistics of issues in a project with ``foobar`` in the ``title`` or the ``description``:: - - statistics = project.issues_statistics.get(search='foobar') diff --git a/docs/gl_objects/keys.rst b/docs/gl_objects/keys.rst deleted file mode 100644 index 6d35218..0000000 --- a/docs/gl_objects/keys.rst +++ /dev/null @@ -1,28 +0,0 @@ -#### -Keys -#### - -Keys -==== - -Reference ---------- - -* v4 API - - + :class:`gitlab.v4.objects.Key` - + :class:`gitlab.v4.objects.KeyManager` - + :attr:`gitlab.Gitlab.keys` - -* GitLab API: https://docs.gitlab.com/ce/api/keys.html - -Examples --------- - -Get an ssh key by its id (requires admin access):: - - key = gl.keys.get(key_id) - -Get an ssh key (requires admin access) or a deploy key by its fingerprint:: - - key = gl.keys.get(fingerprint="SHA256:ERJJ/OweAM6jA8OjJ/gXs4N5fqUaREEJnz/EyfywfXY") diff --git a/docs/gl_objects/labels.rst b/docs/gl_objects/labels.rst deleted file mode 100644 index a4667aa..0000000 --- a/docs/gl_objects/labels.rst +++ /dev/null @@ -1,89 +0,0 @@ -###### -Labels -###### - -Project labels -============== - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectLabel` - + :class:`gitlab.v4.objects.ProjectLabelManager` - + :attr:`gitlab.v4.objects.Project.labels` - -* GitLab API: https://docs.gitlab.com/ce/api/labels.html - -Examples --------- - -List labels for a project:: - - labels = project.labels.list() - -Create a label for a project:: - - label = project.labels.create({'name': 'foo', 'color': '#8899aa'}) - -Update a label for a project:: - - # change the name of the label: - label.new_name = 'bar' - label.save() - # change its color: - label.color = '#112233' - label.save() - -Delete a label for a project:: - - project.labels.delete(label_id) - # or - label.delete() - -Manage labels in issues and merge requests:: - - # Labels are defined as lists in issues and merge requests. The labels must - # exist. - issue = p.issues.create({'title': 'issue title', - 'description': 'issue description', - 'labels': ['foo']}) - issue.labels.append('bar') - issue.save() - -Label events -============ - -Resource label events keep track about who, when, and which label was added or -removed to an issuable. - -Group epic label events are only available in the EE edition. - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectIssueResourceLabelEvent` - + :class:`gitlab.v4.objects.ProjectIssueResourceLabelEventManager` - + :attr:`gitlab.v4.objects.ProjectIssue.resourcelabelevents` - + :class:`gitlab.v4.objects.ProjectMergeRequestResourceLabelEvent` - + :class:`gitlab.v4.objects.ProjectMergeRequestResourceLabelEventManager` - + :attr:`gitlab.v4.objects.ProjectMergeRequest.resourcelabelevents` - + :class:`gitlab.v4.objects.GroupEpicResourceLabelEvent` - + :class:`gitlab.v4.objects.GroupEpicResourceLabelEventManager` - + :attr:`gitlab.v4.objects.GroupEpic.resourcelabelevents` - -* GitLab API: https://docs.gitlab.com/ee/api/resource_label_events.html - -Examples --------- - -Get the events for a resource (issue, merge request or epic):: - - events = resource.resourcelabelevents.list() - -Get a specific event for a resource:: - - event = resource.resourcelabelevents.get(event_id) diff --git a/docs/gl_objects/messages.rst b/docs/gl_objects/messages.rst deleted file mode 100644 index 32fbb95..0000000 --- a/docs/gl_objects/messages.rst +++ /dev/null @@ -1,48 +0,0 @@ -################## -Broadcast messages -################## - -You can use broadcast messages to display information on all pages of the -gitlab web UI. You must have administration permissions to manipulate broadcast -messages. - -References ----------- - -* v4 API: - - + :class:`gitlab.v4.objects.BroadcastMessage` - + :class:`gitlab.v4.objects.BroadcastMessageManager` - + :attr:`gitlab.Gitlab.broadcastmessages` - -* GitLab API: https://docs.gitlab.com/ce/api/broadcast_messages.html - -Examples --------- - -List the messages:: - - msgs = gl.broadcastmessages.list() - -Get a single message:: - - msg = gl.broadcastmessages.get(msg_id) - -Create a message:: - - msg = gl.broadcastmessages.create({'message': 'Important information'}) - -The date format for the ``starts_at`` and ``ends_at`` parameters is -``YYYY-MM-ddThh:mm:ssZ``. - -Update a message:: - - msg.font = '#444444' - msg.color = '#999999' - msg.save() - -Delete a message:: - - gl.broadcastmessages.delete(msg_id) - # or - msg.delete() diff --git a/docs/gl_objects/milestones.rst b/docs/gl_objects/milestones.rst deleted file mode 100644 index 3830f81..0000000 --- a/docs/gl_objects/milestones.rst +++ /dev/null @@ -1,105 +0,0 @@ -########## -Milestones -########## - -Project milestones -================== - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectMilestone` - + :class:`gitlab.v4.objects.ProjectMilestoneManager` - + :attr:`gitlab.v4.objects.Project.milestones` - - + :class:`gitlab.v4.objects.GroupMilestone` - + :class:`gitlab.v4.objects.GroupMilestoneManager` - + :attr:`gitlab.v4.objects.Group.milestones` - -* GitLab API: - - + https://docs.gitlab.com/ce/api/milestones.html - + https://docs.gitlab.com/ce/api/group_milestones.html - -Examples --------- - -List the milestones for a project or a group:: - - p_milestones = project.milestones.list() - g_milestones = group.milestones.list() - -You can filter the list using the following parameters: - -* ``iids``: unique IDs of milestones for the project -* ``state``: either ``active`` or ``closed`` -* ``search``: to search using a string - -:: - - p_milestones = project.milestones.list(state='closed') - g_milestones = group.milestones.list(state='active') - -Get a single milestone:: - - p_milestone = project.milestones.get(milestone_id) - g_milestone = group.milestones.get(milestone_id) - -Create a milestone:: - - milestone = project.milestones.create({'title': '1.0'}) - -Edit a milestone:: - - milestone.description = 'v 1.0 release' - milestone.save() - -Change the state of a milestone (activate / close):: - - # close a milestone - milestone.state_event = 'close' - milestone.save() - - # activate a milestone - milestone.state_event = 'activate' - milestone.save() - -List the issues related to a milestone:: - - issues = milestone.issues() - -List the merge requests related to a milestone:: - - merge_requests = milestone.merge_requests() - -Milestone events -================ - -Resource milestone events keep track of what happens to GitLab issues and merge requests. - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectIssueResourceMilestoneEvent` - + :class:`gitlab.v4.objects.ProjectIssueResourceMilestoneEventManager` - + :attr:`gitlab.v4.objects.ProjectIssue.resourcemilestoneevents` - + :class:`gitlab.v4.objects.ProjectMergeRequestResourceMilestoneEvent` - + :class:`gitlab.v4.objects.ProjectMergeRequestResourceMilestoneEventManager` - + :attr:`gitlab.v4.objects.ProjectMergeRequest.resourcemilestoneevents` - -* GitLab API: https://docs.gitlab.com/ee/api/resource_milestone_events.html - -Examples --------- - -Get milestones for a resource (issue, merge request):: - - milestones = resource.resourcemilestoneevents.list() - -Get a specific milestone for a resource:: - - milestone = resource.resourcemilestoneevents.get(milestone_id) diff --git a/docs/gl_objects/mr_approvals.rst b/docs/gl_objects/mr_approvals.rst deleted file mode 100644 index 9e47535..0000000 --- a/docs/gl_objects/mr_approvals.rst +++ /dev/null @@ -1,86 +0,0 @@ -################################ -Merge request approvals settings -################################ - -Merge request approvals can be defined at the project level or at the merge -request level. - -References ----------- - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectApproval` - + :class:`gitlab.v4.objects.ProjectApprovalManager` - + :class:`gitlab.v4.objects.ProjectApprovalRule` - + :class:`gitlab.v4.objects.ProjectApprovalRuleManager` - + :attr:`gitlab.v4.objects.Project.approvals` - + :class:`gitlab.v4.objects.ProjectMergeRequestApproval` - + :class:`gitlab.v4.objects.ProjectMergeRequestApprovalManager` - + :attr:`gitlab.v4.objects.ProjectMergeRequest.approvals` - + :class:`gitlab.v4.objects.ProjectMergeRequestApprovalRule` - + :class:`gitlab.v4.objects.ProjectMergeRequestApprovalRuleManager` - + :attr:`gitlab.v4.objects.ProjectMergeRequest.approval_rules` - -* GitLab API: https://docs.gitlab.com/ee/api/merge_request_approvals.html - -Examples --------- - -List project-level MR approval rules:: - - p_mras = project.approvalrules.list() - -Change project-level MR approval rule:: - - p_approvalrule.user_ids = [234] - p_approvalrule.save() - -Delete project-level MR approval rule:: - - p_approvalrule.delete() - -Get project-level or MR-level MR approvals settings:: - - p_mras = project.approvals.get() - - mr_mras = mr.approvals.get() - -Change project-level or MR-level MR approvals settings:: - - p_mras.approvals_before_merge = 2 - p_mras.save() - - mr_mras.set_approvers(approvals_required = 1) - -Change project-level MR allowed approvers:: - - project.approvals.set_approvers(approver_ids=[105], - approver_group_ids=[653, 654]) - -Create a new MR-level approval rule or change an existing MR-level approval rule:: - - mr.approvals.set_approvers(approvals_required = 1, approver_ids=[105], - approver_group_ids=[653, 654], - approval_rule_name="my MR custom approval rule") - -List MR-level MR approval rules:: - - mr.approval_rules.list() - -Change MR-level MR approval rule:: - - mr_approvalrule.user_ids = [105] - mr_approvalrule.approvals_required = 2 - mr_approvalrule.group_ids = [653, 654] - mr_approvalrule.save() - -Create a MR-level MR approval rule:: - - mr.approval_rules.create({ - "name": "my MR custom approval rule", - "approvals_required": 2, - "rule_type": "regular", - "user_ids": [105], - "group_ids": [653, 654], - }) diff --git a/docs/gl_objects/mrs.rst b/docs/gl_objects/mrs.rst deleted file mode 100644 index f17ad26..0000000 --- a/docs/gl_objects/mrs.rst +++ /dev/null @@ -1,217 +0,0 @@ -.. _merge_requests_examples: - -############## -Merge requests -############## - -You can use merge requests to notify a project that a branch is ready for -merging. The owner of the target projet can accept the merge request. - -Merge requests are linked to projects, but they can be listed globally or for -groups. - -Group and global listing -======================== - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.GroupMergeRequest` - + :class:`gitlab.v4.objects.GroupMergeRequestManager` - + :attr:`gitlab.v4.objects.Group.mergerequests` - + :class:`gitlab.v4.objects.MergeRequest` - + :class:`gitlab.v4.objects.MergeRequestManager` - + :attr:`gitlab.Gitlab.mergerequests` - -* GitLab API: https://docs.gitlab.com/ce/api/merge_requests.html - -Examples --------- - -List the merge requests created by the user of the token on the GitLab server:: - - mrs = gl.mergerequests.list() - -List the merge requests available on the GitLab server:: - - mrs = gl.mergerequests.list(scope="all") - -List the merge requests for a group:: - - group = gl.groups.get('mygroup') - mrs = group.mergerequests.list() - -.. note:: - - It is not possible to edit or delete ``MergeRequest`` and - ``GroupMergeRequest`` objects. You need to create a ``ProjectMergeRequest`` - object to apply changes:: - - mr = group.mergerequests.list()[0] - project = gl.projects.get(mr.project_id, lazy=True) - editable_mr = project.mergerequests.get(mr.iid, lazy=True) - editable_mr.title = updated_title - editable_mr.save() - -Project merge requests -====================== - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectMergeRequest` - + :class:`gitlab.v4.objects.ProjectMergeRequestManager` - + :attr:`gitlab.v4.objects.Project.mergerequests` - -* GitLab API: https://docs.gitlab.com/ce/api/merge_requests.html - -Examples --------- - -List MRs for a project:: - - mrs = project.mergerequests.list() - -You can filter and sort the returned list with the following parameters: - -* ``state``: state of the MR. It can be one of ``all``, ``merged``, ``opened`` - or ``closed`` -* ``order_by``: sort by ``created_at`` or ``updated_at`` -* ``sort``: sort order (``asc`` or ``desc``) - -For example:: - - mrs = project.mergerequests.list(state='merged', order_by='updated_at') - -Get a single MR:: - - mr = project.mergerequests.get(mr_id) - -Create a MR:: - - mr = project.mergerequests.create({'source_branch': 'cool_feature', - 'target_branch': 'master', - 'title': 'merge cool feature', - 'labels': ['label1', 'label2']}) - -Update a MR:: - - mr.description = 'New description' - mr.labels = ['foo', 'bar'] - mr.save() - -Change the state of a MR (close or reopen):: - - mr.state_event = 'close' # or 'reopen' - mr.save() - -Delete a MR:: - - project.mergerequests.delete(mr_id) - # or - mr.delete() - -Accept a MR:: - - mr.merge() - -Cancel a MR when the build succeeds:: - - mr.cancel_merge_when_pipeline_succeeds() - -List commits of a MR:: - - commits = mr.commits() - -List the changes of a MR:: - - changes = mr.changes() - -List issues that will close on merge:: - - mr.closes_issues() - -Subscribe to / unsubscribe from a MR:: - - mr.subscribe() - mr.unsubscribe() - -Mark a MR as todo:: - - mr.todo() - -List the diffs for a merge request:: - - diffs = mr.diffs.list() - -Get a diff for a merge request:: - - diff = mr.diffs.get(diff_id) - -Get time tracking stats:: - - merge request.time_stats() - -On recent versions of Gitlab the time stats are also returned as a merge -request object attribute:: - - mr = project.mergerequests.get(id) - print(mr.attributes['time_stats']) - -Set a time estimate for a merge request:: - - mr.time_estimate('3h30m') - -Reset a time estimate for a merge request:: - - mr.reset_time_estimate() - -Add spent time for a merge request:: - - mr.add_spent_time('3h30m') - -Reset spent time for a merge request:: - - mr.reset_spent_time() - -Get user agent detail for the issue (admin only):: - - detail = issue.user_agent_detail() - -Attempt to rebase an MR:: - - mr.rebase() - -Attempt to merge changes between source and target branch:: - - response = mr.merge_ref() - print(response['commit_id']) - -Merge Request Pipelines -======================= - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectMergeRequestPipeline` - + :class:`gitlab.v4.objects.ProjectMergeRequestPipelineManager` - + :attr:`gitlab.v4.objects.ProjectMergeRequest.pipelines` - -* GitLab API: https://docs.gitlab.com/ee/api/merge_requests.html#list-mr-pipelines - -Examples --------- - -List pipelines for a merge request:: - - pipelines = mr.pipelines.list() - -Create a pipeline for a merge request:: - - pipeline = mr.pipelines.create() diff --git a/docs/gl_objects/namespaces.rst b/docs/gl_objects/namespaces.rst deleted file mode 100644 index 1aebd29..0000000 --- a/docs/gl_objects/namespaces.rst +++ /dev/null @@ -1,25 +0,0 @@ -########## -Namespaces -########## - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.Namespace` - + :class:`gitlab.v4.objects.NamespaceManager` - + :attr:`gitlab.Gitlab.namespaces` - -* GitLab API: https://docs.gitlab.com/ce/api/namespaces.html - -Examples --------- - -List namespaces:: - - namespaces = gl.namespaces.list() - -Search namespaces:: - - namespaces = gl.namespaces.list(search='foo') diff --git a/docs/gl_objects/notes.rst b/docs/gl_objects/notes.rst deleted file mode 100644 index 053c0a0..0000000 --- a/docs/gl_objects/notes.rst +++ /dev/null @@ -1,63 +0,0 @@ -.. _project-notes: - -##### -Notes -##### - -You can manipulate notes (comments) on project issues, merge requests and -snippets. - -Reference ---------- - -* v4 API: - - Issues: - - + :class:`gitlab.v4.objects.ProjectIssueNote` - + :class:`gitlab.v4.objects.ProjectIssueNoteManager` - + :attr:`gitlab.v4.objects.ProjectIssue.notes` - - MergeRequests: - - + :class:`gitlab.v4.objects.ProjectMergeRequestNote` - + :class:`gitlab.v4.objects.ProjectMergeRequestNoteManager` - + :attr:`gitlab.v4.objects.ProjectMergeRequest.notes` - - Snippets: - - + :class:`gitlab.v4.objects.ProjectSnippetNote` - + :class:`gitlab.v4.objects.ProjectSnippetNoteManager` - + :attr:`gitlab.v4.objects.ProjectSnippet.notes` - -* GitLab API: https://docs.gitlab.com/ce/api/notes.html - -Examples --------- - -List the notes for a resource:: - - i_notes = issue.notes.list() - mr_notes = mr.notes.list() - s_notes = snippet.notes.list() - -Get a note for a resource:: - - i_note = issue.notes.get(note_id) - mr_note = mr.notes.get(note_id) - s_note = snippet.notes.get(note_id) - -Create a note for a resource:: - - i_note = issue.notes.create({'body': 'note content'}) - mr_note = mr.notes.create({'body': 'note content'}) - s_note = snippet.notes.create({'body': 'note content'}) - -Update a note for a resource:: - - note.body = 'updated note content' - note.save() - -Delete a note for a resource:: - - note.delete() diff --git a/docs/gl_objects/notifications.rst b/docs/gl_objects/notifications.rst deleted file mode 100644 index ab0287f..0000000 --- a/docs/gl_objects/notifications.rst +++ /dev/null @@ -1,59 +0,0 @@ -##################### -Notification settings -##################### - -You can define notification settings globally, for groups and for projects. -Valid levels are defined as constants: - -* ``gitlab.NOTIFICATION_LEVEL_DISABLED`` -* ``gitlab.NOTIFICATION_LEVEL_PARTICIPATING`` -* ``gitlab.NOTIFICATION_LEVEL_WATCH`` -* ``gitlab.NOTIFICATION_LEVEL_GLOBAL`` -* ``gitlab.NOTIFICATION_LEVEL_MENTION`` -* ``gitlab.NOTIFICATION_LEVEL_CUSTOM`` - -You get access to fine-grained settings if you use the -``NOTIFICATION_LEVEL_CUSTOM`` level. - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.NotificationSettings` - + :class:`gitlab.v4.objects.NotificationSettingsManager` - + :attr:`gitlab.Gitlab.notificationsettings` - + :class:`gitlab.v4.objects.GroupNotificationSettings` - + :class:`gitlab.v4.objects.GroupNotificationSettingsManager` - + :attr:`gitlab.v4.objects.Group.notificationsettings` - + :class:`gitlab.v4.objects.ProjectNotificationSettings` - + :class:`gitlab.v4.objects.ProjectNotificationSettingsManager` - + :attr:`gitlab.v4.objects.Project.notificationsettings` - -* GitLab API: https://docs.gitlab.com/ce/api/notification_settings.html - -Examples --------- - -Get the notifications settings:: - - # global settings - settings = gl.notificationsettings.get() - # for a group - settings = gl.groups.get(group_id).notificationsettings.get() - # for a project - settings = gl.projects.get(project_id).notificationsettings.get() - -Update the notifications settings:: - - # use a predefined level - settings.level = gitlab.NOTIFICATION_LEVEL_WATCH - - # create a custom setup - settings.level = gitlab.NOTIFICATION_LEVEL_CUSTOM - settings.save() # will create additional attributes, but not mandatory - - settings.new_merge_request = True - settings.new_issue = True - settings.new_note = True - settings.save() diff --git a/docs/gl_objects/packages.rst b/docs/gl_objects/packages.rst deleted file mode 100644 index cc64e07..0000000 --- a/docs/gl_objects/packages.rst +++ /dev/null @@ -1,131 +0,0 @@ -######## -Packages -######## - -Packages allow you to utilize GitLab as a private repository for a variety -of common package managers, as well as GitLab's generic package registry. - -Project Packages -===================== - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectPackage` - + :class:`gitlab.v4.objects.ProjectPackageManager` - + :attr:`gitlab.v4.objects.Project.packages` - -* GitLab API: https://docs.gitlab.com/ee/api/packages.html#within-a-project - -Examples --------- - -List the packages in a project:: - - packages = project.packages.list() - -Filter the results by ``package_type`` or ``package_name`` :: - - packages = project.packages.list(package_type='pypi') - -Get a specific package of a project by id:: - - package = project.packages.get(1) - -Delete a package from a project:: - - package.delete() - # or - project.packages.delete(package.id) - - -Group Packages -=================== - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.GroupPackage` - + :class:`gitlab.v4.objects.GroupPackageManager` - + :attr:`gitlab.v4.objects.Group.packages` - -* GitLab API: https://docs.gitlab.com/ee/api/packages.html#within-a-group - -Examples --------- - -List the packages in a group:: - - packages = group.packages.list() - -Filter the results by ``package_type`` or ``package_name`` :: - - packages = group.packages.list(package_type='pypi') - - -Project Package Files -===================== - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectPackageFile` - + :class:`gitlab.v4.objects.ProjectPackageFileManager` - + :attr:`gitlab.v4.objects.ProjectPackage.package_files` - -* GitLab API: https://docs.gitlab.com/ee/api/packages.html#list-package-files - -Examples --------- - -List package files for package in project:: - - package = project.packages.get(1) - package_files = package.package_files.list() - -Generic Packages -================ - -You can use python-gitlab to upload and download generic packages. - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.GenericPackage` - + :class:`gitlab.v4.objects.GenericPackageManager` - + :attr:`gitlab.v4.objects.Project.generic_packages` - -* GitLab API: https://docs.gitlab.com/ee/user/packages/generic_packages - -Examples --------- - -Upload a generic package to a project:: - - project = gl.projects.get(1, lazy=True) - package = project.generic_packages.upload( - package_name="hello-world", - package_version="v1.0.0", - file_name="hello.tar.gz", - path="/path/to/local/hello.tar.gz" - ) - -Download a project's generic package:: - - project = gl.projects.get(1, lazy=True) - package = project.generic_packages.download( - package_name="hello-world", - package_version="v1.0.0", - file_name="hello.tar.gz", - ) - -.. hint:: You can use the Packages API described above to find packages and - retrieve the metadata you need download them. diff --git a/docs/gl_objects/pagesdomains.rst b/docs/gl_objects/pagesdomains.rst deleted file mode 100644 index d6b39c7..0000000 --- a/docs/gl_objects/pagesdomains.rst +++ /dev/null @@ -1,65 +0,0 @@ -############# -Pages domains -############# - -Admin -===== - -References ----------- - -* v4 API: - - + :class:`gitlab.v4.objects.PagesDomain` - + :class:`gitlab.v4.objects.PagesDomainManager` - + :attr:`gitlab.Gitlab.pagesdomains` - -* GitLab API: https://docs.gitlab.com/ce/api/pages_domains.html#list-all-pages-domains - -Examples --------- - -List all the existing domains (admin only):: - - domains = gl.pagesdomains.list() - -Project pages domain -==================== - -References ----------- - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectPagesDomain` - + :class:`gitlab.v4.objects.ProjectPagesDomainManager` - + :attr:`gitlab.v4.objects.Project.pagesdomains` - -* GitLab API: https://docs.gitlab.com/ce/api/pages_domains.html#list-pages-domains - -Examples --------- - -List domains for a project:: - - domains = project.pagesdomains.list() - -Get a single domain:: - - domain = project.pagesdomains.get('d1.example.com') - -Create a new domain:: - - domain = project.pagesdomains.create({'domain': 'd2.example.com}) - -Update an existing domain:: - - domain.certificate = open('d2.crt').read() - domain.key = open('d2.key').read() - domain.save() - -Delete an existing domain:: - - domain.delete - # or - project.pagesdomains.delete('d2.example.com') diff --git a/docs/gl_objects/personal_access_tokens.rst b/docs/gl_objects/personal_access_tokens.rst deleted file mode 100644 index 0704c75..0000000 --- a/docs/gl_objects/personal_access_tokens.rst +++ /dev/null @@ -1,54 +0,0 @@ -###################### -Personal Access Tokens -###################### - -References ----------- - -* v4 API: - - + :class:`gitlab.v4.objects.PersonalAccessToken` - + :class:`gitlab.v4.objects.PersonalAcessTokenManager` - + :attr:`gitlab.Gitlab.personal_access_tokens` - + :class:`gitlab.v4.objects.UserPersonalAccessToken` - + :class:`gitlab.v4.objects.UserPersonalAcessTokenManager` - + :attr:`gitlab.Gitlab.User.personal_access_tokens` - -* GitLab API: - - + https://docs.gitlab.com/ee/api/personal_access_tokens.html - + https://docs.gitlab.com/ee/api/users.html#create-a-personal-access-token - -Examples --------- - -List personal access tokens:: - - access_tokens = gl.personal_access_tokens.list() - print(access_tokens[0].name) - -List personal access tokens from other user_id (admin only):: - - access_tokens = gl.personal_access_tokens.list(user_id=25) - -Revoke a personal access token fetched via list:: - - access_token = access_tokens[0] - access_token.delete() - -Revoke a personal access token by id:: - - gl.personal_access_tokens.delete(123) - -Create a personal access token for a user (admin only):: - - user = gl.users.get(25, lazy=True) - access_token = user.personal_access_tokens.create({"name": "test", "scopes": "api"}) - -.. note:: As you can see above, you can only create personal access tokens - via the Users API, but you cannot revoke these objects directly. - This is because the create API uses a different endpoint than the list and revoke APIs. - You need to fetch the token via the list API first to revoke it. - - As of 14.2, GitLab does not provide a GET API for single personal access tokens. - You must use the list method to retrieve single tokens. diff --git a/docs/gl_objects/pipelines_and_jobs.rst b/docs/gl_objects/pipelines_and_jobs.rst deleted file mode 100644 index 675ff4e..0000000 --- a/docs/gl_objects/pipelines_and_jobs.rst +++ /dev/null @@ -1,355 +0,0 @@ -################## -Pipelines and Jobs -################## - -Project pipelines -================= - -A pipeline is a group of jobs executed by GitLab CI. - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectPipeline` - + :class:`gitlab.v4.objects.ProjectPipelineManager` - + :attr:`gitlab.v4.objects.Project.pipelines` - -* GitLab API: https://docs.gitlab.com/ce/api/pipelines.html - -Examples --------- - -List pipelines for a project:: - - pipelines = project.pipelines.list() - -Get a pipeline for a project:: - - pipeline = project.pipelines.get(pipeline_id) - -Get variables of a pipeline:: - - variables = pipeline.variables.list() - -Create a pipeline for a particular reference with custom variables:: - - pipeline = project.pipelines.create({'ref': 'master', 'variables': [{'key': 'MY_VARIABLE', 'value': 'hello'}]}) - -Retry the failed builds for a pipeline:: - - pipeline.retry() - -Cancel builds in a pipeline:: - - pipeline.cancel() - -Delete a pipeline:: - - pipeline.delete() - -Triggers -======== - -Triggers provide a way to interact with the GitLab CI. Using a trigger a user -or an application can run a new build/job for a specific commit. - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectTrigger` - + :class:`gitlab.v4.objects.ProjectTriggerManager` - + :attr:`gitlab.v4.objects.Project.triggers` - -* GitLab API: https://docs.gitlab.com/ce/api/pipeline_triggers.html - -Examples --------- - -List triggers:: - - triggers = project.triggers.list() - -Get a trigger:: - - trigger = project.triggers.get(trigger_token) - -Create a trigger:: - - trigger = project.triggers.create({'description': 'mytrigger'}) - -Remove a trigger:: - - project.triggers.delete(trigger_token) - # or - trigger.delete() - -Full example with wait for finish:: - - def get_or_create_trigger(project): - trigger_decription = 'my_trigger_id' - for t in project.triggers.list(): - if t.description == trigger_decription: - return t - return project.triggers.create({'description': trigger_decription}) - - trigger = get_or_create_trigger(project) - pipeline = project.trigger_pipeline('master', trigger.token, variables={"DEPLOY_ZONE": "us-west1"}) - while pipeline.finished_at is None: - pipeline.refresh() - time.sleep(1) - -You can trigger a pipeline using token authentication instead of user -authentication. To do so create an anonymous Gitlab instance and use lazy -objects to get the associated project:: - - gl = gitlab.Gitlab(URL) # no authentication - project = gl.projects.get(project_id, lazy=True) # no API call - project.trigger_pipeline('master', trigger_token) - -Reference: https://docs.gitlab.com/ee/ci/triggers/#trigger-token - -Pipeline schedule -================= - -You can schedule pipeline runs using a cron-like syntax. Variables can be -associated with the scheduled pipelines. - -Reference ---------- - -* v4 API - - + :class:`gitlab.v4.objects.ProjectPipelineSchedule` - + :class:`gitlab.v4.objects.ProjectPipelineScheduleManager` - + :attr:`gitlab.v4.objects.Project.pipelineschedules` - + :class:`gitlab.v4.objects.ProjectPipelineScheduleVariable` - + :class:`gitlab.v4.objects.ProjectPipelineScheduleVariableManager` - + :attr:`gitlab.v4.objects.Project.pipelineschedules` - -* GitLab API: https://docs.gitlab.com/ce/api/pipeline_schedules.html - -Examples --------- - -List pipeline schedules:: - - scheds = project.pipelineschedules.list() - -Get a single schedule:: - - sched = projects.pipelineschedules.get(schedule_id) - -Create a new schedule:: - - sched = project.pipelineschedules.create({ - 'ref': 'master', - 'description': 'Daily test', - 'cron': '0 1 * * *'}) - -Update a schedule:: - - sched.cron = '1 2 * * *' - sched.save() - -Take ownership of a schedule: - - sched.take_ownership() - -Trigger a pipeline schedule immediately:: - - sched = projects.pipelineschedules.get(schedule_id) - sched.play() - -Delete a schedule:: - - sched.delete() - -List schedule variables:: - - # note: you need to use get() to retrieve the schedule variables. The - # attribute is not present in the response of a list() call - sched = projects.pipelineschedules.get(schedule_id) - vars = sched.attributes['variables'] - -Create a schedule variable:: - - var = sched.variables.create({'key': 'foo', 'value': 'bar'}) - -Edit a schedule variable:: - - var.value = 'new_value' - var.save() - -Delete a schedule variable:: - - var.delete() - - -Jobs -==== - -Jobs are associated to projects, pipelines and commits. They provide -information on the jobs that have been run, and methods to manipulate -them. - -Reference ---------- - -* v4 API - - + :class:`gitlab.v4.objects.ProjectJob` - + :class:`gitlab.v4.objects.ProjectJobManager` - + :attr:`gitlab.v4.objects.Project.jobs` - -* GitLab API: https://docs.gitlab.com/ce/api/jobs.html - -Examples --------- - -Jobs are usually automatically triggered, but you can explicitly trigger a new -job:: - - project.trigger_build('master', trigger_token, - {'extra_var1': 'foo', 'extra_var2': 'bar'}) - -List jobs for the project:: - - jobs = project.jobs.list() - -Get a single job:: - - project.jobs.get(job_id) - -List the jobs of a pipeline:: - - project = gl.projects.get(project_id) - pipeline = project.pipelines.get(pipeline_id) - jobs = pipeline.jobs.list() - -.. note:: - - Job methods (play, cancel, and so on) are not available on - ``ProjectPipelineJob`` objects. To use these methods create a ``ProjectJob`` - object:: - - pipeline_job = pipeline.jobs.list()[0] - job = project.jobs.get(pipeline_job.id, lazy=True) - job.retry() - -Get the artifacts of a job:: - - build_or_job.artifacts() - -Get the artifacts of a job by its name from the latest successful pipeline of -a branch or tag: - - project.artifacts(ref_name='master', job='build') - -.. warning:: - - Artifacts are entirely stored in memory in this example. - -.. _streaming_example: - -You can download artifacts as a stream. Provide a callable to handle the -stream:: - - with open("archive.zip", "wb") as f: - build_or_job.artifacts(streamed=True, action=f.write) - -You can also directly stream the output into a file, and unzip it afterwards:: - - zipfn = "___artifacts.zip" - with open(zipfn, "wb") as f: - build_or_job.artifacts(streamed=True, action=f.write) - subprocess.run(["unzip", "-bo", zipfn]) - os.unlink(zipfn) - -Get a single artifact file:: - - build_or_job.artifact('path/to/file') - -Get a single artifact file by branch and job:: - - project.artifact('branch', 'path/to/file', 'job') - -Mark a job artifact as kept when expiration is set:: - - build_or_job.keep_artifacts() - -Delete the artifacts of a job:: - - build_or_job.delete_artifacts() - -Get a job trace:: - - build_or_job.trace() - -.. warning:: - - Traces are entirely stored in memory unless you use the streaming feature. - See :ref:`the artifacts example <streaming_example>`. - -Cancel/retry a job:: - - build_or_job.cancel() - build_or_job.retry() - -Play (trigger) a job:: - - build_or_job.play() - -Erase a job (artifacts and trace):: - - build_or_job.erase() - - -Pipeline bridges -===================== - -Get a list of bridge jobs (including child pipelines) for a pipeline. - -Reference ---------- - -* v4 API - - + :class:`gitlab.v4.objects.ProjectPipelineBridge` - + :class:`gitlab.v4.objects.ProjectPipelineBridgeManager` - + :attr:`gitlab.v4.objects.ProjectPipeline.bridges` - -* GitLab API: https://docs.gitlab.com/ee/api/jobs.html#list-pipeline-bridges - -Examples --------- - -List bridges for the pipeline:: - - bridges = pipeline.bridges.list() - -Pipeline test report -==================== - -Get a pipeline's complete test report. - -Reference ---------- - -* v4 API - - + :class:`gitlab.v4.objects.ProjectPipelineTestReport` - + :class:`gitlab.v4.objects.ProjectPipelineTestReportManager` - + :attr:`gitlab.v4.objects.ProjectPipeline.test_report` - -* GitLab API: https://docs.gitlab.com/ee/api/pipelines.html#get-a-pipelines-test-report - -Examples --------- - -Get the test report for a pipeline:: - - test_report = pipeline.test_report.get() diff --git a/docs/gl_objects/project_access_tokens.rst b/docs/gl_objects/project_access_tokens.rst deleted file mode 100644 index 850cd25..0000000 --- a/docs/gl_objects/project_access_tokens.rst +++ /dev/null @@ -1,34 +0,0 @@ -##################### -Project Access Tokens -##################### - -Get a list of project access tokens - -References ----------- - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectAccessToken` - + :class:`gitlab.v4.objects.ProjectAccessTokenManager` - + :attr:`gitlab.Gitlab.project_access_tokens` - -* GitLab API: https://docs.gitlab.com/ee/api/resource_access_tokens.html - -Examples --------- - -List project access tokens:: - - access_tokens = gl.projects.get(1, lazy=True).access_tokens.list() - print(access_tokens[0].name) - -Create project access token:: - - access_token = gl.projects.get(1).access_tokens.create({"name": "test", "scopes": ["api"]}) - -Revoke a project access tokens:: - - gl.projects.get(1).access_tokens.delete(42) - # or - access_token.delete() diff --git a/docs/gl_objects/projects.rst b/docs/gl_objects/projects.rst deleted file mode 100644 index fdf5ac5..0000000 --- a/docs/gl_objects/projects.rst +++ /dev/null @@ -1,768 +0,0 @@ -######## -Projects -######## - -Projects -======== - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.Project` - + :class:`gitlab.v4.objects.ProjectManager` - + :attr:`gitlab.Gitlab.projects` - -* GitLab API: https://docs.gitlab.com/ce/api/projects.html - -Examples --------- - -List projects:: - - projects = gl.projects.list() - -The API provides several filtering parameters for the listing methods: - -* ``archived``: if ``True`` only archived projects will be returned -* ``visibility``: returns only projects with the specified visibility (can be - ``public``, ``internal`` or ``private``) -* ``search``: returns project matching the given pattern - -Results can also be sorted using the following parameters: - -* ``order_by``: sort using the given argument. Valid values are ``id``, - ``name``, ``path``, ``created_at``, ``updated_at`` and ``last_activity_at``. - The default is to sort by ``created_at`` -* ``sort``: sort order (``asc`` or ``desc``) - -:: - - # List all projects (default 20) - projects = gl.projects.list(all=True) - # Archived projects - projects = gl.projects.list(archived=1) - # Limit to projects with a defined visibility - projects = gl.projects.list(visibility='public') - - # List owned projects - projects = gl.projects.list(owned=True) - - # List starred projects - projects = gl.projects.list(starred=True) - - # Search projects - projects = gl.projects.list(search='keyword') - -.. note:: - - Fetching a list of projects, doesn't include all attributes of all projects. - To retrieve all attributes, you'll need to fetch a single project - -Get a single project:: - - # Get a project by ID - project_id = 851 - project = gl.projects.get(project_id) - - # Get a project by name with namespace - project_name_with_namespace = "namespace/project_name" - project = gl.projects.get(project_name_with_namespace) - -Create a project:: - - project = gl.projects.create({'name': 'project1'}) - -Create a project for a user (admin only):: - - alice = gl.users.list(username='alice')[0] - user_project = alice.projects.create({'name': 'project'}) - user_projects = alice.projects.list() - -Create a project in a group:: - - # You need to get the id of the group, then use the namespace_id attribute - # to create the group - group_id = gl.groups.list(search='my-group')[0].id - project = gl.projects.create({'name': 'myrepo', 'namespace_id': group_id}) - -Update a project:: - - project.snippets_enabled = 1 - project.save() - -Set the avatar image for a project:: - - # the avatar image can be passed as data (content of the file) or as a file - # object opened in binary mode - project.avatar = open('path/to/file.png', 'rb') - project.save() - -Delete a project:: - - gl.projects.delete(project_id) - # or - project.delete() - -Fork a project:: - - fork = project.forks.create({}) - - # fork to a specific namespace - fork = project.forks.create({'namespace': 'myteam'}) - -Get a list of forks for the project:: - - forks = project.forks.list() - -Create/delete a fork relation between projects (requires admin permissions):: - - project.create_fork_relation(source_project.id) - project.delete_fork_relation() - -Get languages used in the project with percentage value:: - - languages = project.languages() - -Star/unstar a project:: - - project.star() - project.unstar() - -Archive/unarchive a project:: - - project.archive() - project.unarchive() - -Start the housekeeping job:: - - project.housekeeping() - -List the repository tree:: - - # list the content of the root directory for the default branch - items = project.repository_tree() - - # list the content of a subdirectory on a specific branch - items = project.repository_tree(path='docs', ref='branch1') - -Get the content and metadata of a file for a commit, using a blob sha:: - - items = project.repository_tree(path='docs', ref='branch1') - file_info = p.repository_blob(items[0]['id']) - content = base64.b64decode(file_info['content']) - size = file_info['size'] - -Update a project submodule:: - - items = project.update_submodule( - submodule="foo/bar", - branch="master", - commit_sha="4c3674f66071e30b3311dac9b9ccc90502a72664", - commit_message="Message", # optional - ) - -Get the repository archive:: - - tgz = project.repository_archive() - - # get the archive for a branch/tag/commit - tgz = project.repository_archive(sha='4567abc') - -.. warning:: - - Archives are entirely stored in memory unless you use the streaming feature. - See :ref:`the artifacts example <streaming_example>`. - -Get the content of a file using the blob id:: - - # find the id for the blob (simple search) - id = [d['id'] for d in p.repository_tree() if d['name'] == 'README.rst'][0] - - # get the content - file_content = p.repository_raw_blob(id) - -.. warning:: - - Blobs are entirely stored in memory unless you use the streaming feature. - See :ref:`the artifacts example <streaming_example>`. - -Get a snapshot of the repository:: - - tar_file = project.snapshot() - -.. warning:: - - Snapshots are entirely stored in memory unless you use the streaming - feature. See :ref:`the artifacts example <streaming_example>`. - -Compare two branches, tags or commits:: - - result = project.repository_compare('master', 'branch1') - - # get the commits - for commit in result['commits']: - print(commit) - - # get the diffs - for file_diff in result['diffs']: - print(file_diff) - -Get a list of contributors for the repository:: - - contributors = project.repository_contributors() - -Get a list of users for the repository:: - - users = p.users.list() - - # search for users - users = p.users.list(search='pattern') - -Start the pull mirroring process (EE edition):: - - project.mirror_pull() - -Import / Export -=============== - -You can export projects from gitlab, and re-import them to create new projects -or overwrite existing ones. - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectExport` - + :class:`gitlab.v4.objects.ProjectExportManager` - + :attr:`gitlab.v4.objects.Project.exports` - + :class:`gitlab.v4.objects.ProjectImport` - + :class:`gitlab.v4.objects.ProjectImportManager` - + :attr:`gitlab.v4.objects.Project.imports` - + :attr:`gitlab.v4.objects.ProjectManager.import_project` - -* GitLab API: https://docs.gitlab.com/ce/api/project_import_export.html - -Examples --------- - -A project export is an asynchronous operation. To retrieve the archive -generated by GitLab you need to: - -#. Create an export using the API -#. Wait for the export to be done -#. Download the result - -:: - - # Create the export - p = gl.projects.get(my_project) - export = p.exports.create() - - # Wait for the 'finished' status - export.refresh() - while export.export_status != 'finished': - time.sleep(1) - export.refresh() - - # Download the result - with open('/tmp/export.tgz', 'wb') as f: - export.download(streamed=True, action=f.write) - -Import the project:: - - output = gl.projects.import_project(open('/tmp/export.tgz', 'rb'), 'my_new_project') - # Get a ProjectImport object to track the import status - project_import = gl.projects.get(output['id'], lazy=True).imports.get() - while project_import.import_status != 'finished': - time.sleep(1) - project_import.refresh() - - -Project custom attributes -========================= - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectCustomAttribute` - + :class:`gitlab.v4.objects.ProjectCustomAttributeManager` - + :attr:`gitlab.v4.objects.Project.customattributes` - -* GitLab API: https://docs.gitlab.com/ce/api/custom_attributes.html - -Examples --------- - -List custom attributes for a project:: - - attrs = project.customattributes.list() - -Get a custom attribute for a project:: - - attr = project.customattributes.get(attr_key) - -Set (create or update) a custom attribute for a project:: - - attr = project.customattributes.set(attr_key, attr_value) - -Delete a custom attribute for a project:: - - attr.delete() - # or - project.customattributes.delete(attr_key) - -Search projects by custom attribute:: - - project.customattributes.set('type', 'internal') - gl.projects.list(custom_attributes={'type': 'internal'}) - -Project files -============= - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectFile` - + :class:`gitlab.v4.objects.ProjectFileManager` - + :attr:`gitlab.v4.objects.Project.files` - -* GitLab API: https://docs.gitlab.com/ce/api/repository_files.html - -Examples --------- - -Get a file:: - - f = project.files.get(file_path='README.rst', ref='master') - - # get the base64 encoded content - print(f.content) - - # get the decoded content - print(f.decode()) - -Get a raw file:: - - raw_content = project.files.raw(file_path='README.rst', ref='master') - print(raw_content) - with open('/tmp/raw-download.txt', 'wb') as f: - project.files.raw(file_path='README.rst', ref='master', streamed=True, action=f.write) - -Create a new file:: - - f = project.files.create({'file_path': 'testfile.txt', - 'branch': 'master', - 'content': file_content, - 'author_email': 'test@example.com', - 'author_name': 'yourname', - 'encoding': 'text', - 'commit_message': 'Create testfile'}) - -Update a file. The entire content must be uploaded, as plain text or as base64 -encoded text:: - - f.content = 'new content' - f.save(branch='master', commit_message='Update testfile') - - # or for binary data - # Note: decode() is required with python 3 for data serialization. You can omit - # it with python 2 - f.content = base64.b64encode(open('image.png').read()).decode() - f.save(branch='master', commit_message='Update testfile', encoding='base64') - -Delete a file:: - - f.delete(commit_message='Delete testfile', branch='master') - # or - project.files.delete(file_path='testfile.txt', commit_message='Delete testfile', branch='master') - -Get file blame:: - - b = project.files.blame(file_path='README.rst', ref='master') - -Project tags -============ - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectTag` - + :class:`gitlab.v4.objects.ProjectTagManager` - + :attr:`gitlab.v4.objects.Project.tags` - -* GitLab API: https://docs.gitlab.com/ce/api/tags.html - -Examples --------- - -List the project tags:: - - tags = project.tags.list() - -Get a tag:: - - tag = project.tags.get('1.0') - -Create a tag:: - - tag = project.tags.create({'tag_name': '1.0', 'ref': 'master'}) - -Delete a tag:: - - project.tags.delete('1.0') - # or - tag.delete() - -.. _project_snippets: - -Project snippets -================ - -The snippet visibility can be defined using the following constants: - -* ``gitlab.VISIBILITY_PRIVATE`` -* ``gitlab.VISIBILITY_INTERNAL`` -* ``gitlab.VISIBILITY_PUBLIC`` - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectSnippet` - + :class:`gitlab.v4.objects.ProjectSnippetManager` - + :attr:`gitlab.v4.objects.Project.files` - -* GitLab API: https://docs.gitlab.com/ce/api/project_snippets.html - -Examples --------- - -List the project snippets:: - - snippets = project.snippets.list() - -Get a snippet:: - - snippet = project.snippets.get(snippet_id) - -Get the content of a snippet:: - - print(snippet.content()) - -.. warning:: - - The snippet content is entirely stored in memory unless you use the - streaming feature. See :ref:`the artifacts example <streaming_example>`. - -Create a snippet:: - - snippet = project.snippets.create({'title': 'sample 1', - 'file_name': 'foo.py', - 'code': 'import gitlab', - 'visibility_level': - gitlab.VISIBILITY_PRIVATE}) - -Update a snippet:: - - snippet.code = 'import gitlab\nimport whatever' - snippet.save - -Delete a snippet:: - - project.snippets.delete(snippet_id) - # or - snippet.delete() - -Get user agent detail (admin only):: - - detail = snippet.user_agent_detail() - -Notes -===== - -See :ref:`project-notes`. - -Project members -=============== - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectMember` - + :class:`gitlab.v4.objects.ProjectMemberManager` - + :class:`gitlab.v4.objects.ProjectMemberAllManager` - + :attr:`gitlab.v4.objects.Project.members` - + :attr:`gitlab.v4.objects.Project.members_all` - -* GitLab API: https://docs.gitlab.com/ce/api/members.html - -Examples --------- - -List only direct project members:: - - members = project.members.list() - -List the project members recursively (including inherited members through -ancestor groups):: - - members = project.members_all.list(all=True) - -Search project members matching a query string:: - - members = project.members.list(query='bar') - -Get only direct project member:: - - member = project.members.get(user_id) - -Get a member of a project, including members inherited through ancestor groups:: - - members = project.members_all.get(member_id) - - -Add a project member:: - - member = project.members.create({'user_id': user.id, 'access_level': - gitlab.DEVELOPER_ACCESS}) - -Modify a project member (change the access level):: - - member.access_level = gitlab.MAINTAINER_ACCESS - member.save() - -Remove a member from the project team:: - - project.members.delete(user.id) - # or - member.delete() - -Share/unshare the project with a group:: - - project.share(group.id, gitlab.DEVELOPER_ACCESS) - project.unshare(group.id) - -Project hooks -============= - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectHook` - + :class:`gitlab.v4.objects.ProjectHookManager` - + :attr:`gitlab.v4.objects.Project.hooks` - -* GitLab API: https://docs.gitlab.com/ce/api/projects.html#hooks - -Examples --------- - -List the project hooks:: - - hooks = project.hooks.list() - -Get a project hook:: - - hook = project.hooks.get(hook_id) - -Create a project hook:: - - hook = project.hooks.create({'url': 'http://my/action/url', 'push_events': 1}) - -Update a project hook:: - - hook.push_events = 0 - hook.save() - -Delete a project hook:: - - project.hooks.delete(hook_id) - # or - hook.delete() - -Project Services -================ - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectService` - + :class:`gitlab.v4.objects.ProjectServiceManager` - + :attr:`gitlab.v4.objects.Project.services` - -* GitLab API: https://docs.gitlab.com/ce/api/services.html - -Examples ---------- - -Get a service:: - - service = project.services.get('asana') - # display its status (enabled/disabled) - print(service.active) - -List active project services:: - - service = project.services.list() - -List the code names of available services (doesn't return objects):: - - services = project.services.available() - -Configure and enable a service:: - - service.api_key = 'randomkey' - service.save() - -Disable a service:: - - service.delete() - -File uploads -============ - -Reference ---------- - -* v4 API: - - + :attr:`gitlab.v4.objects.Project.upload` - -* Gitlab API: https://docs.gitlab.com/ce/api/projects.html#upload-a-file - -Examples --------- - -Upload a file into a project using a filesystem path:: - - project.upload("filename.txt", filepath="/some/path/filename.txt") - -Upload a file into a project without a filesystem path:: - - project.upload("filename.txt", filedata="Raw data") - -Upload a file and comment on an issue using the uploaded file's -markdown:: - - uploaded_file = project.upload("filename.txt", filedata="data") - issue = project.issues.get(issue_id) - issue.notes.create({ - "body": "See the attached file: {}".format(uploaded_file["markdown"]) - }) - -Upload a file and comment on an issue while using custom -markdown to reference the uploaded file:: - - uploaded_file = project.upload("filename.txt", filedata="data") - issue = project.issues.get(issue_id) - issue.notes.create({ - "body": "See the [attached file]({})".format(uploaded_file["url"]) - }) - -Project push rules -================== - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectPushRules` - + :class:`gitlab.v4.objects.ProjectPushRulesManager` - + :attr:`gitlab.v4.objects.Project.pushrules` - -* GitLab API: https://docs.gitlab.com/ee/api/projects.html#push-rules - -Examples ---------- - -Create project push rules (at least one rule is necessary):: - - project.pushrules.create({'deny_delete_tag': True}) - -Get project push rules (returns None is there are no push rules):: - - pr = project.pushrules.get() - -Edit project push rules:: - - pr.branch_name_regex = '^(master|develop|support-\d+|release-\d+\..+|hotfix-.+|feature-.+)$' - pr.save() - -Delete project push rules:: - - pr.delete() - -Project protected tags -====================== - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectProtectedTag` - + :class:`gitlab.v4.objects.ProjectProtectedTagManager` - + :attr:`gitlab.v4.objects.Project.protectedtags` - -* GitLab API: https://docs.gitlab.com/ce/api/protected_tags.html - -Examples ---------- - -Get a list of protected tags from a project:: - - protected_tags = project.protectedtags.list() - -Get a single protected tag or wildcard protected tag:: - - protected_tag = project.protectedtags.get('v*') - -Protect a single repository tag or several project repository tags using a wildcard protected tag:: - - project.protectedtags.create({'name': 'v*', 'create_access_level': '40'}) - -Unprotect the given protected tag or wildcard protected tag.:: - - protected_tag.delete() - -Additional project statistics -============================= - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectAdditionalStatistics` - + :class:`gitlab.v4.objects.ProjectAdditionalStatisticsManager` - + :attr:`gitlab.v4.objects.Project.additionalstatistics` - -* GitLab API: https://docs.gitlab.com/ce/api/project_statistics.html - -Examples ---------- - -Get all additional statistics of a project:: - - statistics = project.additionalstatistics.get() - -Get total fetches in last 30 days of a project:: - - total_fetches = project.additionalstatistics.get().fetches['total'] diff --git a/docs/gl_objects/protected_branches.rst b/docs/gl_objects/protected_branches.rst deleted file mode 100644 index 3498aa5..0000000 --- a/docs/gl_objects/protected_branches.rst +++ /dev/null @@ -1,51 +0,0 @@ -################## -Protected branches -################## - -You can define a list of protected branch names on a repository. Names can use -wildcards (``*``). - -References ----------- - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectProtectedBranch` - + :class:`gitlab.v4.objects.ProjectProtectedBranchManager` - + :attr:`gitlab.v4.objects.Project.protectedbranches` - -* GitLab API: https://docs.gitlab.com/ce/api/protected_branches.html#protected-branches-api - -Examples --------- - -Get the list of protected branches for a project:: - - p_branches = project.protectedbranches.list() - -Get a single protected branch:: - - p_branch = project.protectedbranches.get('master') - -Create a protected branch:: - - p_branch = project.protectedbranches.create({ - 'name': '*-stable', - 'merge_access_level': gitlab.DEVELOPER_ACCESS, - 'push_access_level': gitlab.MAINTAINER_ACCESS - }) - -Create a protected branch with more granular access control:: - - p_branch = project.protectedbranches.create({ - 'name': '*-stable', - 'allowed_to_push': [{"user_id": 99}, {"user_id": 98}], - 'allowed_to_merge': [{"group_id": 653}], - 'allowed_to_unprotect': [{"access_level": gitlab.MAINTAINER_ACCESS}] - }) - -Delete a protected branch:: - - project.protectedbranches.delete('*-stable') - # or - p_branch.delete() diff --git a/docs/gl_objects/releases.rst b/docs/gl_objects/releases.rst deleted file mode 100644 index 6077fe9..0000000 --- a/docs/gl_objects/releases.rst +++ /dev/null @@ -1,83 +0,0 @@ -######## -Releases -######## - -Project releases -================ - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectRelease` - + :class:`gitlab.v4.objects.ProjectReleaseManager` - + :attr:`gitlab.v4.objects.Project.releases` - -* Gitlab API: https://docs.gitlab.com/ee/api/releases/index.html - -Examples --------- - -Get a list of releases from a project:: - - release = project.releases.list() - -Get a single release:: - - release = project.releases.get('v1.2.3') - -Edit a release:: - - release.name = "Demo Release" - release.description = "release notes go here" - release.save() - -Create a release for a project tag:: - - release = project.releases.create({'name':'Demo Release', 'tag_name':'v1.2.3', 'description':'release notes go here'}) - -Delete a release:: - - # via its tag name from project attributes - release = project.releases.delete('v1.2.3') - - # delete object directly - release.delete() - -Project release links -===================== - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectReleaseLink` - + :class:`gitlab.v4.objects.ProjectReleaseLinkManager` - + :attr:`gitlab.v4.objects.ProjectRelease.links` - -* Gitlab API: https://docs.gitlab.com/ee/api/releases/links.html - -Examples --------- - -Get a list of releases from a project:: - - links = release.links.list() - -Get a single release link:: - - link = release.links.get(1) - -Create a release link for a release:: - - link = release.links.create({"url": "https://example.com/asset", "name": "asset"}) - -Delete a release link:: - - # via its ID from release attributes - release.links.delete(1) - - # delete object directly - link.delete() diff --git a/docs/gl_objects/remote_mirrors.rst b/docs/gl_objects/remote_mirrors.rst deleted file mode 100644 index 9024228..0000000 --- a/docs/gl_objects/remote_mirrors.rst +++ /dev/null @@ -1,34 +0,0 @@ -###################### -Project Remote Mirrors -###################### - -Remote Mirrors allow you to set up push mirroring for a project. - -References -========== - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectRemoteMirror` - + :class:`gitlab.v4.objects.ProjectRemoteMirrorManager` - + :attr:`gitlab.v4.objects.Project.remote_mirrors` - -* GitLab API: https://docs.gitlab.com/ce/api/remote_mirrors.html - -Examples --------- - -Get the list of a project's remote mirrors:: - - mirrors = project.remote_mirrors.list() - -Create (and enable) a remote mirror for a project:: - - mirror = project.remote_mirrors.create({'url': 'https://gitlab.com/example.git', - 'enabled': True}) - -Update an existing remote mirror's attributes:: - - mirror.enabled = False - mirror.only_protected_branches = True - mirror.save() diff --git a/docs/gl_objects/repositories.rst b/docs/gl_objects/repositories.rst deleted file mode 100644 index 6622c0c..0000000 --- a/docs/gl_objects/repositories.rst +++ /dev/null @@ -1,28 +0,0 @@ -##################### -Registry Repositories -##################### - -References ----------- - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectRegistryRepository` - + :class:`gitlab.v4.objects.ProjectRegistryRepositoryManager` - + :attr:`gitlab.v4.objects.Project.repositories` - -* Gitlab API: https://docs.gitlab.com/ce/api/container_registry.html - -Examples --------- - -Get the list of container registry repositories associated with the project:: - - repositories = project.repositories.list() - -Delete repository:: - - project.repositories.delete(id=x) - # or - repository = repositories.pop() - repository.delete() diff --git a/docs/gl_objects/repository_tags.rst b/docs/gl_objects/repository_tags.rst deleted file mode 100644 index 2fa807c..0000000 --- a/docs/gl_objects/repository_tags.rst +++ /dev/null @@ -1,47 +0,0 @@ -######################## -Registry Repository Tags -######################## - -References ----------- - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectRegistryTag` - + :class:`gitlab.v4.objects.ProjectRegistryTagManager` - + :attr:`gitlab.v4.objects.Repository.tags` - -* Gitlab API: https://docs.gitlab.com/ce/api/container_registry.html - -Examples --------- - -Get the list of repository tags in given registry:: - - repositories = project.repositories.list() - repository = repositories.pop() - tags = repository.tags.list() - -Get specific tag:: - - repository.tags.get(id=tag_name) - -Delete tag:: - - repository.tags.delete(id=tag_name) - # or - tag = repository.tags.get(id=tag_name) - tag.delete() - -Delete tag in bulk:: - - repository.tags.delete_in_bulk(keep_n=1) - # or - repository.tags.delete_in_bulk(older_than="1m") - # or - repository.tags.delete_in_bulk(name_regex="v.+", keep_n=2) - -.. note:: - - Delete in bulk is asynchronous operation and may take a while. - Refer to: https://docs.gitlab.com/ce/api/container_registry.html#delete-repository-tags-in-bulk diff --git a/docs/gl_objects/runners.rst b/docs/gl_objects/runners.rst deleted file mode 100644 index 1919975..0000000 --- a/docs/gl_objects/runners.rst +++ /dev/null @@ -1,137 +0,0 @@ -####### -Runners -####### - -Runners are external processes used to run CI jobs. They are deployed by the -administrator and registered to the GitLab instance. - -Shared runners are available for all projects. Specific runners are enabled for -a list of projects. - -Global runners (admin) -====================== - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.Runner` - + :class:`gitlab.v4.objects.RunnerManager` - + :attr:`gitlab.Gitlab.runners` - -* GitLab API: https://docs.gitlab.com/ce/api/runners.html - -Examples --------- - -Use the ``list()`` and ``all()`` methods to list runners. - -Both methods accept a ``scope`` parameter to filter the list. Allowed values -for this parameter are: - -* ``active`` -* ``paused`` -* ``online`` -* ``specific`` (``all()`` only) -* ``shared`` (``all()`` only) - -.. note:: - - The returned objects hold minimal information about the runners. Use the - ``get()`` method to retrieve detail about a runner. - -:: - - # List owned runners - runners = gl.runners.list() - # With a filter - runners = gl.runners.list(scope='active') - # List all runners, using a filter - runners = gl.runners.all(scope='paused') - -Get a runner's detail:: - - runner = gl.runners.get(runner_id) - -Register a new runner:: - - runner = gl.runners.create({'token': secret_token}) - -Update a runner:: - - runner = gl.runners.get(runner_id) - runner.tag_list.append('new_tag') - runner.save() - -Remove a runner:: - - gl.runners.delete(runner_id) - # or - runner.delete() - -Verify a registered runner token:: - - try: - gl.runners.verify(runner_token) - print("Valid token") - except GitlabVerifyError: - print("Invalid token") - -Project/Group runners -===================== - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectRunner` - + :class:`gitlab.v4.objects.ProjectRunnerManager` - + :attr:`gitlab.v4.objects.Project.runners` - + :class:`gitlab.v4.objects.GroupRunner` - + :class:`gitlab.v4.objects.GroupRunnerManager` - + :attr:`gitlab.v4.objects.Group.runners` - -* GitLab API: https://docs.gitlab.com/ce/api/runners.html - -Examples --------- - -List the runners for a project:: - - runners = project.runners.list() - -Enable a specific runner for a project:: - - p_runner = project.runners.create({'runner_id': runner.id}) - -Disable a specific runner for a project:: - - project.runners.delete(runner.id) - -Runner jobs -=========== - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.RunnerJob` - + :class:`gitlab.v4.objects.RunnerJobManager` - + :attr:`gitlab.v4.objects.Runner.jobs` - -* GitLab API: https://docs.gitlab.com/ce/api/runners.html - -Examples --------- - -List for jobs for a runner:: - - jobs = runner.jobs.list() - -Filter the list using the jobs status:: - - # status can be 'running', 'success', 'failed' or 'canceled' - active_jobs = runner.jobs.list(status='running') diff --git a/docs/gl_objects/search.rst b/docs/gl_objects/search.rst deleted file mode 100644 index eb8ba80..0000000 --- a/docs/gl_objects/search.rst +++ /dev/null @@ -1,77 +0,0 @@ -########## -Search API -########## - -You can search for resources at the top level, in a project or in a group. -Searches are based on a scope (issues, merge requests, and so on) and a search -string. The following constants are provided to represent the possible scopes: - - -* Shared scopes (global, group and project): - - + ``gitlab.SEARCH_SCOPE_PROJECTS``: ``projects`` - + ``gitlab.SEARCH_SCOPE_ISSUES``: ``issues`` - + ``gitlab.SEARCH_SCOPE_MERGE_REQUESTS``: ``merge_requests`` - + ``gitlab.SEARCH_SCOPE_MILESTONES``: ``milestones`` - + ``gitlab.SEARCH_SCOPE_WIKI_BLOBS``: ``wiki_blobs`` - + ``gitlab.SEARCH_SCOPE_COMMITS``: ``commits`` - + ``gitlab.SEARCH_SCOPE_BLOBS``: ``blobs`` - + ``gitlab.SEARCH_SCOPE_USERS``: ``users`` - - -* specific global scope: - - + ``gitlab.SEARCH_SCOPE_GLOBAL_SNIPPET_TITLES``: ``snippet_titles`` - - -* specific project scope: - - + ``gitlab.SEARCH_SCOPE_PROJECT_NOTES``: ``notes`` - - -Reference ---------- - -* v4 API: - - + :attr:`gitlab.Gitlab.search` - + :attr:`gitlab.v4.objects.Group.search` - + :attr:`gitlab.v4.objects.Project.search` - -* GitLab API: https://docs.gitlab.com/ce/api/search.html - -Examples --------- - -Search for issues matching a specific string:: - - # global search - gl.search(gitlab.SEARCH_SCOPE_ISSUES, 'regression') - - # group search - group = gl.groups.get('mygroup') - group.search(gitlab.SEARCH_SCOPE_ISSUES, 'regression') - - # project search - project = gl.projects.get('myproject') - project.search(gitlab.SEARCH_SCOPE_ISSUES, 'regression') - -The ``search()`` methods implement the pagination support:: - - # get lists of 10 items, and start at page 2 - gl.search(gitlab.SEARCH_SCOPE_ISSUES, search_str, page=2, per_page=10) - - # get a generator that will automatically make required API calls for - # pagination - for item in gl.search(gitlab.SEARCH_SCOPE_ISSUES, search_str, as_list=False): - do_something(item) - -The search API doesn't return objects, but dicts. If you need to act on -objects, you need to create them explicitly:: - - for item in gl.search(gitlab.SEARCH_SCOPE_ISSUES, search_str, as_list=False): - issue_project = gl.projects.get(item['project_id'], lazy=True) - issue = issue_project.issues.get(item['iid']) - issue.state = 'closed' - issue.save() - diff --git a/docs/gl_objects/settings.rst b/docs/gl_objects/settings.rst deleted file mode 100644 index 4accfe0..0000000 --- a/docs/gl_objects/settings.rst +++ /dev/null @@ -1,26 +0,0 @@ -######## -Settings -######## - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.ApplicationSettings` - + :class:`gitlab.v4.objects.ApplicationSettingsManager` - + :attr:`gitlab.Gitlab.settings` - -* GitLab API: https://docs.gitlab.com/ce/api/settings.html - -Examples --------- - -Get the settings:: - - settings = gl.settings.get() - -Update the settings:: - - settings.signin_enabled = False - settings.save() diff --git a/docs/gl_objects/sidekiq.rst b/docs/gl_objects/sidekiq.rst deleted file mode 100644 index 5f44762..0000000 --- a/docs/gl_objects/sidekiq.rst +++ /dev/null @@ -1,23 +0,0 @@ -############### -Sidekiq metrics -############### - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.SidekiqManager` - + :attr:`gitlab.Gitlab.sidekiq` - -* GitLab API: https://docs.gitlab.com/ce/api/sidekiq_metrics.html - -Examples --------- - -.. code-block:: python - - gl.sidekiq.queue_metrics() - gl.sidekiq.process_metrics() - gl.sidekiq.job_stats() - gl.sidekiq.compound_metrics() diff --git a/docs/gl_objects/snippets.rst b/docs/gl_objects/snippets.rst deleted file mode 100644 index 1bedb07..0000000 --- a/docs/gl_objects/snippets.rst +++ /dev/null @@ -1,66 +0,0 @@ -######## -Snippets -######## - -Reference -========= - -* v4 API: - - + :class:`gitlab.v4.objects.Snippet` - + :class:`gitlab.v4.objects.SnipptManager` - + :attr:`gitlab.Gitlab.snippets` - -* GitLab API: https://docs.gitlab.com/ce/api/snippets.html - -Examples -======== - -List snippets owned by the current user:: - - snippets = gl.snippets.list() - -List the public snippets:: - - public_snippets = gl.snippets.public() - -Get a snippet:: - - snippet = gl.snippets.get(snippet_id) - # get the content - content = snippet.content() - -.. warning:: - - Blobs are entirely stored in memory unless you use the streaming feature. - See :ref:`the artifacts example <streaming_example>`. - - -Create a snippet:: - - snippet = gl.snippets.create({'title': 'snippet1', - 'file_name': 'snippet1.py', - 'content': open('snippet1.py').read()}) - -Update the snippet attributes:: - - snippet.visibility_level = gitlab.VISIBILITY_PUBLIC - snippet.save() - -To update a snippet code you need to create a ``ProjectSnippet`` object:: - - snippet = gl.snippets.get(snippet_id) - project = gl.projects.get(snippet.projec_id, lazy=True) - editable_snippet = project.snippets.get(snippet.id) - editable_snippet.code = new_snippet_content - editable_snippet.save() - -Delete a snippet:: - - gl.snippets.delete(snippet_id) - # or - snippet.delete() - -Get user agent detail (admin only):: - - detail = snippet.user_agent_detail() diff --git a/docs/gl_objects/system_hooks.rst b/docs/gl_objects/system_hooks.rst deleted file mode 100644 index 6203168..0000000 --- a/docs/gl_objects/system_hooks.rst +++ /dev/null @@ -1,35 +0,0 @@ -############ -System hooks -############ - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.Hook` - + :class:`gitlab.v4.objects.HookManager` - + :attr:`gitlab.Gitlab.hooks` - -* GitLab API: https://docs.gitlab.com/ce/api/system_hooks.html - -Examples --------- - -List the system hooks:: - - hooks = gl.hooks.list() - -Create a system hook:: - - gl.hooks.get(hook_id) - -Test a system hook. The returned object is not usable (it misses the hook ID):: - - hook = gl.hooks.create({'url': 'http://your.target.url'}) - -Delete a system hook:: - - gl.hooks.delete(hook_id) - # or - hook.delete() diff --git a/docs/gl_objects/templates.rst b/docs/gl_objects/templates.rst deleted file mode 100644 index f939e5f..0000000 --- a/docs/gl_objects/templates.rst +++ /dev/null @@ -1,114 +0,0 @@ -######### -Templates -######### - -You can request templates for different type of files: - -* License files -* .gitignore files -* GitLab CI configuration files -* Dockerfiles - -License templates -================= - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.License` - + :class:`gitlab.v4.objects.LicenseManager` - + :attr:`gitlab.Gitlab.licenses` - -* GitLab API: https://docs.gitlab.com/ce/api/templates/licenses.html - -Examples --------- - -List known license templates:: - - licenses = gl.licenses.list() - -Generate a license content for a project:: - - license = gl.licenses.get('apache-2.0', project='foobar', fullname='John Doe') - print(license.content) - -.gitignore templates -==================== - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.Gitignore` - + :class:`gitlab.v4.objects.GitignoreManager` - + :attr:`gitlab.Gitlab.gitignores` - -* GitLab API: https://docs.gitlab.com/ce/api/templates/gitignores.html - -Examples --------- - -List known gitignore templates:: - - gitignores = gl.gitignores.list() - -Get a gitignore template:: - - gitignore = gl.gitignores.get('Python') - print(gitignore.content) - -GitLab CI templates -=================== - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.Gitlabciyml` - + :class:`gitlab.v4.objects.GitlabciymlManager` - + :attr:`gitlab.Gitlab.gitlabciymls` - -* GitLab API: https://docs.gitlab.com/ce/api/templates/gitlab_ci_ymls.html - -Examples --------- - -List known GitLab CI templates:: - - gitlabciymls = gl.gitlabciymls.list() - -Get a GitLab CI template:: - - gitlabciyml = gl.gitlabciymls.get('Pelican') - print(gitlabciyml.content) - -Dockerfile templates -==================== - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.Dockerfile` - + :class:`gitlab.v4.objects.DockerfileManager` - + :attr:`gitlab.Gitlab.gitlabciymls` - -* GitLab API: Not documented. - -Examples --------- - -List known Dockerfile templates:: - - dockerfiles = gl.dockerfiles.list() - -Get a Dockerfile template:: - - dockerfile = gl.dockerfiles.get('Python') - print(dockerfile.content) diff --git a/docs/gl_objects/todos.rst b/docs/gl_objects/todos.rst deleted file mode 100644 index 24a14c2..0000000 --- a/docs/gl_objects/todos.rst +++ /dev/null @@ -1,44 +0,0 @@ -##### -Todos -##### - -Reference ---------- - -* v4 API: - - + :class:`~gitlab.objects.Todo` - + :class:`~gitlab.objects.TodoManager` - + :attr:`gitlab.Gitlab.todos` - -* GitLab API: https://docs.gitlab.com/ce/api/todos.html - -Examples --------- - -List active todos:: - - todos = gl.todos.list() - -You can filter the list using the following parameters: - -* ``action``: can be ``assigned``, ``mentioned``, ``build_failed``, ``marked``, - or ``approval_required`` -* ``author_id`` -* ``project_id`` -* ``state``: can be ``pending`` or ``done`` -* ``type``: can be ``Issue`` or ``MergeRequest`` - -For example:: - - todos = gl.todos.list(project_id=1) - todos = gl.todos.list(state='done', type='Issue') - -Mark a todo as done:: - - todos = gl.todos.list(project_id=1) - todos[0].mark_as_done() - -Mark all the todos as done:: - - gl.todos.mark_all_as_done() diff --git a/docs/gl_objects/users.rst b/docs/gl_objects/users.rst deleted file mode 100644 index dd6db6a..0000000 --- a/docs/gl_objects/users.rst +++ /dev/null @@ -1,404 +0,0 @@ -###################### -Users and current user -###################### - -The Gitlab API exposes user-related method that can be manipulated by admins -only. - -The currently logged-in user is also exposed. - -Users -===== - -References ----------- - -* v4 API: - - + :class:`gitlab.v4.objects.User` - + :class:`gitlab.v4.objects.UserManager` - + :attr:`gitlab.Gitlab.users` - -* GitLab API: https://docs.gitlab.com/ce/api/users.html - -Examples --------- - -Get the list of users:: - - users = gl.users.list() - -Search users whose username match a given string:: - - users = gl.users.list(search='foo') - -Get a single user:: - - # by ID - user = gl.users.get(user_id) - # by username - user = gl.users.list(username='root')[0] - -Create a user:: - - user = gl.users.create({'email': 'john@doe.com', - 'password': 's3cur3s3cr3T', - 'username': 'jdoe', - 'name': 'John Doe'}) - -Update a user:: - - user.name = 'Real Name' - user.save() - -Delete a user:: - - gl.users.delete(user_id) - # or - user.delete() - -Block/Unblock a user:: - - user.block() - user.unblock() - -Activate/Deactivate a user:: - - user.activate() - user.deactivate() - -Follow/Unfollow a user:: - - user.follow() - user.unfollow() - -Set the avatar image for a user:: - - # the avatar image can be passed as data (content of the file) or as a file - # object opened in binary mode - user.avatar = open('path/to/file.png', 'rb') - user.save() - -Set an external identity for a user:: - - user.provider = 'oauth2_generic' - user.extern_uid = '3' - user.save() - -Delete an external identity by provider name:: - - user.identityproviders.delete('oauth2_generic') - -Get the followers of a user - - user.followers_users.list() - -Get the followings of a user - - user.following_users.list() - - -User custom attributes -====================== - -References ----------- - -* v4 API: - - + :class:`gitlab.v4.objects.UserCustomAttribute` - + :class:`gitlab.v4.objects.UserCustomAttributeManager` - + :attr:`gitlab.v4.objects.User.customattributes` - -* GitLab API: https://docs.gitlab.com/ce/api/custom_attributes.html - -Examples --------- - -List custom attributes for a user:: - - attrs = user.customattributes.list() - -Get a custom attribute for a user:: - - attr = user.customattributes.get(attr_key) - -Set (create or update) a custom attribute for a user:: - - attr = user.customattributes.set(attr_key, attr_value) - -Delete a custom attribute for a user:: - - attr.delete() - # or - user.customattributes.delete(attr_key) - -Search users by custom attribute:: - - user.customattributes.set('role', 'QA') - gl.users.list(custom_attributes={'role': 'QA'}) - -User impersonation tokens -========================= - -References ----------- - -* v4 API: - - + :class:`gitlab.v4.objects.UserImpersonationToken` - + :class:`gitlab.v4.objects.UserImpersonationTokenManager` - + :attr:`gitlab.v4.objects.User.impersonationtokens` - -* GitLab API: https://docs.gitlab.com/ce/api/users.html#get-all-impersonation-tokens-of-a-user - -List impersonation tokens for a user:: - - i_t = user.impersonationtokens.list(state='active') - i_t = user.impersonationtokens.list(state='inactive') - -Get an impersonation token for a user:: - - i_t = user.impersonationtokens.get(i_t_id) - -Create and use an impersonation token for a user:: - - i_t = user.impersonationtokens.create({'name': 'token1', 'scopes': ['api']}) - # use the token to create a new gitlab connection - user_gl = gitlab.Gitlab(gitlab_url, private_token=i_t.token) - -Revoke (delete) an impersonation token for a user:: - - i_t.delete() - - -User memberships -========================= - -References ----------- - -* v4 API: - - + :class:`gitlab.v4.objects.UserMembership` - + :class:`gitlab.v4.objects.UserMembershipManager` - + :attr:`gitlab.v4.objects.User.memberships` - -* GitLab API: https://docs.gitlab.com/ee/api/users.html#user-memberships-admin-only - -List direct memberships for a user:: - - memberships = user.memberships.list() - -List only direct project memberships:: - - memberships = user.memberships.list(type='Project') - -List only direct group memberships:: - - memberships = user.memberships.list(type='Namespace') - -Current User -============ - -References ----------- - -* v4 API: - - + :class:`gitlab.v4.objects.CurrentUser` - + :class:`gitlab.v4.objects.CurrentUserManager` - + :attr:`gitlab.Gitlab.user` - -* GitLab API: https://docs.gitlab.com/ce/api/users.html - -Examples --------- - -Get the current user:: - - gl.auth() - current_user = gl.user - -GPG keys -======== - -References ----------- - -You can manipulate GPG keys for the current user and for the other users if you -are admin. - -* v4 API: - - + :class:`gitlab.v4.objects.CurrentUserGPGKey` - + :class:`gitlab.v4.objects.CurrentUserGPGKeyManager` - + :attr:`gitlab.v4.objects.CurrentUser.gpgkeys` - + :class:`gitlab.v4.objects.UserGPGKey` - + :class:`gitlab.v4.objects.UserGPGKeyManager` - + :attr:`gitlab.v4.objects.User.gpgkeys` - -* GitLab API: https://docs.gitlab.com/ce/api/users.html#list-all-gpg-keys - -Examples --------- - -List GPG keys for a user:: - - gpgkeys = user.gpgkeys.list() - -Get a GPG gpgkey for a user:: - - gpgkey = user.gpgkeys.get(key_id) - -Create a GPG gpgkey for a user:: - - # get the key with `gpg --export -a GPG_KEY_ID` - k = user.gpgkeys.create({'key': public_key_content}) - -Delete a GPG gpgkey for a user:: - - user.gpgkeys.delete(key_id) - # or - gpgkey.delete() - -SSH keys -======== - -References ----------- - -You can manipulate SSH keys for the current user and for the other users if you -are admin. - -* v4 API: - - + :class:`gitlab.v4.objects.CurrentUserKey` - + :class:`gitlab.v4.objects.CurrentUserKeyManager` - + :attr:`gitlab.v4.objects.CurrentUser.keys` - + :class:`gitlab.v4.objects.UserKey` - + :class:`gitlab.v4.objects.UserKeyManager` - + :attr:`gitlab.v4.objects.User.keys` - -* GitLab API: https://docs.gitlab.com/ce/api/users.html#list-ssh-keys - -Examples --------- - -List SSH keys for a user:: - - keys = user.keys.list() - -Create an SSH key for a user:: - - k = user.keys.create({'title': 'my_key', - 'key': open('/home/me/.ssh/id_rsa.pub').read()}) - -Delete an SSH key for a user:: - - user.keys.delete(key_id) - # or - key.delete() - -Status -====== - -References ----------- - -You can manipulate the status for the current user and you can read the status of other users. - -* v4 API: - - + :class:`gitlab.v4.objects.CurrentUserStatus` - + :class:`gitlab.v4.objects.CurrentUserStatusManager` - + :attr:`gitlab.v4.objects.CurrentUser.status` - + :class:`gitlab.v4.objects.UserStatus` - + :class:`gitlab.v4.objects.UserStatusManager` - + :attr:`gitlab.v4.objects.User.status` - -* GitLab API: https://docs.gitlab.com/ce/api/users.html#user-status - -Examples --------- - -Get current user status:: - - status = user.status.get() - -Update the status for the current user:: - - status = user.status.get() - status.message = "message" - status.emoji = "thumbsup" - status.save() - -Get the status of other users:: - - gl.users.get(1).status.get() - -Emails -====== - -References ----------- - -You can manipulate emails for the current user and for the other users if you -are admin. - -* v4 API: - - + :class:`gitlab.v4.objects.CurrentUserEmail` - + :class:`gitlab.v4.objects.CurrentUserEmailManager` - + :attr:`gitlab.v4.objects.CurrentUser.emails` - + :class:`gitlab.v4.objects.UserEmail` - + :class:`gitlab.v4.objects.UserEmailManager` - + :attr:`gitlab.v4.objects.User.emails` - -* GitLab API: https://docs.gitlab.com/ce/api/users.html#list-emails - -Examples --------- - -List emails for a user:: - - emails = user.emails.list() - -Get an email for a user:: - - email = user.emails.get(email_id) - -Create an email for a user:: - - k = user.emails.create({'email': 'foo@bar.com'}) - -Delete an email for a user:: - - user.emails.delete(email_id) - # or - email.delete() - -Users activities -================ - -References ----------- - -* admin only - -* v4 API: - - + :class:`gitlab.v4.objects.UserActivities` - + :class:`gitlab.v4.objects.UserActivitiesManager` - + :attr:`gitlab.Gitlab.user_activities` - -* GitLab API: https://docs.gitlab.com/ce/api/users.html#get-user-activities-admin-only - -Examples --------- - -Get the users activities:: - - activities = gl.user_activities.list( - query_parameters={'from': '2018-07-01'}, - all=True, as_list=False) diff --git a/docs/gl_objects/variables.rst b/docs/gl_objects/variables.rst deleted file mode 100644 index f679925..0000000 --- a/docs/gl_objects/variables.rst +++ /dev/null @@ -1,104 +0,0 @@ -############### -CI/CD Variables -############### - -You can configure variables at the instance-level (admin only), or associate -variables to projects and groups, to modify pipeline/job scripts behavior. - - -Instance-level variables -======================== - -This endpoint requires admin access. - -Reference ---------- - -* v4 API - - + :class:`gitlab.v4.objects.Variable` - + :class:`gitlab.v4.objects.VariableManager` - + :attr:`gitlab.Gitlab.variables` - -* GitLab API - - + https://docs.gitlab.com/ce/api/instance_level_ci_variables.html - -Examples --------- - -List all instance variables:: - - variables = gl.variables.list() - -Get an instance variable by key:: - - variable = gl.variables.get('key_name') - -Create an instance variable:: - - variable = gl.variables.create({'key': 'key1', 'value': 'value1'}) - -Update a variable value:: - - variable.value = 'new_value' - variable.save() - -Remove a variable:: - - gl.variables.delete('key_name') - # or - variable.delete() - -Projects and groups variables -============================= - -Reference ---------- - -* v4 API - - + :class:`gitlab.v4.objects.ProjectVariable` - + :class:`gitlab.v4.objects.ProjectVariableManager` - + :attr:`gitlab.v4.objects.Project.variables` - + :class:`gitlab.v4.objects.GroupVariable` - + :class:`gitlab.v4.objects.GroupVariableManager` - + :attr:`gitlab.v4.objects.Group.variables` - -* GitLab API - - + https://docs.gitlab.com/ce/api/instance_level_ci_variables.html - + https://docs.gitlab.com/ce/api/project_level_variables.html - + https://docs.gitlab.com/ce/api/group_level_variables.html - -Examples --------- - -List variables:: - - p_variables = project.variables.list() - g_variables = group.variables.list() - -Get a variable:: - - p_var = project.variables.get('key_name') - g_var = group.variables.get('key_name') - -Create a variable:: - - var = project.variables.create({'key': 'key1', 'value': 'value1'}) - var = group.variables.create({'key': 'key1', 'value': 'value1'}) - -Update a variable value:: - - var.value = 'new_value' - var.save() - # or - project.variables.update("key1", {"value": "new_value"}) - -Remove a variable:: - - project.variables.delete('key_name') - group.variables.delete('key_name') - # or - var.delete() diff --git a/docs/gl_objects/wikis.rst b/docs/gl_objects/wikis.rst deleted file mode 100644 index e98b9d4..0000000 --- a/docs/gl_objects/wikis.rst +++ /dev/null @@ -1,56 +0,0 @@ -########## -Wiki pages -########## - - -References -========== - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectWiki` - + :class:`gitlab.v4.objects.ProjectWikiManager` - + :attr:`gitlab.v4.objects.Project.wikis` - + :class:`gitlab.v4.objects.GroupWiki` - + :class:`gitlab.v4.objects.GroupWikiManager` - + :attr:`gitlab.v4.objects.Group.wikis` - -* GitLab API for Projects: https://docs.gitlab.com/ce/api/wikis.html -* GitLab API for Groups: https://docs.gitlab.com/ee/api/group_wikis.html - -Examples --------- - -Get the list of wiki pages for a project. These do not contain the contents of the wiki page. You will need to call get(slug) to retrieve the content by accessing the content attribute:: - - pages = project.wikis.list() - -Get the list of wiki pages for a group. These do not contain the contents of the wiki page. You will need to call get(slug) to retrieve the content by accessing the content attribute:: - - pages = group.wikis.list() - -Get a single wiki page for a project:: - - page = project.wikis.get(page_slug) - -Get a single wiki page for a group:: - - page = group.wikis.get(page_slug) - -Get the contents of a wiki page:: - - print(page.content) - -Create a wiki page on a project level:: - - page = project.wikis.create({'title': 'Wiki Page 1', - 'content': open(a_file).read()}) - -Update a wiki page:: - - page.content = 'My new content' - page.save() - -Delete a wiki page:: - - page.delete() diff --git a/docs/index.rst b/docs/index.rst deleted file mode 100644 index 3f8672b..0000000 --- a/docs/index.rst +++ /dev/null @@ -1,30 +0,0 @@ -.. python-gitlab documentation master file, created by - sphinx-quickstart on Mon Dec 8 15:17:39 2014. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - -Welcome to python-gitlab's documentation! -========================================= - -Contents: - -.. toctree:: - :maxdepth: 2 - - install - cli-usage - api-usage - faq - api-objects - api/gitlab - cli-objects - changelog - release-notes - - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` diff --git a/docs/install.rst b/docs/install.rst deleted file mode 100644 index acd2528..0000000 --- a/docs/install.rst +++ /dev/null @@ -1,26 +0,0 @@ -############ -Installation -############ - -``python-gitlab`` is compatible with Python 3.6+. - -Use :command:`pip` to install the latest stable version of ``python-gitlab``: - -.. code-block:: console - - $ pip install --upgrade python-gitlab - -The current development version is available on both `GitHub.com -<https://github.com/python-gitlab/python-gitlab>`__ and `GitLab.com -<https://gitlab.com/python-gitlab/python-gitlab>`__, and can be -installed directly from the git repository: - -.. code-block:: console - - $ pip install git+https://github.com/python-gitlab/python-gitlab.git - -From GitLab: - -.. code-block:: console - - $ pip install git+https://gitlab.com/python-gitlab/python-gitlab.git diff --git a/docs/make.bat b/docs/make.bat deleted file mode 100644 index 7c29850..0000000 --- a/docs/make.bat +++ /dev/null @@ -1,242 +0,0 @@ -@ECHO OFF
-
-REM Command file for Sphinx documentation
-
-if "%SPHINXBUILD%" == "" (
- set SPHINXBUILD=sphinx-build
-)
-set BUILDDIR=_build
-set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% .
-set I18NSPHINXOPTS=%SPHINXOPTS% .
-if NOT "%PAPER%" == "" (
- set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%
- set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS%
-)
-
-if "%1" == "" goto help
-
-if "%1" == "help" (
- :help
- echo.Please use `make ^<target^>` where ^<target^> is one of
- echo. html to make standalone HTML files
- echo. dirhtml to make HTML files named index.html in directories
- echo. singlehtml to make a single large HTML file
- echo. pickle to make pickle files
- echo. json to make JSON files
- echo. htmlhelp to make HTML files and a HTML help project
- echo. qthelp to make HTML files and a qthelp project
- echo. devhelp to make HTML files and a Devhelp project
- echo. epub to make an epub
- echo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter
- echo. text to make text files
- echo. man to make manual pages
- echo. texinfo to make Texinfo files
- echo. gettext to make PO message catalogs
- echo. changes to make an overview over all changed/added/deprecated items
- echo. xml to make Docutils-native XML files
- echo. pseudoxml to make pseudoxml-XML files for display purposes
- echo. linkcheck to check all external links for integrity
- echo. doctest to run all doctests embedded in the documentation if enabled
- goto end
-)
-
-if "%1" == "clean" (
- for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i
- del /q /s %BUILDDIR%\*
- goto end
-)
-
-
-%SPHINXBUILD% 2> nul
-if errorlevel 9009 (
- echo.
- echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
- echo.installed, then set the SPHINXBUILD environment variable to point
- echo.to the full path of the 'sphinx-build' executable. Alternatively you
- echo.may add the Sphinx directory to PATH.
- echo.
- echo.If you don't have Sphinx installed, grab it from
- echo.http://sphinx-doc.org/
- exit /b 1
-)
-
-if "%1" == "html" (
- %SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html
- if errorlevel 1 exit /b 1
- echo.
- echo.Build finished. The HTML pages are in %BUILDDIR%/html.
- goto end
-)
-
-if "%1" == "dirhtml" (
- %SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml
- if errorlevel 1 exit /b 1
- echo.
- echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml.
- goto end
-)
-
-if "%1" == "singlehtml" (
- %SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml
- if errorlevel 1 exit /b 1
- echo.
- echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml.
- goto end
-)
-
-if "%1" == "pickle" (
- %SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle
- if errorlevel 1 exit /b 1
- echo.
- echo.Build finished; now you can process the pickle files.
- goto end
-)
-
-if "%1" == "json" (
- %SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json
- if errorlevel 1 exit /b 1
- echo.
- echo.Build finished; now you can process the JSON files.
- goto end
-)
-
-if "%1" == "htmlhelp" (
- %SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp
- if errorlevel 1 exit /b 1
- echo.
- echo.Build finished; now you can run HTML Help Workshop with the ^
-.hhp project file in %BUILDDIR%/htmlhelp.
- goto end
-)
-
-if "%1" == "qthelp" (
- %SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp
- if errorlevel 1 exit /b 1
- echo.
- echo.Build finished; now you can run "qcollectiongenerator" with the ^
-.qhcp project file in %BUILDDIR%/qthelp, like this:
- echo.^> qcollectiongenerator %BUILDDIR%\qthelp\python-gitlab.qhcp
- echo.To view the help file:
- echo.^> assistant -collectionFile %BUILDDIR%\qthelp\python-gitlab.ghc
- goto end
-)
-
-if "%1" == "devhelp" (
- %SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp
- if errorlevel 1 exit /b 1
- echo.
- echo.Build finished.
- goto end
-)
-
-if "%1" == "epub" (
- %SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub
- if errorlevel 1 exit /b 1
- echo.
- echo.Build finished. The epub file is in %BUILDDIR%/epub.
- goto end
-)
-
-if "%1" == "latex" (
- %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
- if errorlevel 1 exit /b 1
- echo.
- echo.Build finished; the LaTeX files are in %BUILDDIR%/latex.
- goto end
-)
-
-if "%1" == "latexpdf" (
- %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
- cd %BUILDDIR%/latex
- make all-pdf
- cd %BUILDDIR%/..
- echo.
- echo.Build finished; the PDF files are in %BUILDDIR%/latex.
- goto end
-)
-
-if "%1" == "latexpdfja" (
- %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
- cd %BUILDDIR%/latex
- make all-pdf-ja
- cd %BUILDDIR%/..
- echo.
- echo.Build finished; the PDF files are in %BUILDDIR%/latex.
- goto end
-)
-
-if "%1" == "text" (
- %SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text
- if errorlevel 1 exit /b 1
- echo.
- echo.Build finished. The text files are in %BUILDDIR%/text.
- goto end
-)
-
-if "%1" == "man" (
- %SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man
- if errorlevel 1 exit /b 1
- echo.
- echo.Build finished. The manual pages are in %BUILDDIR%/man.
- goto end
-)
-
-if "%1" == "texinfo" (
- %SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo
- if errorlevel 1 exit /b 1
- echo.
- echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo.
- goto end
-)
-
-if "%1" == "gettext" (
- %SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale
- if errorlevel 1 exit /b 1
- echo.
- echo.Build finished. The message catalogs are in %BUILDDIR%/locale.
- goto end
-)
-
-if "%1" == "changes" (
- %SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes
- if errorlevel 1 exit /b 1
- echo.
- echo.The overview file is in %BUILDDIR%/changes.
- goto end
-)
-
-if "%1" == "linkcheck" (
- %SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck
- if errorlevel 1 exit /b 1
- echo.
- echo.Link check complete; look for any errors in the above output ^
-or in %BUILDDIR%/linkcheck/output.txt.
- goto end
-)
-
-if "%1" == "doctest" (
- %SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest
- if errorlevel 1 exit /b 1
- echo.
- echo.Testing of doctests in the sources finished, look at the ^
-results in %BUILDDIR%/doctest/output.txt.
- goto end
-)
-
-if "%1" == "xml" (
- %SPHINXBUILD% -b xml %ALLSPHINXOPTS% %BUILDDIR%/xml
- if errorlevel 1 exit /b 1
- echo.
- echo.Build finished. The XML files are in %BUILDDIR%/xml.
- goto end
-)
-
-if "%1" == "pseudoxml" (
- %SPHINXBUILD% -b pseudoxml %ALLSPHINXOPTS% %BUILDDIR%/pseudoxml
- if errorlevel 1 exit /b 1
- echo.
- echo.Build finished. The pseudo-XML files are in %BUILDDIR%/pseudoxml.
- goto end
-)
-
-:end
diff --git a/docs/release-notes.rst b/docs/release-notes.rst deleted file mode 100644 index 927d2c4..0000000 --- a/docs/release-notes.rst +++ /dev/null @@ -1,221 +0,0 @@ -############# -Release notes -############# - -Prior to version 2.0.0 and GitHub Releases, a summary of changes was maintained -in release notes. They are available below for historical purposes. -For the list of current releases, including breaking changes, please see the changelog. - -Changes from 1.8 to 1.9 -======================= - -* ``ProjectMemberManager.all()`` and ``GroupMemberManager.all()`` now return a - list of ``ProjectMember`` and ``GroupMember`` objects respectively, instead - of a list of dicts. - -Changes from 1.7 to 1.8 -======================= - -* You can now use the ``query_parameters`` argument in method calls to define - arguments to send to the GitLab server. This allows to avoid conflicts - between python-gitlab and GitLab server variables, and allows to use the - python reserved keywords as GitLab arguments. - - The following examples make the same GitLab request with the 2 syntaxes:: - - projects = gl.projects.list(owned=True, starred=True) - projects = gl.projects.list(query_parameters={'owned': True, 'starred': True}) - - The following example only works with the new parameter:: - - activities = gl.user_activities.list( - query_parameters={'from': '2019-01-01'}, - all=True) - -* Additionally the ``all`` paremeter is not sent to the GitLab anymore. - -Changes from 1.5 to 1.6 -======================= - -* When python-gitlab detects HTTP redirections from http to https it will raise - a RedirectionError instead of a cryptic error. - - Make sure to use an ``https://`` protocol in your GitLab URL parameter if the - server requires it. - -Changes from 1.4 to 1.5 -======================= - -* APIv3 support has been removed. Use the 1.4 release/branch if you need v3 - support. -* GitLab EE features are now supported: Geo nodes, issue links, LDAP groups, - project/group boards, project mirror pulling, project push rules, EE license - configuration, epics. -* The ``GetFromListMixin`` class has been removed. The ``get()`` method is not - available anymore for the following managers: - - - UserKeyManager - - DeployKeyManager - - GroupAccessRequestManager - - GroupIssueManager - - GroupProjectManager - - GroupSubgroupManager - - IssueManager - - ProjectCommitStatusManager - - ProjectEnvironmentManager - - ProjectLabelManager - - ProjectPipelineJobManager - - ProjectAccessRequestManager - - TodoManager - -* ``ProjectPipelineJob`` do not heritate from ``ProjectJob`` anymore and thus - can only be listed. - -Changes from 1.3 to 1.4 -======================= - -* 1.4 is the last release supporting the v3 API, and the related code will be - removed in the 1.5 version. - - If you are using a Gitlab server version that does not support the v4 API you - can: - - * upgrade the server (recommended) - * make sure to use version 1.4 of python-gitlab (``pip install - python-gitlab==1.4``) - - See also the `Switching to GitLab API v4 documentation - <http://python-gitlab.readthedocs.io/en/master/switching-to-v4.html>`__. -* python-gitlab now handles the server rate limiting feature. It will pause for - the required time when reaching the limit (`documentation - <http://python-gitlab.readthedocs.io/en/master/api-usage.html#rate-limits>`__) -* The ``GetFromListMixin.get()`` method is deprecated and will be removed in - the next python-gitlab version. The goal of this mixin/method is to provide a - way to get an object by looping through a list for GitLab objects that don't - support the GET method. The method `is broken - <https://github.com/python-gitlab/python-gitlab/issues/499>`__ and conflicts - with the GET method now supported by some GitLab objects. - - You can implement your own method with something like: - - .. code-block:: python - - def get_from_list(self, id): - for obj in self.list(as_list=False): - if obj.get_id() == id: - return obj - -* The ``GroupMemberManager``, ``NamespaceManager`` and ``ProjectBoardManager`` - managers now use the GET API from GitLab instead of the - ``GetFromListMixin.get()`` method. - - -Changes from 1.2 to 1.3 -======================= - -* ``gitlab.Gitlab`` objects can be used as context managers in a ``with`` - block. - -Changes from 1.1 to 1.2 -======================= - -* python-gitlab now respects the ``*_proxy``, ``REQUESTS_CA_BUNDLE`` and - ``CURL_CA_BUNDLE`` environment variables (#352) -* The following deprecated methods and objects have been removed: - - * gitlab.v3.object ``Key`` and ``KeyManager`` objects: use ``DeployKey`` and - ``DeployKeyManager`` instead - * gitlab.v3.objects.Project ``archive_`` and ``unarchive_`` methods - * gitlab.Gitlab ``credentials_auth``, ``token_auth``, ``set_url``, - ``set_token`` and ``set_credentials`` methods. Once a Gitlab object has been - created its URL and authentication information cannot be updated: create a - new Gitlab object if you need to use new information -* The ``todo()`` method raises a ``GitlabTodoError`` exception on error - -Changes from 1.0.2 to 1.1 -========================= - -* The ``ProjectUser`` class doesn't inherit from ``User`` anymore, and the - ``GroupProject`` class doesn't inherit from ``Project`` anymore. The Gitlab - API doesn't provide the same set of features for these objects, so - python-gitlab objects shouldn't try to workaround that. - - You can create ``User`` or ``Project`` objects from ``ProjectUser`` and - ``GroupProject`` objects using the ``id`` attribute: - - .. code-block:: python - - for gr_project in group.projects.list(): - # lazy object creation avoids a Gitlab API request - project = gl.projects.get(gr_project.id, lazy=True) - project.default_branch = 'develop' - project.save() - -Changes from 0.21 to 1.0.0 -========================== - -1.0.0 brings a stable python-gitlab API for the v4 Gitlab API. v3 is still used -by default. - -v4 is mostly compatible with the v3, but some important changes have been -introduced. Make sure to read `Switching to GitLab API v4 -<http://python-gitlab.readthedocs.io/en/master/switching-to-v4.html>`_. - -The development focus will be v4 from now on. v3 has been deprecated by GitLab -and will disappear from python-gitlab at some point. - -Changes from 0.20 to 0.21 -========================= - -* Initial support for the v4 API (experimental) - - The support for v4 is stable enough to be tested, but some features might be - broken. Please report issues to - https://github.com/python-gitlab/python-gitlab/issues/ - - Be aware that the python-gitlab API for v4 objects might change in the next - releases. - - .. warning:: - - Consider defining explicitly which API version you want to use in the - configuration files or in your ``gitlab.Gitlab`` instances. The default - will change from v3 to v4 soon. - -* Several methods have been deprecated in the ``gitlab.Gitlab`` class: - - + ``credentials_auth()`` is deprecated and will be removed. Call ``auth()``. - + ``token_auth()`` is deprecated and will be removed. Call ``auth()``. - + ``set_url()`` is deprecated, create a new ``Gitlab`` instance if you need - an updated URL. - + ``set_token()`` is deprecated, use the ``private_token`` argument of the - ``Gitlab`` constructor. - + ``set_credentials()`` is deprecated, use the ``email`` and ``password`` - arguments of the ``Gitlab`` constructor. - -* The service listing method (``ProjectServiceManager.list()``) now returns a - python list instead of a JSON string. - -Changes from 0.19 to 0.20 -========================= - -* The ``projects`` attribute of ``Group`` objects is not a list of ``Project`` - objects anymore. It is a Manager object giving access to ``GroupProject`` - objects. To get the list of projects use: - - .. code-block:: python - - group.projects.list() - - Documentation: - http://python-gitlab.readthedocs.io/en/stable/gl_objects/groups.html#examples - - Related issue: https://github.com/python-gitlab/python-gitlab/issues/209 - -* The ``Key`` objects are deprecated in favor of the new ``DeployKey`` objects. - They are exactly the same but the name makes more sense. - - Documentation: - http://python-gitlab.readthedocs.io/en/stable/gl_objects/deploy_keys.html - - Related issue: https://github.com/python-gitlab/python-gitlab/issues/212 |