diff options
Diffstat (limited to 'docs/gl_objects')
49 files changed, 697 insertions, 2319 deletions
diff --git a/docs/gl_objects/access_requests.py b/docs/gl_objects/access_requests.py deleted file mode 100644 index 9df639d..0000000 --- a/docs/gl_objects/access_requests.py +++ /dev/null @@ -1,26 +0,0 @@ -# list -p_ars = project.accessrequests.list() -g_ars = group.accessrequests.list() -# end list - -# get -p_ar = project.accessrequests.get(user_id) -g_ar = group.accessrequests.get(user_id) -# end get - -# create -p_ar = project.accessrequests.create({}) -g_ar = group.accessrequests.create({}) -# end create - -# approve -ar.approve() # defaults to DEVELOPER level -ar.approve(access_level=gitlab.MASTER_ACCESS) # explicitly set access level -# end approve - -# delete -project.accessrequests.delete(user_id) -group.accessrequests.delete(user_id) -# or -ar.delete() -# end delete diff --git a/docs/gl_objects/access_requests.rst b/docs/gl_objects/access_requests.rst index f64e795..9a147c1 100644 --- a/docs/gl_objects/access_requests.rst +++ b/docs/gl_objects/access_requests.rst @@ -25,48 +25,29 @@ References + :class:`gitlab.v4.objects.GroupAccessRequestManager` + :attr:`gitlab.v4.objects.Group.accessrequests` -* v3 API: - - + :class:`gitlab.v3.objects.ProjectAccessRequest` - + :class:`gitlab.v3.objects.ProjectAccessRequestManager` - + :attr:`gitlab.v3.objects.Project.accessrequests` - + :attr:`gitlab.Gitlab.project_accessrequests` - + :class:`gitlab.v3.objects.GroupAccessRequest` - + :class:`gitlab.v3.objects.GroupAccessRequestManager` - + :attr:`gitlab.v3.objects.Group.accessrequests` - + :attr:`gitlab.Gitlab.group_accessrequests` - * GitLab API: https://docs.gitlab.com/ce/api/access_requests.html Examples -------- -List access requests from projects and groups: - -.. literalinclude:: access_requests.py - :start-after: # list - :end-before: # end list - -Get a single request: +List access requests from projects and groups:: -.. literalinclude:: access_requests.py - :start-after: # get - :end-before: # end get + p_ars = project.accessrequests.list() + g_ars = group.accessrequests.list() -Create an access request: +Create an access request:: -.. literalinclude:: access_requests.py - :start-after: # create - :end-before: # end create + p_ar = project.accessrequests.create({}) + g_ar = group.accessrequests.create({}) -Approve an access request: +Approve an access request:: -.. literalinclude:: access_requests.py - :start-after: # approve - :end-before: # end approve + ar.approve() # defaults to DEVELOPER level + ar.approve(access_level=gitlab.MASTER_ACCESS) # explicitly set access level -Deny (delete) an access request: +Deny (delete) an access request:: -.. literalinclude:: access_requests.py - :start-after: # delete - :end-before: # end delete + project.accessrequests.delete(user_id) + group.accessrequests.delete(user_id) + # or + ar.delete() diff --git a/docs/gl_objects/branches.py b/docs/gl_objects/branches.py deleted file mode 100644 index 431e09d..0000000 --- a/docs/gl_objects/branches.py +++ /dev/null @@ -1,46 +0,0 @@ -# list -branches = project.branches.list() -# end list - -# get -branch = project.branches.get('master') -# end get - -# create -# v4 -branch = project.branches.create({'branch': 'feature1', - 'ref': 'master'}) - -#v3 -branch = project.branches.create({'branch_name': 'feature1', - 'ref': 'master'}) -# end create - -# delete -project.branches.delete('feature1') -# or -branch.delete() -# end delete - -# protect -branch.protect() -branch.unprotect() -# end protect - -# p_branch list -p_branches = project.protectedbranches.list() -# end p_branch list - -# p_branch get -p_branch = project.protectedbranches.get('master') -# end p_branch get - -# p_branch create -p_branch = project.protectedbranches.create({'name': '*-stable'}) -# end p_branch create - -# p_branch delete -project.protectedbranches.delete('*-stable') -# or -p_branch.delete() -# end p_branch delete diff --git a/docs/gl_objects/branches.rst b/docs/gl_objects/branches.rst index 279ca0c..15f2b5c 100644 --- a/docs/gl_objects/branches.rst +++ b/docs/gl_objects/branches.rst @@ -11,46 +11,34 @@ References + :class:`gitlab.v4.objects.ProjectBranchManager` + :attr:`gitlab.v4.objects.Project.branches` -* v3 API: - - + :class:`gitlab.v3.objects.ProjectBranch` - + :class:`gitlab.v3.objects.ProjectBranchManager` - + :attr:`gitlab.v3.objects.Project.branches` - * GitLab API: https://docs.gitlab.com/ce/api/branches.html Examples -------- -Get the list of branches for a repository: +Get the list of branches for a repository:: -.. literalinclude:: branches.py - :start-after: # list - :end-before: # end list + branches = project.branches.list() -Get a single repository branch: +Get a single repository branch:: -.. literalinclude:: branches.py - :start-after: # get - :end-before: # end get + branch = project.branches.get('master') -Create a repository branch: +Create a repository branch:: -.. literalinclude:: branches.py - :start-after: # create - :end-before: # end create + branch = project.branches.create({'branch': 'feature1', + 'ref': 'master'}) -Delete a repository branch: +Delete a repository branch:: -.. literalinclude:: branches.py - :start-after: # delete - :end-before: # end delete + project.branches.delete('feature1') + # or + branch.delete() -Protect/unprotect a repository branch: +Protect/unprotect a repository branch:: -.. literalinclude:: branches.py - :start-after: # protect - :end-before: # end protect + branch.protect() + branch.unprotect() .. note:: diff --git a/docs/gl_objects/builds.rst b/docs/gl_objects/builds.rst index d5f851c..089aab7 100644 --- a/docs/gl_objects/builds.rst +++ b/docs/gl_objects/builds.rst @@ -1,9 +1,6 @@ -########################## -Pipelines, Builds and Jobs -########################## - -Build and job are two classes representing the same object. Builds are used in -v3 API, jobs in v4 API. +################## +Pipelines and Jobs +################## Project pipelines ================= @@ -19,13 +16,6 @@ Reference + :class:`gitlab.v4.objects.ProjectPipelineManager` + :attr:`gitlab.v4.objects.Project.pipelines` -* v3 API: - - + :class:`gitlab.v3.objects.ProjectPipeline` - + :class:`gitlab.v3.objects.ProjectPipelineManager` - + :attr:`gitlab.v3.objects.Project.pipelines` - + :attr:`gitlab.Gitlab.project_pipelines` - * GitLab API: https://docs.gitlab.com/ce/api/pipelines.html Examples @@ -66,13 +56,6 @@ Reference + :class:`gitlab.v4.objects.ProjectTriggerManager` + :attr:`gitlab.v4.objects.Project.triggers` -* v3 API: - - + :class:`gitlab.v3.objects.ProjectTrigger` - + :class:`gitlab.v3.objects.ProjectTriggerManager` - + :attr:`gitlab.v3.objects.Project.triggers` - + :attr:`gitlab.Gitlab.project_triggers` - * GitLab API: https://docs.gitlab.com/ce/api/pipeline_triggers.html Examples @@ -88,8 +71,7 @@ Get a trigger:: Create a trigger:: - trigger = project.triggers.create({}) # v3 - trigger = project.triggers.create({'description': 'mytrigger'}) # v4 + trigger = project.triggers.create({'description': 'mytrigger'}) Remove a trigger:: @@ -190,13 +172,6 @@ Reference + :class:`gitlab.v4.objects.GroupVariableManager` + :attr:`gitlab.v4.objects.Group.variables` -* v3 API - - + :class:`gitlab.v3.objects.ProjectVariable` - + :class:`gitlab.v3.objects.ProjectVariableManager` - + :attr:`gitlab.v3.objects.Project.variables` - + :attr:`gitlab.Gitlab.project_variables` - * GitLab API + https://docs.gitlab.com/ce/api/project_level_variables.html @@ -232,11 +207,11 @@ Remove a variable:: # or var.delete() -Builds/Jobs -=========== +Jobs +==== -Builds/Jobs are associated to projects, pipelines and commits. They provide -information on the builds/jobs that have been run, and methods to manipulate +Jobs are associated to projects, pipelines and commits. They provide +information on the jobs that have been run, and methods to manipulate them. Reference @@ -248,13 +223,6 @@ Reference + :class:`gitlab.v4.objects.ProjectJobManager` + :attr:`gitlab.v4.objects.Project.jobs` -* v3 API - - + :class:`gitlab.v3.objects.ProjectJob` - + :class:`gitlab.v3.objects.ProjectJobManager` - + :attr:`gitlab.v3.objects.Project.jobs` - + :attr:`gitlab.Gitlab.project_jobs` - * GitLab API: https://docs.gitlab.com/ce/api/jobs.html Examples @@ -268,23 +236,13 @@ job:: List jobs for the project:: - builds = project.builds.list() # v3 - jobs = project.jobs.list() # v4 - -To list builds for a specific commit, create a -:class:`~gitlab.v3.objects.ProjectCommit` object and use its -:attr:`~gitlab.v3.objects.ProjectCommit.builds` method (v3 only):: - - # v3 only - commit = gl.project_commits.get(commit_sha, project_id=1) - builds = commit.builds() + jobs = project.jobs.list() To list builds for a specific pipeline or get a single job within a specific pipeline, create a :class:`~gitlab.v4.objects.ProjectPipeline` object and use its -:attr:`~gitlab.v4.objects.ProjectPipeline.jobs` method (v4 only):: +:attr:`~gitlab.v4.objects.ProjectPipeline.jobs` method:: - # v4 only project = gl.projects.get(project_id) pipeline = project.pipelines.get(pipeline_id) jobs = pipeline.jobs.list() # gets all jobs in pipeline @@ -292,8 +250,7 @@ pipeline, create a Get a job:: - project.builds.get(build_id) # v3 - project.jobs.get(job_id) # v4 + project.jobs.get(job_id) Get the artifacts of a job:: diff --git a/docs/gl_objects/commits.py b/docs/gl_objects/commits.py deleted file mode 100644 index 88d0095..0000000 --- a/docs/gl_objects/commits.py +++ /dev/null @@ -1,68 +0,0 @@ -# list -commits = project.commits.list() -# end list - -# filter list -commits = project.commits.list(ref_name='my_branch') -commits = project.commits.list(since='2016-01-01T00:00:00Z') -# end filter list - -# create -# See https://docs.gitlab.com/ce/api/commits.html#create-a-commit-with-multiple-files-and-actions -# for actions detail -data = { - 'branch_name': 'master', # v3 - 'branch': 'master', # v4 - '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) -# end create - -# get -commit = project.commits.get('e3d5a71b') -# end get - -# diff -diff = commit.diff() -# end diff - -# cherry -commit.cherry_pick(branch='target_branch') -# end cherry - -# comments list -comments = commit.comments.list() -# end comments list - -# comments create -# 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'}) -# end comments create - -# statuses list -statuses = commit.statuses.list() -# end statuses list - -# statuses set -commit.statuses.create({'state': 'success'}) -# end statuses set diff --git a/docs/gl_objects/commits.rst b/docs/gl_objects/commits.rst index 8a32709..22e23f6 100644 --- a/docs/gl_objects/commits.rst +++ b/docs/gl_objects/commits.rst @@ -14,60 +14,56 @@ Reference + :class:`gitlab.v4.objects.ProjectCommitManager` + :attr:`gitlab.v4.objects.Project.commits` -* v3 API: - - + :class:`gitlab.v3.objects.ProjectCommit` - + :class:`gitlab.v3.objects.ProjectCommitManager` - + :attr:`gitlab.v3.objects.Project.commits` - + :attr:`gitlab.Gitlab.project_commits` - -* GitLab API: https://docs.gitlab.com/ce/api/commits.html - -.. warning:: - - Pagination starts at page 0 in v3, but starts at page 1 in v4 (like all the - v4 endpoints). - - Examples -------- -List the commits for a project: +List the commits for a project:: -.. literalinclude:: commits.py - :start-after: # list - :end-before: # end list + commits = project.commits.list() You can use the ``ref_name``, ``since`` and ``until`` filters to limit the -results: +results:: + + commits = project.commits.list(ref_name='my_branch') + commits = project.commits.list(since='2016-01-01T00:00:00Z') -.. literalinclude:: commits.py - :start-after: # filter list - :end-before: # end filter list +Create a commit:: -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_name': 'master', # v3 + 'branch': 'master', # v4 + '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', + } + ] + } -.. literalinclude:: commits.py - :start-after: # create - :end-before: # end create + commit = project.commits.create(data) -Get a commit detail: +Get a commit detail:: -.. literalinclude:: commits.py - :start-after: # get - :end-before: # end get + commit = project.commits.get('e3d5a71b') -Get the diff for a commit: +Get the diff for a commit:: -.. literalinclude:: commits.py - :start-after: # diff - :end-before: # end diff + diff = commit.diff() -Cherry-pick a commit into another branch: +Cherry-pick a commit into another branch:: -.. literalinclude:: commits.py - :start-after: # cherry - :end-before: # end cherry + commit.cherry_pick(branch='target_branch') Commit comments =============== @@ -81,30 +77,24 @@ Reference + :class:`gitlab.v4.objects.ProjectCommitCommentManager` + :attr:`gitlab.v4.objects.Commit.comments` -* v3 API: - - + :class:`gitlab.v3.objects.ProjectCommit` - + :class:`gitlab.v3.objects.ProjectCommitManager` - + :attr:`gitlab.v3.objects.Commit.comments` - + :attr:`gitlab.v3.objects.Project.commit_comments` - + :attr:`gitlab.Gitlab.project_commit_comments` - * GitLab API: https://docs.gitlab.com/ce/api/commits.html Examples -------- -Get the comments for a commit: +Get the comments for a commit:: -.. literalinclude:: commits.py - :start-after: # comments list - :end-before: # end comments list + comments = commit.comments.list() -Add a comment on a commit: +Add a comment on a commit:: -.. literalinclude:: commits.py - :start-after: # comments create - :end-before: # end comments create + # 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 ============= @@ -118,27 +108,15 @@ Reference + :class:`gitlab.v4.objects.ProjectCommitStatusManager` + :attr:`gitlab.v4.objects.Commit.statuses` -* v3 API: - - + :class:`gitlab.v3.objects.ProjectCommit` - + :class:`gitlab.v3.objects.ProjectCommitManager` - + :attr:`gitlab.v3.objects.Commit.statuses` - + :attr:`gitlab.v3.objects.Project.commit_statuses` - + :attr:`gitlab.Gitlab.project_commit_statuses` - * GitLab API: https://docs.gitlab.com/ce/api/commits.html Examples -------- -Get the statuses for a commit: +List the statuses for a commit:: -.. literalinclude:: commits.py - :start-after: # statuses list - :end-before: # end statuses list + statuses = commit.statuses.list() -Change the status of a commit: +Change the status of a commit:: -.. literalinclude:: commits.py - :start-after: # statuses set - :end-before: # end statuses set + commit.statuses.create({'state': 'success'}) diff --git a/docs/gl_objects/deploy_keys.py b/docs/gl_objects/deploy_keys.py deleted file mode 100644 index ccdf30e..0000000 --- a/docs/gl_objects/deploy_keys.py +++ /dev/null @@ -1,35 +0,0 @@ -# global list -keys = gl.deploykeys.list() -# end global list - -# global get -key = gl.deploykeys.get(key_id) -# end global get - -# list -keys = project.keys.list() -# end list - -# get -key = project.keys.get(key_id) -# end get - -# create -key = project.keys.create({'title': 'jenkins key', - 'key': open('/home/me/.ssh/id_rsa.pub').read()}) -# end create - -# delete -key = project.keys.list(key_id) -# or -key.delete() -# end delete - -# enable -project.keys.enable(key_id) -# end enable - -# disable -project_key.delete() # v4 -project.keys.disable(key_id) # v3 -# end disable diff --git a/docs/gl_objects/deploy_keys.rst b/docs/gl_objects/deploy_keys.rst index a293d27..31e31a9 100644 --- a/docs/gl_objects/deploy_keys.rst +++ b/docs/gl_objects/deploy_keys.rst @@ -14,28 +14,14 @@ Reference + :class:`gitlab.v4.objects.DeployKeyManager` + :attr:`gitlab.Gitlab.deploykeys` -* v3 API: - - + :class:`gitlab.v3.objects.DeployKey` - + :class:`gitlab.v3.objects.DeployKeyManager` - + :attr:`gitlab.Gitlab.deploykeys` - * GitLab API: https://docs.gitlab.com/ce/api/deploy_keys.html Examples -------- -List the deploy keys: - -.. literalinclude:: deploy_keys.py - :start-after: # global list - :end-before: # end global list +List the deploy keys:: -Get a single deploy key: - -.. literalinclude:: deploy_keys.py - :start-after: # global get - :end-before: # end global get + keys = gl.deploykeys.list() Deploy keys for projects ======================== @@ -51,50 +37,34 @@ Reference + :class:`gitlab.v4.objects.ProjectKeyManager` + :attr:`gitlab.v4.objects.Project.keys` -* v3 API: - - + :class:`gitlab.v3.objects.ProjectKey` - + :class:`gitlab.v3.objects.ProjectKeyManager` - + :attr:`gitlab.v3.objects.Project.keys` - + :attr:`gitlab.Gitlab.project_keys` - * GitLab API: https://docs.gitlab.com/ce/api/deploy_keys.html Examples -------- -List keys for a project: +List keys for a project:: -.. literalinclude:: deploy_keys.py - :start-after: # list - :end-before: # end list + keys = project.keys.list() -Get a single deploy key: +Get a single deploy key:: -.. literalinclude:: deploy_keys.py - :start-after: # get - :end-before: # end get + key = project.keys.get(key_id) -Create a deploy key for a project: +Create a deploy key for a project:: -.. literalinclude:: deploy_keys.py - :start-after: # create - :end-before: # end create + key = project.keys.create({'title': 'jenkins key', + 'key': open('/home/me/.ssh/id_rsa.pub').read()}) -Delete a deploy key for a project: +Delete a deploy key for a project:: -.. literalinclude:: deploy_keys.py - :start-after: # delete - :end-before: # end delete + key = project.keys.list(key_id) + # or + key.delete() -Enable a deploy key for a project: +Enable a deploy key for a project:: -.. literalinclude:: deploy_keys.py - :start-after: # enable - :end-before: # end enable + project.keys.enable(key_id) -Disable a deploy key for a project: +Disable a deploy key for a project:: -.. literalinclude:: deploy_keys.py - :start-after: # disable - :end-before: # end disable + project_key.delete() diff --git a/docs/gl_objects/deployments.py b/docs/gl_objects/deployments.py deleted file mode 100644 index 5084b4d..0000000 --- a/docs/gl_objects/deployments.py +++ /dev/null @@ -1,7 +0,0 @@ -# list -deployments = project.deployments.list() -# end list - -# get -deployment = project.deployments.get(deployment_id) -# end get diff --git a/docs/gl_objects/deployments.rst b/docs/gl_objects/deployments.rst index 37e9468..333d497 100644 --- a/docs/gl_objects/deployments.rst +++ b/docs/gl_objects/deployments.rst @@ -11,26 +11,15 @@ Reference + :class:`gitlab.v4.objects.ProjectDeploymentManager` + :attr:`gitlab.v4.objects.Project.deployments` -* v3 API: - - + :class:`gitlab.v3.objects.ProjectDeployment` - + :class:`gitlab.v3.objects.ProjectDeploymentManager` - + :attr:`gitlab.v3.objects.Project.deployments` - + :attr:`gitlab.Gitlab.project_deployments` - * GitLab API: https://docs.gitlab.com/ce/api/deployments.html Examples -------- -List deployments for a project: +List deployments for a project:: -.. literalinclude:: deployments.py - :start-after: # list - :end-before: # end list + deployments = project.deployments.list() -Get a single deployment: +Get a single deployment:: -.. literalinclude:: deployments.py - :start-after: # get - :end-before: # end get + deployment = project.deployments.get(deployment_id) diff --git a/docs/gl_objects/environments.py b/docs/gl_objects/environments.py deleted file mode 100644 index 3ca6fc1..0000000 --- a/docs/gl_objects/environments.py +++ /dev/null @@ -1,22 +0,0 @@ -# list -environments = project.environments.list() -# end list - -# get -environment = project.environments.get(environment_id) -# end get - -# create -environment = project.environments.create({'name': 'production'}) -# end create - -# update -environment.external_url = 'http://foo.bar.com' -environment.save() -# end update - -# delete -environment = project.environments.delete(environment_id) -# or -environment.delete() -# end delete diff --git a/docs/gl_objects/environments.rst b/docs/gl_objects/environments.rst index d94c453..1867d24 100644 --- a/docs/gl_objects/environments.rst +++ b/docs/gl_objects/environments.rst @@ -11,44 +11,26 @@ Reference + :class:`gitlab.v4.objects.ProjectEnvironmentManager` + :attr:`gitlab.v4.objects.Project.environments` -* v3 API: - - + :class:`gitlab.v3.objects.ProjectEnvironment` - + :class:`gitlab.v3.objects.ProjectEnvironmentManager` - + :attr:`gitlab.v3.objects.Project.environments` - + :attr:`gitlab.Gitlab.project_environments` - * GitLab API: https://docs.gitlab.com/ce/api/environments.html Examples -------- -List environments for a project: - -.. literalinclude:: environments.py - :start-after: # list - :end-before: # end list - -Get a single environment: +List environments for a project:: -.. literalinclude:: environments.py - :start-after: # get - :end-before: # end get + environments = project.environments.list() -Create an environment for a project: +Create an environment for a project:: -.. literalinclude:: environments.py - :start-after: # create - :end-before: # end create + environment = project.environments.create({'name': 'production'}) -Update an environment for a project: +Update an environment for a project:: -.. literalinclude:: environments.py - :start-after: # update - :end-before: # end update + environment.external_url = 'http://foo.bar.com' + environment.save() -Delete an environment for a project: +Delete an environment for a project:: -.. literalinclude:: environments.py - :start-after: # delete - :end-before: # end delete + environment = project.environments.delete(environment_id) + # or + environment.delete() diff --git a/docs/gl_objects/events.rst b/docs/gl_objects/events.rst index eef524f..8071b00 100644 --- a/docs/gl_objects/events.rst +++ b/docs/gl_objects/events.rst @@ -17,13 +17,6 @@ Reference + :class:`gitlab.v4.objects.UserEventManager` + :attr:`gitlab.v4.objects.User.events` -* v3 API (projects events only): - - + :class:`gitlab.v3.objects.ProjectEvent` - + :class:`gitlab.v3.objects.ProjectEventManager` - + :attr:`gitlab.v3.objects.Project.events` - + :attr:`gitlab.Gitlab.project_events` - * GitLab API: https://docs.gitlab.com/ce/api/events.html Examples diff --git a/docs/gl_objects/groups.rst b/docs/gl_objects/groups.rst index 493f5d0..d24e53c 100644 --- a/docs/gl_objects/groups.rst +++ b/docs/gl_objects/groups.rst @@ -14,12 +14,6 @@ Reference + :class:`gitlab.v4.objects.GroupManager` + :attr:`gitlab.Gitlab.groups` -* v3 API: - - + :class:`gitlab.v3.objects.Group` - + :class:`gitlab.v3.objects.GroupManager` - + :attr:`gitlab.Gitlab.groups` - * GitLab API: https://docs.gitlab.com/ce/api/groups.html Examples @@ -148,13 +142,6 @@ Reference + :class:`gitlab.v4.objects.GroupMemberManager` + :attr:`gitlab.v4.objects.Group.members` -* v3 API: - - + :class:`gitlab.v3.objects.GroupMember` - + :class:`gitlab.v3.objects.GroupMemberManager` - + :attr:`gitlab.v3.objects.Group.members` - + :attr:`gitlab.Gitlab.group_members` - * GitLab API: https://docs.gitlab.com/ce/api/groups.html diff --git a/docs/gl_objects/issues.py b/docs/gl_objects/issues.py deleted file mode 100644 index fe77473..0000000 --- a/docs/gl_objects/issues.py +++ /dev/null @@ -1,95 +0,0 @@ -# list -issues = gl.issues.list() -# end list - -# filtered list -open_issues = gl.issues.list(state='opened') -closed_issues = gl.issues.list(state='closed') -tagged_issues = gl.issues.list(labels=['foo', 'bar']) -# end filtered list - -# group issues list -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') -# end group issues list - -# project issues list -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') -# end project issues list - -# project issues get -issue = project.issues.get(issue_id) -# end project issues get - -# project issues get from iid -issue = project.issues.list(iid=issue_iid)[0] -# end project issues get from iid - -# project issues create -issue = project.issues.create({'title': 'I have a bug', - 'description': 'Something useful here.'}) -# end project issues create - -# project issue update -issue.labels = ['foo', 'bar'] -issue.save() -# end project issue update - -# project issue open_close -# close an issue -issue.state_event = 'close' -issue.save() -# reopen it -issue.state_event = 'reopen' -issue.save() -# end project issue open_close - -# project issue delete -project.issues.delete(issue_id) -# pr -issue.delete() -# end project issue delete - -# project issue subscribe -issue.subscribe() -issue.unsubscribe() -# end project issue subscribe - -# project issue move -issue.move(new_project_id) -# end project issue move - -# project issue todo -issue.todo() -# end project issue todo - -# project issue time tracking stats -issue.time_stats() -# end project issue time tracking stats - -# project issue set time estimate -issue.time_estimate('3h30m') -# end project issue set time estimate - -# project issue reset time estimate -issue.reset_time_estimate() -# end project issue reset time estimate - -# project issue set time spent -issue.add_spent_time('3h30m') -# end project issue set time spent - -# project issue reset time spent -issue.reset_spent_time() -# end project issue reset time spent - -# project issue useragent -detail = issue.user_agent_detail() -# end project issue useragent diff --git a/docs/gl_objects/issues.rst b/docs/gl_objects/issues.rst index 136d8b8..2f58dd6 100644 --- a/docs/gl_objects/issues.rst +++ b/docs/gl_objects/issues.rst @@ -14,29 +14,21 @@ Reference + :class:`gitlab.v4.objects.IssueManager` + :attr:`gitlab.Gitlab.issues` -* v3 API: - - + :class:`gitlab.v3.objects.Issue` - + :class:`gitlab.v3.objects.IssueManager` - + :attr:`gitlab.Gitlab.issues` - * GitLab API: https://docs.gitlab.com/ce/api/issues.html Examples -------- -List the issues: +List the issues:: -.. literalinclude:: issues.py - :start-after: # list - :end-before: # end list + 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: +``order_by`` and ``sort`` attributes to sort the results:: -.. literalinclude:: issues.py - :start-after: # filtered list - :end-before: # end filtered list + open_issues = gl.issues.list(state='opened') + closed_issues = gl.issues.list(state='closed') + tagged_issues = gl.issues.list(labels=['foo', 'bar']) Group issues ============ @@ -50,23 +42,18 @@ Reference + :class:`gitlab.v4.objects.GroupIssueManager` + :attr:`gitlab.v4.objects.Group.issues` -* v3 API: - - + :class:`gitlab.v3.objects.GroupIssue` - + :class:`gitlab.v3.objects.GroupIssueManager` - + :attr:`gitlab.v3.objects.Group.issues` - + :attr:`gitlab.Gitlab.group_issues` - * GitLab API: https://docs.gitlab.com/ce/api/issues.html Examples -------- -List the group issues: +List the group issues:: -.. literalinclude:: issues.py - :start-after: # group issues list - :end-before: # end group issues list + 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') Project issues ============== @@ -80,110 +67,81 @@ Reference + :class:`gitlab.v4.objects.ProjectIssueManager` + :attr:`gitlab.v4.objects.Project.issues` -* v3 API: - - + :class:`gitlab.v3.objects.ProjectIssue` - + :class:`gitlab.v3.objects.ProjectIssueManager` - + :attr:`gitlab.v3.objects.Project.issues` - + :attr:`gitlab.Gitlab.project_issues` - * GitLab API: https://docs.gitlab.com/ce/api/issues.html Examples -------- -List the project issues: - -.. literalinclude:: issues.py - :start-after: # project issues list - :end-before: # end project issues list - -Get a project issue: +List the project issues:: -.. literalinclude:: issues.py - :start-after: # project issues get - :end-before: # end project issues get + 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 from its `iid` (v3 only. Issues are retrieved by iid in V4 by default): +Get a project issue:: -.. literalinclude:: issues.py - :start-after: # project issues get from iid - :end-before: # end project issues get from iid + issue = project.issues.get(issue_iid) -Create a new issue: +Create a new issue:: -.. literalinclude:: issues.py - :start-after: # project issues create - :end-before: # end project issues create + issue = project.issues.create({'title': 'I have a bug', + 'description': 'Something useful here.'}) -Update an issue: +Update an issue:: -.. literalinclude:: issues.py - :start-after: # project issue update - :end-before: # end project issue update + issue.labels = ['foo', 'bar'] + issue.save() -Close / reopen an issue: +Close / reopen an issue:: -.. literalinclude:: issues.py - :start-after: # project issue open_close - :end-before: # end project issue open_close + # close an issue + issue.state_event = 'close' + issue.save() + # reopen it + issue.state_event = 'reopen' + issue.save() -Delete an issue: +Delete an issue:: -.. literalinclude:: issues.py - :start-after: # project issue delete - :end-before: # end project issue delete + project.issues.delete(issue_id) + # pr + issue.delete() -Subscribe / unsubscribe from an issue: +Subscribe / unsubscribe from an issue:: -.. literalinclude:: issues.py - :start-after: # project issue subscribe - :end-before: # end project issue subscribe + issue.subscribe() + issue.unsubscribe() -Move an issue to another project: +Move an issue to another project:: -.. literalinclude:: issues.py - :start-after: # project issue move - :end-before: # end project issue move + issue.move(other_project_id) -Make an issue as todo: +Make an issue as todo:: -.. literalinclude:: issues.py - :start-after: # project issue todo - :end-before: # end project issue todo + issue.todo() -Get time tracking stats: +Get time tracking stats:: -.. literalinclude:: issues.py - :start-after: # project issue time tracking stats - :end-before: # end project issue time tracking stats + issue.time_stats() -Set a time estimate for an issue: +Set a time estimate for an issue:: -.. literalinclude:: issues.py - :start-after: # project issue set time estimate - :end-before: # end project issue set time estimate + issue.time_estimate('3h30m') -Reset a time estimate for an issue: +Reset a time estimate for an issue:: -.. literalinclude:: issues.py - :start-after: # project issue reset time estimate - :end-before: # end project issue reset time estimate + issue.reset_time_estimate() -Add spent time for an issue: +Add spent time for an issue:: -.. literalinclude:: issues.py - :start-after: # project issue set time spent - :end-before: # end project issue set time spent + issue.add_spent_time('3h30m') -Reset spent time for an issue: +Reset spent time for an issue:: -.. literalinclude:: issues.py - :start-after: # project issue reset time spent - :end-before: # end project issue reset time spent + issue.reset_spent_time() -Get user agent detail for the issue (admin only): +Get user agent detail for the issue (admin only):: -.. literalinclude:: issues.py - :start-after: # project issue useragent - :end-before: # end project issue useragent + detail = issue.user_agent_detail() diff --git a/docs/gl_objects/labels.py b/docs/gl_objects/labels.py deleted file mode 100644 index a63e295..0000000 --- a/docs/gl_objects/labels.py +++ /dev/null @@ -1,36 +0,0 @@ -# list -labels = project.labels.list() -# end list - -# get -label = project.labels.get(label_name) -# end get - -# create -label = project.labels.create({'name': 'foo', 'color': '#8899aa'}) -# end create - -# update -# change the name of the label: -label.new_name = 'bar' -label.save() -# change its color: -label.color = '#112233' -label.save() -# end update - -# delete -project.labels.delete(label_id) -# or -label.delete() -# end delete - -# use -# 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() -# end use diff --git a/docs/gl_objects/labels.rst b/docs/gl_objects/labels.rst index 3c8034d..1c98971 100644 --- a/docs/gl_objects/labels.rst +++ b/docs/gl_objects/labels.rst @@ -11,50 +11,40 @@ Reference + :class:`gitlab.v4.objects.ProjectLabelManager` + :attr:`gitlab.v4.objects.Project.labels` -* v3 API: - - + :class:`gitlab.v3.objects.ProjectLabel` - + :class:`gitlab.v3.objects.ProjectLabelManager` - + :attr:`gitlab.v3.objects.Project.labels` - + :attr:`gitlab.Gitlab.project_labels` - * GitLab API: https://docs.gitlab.com/ce/api/labels.html Examples -------- -List labels for a project: - -.. literalinclude:: labels.py - :start-after: # list - :end-before: # end list - -Get a single label: +List labels for a project:: -.. literalinclude:: labels.py - :start-after: # get - :end-before: # end get + labels = project.labels.list() -Create a label for a project: +Create a label for a project:: -.. literalinclude:: labels.py - :start-after: # create - :end-before: # end create + label = project.labels.create({'name': 'foo', 'color': '#8899aa'}) -Update a label for a project: +Update a label for a project:: -.. literalinclude:: labels.py - :start-after: # update - :end-before: # end update + # 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: +Delete a label for a project:: -.. literalinclude:: labels.py - :start-after: # delete - :end-before: # end delete + project.labels.delete(label_id) + # or + label.delete() -Managing labels in issues and merge requests: +Manage labels in issues and merge requests:: -.. literalinclude:: labels.py - :start-after: # use - :end-before: # end use + # 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() diff --git a/docs/gl_objects/messages.py b/docs/gl_objects/messages.py deleted file mode 100644 index 74714e5..0000000 --- a/docs/gl_objects/messages.py +++ /dev/null @@ -1,23 +0,0 @@ -# list -msgs = gl.broadcastmessages.list() -# end list - -# get -msg = gl.broadcastmessages.get(msg_id) -# end get - -# create -msg = gl.broadcastmessages.create({'message': 'Important information'}) -# end create - -# update -msg.font = '#444444' -msg.color = '#999999' -msg.save() -# end update - -# delete -gl.broadcastmessages.delete(msg_id) -# or -msg.delete() -# end delete diff --git a/docs/gl_objects/messages.rst b/docs/gl_objects/messages.rst index 452370d..32fbb95 100644 --- a/docs/gl_objects/messages.rst +++ b/docs/gl_objects/messages.rst @@ -15,46 +15,34 @@ References + :class:`gitlab.v4.objects.BroadcastMessageManager` + :attr:`gitlab.Gitlab.broadcastmessages` -* v3 API: - - + :class:`gitlab.v3.objects.BroadcastMessage` - + :class:`gitlab.v3.objects.BroadcastMessageManager` - + :attr:`gitlab.Gitlab.broadcastmessages` - * GitLab API: https://docs.gitlab.com/ce/api/broadcast_messages.html Examples -------- -List the messages: +List the messages:: -.. literalinclude:: messages.py - :start-after: # list - :end-before: # end list + msgs = gl.broadcastmessages.list() -Get a single message: +Get a single message:: -.. literalinclude:: messages.py - :start-after: # get - :end-before: # end get + msg = gl.broadcastmessages.get(msg_id) -Create a message: +Create a message:: -.. literalinclude:: messages.py - :start-after: # create - :end-before: # end create + msg = gl.broadcastmessages.create({'message': 'Important information'}) -The date format for ``starts_at`` and ``ends_at`` parameters is +The date format for the ``starts_at`` and ``ends_at`` parameters is ``YYYY-MM-ddThh:mm:ssZ``. -Update a message: +Update a message:: -.. literalinclude:: messages.py - :start-after: # update - :end-before: # end update + msg.font = '#444444' + msg.color = '#999999' + msg.save() -Delete a message: +Delete a message:: -.. literalinclude:: messages.py - :start-after: # delete - :end-before: # end delete + gl.broadcastmessages.delete(msg_id) + # or + msg.delete() diff --git a/docs/gl_objects/milestones.py b/docs/gl_objects/milestones.py deleted file mode 100644 index d1985d9..0000000 --- a/docs/gl_objects/milestones.py +++ /dev/null @@ -1,41 +0,0 @@ -# list -p_milestones = project.milestones.list() -g_milestones = group.milestones.list() -# end list - -# filter -p_milestones = project.milestones.list(state='closed') -g_milestones = group.milestones.list(state='active') -# end filter - -# get -p_milestone = project.milestones.get(milestone_id) -g_milestone = group.milestones.get(milestone_id) -# end get - -# create -milestone = project.milestones.create({'title': '1.0'}) -# end create - -# update -milestone.description = 'v 1.0 release' -milestone.save() -# end update - -# state -# close a milestone -milestone.state_event = 'close' -milestone.save() - -# activate a milestone -milestone.state_event = 'activate' -milestone.save() -# end state - -# issues -issues = milestone.issues() -# end issues - -# merge_requests -merge_requests = milestone.merge_requests() -# end merge_requests diff --git a/docs/gl_objects/milestones.rst b/docs/gl_objects/milestones.rst index c96560a..0d3f576 100644 --- a/docs/gl_objects/milestones.rst +++ b/docs/gl_objects/milestones.rst @@ -15,13 +15,6 @@ Reference + :class:`gitlab.v4.objects.GroupMilestoneManager` + :attr:`gitlab.v4.objects.Group.milestones` -* v3 API: - - + :class:`gitlab.v3.objects.ProjectMilestone` - + :class:`gitlab.v3.objects.ProjectMilestoneManager` - + :attr:`gitlab.v3.objects.Project.milestones` - + :attr:`gitlab.Gitlab.project_milestones` - * GitLab API: + https://docs.gitlab.com/ce/api/milestones.html @@ -30,11 +23,10 @@ Reference Examples -------- -List the milestones for a project or a group: +List the milestones for a project or a group:: -.. literalinclude:: milestones.py - :start-after: # list - :end-before: # end list + p_milestones = project.milestones.list() + g_milestones = group.milestones.list() You can filter the list using the following parameters: @@ -42,42 +34,39 @@ You can filter the list using the following parameters: * ``state``: either ``active`` or ``closed`` * ``search``: to search using a string -.. literalinclude:: milestones.py - :start-after: # filter - :end-before: # end filter +:: + + p_milestones = project.milestones.list(state='closed') + g_milestones = group.milestones.list(state='active') + +Get a single milestone:: -Get a single milestone: + p_milestone = project.milestones.get(milestone_id) + g_milestone = group.milestones.get(milestone_id) -.. literalinclude:: milestones.py - :start-after: # get - :end-before: # end get +Create a milestone:: -Create a milestone: + milestone = project.milestones.create({'title': '1.0'}) -.. literalinclude:: milestones.py - :start-after: # create - :end-before: # end create +Edit a milestone:: -Edit a milestone: + milestone.description = 'v 1.0 release' + milestone.save() -.. literalinclude:: milestones.py - :start-after: # update - :end-before: # end update +Change the state of a milestone (activate / close):: -Change the state of a milestone (activate / close): + # close a milestone + milestone.state_event = 'close' + milestone.save() -.. literalinclude:: milestones.py - :start-after: # state - :end-before: # end state + # activate a milestone + milestone.state_event = 'activate' + milestone.save() -List the issues related to a milestone: +List the issues related to a milestone:: -.. literalinclude:: milestones.py - :start-after: # issues - :end-before: # end issues + issues = milestone.issues() -List the merge requests related to a milestone: +List the merge requests related to a milestone:: -.. literalinclude:: milestones.py - :start-after: # merge_requests - :end-before: # end merge_requests + merge_requests = milestone.merge_requests() diff --git a/docs/gl_objects/mrs.rst b/docs/gl_objects/mrs.rst index ba1090e..731785d 100644 --- a/docs/gl_objects/mrs.rst +++ b/docs/gl_objects/mrs.rst @@ -5,9 +5,6 @@ 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. -The v3 API uses the ``id`` attribute to identify a merge request, the v4 API -uses the ``iid`` attribute. - Reference --------- @@ -17,13 +14,6 @@ Reference + :class:`gitlab.v4.objects.ProjectMergeRequestManager` + :attr:`gitlab.v4.objects.Project.mergerequests` -* v3 API: - - + :class:`gitlab.v3.objects.ProjectMergeRequest` - + :class:`gitlab.v3.objects.ProjectMergeRequestManager` - + :attr:`gitlab.v3.objects.Project.mergerequests` - + :attr:`gitlab.Gitlab.project_mergerequests` - * GitLab API: https://docs.gitlab.com/ce/api/merge_requests.html Examples @@ -35,7 +25,6 @@ List MRs for a project:: You can filter and sort the returned list with the following parameters: -* ``iid``: iid (unique ID for the project) of the MR (v3 API) * ``state``: state of the MR. It can be one of ``all``, ``merged``, ``opened`` or ``closed`` * ``order_by``: sort by ``created_at`` or ``updated_at`` @@ -79,8 +68,7 @@ Accept a MR:: Cancel a MR when the build succeeds:: - mr.cancel_merge_when_build_succeeds() # v3 - mr.cancel_merge_when_pipeline_succeeds() # v4 + mr.cancel_merge_when_pipeline_succeeds() List commits of a MR:: diff --git a/docs/gl_objects/namespaces.py b/docs/gl_objects/namespaces.py deleted file mode 100644 index fe50697..0000000 --- a/docs/gl_objects/namespaces.py +++ /dev/null @@ -1,7 +0,0 @@ -# list -namespaces = gl.namespaces.list() -# end list - -# search -namespaces = gl.namespaces.list(search='foo') -# end search diff --git a/docs/gl_objects/namespaces.rst b/docs/gl_objects/namespaces.rst index 0dabdd9..1aebd29 100644 --- a/docs/gl_objects/namespaces.rst +++ b/docs/gl_objects/namespaces.rst @@ -11,25 +11,15 @@ Reference + :class:`gitlab.v4.objects.NamespaceManager` + :attr:`gitlab.Gitlab.namespaces` -* v3 API: - - + :class:`gitlab.v3.objects.Namespace` - + :class:`gitlab.v3.objects.NamespaceManager` - + :attr:`gitlab.Gitlab.namespaces` - * GitLab API: https://docs.gitlab.com/ce/api/namespaces.html Examples -------- -List namespaces: +List namespaces:: -.. literalinclude:: namespaces.py - :start-after: # list - :end-before: # end list + namespaces = gl.namespaces.list() -Search namespaces: +Search namespaces:: -.. literalinclude:: namespaces.py - :start-after: # search - :end-before: # end search + namespaces = gl.namespaces.list(search='foo') diff --git a/docs/gl_objects/notes.rst b/docs/gl_objects/notes.rst index fd0788b..053c0a0 100644 --- a/docs/gl_objects/notes.rst +++ b/docs/gl_objects/notes.rst @@ -30,32 +30,6 @@ Reference + :class:`gitlab.v4.objects.ProjectSnippetNoteManager` + :attr:`gitlab.v4.objects.ProjectSnippet.notes` -* v3 API: - - Issues: - - + :class:`gitlab.v3.objects.ProjectIssueNote` - + :class:`gitlab.v3.objects.ProjectIssueNoteManager` - + :attr:`gitlab.v3.objects.ProjectIssue.notes` - + :attr:`gitlab.v3.objects.Project.issue_notes` - + :attr:`gitlab.Gitlab.project_issue_notes` - - MergeRequests: - - + :class:`gitlab.v3.objects.ProjectMergeRequestNote` - + :class:`gitlab.v3.objects.ProjectMergeRequestNoteManager` - + :attr:`gitlab.v3.objects.ProjectMergeRequest.notes` - + :attr:`gitlab.v3.objects.Project.mergerequest_notes` - + :attr:`gitlab.Gitlab.project_mergerequest_notes` - - Snippets: - - + :class:`gitlab.v3.objects.ProjectSnippetNote` - + :class:`gitlab.v3.objects.ProjectSnippetNoteManager` - + :attr:`gitlab.v3.objects.ProjectSnippet.notes` - + :attr:`gitlab.v3.objects.Project.snippet_notes` - + :attr:`gitlab.Gitlab.project_snippet_notes` - * GitLab API: https://docs.gitlab.com/ce/api/notes.html Examples diff --git a/docs/gl_objects/notifications.py b/docs/gl_objects/notifications.py deleted file mode 100644 index c46e36e..0000000 --- a/docs/gl_objects/notifications.py +++ /dev/null @@ -1,21 +0,0 @@ -# get -# 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() -# end get - -# update -# 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() -# end update diff --git a/docs/gl_objects/notifications.rst b/docs/gl_objects/notifications.rst index a7310f3..ab0287f 100644 --- a/docs/gl_objects/notifications.rst +++ b/docs/gl_objects/notifications.rst @@ -30,31 +30,30 @@ Reference + :class:`gitlab.v4.objects.ProjectNotificationSettingsManager` + :attr:`gitlab.v4.objects.Project.notificationsettings` -* v3 API: - - + :class:`gitlab.v3.objects.NotificationSettings` - + :class:`gitlab.v3.objects.NotificationSettingsManager` - + :attr:`gitlab.Gitlab.notificationsettings` - + :class:`gitlab.v3.objects.GroupNotificationSettings` - + :class:`gitlab.v3.objects.GroupNotificationSettingsManager` - + :attr:`gitlab.v3.objects.Group.notificationsettings` - + :class:`gitlab.v3.objects.ProjectNotificationSettings` - + :class:`gitlab.v3.objects.ProjectNotificationSettingsManager` - + :attr:`gitlab.v3.objects.Project.notificationsettings` - * GitLab API: https://docs.gitlab.com/ce/api/notification_settings.html Examples -------- -Get the settings: +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:: -.. literalinclude:: notifications.py - :start-after: # get - :end-before: # end get + # use a predefined level + settings.level = gitlab.NOTIFICATION_LEVEL_WATCH -Update the settings: + # create a custom setup + settings.level = gitlab.NOTIFICATION_LEVEL_CUSTOM + settings.save() # will create additional attributes, but not mandatory -.. literalinclude:: notifications.py - :start-after: # update - :end-before: # end update + settings.new_merge_request = True + settings.new_issue = True + settings.new_note = True + settings.save() diff --git a/docs/gl_objects/projects.py b/docs/gl_objects/projects.py deleted file mode 100644 index a82665a..0000000 --- a/docs/gl_objects/projects.py +++ /dev/null @@ -1,367 +0,0 @@ -# list -# Active projects -projects = gl.projects.list() -# 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.owned() - -# List starred projects -projects = gl.projects.starred() - -# List all the projects -projects = gl.projects.all() - -# Search projects -projects = gl.projects.list(search='keyword') -# end list - -# get -# Get a project by ID -project = gl.projects.get(10) -# Get a project by userspace/name -project = gl.projects.get('myteam/myproject') -# end get - -# create -project = gl.projects.create({'name': 'project1'}) -# end create - -# user create -alice = gl.users.list(username='alice')[0] -user_project = alice.projects.create({'name': 'project'}) -user_projects = alice.projects.list() -# end user create - -# update -project.snippets_enabled = 1 -project.save() -# end update - -# delete -gl.projects.delete(1) -# or -project.delete() -# end delete - -# fork -fork = project.forks.create({}) - -# fork to a specific namespace -fork = project.forks.create({'namespace': 'myteam'}) -# end fork - -# forkrelation -project.create_fork_relation(source_project.id) -project.delete_fork_relation() -# end forkrelation - -# star -project.star() -project.unstar() -# end star - -# archive -project.archive() -project.unarchive() -# end archive - -# members list -members = project.members.list() -# end members list - -# members search -members = project.members.list(query='bar') -# end members search - -# members get -member = project.members.get(1) -# end members get - -# members add -member = project.members.create({'user_id': user.id, 'access_level': - gitlab.DEVELOPER_ACCESS}) -# end members add - -# members update -member.access_level = gitlab.MASTER_ACCESS -member.save() -# end members update - -# members delete -project.members.delete(user.id) -# or -member.delete() -# end members delete - -# share -project.share(group.id, gitlab.DEVELOPER_ACCESS) -# end share - -# unshare -project.unshare(group.id) -# end unshare - -# hook list -hooks = project.hooks.list() -# end hook list - -# hook get -hook = project.hooks.get(1) -# end hook get - -# hook create -hook = gl.project_hooks.create({'url': 'http://my/action/url', - 'push_events': 1}, - project_id=1) -# or -hook = project.hooks.create({'url': 'http://my/action/url', 'push_events': 1}) -# end hook create - -# hook update -hook.push_events = 0 -hook.save() -# end hook update - -# hook delete -project.hooks.delete(1) -# or -hook.delete() -# end hook delete - -# 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') -# end repository tree - -# repository blob -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'] -# end repository blob - -# repository raw_blob -# 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) -# end repository raw_blob - -# repository compare -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) -# end repository compare - -# repository archive -# get the archive for the default branch -tgz = project.repository_archive() - -# get the archive for a branch/tag/commit -tgz = project.repository_archive(sha='4567abc') -# end repository archive - -# repository contributors -contributors = project.repository_contributors() -# end repository contributors - -# housekeeping -project.housekeeping() -# end housekeeping - -# files get -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()) -# end files get - -# files create -# v4 -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'}) -# v3 -f = project.files.create({'file_path': 'testfile', - 'branch_name': 'master', - 'content': file_content, - 'commit_message': 'Create testfile'}) -# end files create - -# files update -f.content = 'new content' -f.save(branch='master', commit_message='Update testfile') # v4 -f.save(branch_name='master', commit_message='Update testfile') # v3 - -# 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') -# end files update - -# files delete -f.delete(commit_message='Delete testfile') -# end files delete - -# tags list -tags = project.tags.list() -# end tags list - -# tags get -tag = project.tags.get('1.0') -# end tags get - -# tags create -tag = project.tags.create({'tag_name': '1.0', 'ref': 'master'}) -# end tags create - -# tags delete -project.tags.delete('1.0') -# or -tag.delete() -# end tags delete - -# tags release -tag.set_release_description('awesome v1.0 release') -# end tags release - -# snippets list -snippets = project.snippets.list() -# end snippets list - -# snippets get -snippets = project.snippets.list(snippet_id) -# end snippets get - -# snippets create -snippet = project.snippets.create({'title': 'sample 1', - 'file_name': 'foo.py', - 'code': 'import gitlab', - 'visibility_level': - gitlab.VISIBILITY_PRIVATE}) -# end snippets create - -# snippets content -print(snippet.content()) -# end snippets content - -# snippets update -snippet.code = 'import gitlab\nimport whatever' -snippet.save -# end snippets update - -# snippets delete -project.snippets.delete(snippet_id) -# or -snippet.delete() -# end snippets delete - -# service get -# For v3 -service = project.services.get(service_name='asana', project_id=1) -# For v4 -service = project.services.get('asana') -# display its status (enabled/disabled) -print(service.active) -# end service get - -# service list -services = gl.project_services.available() # API v3 -services = project.services.available() # API v4 -# end service list - -# service update -service.api_key = 'randomkey' -service.save() -# end service update - -# service delete -service.delete() -# end service delete - -# boards list -boards = project.boards.list() -# end boards list - -# boards get -board = project.boards.get(board_id) -# end boards get - -# board lists list -b_lists = board.lists.list() -# end board lists list - -# board lists get -b_list = board.lists.get(list_id) -# end board lists get - -# board lists create -# 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}) -# end board lists create - -# board lists update -b_list.position = 2 -b_list.save() -# end board lists update - -# board lists delete -b_list.delete() -# end board lists delete - -# project file upload by path -# Or provide a full path to the uploaded file -project.upload("filename.txt", filepath="/some/path/filename.txt") -# end project file upload by path - -# project file upload with data -# Upload a file using its filename and filedata -project.upload("filename.txt", filedata="Raw data") -# end project file upload with data - -# project file upload 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"]) -}) -# end project file upload markdown - -# project file upload markdown custom -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"]) -}) -# end project file upload markdown custom - -# users list -users = p.users.list() - -# search for users -users = p.users.list(search='pattern') -# end users list diff --git a/docs/gl_objects/projects.rst b/docs/gl_objects/projects.rst index 907f8df..fdea7aa 100644 --- a/docs/gl_objects/projects.rst +++ b/docs/gl_objects/projects.rst @@ -14,18 +14,14 @@ Reference + :class:`gitlab.v4.objects.ProjectManager` + :attr:`gitlab.Gitlab.projects` -* v3 API: - - + :class:`gitlab.v3.objects.Project` - + :class:`gitlab.v3.objects.ProjectManager` - + :attr:`gitlab.Gitlab.projects` - * GitLab API: https://docs.gitlab.com/ce/api/projects.html Examples -------- -List projects: +List projects:: + + projects = gl.projects.list() The API provides several filtering parameters for the listing methods: @@ -41,136 +37,148 @@ Results can also be sorted using the following parameters: The default is to sort by ``created_at`` * ``sort``: sort order (``asc`` or ``desc``) -.. literalinclude:: projects.py - :start-after: # list - :end-before: # end list +:: + + # Archived projects + projects = gl.projects.list(archived=1) + # Limit to projects with a defined visibility + projects = gl.projects.list(visibility='public') -Get a single project: + # List owned projects + projects = gl.projects.owned() -.. literalinclude:: projects.py - :start-after: # get - :end-before: # end get + # List starred projects + projects = gl.projects.starred() -Create a project: + # List all the projects + projects = gl.projects.all() -.. literalinclude:: projects.py - :start-after: # create - :end-before: # end create + # Search projects + projects = gl.projects.list(search='keyword') -Create a project for a user (admin only): +Get a single project:: -.. literalinclude:: projects.py - :start-after: # user create - :end-before: # end user create + # Get a project by ID + project = gl.projects.get(10) + # Get a project by userspace/name + project = gl.projects.get('myteam/myproject') -Create a project in a group: +Create a project:: -You need to get the id of the group, then use the namespace_id attribute to create the group: + project = gl.projects.create({'name': 'project1'}) -.. code:: python +Create a project for a user (admin only):: - group_id = gl.groups.search('my-group')[0].id - project = gl.projects.create({'name': 'myrepo', 'namespace_id': group_id}) + 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:: -Update a project: + # You need to get the id of the group, then use the namespace_id attribute + # to create the group + group_id = gl.groups.search('my-group')[0].id + project = gl.projects.create({'name': 'myrepo', 'namespace_id': group_id}) -.. literalinclude:: projects.py - :start-after: # update - :end-before: # end update +Update a project:: -Delete a project: + project.snippets_enabled = 1 + project.save() -.. literalinclude:: projects.py - :start-after: # delete - :end-before: # end delete +Delete a project:: -Fork a project: + gl.projects.delete(1) + # or + project.delete() + +Fork a project:: + + fork = project.forks.create({}) -.. literalinclude:: projects.py - :start-after: # fork - :end-before: # end fork + # fork to a specific namespace + fork = project.forks.create({'namespace': 'myteam'}) -Create/delete a fork relation between projects (requires admin permissions): +Create/delete a fork relation between projects (requires admin permissions):: -.. literalinclude:: projects.py - :start-after: # forkrelation - :end-before: # end forkrelation + project.create_fork_relation(source_project.id) + project.delete_fork_relation() -Star/unstar a project: +Star/unstar a project:: -.. literalinclude:: projects.py - :start-after: # star - :end-before: # end star + project.star() + project.unstar() -Archive/unarchive a project: +Archive/unarchive a project:: -.. literalinclude:: projects.py - :start-after: # archive - :end-before: # end archive + project.archive() + project.unarchive() -.. note:: +Start the housekeeping job:: - Previous versions used ``archive_`` and ``unarchive_`` due to a naming issue, - they have been deprecated but not yet removed. + project.housekeeping() -Start the housekeeping job: +List the repository tree:: -.. literalinclude:: projects.py - :start-after: # housekeeping - :end-before: # end housekeeping + # list the content of the root directory for the default branch + items = project.repository_tree() -List the repository tree: + # list the content of a subdirectory on a specific branch + items = project.repository_tree(path='docs', ref='branch1') -.. literalinclude:: projects.py - :start-after: # repository tree - :end-before: # end repository tree +Get the content and metadata of a file for a commit, using a blob sha:: -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'] -.. literalinclude:: projects.py - :start-after: # repository blob - :end-before: # end repository blob +Get the repository archive:: -Get the repository archive: + tgz = project.repository_archive() -.. literalinclude:: projects.py - :start-after: # repository archive - :end-before: # end 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: +Get the content of a file using the blob id:: -.. literalinclude:: projects.py - :start-after: # repository raw_blob - :end-before: # end repository raw_blob + # 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>`. -Compare two branches, tags or commits: +Compare two branches, tags or commits:: + + result = project.repository_compare('master', 'branch1') -.. literalinclude:: projects.py - :start-after: # repository compare - :end-before: # end repository compare + # get the commits + for commit in result['commits']: + print(commit) -Get a list of contributors for the repository: + # get the diffs + for file_diff in result['diffs']: + print(file_diff) -.. literalinclude:: projects.py - :start-after: # repository contributors - :end-before: # end repository contributors +Get a list of contributors for the repository:: -Get a list of users for the repository: + contributors = project.repository_contributors() -.. literalinclude:: projects.py - :start-after: # users list - :end-before: # end users list +Get a list of users for the repository:: + + users = p.users.list() + + # search for users + users = p.users.list(search='pattern') Project custom attributes ========================= @@ -224,42 +232,46 @@ Reference + :class:`gitlab.v4.objects.ProjectFileManager` + :attr:`gitlab.v4.objects.Project.files` -* v3 API: - - + :class:`gitlab.v3.objects.ProjectFile` - + :class:`gitlab.v3.objects.ProjectFileManager` - + :attr:`gitlab.v3.objects.Project.files` - + :attr:`gitlab.Gitlab.project_files` - * GitLab API: https://docs.gitlab.com/ce/api/repository_files.html Examples -------- -Get a file: +Get a file:: + + f = project.files.get(file_path='README.rst', ref='master') -.. literalinclude:: projects.py - :start-after: # files get - :end-before: # end files get + # get the base64 encoded content + print(f.content) -Create a new file: + # get the decoded content + print(f.decode()) -.. literalinclude:: projects.py - :start-after: # files create - :end-before: # end files create +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: +encoded text:: + + f.content = 'new content' + f.save(branch='master', commit_message='Update testfile') -.. literalinclude:: projects.py - :start-after: # files update - :end-before: # end files update + # 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: +Delete a file:: -.. literalinclude:: projects.py - :start-after: # files delete - :end-before: # end files delete + f.delete(commit_message='Delete testfile') Project tags ============ @@ -273,47 +285,32 @@ Reference + :class:`gitlab.v4.objects.ProjectTagManager` + :attr:`gitlab.v4.objects.Project.tags` -* v3 API: - - + :class:`gitlab.v3.objects.ProjectTag` - + :class:`gitlab.v3.objects.ProjectTagManager` - + :attr:`gitlab.v3.objects.Project.tags` - + :attr:`gitlab.Gitlab.project_tags` - * GitLab API: https://docs.gitlab.com/ce/api/tags.html Examples -------- -List the project tags: +List the project tags:: -.. literalinclude:: projects.py - :start-after: # tags list - :end-before: # end tags list + tags = project.tags.list() -Get a tag: +Get a tag:: -.. literalinclude:: projects.py - :start-after: # tags get - :end-before: # end tags get + tag = project.tags.get('1.0') -Create a tag: +Create a tag:: -.. literalinclude:: projects.py - :start-after: # tags create - :end-before: # end tags create + tag = project.tags.create({'tag_name': '1.0', 'ref': 'master'}) -Set or update the release note for a tag: +Set or update the release note for a tag:: -.. literalinclude:: projects.py - :start-after: # tags release - :end-before: # end tags release + tag.set_release_description('awesome v1.0 release') -Delete a tag: +Delete a tag:: -.. literalinclude:: projects.py - :start-after: # tags delete - :end-before: # end tags delete + project.tags.delete('1.0') + # or + tag.delete() .. _project_snippets: @@ -335,58 +332,46 @@ Reference + :class:`gitlab.v4.objects.ProjectSnippetManager` + :attr:`gitlab.v4.objects.Project.files` -* v3 API: - - + :class:`gitlab.v3.objects.ProjectSnippet` - + :class:`gitlab.v3.objects.ProjectSnippetManager` - + :attr:`gitlab.v3.objects.Project.files` - + :attr:`gitlab.Gitlab.project_files` - * GitLab API: https://docs.gitlab.com/ce/api/project_snippets.html Examples -------- -List the project snippets: +List the project snippets:: -.. literalinclude:: projects.py - :start-after: # snippets list - :end-before: # end snippets list + snippets = project.snippets.list() -Get a snippet: +Get a snippet:: -.. literalinclude:: projects.py - :start-after: # snippets get - :end-before: # end snippets get + snippets = project.snippets.list(snippet_id) -Get the content of a snippet: +Get the content of a snippet:: -.. literalinclude:: projects.py - :start-after: # snippets content - :end-before: # end snippets content + 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: +Create a snippet:: -.. literalinclude:: projects.py - :start-after: # snippets create - :end-before: # end snippets create + snippet = project.snippets.create({'title': 'sample 1', + 'file_name': 'foo.py', + 'code': 'import gitlab', + 'visibility_level': + gitlab.VISIBILITY_PRIVATE}) -Update a snippet: +Update a snippet:: -.. literalinclude:: projects.py - :start-after: # snippets update - :end-before: # end snippets update + snippet.code = 'import gitlab\nimport whatever' + snippet.save -Delete a snippet: +Delete a snippet:: -.. literalinclude:: projects.py - :start-after: # snippets delete - :end-before: # end snippets delete + project.snippets.delete(snippet_id) + # or + snippet.delete() Notes ===== @@ -405,59 +390,43 @@ Reference + :class:`gitlab.v4.objects.ProjectMemberManager` + :attr:`gitlab.v4.objects.Project.members` -* v3 API: - - + :class:`gitlab.v3.objects.ProjectMember` - + :class:`gitlab.v3.objects.ProjectMemberManager` - + :attr:`gitlab.v3.objects.Project.members` - + :attr:`gitlab.Gitlab.project_members` - * GitLab API: https://docs.gitlab.com/ce/api/members.html Examples -------- -List the project members: +List the project members:: -.. literalinclude:: projects.py - :start-after: # members list - :end-before: # end members list + members = project.members.list() -Search project members matching a query string: +Search project members matching a query string:: -.. literalinclude:: projects.py - :start-after: # members search - :end-before: # end members search + members = project.members.list(query='bar') -Get a single project member: +Get a single project member:: -.. literalinclude:: projects.py - :start-after: # members get - :end-before: # end members get + member = project.members.get(1) -Add a project member: +Add a project member:: -.. literalinclude:: projects.py - :start-after: # members add - :end-before: # end members add + member = project.members.create({'user_id': user.id, 'access_level': + gitlab.DEVELOPER_ACCESS}) -Modify a project member (change the access level): +Modify a project member (change the access level):: -.. literalinclude:: projects.py - :start-after: # members update - :end-before: # end members update + member.access_level = gitlab.MASTER_ACCESS + member.save() -Remove a member from the project team: +Remove a member from the project team:: -.. literalinclude:: projects.py - :start-after: # members delete - :end-before: # end members delete + project.members.delete(user.id) + # or + member.delete() -Share the project with a group: +Share/unshare the project with a group:: -.. literalinclude:: projects.py - :start-after: # share - :end-before: # end share + project.share(group.id, gitlab.DEVELOPER_ACCESS) + project.unshare(group.id) Project hooks ============= @@ -471,47 +440,33 @@ Reference + :class:`gitlab.v4.objects.ProjectHookManager` + :attr:`gitlab.v4.objects.Project.hooks` -* v3 API: - - + :class:`gitlab.v3.objects.ProjectHook` - + :class:`gitlab.v3.objects.ProjectHookManager` - + :attr:`gitlab.v3.objects.Project.hooks` - + :attr:`gitlab.Gitlab.project_hooks` - * GitLab API: https://docs.gitlab.com/ce/api/projects.html#hooks Examples -------- -List the project hooks: +List the project hooks:: -.. literalinclude:: projects.py - :start-after: # hook list - :end-before: # end hook list + hooks = project.hooks.list() -Get a project hook: +Get a project hook:: -.. literalinclude:: projects.py - :start-after: # hook get - :end-before: # end hook get + hook = project.hooks.get(1) -Create a project hook: +Create a project hook:: -.. literalinclude:: projects.py - :start-after: # hook create - :end-before: # end hook create + hook = project.hooks.create({'url': 'http://my/action/url', 'push_events': 1}) -Update a project hook: +Update a project hook:: -.. literalinclude:: projects.py - :start-after: # hook update - :end-before: # end hook update + hook.push_events = 0 + hook.save() -Delete a project hook: +Delete a project hook:: -.. literalinclude:: projects.py - :start-after: # hook delete - :end-before: # end hook delete + project.hooks.delete(1) + # or + hook.delete() Project Services ================ @@ -525,41 +480,29 @@ Reference + :class:`gitlab.v4.objects.ProjectServiceManager` + :attr:`gitlab.v4.objects.Project.services` -* v3 API: - - + :class:`gitlab.v3.objects.ProjectService` - + :class:`gitlab.v3.objects.ProjectServiceManager` - + :attr:`gitlab.v3.objects.Project.services` - + :attr:`gitlab.Gitlab.project_services` - * GitLab API: https://docs.gitlab.com/ce/api/services.html Examples --------- -Get a service: +Get a service:: -.. literalinclude:: projects.py - :start-after: # service get - :end-before: # end service get + service = project.services.get('asana') + # display its status (enabled/disabled) + print(service.active) -List the code names of available services (doesn't return objects): +List the code names of available services (doesn't return objects):: -.. literalinclude:: projects.py - :start-after: # service list - :end-before: # end service list + services = project.services.available() -Configure and enable a service: +Configure and enable a service:: -.. literalinclude:: projects.py - :start-after: # service update - :end-before: # end service update + service.api_key = 'randomkey' + service.save() -Disable a service: +Disable a service:: -.. literalinclude:: projects.py - :start-after: # service delete - :end-before: # end service delete + service.delete() Issue boards ============ @@ -577,29 +520,18 @@ Reference + :class:`gitlab.v4.objects.ProjectBoardManager` + :attr:`gitlab.v4.objects.Project.boards` -* v3 API: - - + :class:`gitlab.v3.objects.ProjectBoard` - + :class:`gitlab.v3.objects.ProjectBoardManager` - + :attr:`gitlab.v3.objects.Project.boards` - + :attr:`gitlab.Gitlab.project_boards` - * GitLab API: https://docs.gitlab.com/ce/api/boards.html Examples -------- -Get the list of existing boards for a project: +Get the list of existing boards for a project:: -.. literalinclude:: projects.py - :start-after: # boards list - :end-before: # end boards list + boards = project.boards.list() -Get a single board for a project: +Get a single board for a project:: -.. literalinclude:: projects.py - :start-after: # boards get - :end-before: # end boards get + board = project.boards.get(board_id) Board lists =========== @@ -613,49 +545,35 @@ Reference + :class:`gitlab.v4.objects.ProjectBoardListManager` + :attr:`gitlab.v4.objects.Project.board_lists` -* v3 API: - - + :class:`gitlab.v3.objects.ProjectBoardList` - + :class:`gitlab.v3.objects.ProjectBoardListManager` - + :attr:`gitlab.v3.objects.ProjectBoard.lists` - + :attr:`gitlab.v3.objects.Project.board_lists` - + :attr:`gitlab.Gitlab.project_board_lists` - * GitLab API: https://docs.gitlab.com/ce/api/boards.html Examples -------- -List the issue lists for a board: +List the issue lists for a board:: -.. literalinclude:: projects.py - :start-after: # board lists list - :end-before: # end board lists list + b_lists = board.lists.list() -Get a single list: +Get a single list:: -.. literalinclude:: projects.py - :start-after: # board lists get - :end-before: # end board lists get + b_list = board.lists.get(list_id) -Create a new list: +Create a new list:: -.. literalinclude:: projects.py - :start-after: # board lists create - :end-before: # end board lists create + # 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: +set it at the given position and move the following lists up a position:: -.. literalinclude:: projects.py - :start-after: # board lists update - :end-before: # end board lists update + b_list.position = 2 + b_list.save() -Delete a list: +Delete a list:: -.. literalinclude:: projects.py - :start-after: # board lists delete - :end-before: # end board lists delete + b_list.delete() File uploads @@ -668,37 +586,33 @@ Reference + :attr:`gitlab.v4.objects.Project.upload` -* v3 API: - - + :attr:`gitlab.v3.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: +Upload a file into a project using a filesystem path:: -.. literalinclude:: projects.py - :start-after: # project file upload by path - :end-before: # end project file upload by path + project.upload("filename.txt", filepath="/some/path/filename.txt") -Upload a file into a project without a filesystem path: +Upload a file into a project without a filesystem path:: -.. literalinclude:: projects.py - :start-after: # project file upload with data - :end-before: # end project file upload with data + project.upload("filename.txt", filedata="Raw data") Upload a file and comment on an issue using the uploaded file's -markdown: +markdown:: -.. literalinclude:: projects.py - :start-after: # project file upload markdown - :end-before: # end project file upload 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: +markdown to reference the uploaded file:: -.. literalinclude:: projects.py - :start-after: # project file upload markdown custom - :end-before: # end project file upload markdown custom + 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"]) + }) diff --git a/docs/gl_objects/protected_branches.rst b/docs/gl_objects/protected_branches.rst index 4a6c837..006bb8b 100644 --- a/docs/gl_objects/protected_branches.rst +++ b/docs/gl_objects/protected_branches.rst @@ -19,26 +19,20 @@ References Examples -------- -Get the list of protected branches for a project: +Get the list of protected branches for a project:: -.. literalinclude:: branches.py - :start-after: # p_branch list - :end-before: # end p_branch list + p_branches = project.protectedbranches.list() -Get a single protected branch: +Get a single protected branch:: -.. literalinclude:: branches.py - :start-after: # p_branch get - :end-before: # end p_branch get + p_branch = project.protectedbranches.get('master') -Create a protected branch: +Create a protected branch:: -.. literalinclude:: branches.py - :start-after: # p_branch create - :end-before: # end p_branch create + p_branch = project.protectedbranches.create({'name': '*-stable'}) -Delete a protected branch: +Delete a protected branch:: -.. literalinclude:: branches.py - :start-after: # p_branch delete - :end-before: # end p_branch delete + project.protectedbranches.delete('*-stable') + # or + p_branch.delete() diff --git a/docs/gl_objects/runners.py b/docs/gl_objects/runners.py deleted file mode 100644 index 93aca0d..0000000 --- a/docs/gl_objects/runners.py +++ /dev/null @@ -1,36 +0,0 @@ -# list -# 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') -# end list - -# get -runner = gl.runners.get(runner_id) -# end get - -# update -runner = gl.runners.get(runner_id) -runner.tag_list.append('new_tag') -runner.save() -# end update - -# delete -gl.runners.delete(runner_id) -# or -runner.delete() -# end delete - -# project list -runners = project.runners.list() -# end project list - -# project enable -p_runner = project.runners.create({'runner_id': runner.id}) -# end project enable - -# project disable -project.runners.delete(runner.id) -# end project disable diff --git a/docs/gl_objects/runners.rst b/docs/gl_objects/runners.rst index e26c8af..70bd60f 100644 --- a/docs/gl_objects/runners.rst +++ b/docs/gl_objects/runners.rst @@ -20,12 +20,6 @@ Reference + :class:`gitlab.v4.objects.RunnerManager` + :attr:`gitlab.Gitlab.runners` -* v3 API: - - + :class:`gitlab.v3.objects.Runner` - + :class:`gitlab.v3.objects.RunnerManager` - + :attr:`gitlab.Gitlab.runners` - * GitLab API: https://docs.gitlab.com/ce/api/runners.html Examples @@ -47,27 +41,30 @@ for this parameter are: The returned objects hold minimal information about the runners. Use the ``get()`` method to retrieve detail about a runner. -.. literalinclude:: runners.py - :start-after: # list - :end-before: # end list +:: -Get a runner's detail: + # 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') -.. literalinclude:: runners.py - :start-after: # get - :end-before: # end get +Get a runner's detail:: -Update a runner: + runner = gl.runners.get(runner_id) -.. literalinclude:: runners.py - :start-after: # update - :end-before: # end update +Update a runner:: -Remove a runner: + runner = gl.runners.get(runner_id) + runner.tag_list.append('new_tag') + runner.save() -.. literalinclude:: runners.py - :start-after: # delete - :end-before: # end delete +Remove a runner:: + + gl.runners.delete(runner_id) + # or + runner.delete() Project runners =============== @@ -81,32 +78,19 @@ Reference + :class:`gitlab.v4.objects.ProjectRunnerManager` + :attr:`gitlab.v4.objects.Project.runners` -* v3 API: - - + :class:`gitlab.v3.objects.ProjectRunner` - + :class:`gitlab.v3.objects.ProjectRunnerManager` - + :attr:`gitlab.v3.objects.Project.runners` - + :attr:`gitlab.Gitlab.project_runners` - * GitLab API: https://docs.gitlab.com/ce/api/runners.html Examples -------- -List the runners for a project: +List the runners for a project:: -.. literalinclude:: runners.py - :start-after: # project list - :end-before: # end project list + runners = project.runners.list() -Enable a specific runner for a project: +Enable a specific runner for a project:: -.. literalinclude:: runners.py - :start-after: # project enable - :end-before: # end project enable + p_runner = project.runners.create({'runner_id': runner.id}) -Disable a specific runner for a project: +Disable a specific runner for a project:: -.. literalinclude:: runners.py - :start-after: # project disable - :end-before: # end project disable + project.runners.delete(runner.id) diff --git a/docs/gl_objects/settings.py b/docs/gl_objects/settings.py deleted file mode 100644 index 834d43d..0000000 --- a/docs/gl_objects/settings.py +++ /dev/null @@ -1,8 +0,0 @@ -# get -settings = gl.settings.get() -# end get - -# update -s.signin_enabled = False -s.save() -# end update diff --git a/docs/gl_objects/settings.rst b/docs/gl_objects/settings.rst index cf3fd4d..4accfe0 100644 --- a/docs/gl_objects/settings.rst +++ b/docs/gl_objects/settings.rst @@ -11,25 +11,16 @@ Reference + :class:`gitlab.v4.objects.ApplicationSettingsManager` + :attr:`gitlab.Gitlab.settings` -* v3 API: - - + :class:`gitlab.v3.objects.ApplicationSettings` - + :class:`gitlab.v3.objects.ApplicationSettingsManager` - + :attr:`gitlab.Gitlab.settings` - * GitLab API: https://docs.gitlab.com/ce/api/settings.html Examples -------- -Get the settings: +Get the settings:: -.. literalinclude:: settings.py - :start-after: # get - :end-before: # end get + settings = gl.settings.get() -Update the settings: +Update the settings:: -.. literalinclude:: settings.py - :start-after: # update - :end-before: # end update + settings.signin_enabled = False + settings.save() diff --git a/docs/gl_objects/sidekiq.rst b/docs/gl_objects/sidekiq.rst index 593dda0..5f44762 100644 --- a/docs/gl_objects/sidekiq.rst +++ b/docs/gl_objects/sidekiq.rst @@ -10,11 +10,6 @@ Reference + :class:`gitlab.v4.objects.SidekiqManager` + :attr:`gitlab.Gitlab.sidekiq` -* v3 API: - - + :class:`gitlab.v3.objects.SidekiqManager` - + :attr:`gitlab.Gitlab.sidekiq` - * GitLab API: https://docs.gitlab.com/ce/api/sidekiq_metrics.html Examples diff --git a/docs/gl_objects/snippets.py b/docs/gl_objects/snippets.py deleted file mode 100644 index 87d1a42..0000000 --- a/docs/gl_objects/snippets.py +++ /dev/null @@ -1,33 +0,0 @@ -# list -snippets = gl.snippets.list() -# end list - -# public list -public_snippets = gl.snippets.public() -# end public list - -# get -snippet = gl.snippets.get(snippet_id) -# get the content - API v4 -content = snippet.content() - -# get the content - API v3 -content = snippet.raw() -# end get - -# create -snippet = gl.snippets.create({'title': 'snippet1', - 'file_name': 'snippet1.py', - 'content': open('snippet1.py').read()}) -# end create - -# update -snippet.visibility_level = gitlab.Project.VISIBILITY_PUBLIC -snippet.save() -# end update - -# delete -gl.snippets.delete(snippet_id) -# or -snippet.delete() -# end delete diff --git a/docs/gl_objects/snippets.rst b/docs/gl_objects/snippets.rst index 34c39fb..5493db0 100644 --- a/docs/gl_objects/snippets.rst +++ b/docs/gl_objects/snippets.rst @@ -2,32 +2,33 @@ Snippets ######## -You can store code snippets in Gitlab. Snippets can be attached to projects -(see :ref:`project_snippets`), but can also be detached. +Reference +========= -* Object class: :class:`gitlab.objects.Namespace` -* Manager object: :attr:`gitlab.Gitlab.snippets` +* v4 API: + + + :class:`gitlab.v4.objects.Snippet` + + :class:`gitlab.v4.objects.SnipptManager` + + :attr:`gilab.Gitlab.snippets` + +* GitLab API: https://docs.gitlab.com/ce/api/snippets.html Examples ======== -List snippets woned by the current user: +List snippets owned by the current user:: -.. literalinclude:: snippets.py - :start-after: # list - :end-before: # end list + snippets = gl.snippets.list() -List the public snippets: +List the public snippets:: -.. literalinclude:: snippets.py - :start-after: # public list - :end-before: # end public list + public_snippets = gl.snippets.public() -Get a snippet: +Get a snippet:: -.. literalinclude:: snippets.py - :start-after: # get - :end-before: # end get + snippet = gl.snippets.get(snippet_id) + # get the content + content = snippet.content() .. warning:: @@ -35,20 +36,19 @@ Get a snippet: See :ref:`the artifacts example <streaming_example>`. -Create a snippet: +Create a snippet:: -.. literalinclude:: snippets.py - :start-after: # create - :end-before: # end create + snippet = gl.snippets.create({'title': 'snippet1', + 'file_name': 'snippet1.py', + 'content': open('snippet1.py').read()}) -Update a snippet: +Update a snippet:: -.. literalinclude:: snippets.py - :start-after: # update - :end-before: # end update + snippet.visibility_level = gitlab.Project.VISIBILITY_PUBLIC + snippet.save() -Delete a snippet: +Delete a snippet:: -.. literalinclude:: snippets.py - :start-after: # delete - :end-before: # end delete + gl.snippets.delete(snippet_id) + # or + snippet.delete() diff --git a/docs/gl_objects/system_hooks.py b/docs/gl_objects/system_hooks.py deleted file mode 100644 index 9bc487b..0000000 --- a/docs/gl_objects/system_hooks.py +++ /dev/null @@ -1,17 +0,0 @@ -# list -hooks = gl.hooks.list() -# end list - -# test -gl.hooks.get(hook_id) -# end test - -# create -hook = gl.hooks.create({'url': 'http://your.target.url'}) -# end create - -# delete -gl.hooks.delete(hook_id) -# or -hook.delete() -# end delete diff --git a/docs/gl_objects/system_hooks.rst b/docs/gl_objects/system_hooks.rst index a9e9fee..6203168 100644 --- a/docs/gl_objects/system_hooks.rst +++ b/docs/gl_objects/system_hooks.rst @@ -11,37 +11,25 @@ Reference + :class:`gitlab.v4.objects.HookManager` + :attr:`gitlab.Gitlab.hooks` -* v3 API: - - + :class:`gitlab.v3.objects.Hook` - + :class:`gitlab.v3.objects.HookManager` - + :attr:`gitlab.Gitlab.hooks` - * GitLab API: https://docs.gitlab.com/ce/api/system_hooks.html Examples -------- -List the system hooks: +List the system hooks:: -.. literalinclude:: system_hooks.py - :start-after: # list - :end-before: # end list + hooks = gl.hooks.list() -Create a system hook: +Create a system hook:: -.. literalinclude:: system_hooks.py - :start-after: # create - :end-before: # end create + gl.hooks.get(hook_id) -Test a system hook. The returned object is not usable (it misses the hook ID): +Test a system hook. The returned object is not usable (it misses the hook ID):: -.. literalinclude:: system_hooks.py - :start-after: # test - :end-before: # end test + hook = gl.hooks.create({'url': 'http://your.target.url'}) -Delete a system hook: +Delete a system hook:: -.. literalinclude:: system_hooks.py - :start-after: # delete - :end-before: # end delete + gl.hooks.delete(hook_id) + # or + hook.delete() diff --git a/docs/gl_objects/templates.py b/docs/gl_objects/templates.py deleted file mode 100644 index 0874dc7..0000000 --- a/docs/gl_objects/templates.py +++ /dev/null @@ -1,35 +0,0 @@ -# license list -licenses = gl.licenses.list() -# end license list - -# license get -license = gl.licenses.get('apache-2.0', project='foobar', fullname='John Doe') -print(license.content) -# end license get - -# gitignore list -gitignores = gl.gitignores.list() -# end gitignore list - -# gitignore get -gitignore = gl.gitignores.get('Python') -print(gitignore.content) -# end gitignore get - -# gitlabciyml list -gitlabciymls = gl.gitlabciymls.list() -# end gitlabciyml list - -# gitlabciyml get -gitlabciyml = gl.gitlabciymls.get('Pelican') -print(gitlabciyml.content) -# end gitlabciyml get - -# dockerfile list -dockerfiles = gl.dockerfiles.list() -# end dockerfile list - -# dockerfile get -dockerfile = gl.dockerfiles.get('Python') -print(dockerfile.content) -# end dockerfile get diff --git a/docs/gl_objects/templates.rst b/docs/gl_objects/templates.rst index c43b7ae..f939e5f 100644 --- a/docs/gl_objects/templates.rst +++ b/docs/gl_objects/templates.rst @@ -21,28 +21,19 @@ Reference + :class:`gitlab.v4.objects.LicenseManager` + :attr:`gitlab.Gitlab.licenses` -* v3 API: - - + :class:`gitlab.v3.objects.License` - + :class:`gitlab.v3.objects.LicenseManager` - + :attr:`gitlab.Gitlab.licenses` - * GitLab API: https://docs.gitlab.com/ce/api/templates/licenses.html Examples -------- -List known license templates: +List known license templates:: -.. literalinclude:: templates.py - :start-after: # license list - :end-before: # end license list + licenses = gl.licenses.list() -Generate a license content for a project: +Generate a license content for a project:: -.. literalinclude:: templates.py - :start-after: # license get - :end-before: # end license get + license = gl.licenses.get('apache-2.0', project='foobar', fullname='John Doe') + print(license.content) .gitignore templates ==================== @@ -56,28 +47,19 @@ Reference + :class:`gitlab.v4.objects.GitignoreManager` + :attr:`gitlab.Gitlab.gitignores` -* v3 API: - - + :class:`gitlab.v3.objects.Gitignore` - + :class:`gitlab.v3.objects.GitignoreManager` - + :attr:`gitlab.Gitlab.gitignores` - * GitLab API: https://docs.gitlab.com/ce/api/templates/gitignores.html Examples -------- -List known gitignore templates: +List known gitignore templates:: -.. literalinclude:: templates.py - :start-after: # gitignore list - :end-before: # end gitignore list + gitignores = gl.gitignores.list() -Get a gitignore template: +Get a gitignore template:: -.. literalinclude:: templates.py - :start-after: # gitignore get - :end-before: # end gitignore get + gitignore = gl.gitignores.get('Python') + print(gitignore.content) GitLab CI templates =================== @@ -91,28 +73,19 @@ Reference + :class:`gitlab.v4.objects.GitlabciymlManager` + :attr:`gitlab.Gitlab.gitlabciymls` -* v3 API: - - + :class:`gitlab.v3.objects.Gitlabciyml` - + :class:`gitlab.v3.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: +List known GitLab CI templates:: -.. literalinclude:: templates.py - :start-after: # gitlabciyml list - :end-before: # end gitlabciyml list + gitlabciymls = gl.gitlabciymls.list() -Get a GitLab CI template: +Get a GitLab CI template:: -.. literalinclude:: templates.py - :start-after: # gitlabciyml get - :end-before: # end gitlabciyml get + gitlabciyml = gl.gitlabciymls.get('Pelican') + print(gitlabciyml.content) Dockerfile templates ==================== @@ -131,14 +104,11 @@ Reference Examples -------- -List known Dockerfile templates: +List known Dockerfile templates:: -.. literalinclude:: templates.py - :start-after: # dockerfile list - :end-before: # end dockerfile list + dockerfiles = gl.dockerfiles.list() -Get a Dockerfile template: +Get a Dockerfile template:: -.. literalinclude:: templates.py - :start-after: # dockerfile get - :end-before: # end dockerfile get + dockerfile = gl.dockerfiles.get('Python') + print(dockerfile.content) diff --git a/docs/gl_objects/todos.py b/docs/gl_objects/todos.py deleted file mode 100644 index 74ec211..0000000 --- a/docs/gl_objects/todos.py +++ /dev/null @@ -1,22 +0,0 @@ -# list -todos = gl.todos.list() -# end list - -# filter -todos = gl.todos.list(project_id=1) -todos = gl.todos.list(state='done', type='Issue') -# end filter - -# get -todo = gl.todos.get(todo_id) -# end get - -# delete -gl.todos.delete(todo_id) -# or -todo.delete() -# end delete - -# all_delete -nb_of_closed_todos = gl.todos.delete_all() -# end all_delete diff --git a/docs/gl_objects/todos.rst b/docs/gl_objects/todos.rst index bd7f1fa..a01aa43 100644 --- a/docs/gl_objects/todos.rst +++ b/docs/gl_objects/todos.rst @@ -2,17 +2,23 @@ Todos ##### -Use :class:`~gitlab.objects.Todo` objects to manipulate todos. The -:attr:`gitlab.Gitlab.todos` manager object provides helper functions. +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: +List active todos:: -.. literalinclude:: todos.py - :start-after: # list - :end-before: # end list + todos = gl.todos.list() You can filter the list using the following parameters: @@ -23,26 +29,17 @@ You can filter the list using the following parameters: * ``state``: can be ``pending`` or ``done`` * ``type``: can be ``Issue`` or ``MergeRequest`` -For example: - -.. literalinclude:: todos.py - :start-after: # filter - :end-before: # end filter - -Get a single todo: +For example:: -.. literalinclude:: todos.py - :start-after: # get - :end-before: # end get + todos = gl.todos.list(project_id=1) + todos = gl.todos.list(state='done', type='Issue') -Mark a todo as done: +Mark a todo as done:: -.. literalinclude:: todos.py - :start-after: # delete - :end-before: # end delete + gl.todos.delete(todo_id) + # or + todo.delete() -Mark all the todos as done: +Mark all the todos as done:: -.. literalinclude:: todos.py - :start-after: # all_delete - :end-before: # end all_delete + nb_of_closed_todos = gl.todos.delete_all() diff --git a/docs/gl_objects/users.py b/docs/gl_objects/users.py deleted file mode 100644 index 842e35d..0000000 --- a/docs/gl_objects/users.py +++ /dev/null @@ -1,118 +0,0 @@ -# list -users = gl.users.list() -# end list - -# search -users = gl.users.list(search='oo') -# end search - -# get -# by ID -user = gl.users.get(2) -# by username -user = gl.users.list(username='root')[0] -# end get - -# create -user = gl.users.create({'email': 'john@doe.com', - 'password': 's3cur3s3cr3T', - 'username': 'jdoe', - 'name': 'John Doe'}) -# end create - -# update -user.name = 'Real Name' -user.save() -# end update - -# delete -gl.users.delete(2) -user.delete() -# end delete - -# block -user.block() -user.unblock() -# end block - -# key list -keys = user.keys.list() -# end key list - -# key get -key = user.keys.get(1) -# end key get - -# key create -k = user.keys.create({'title': 'my_key', - 'key': open('/home/me/.ssh/id_rsa.pub').read()}) -# end key create - -# key delete -user.keys.delete(1) -# or -key.delete() -# end key delete - -# gpgkey list -gpgkeys = user.gpgkeys.list() -# end gpgkey list - -# gpgkey get -gpgkey = user.gpgkeys.get(1) -# end gpgkey get - -# gpgkey create -# get the key with `gpg --export -a GPG_KEY_ID` -k = user.gpgkeys.create({'key': public_key_content}) -# end gpgkey create - -# gpgkey delete -user.gpgkeys.delete(1) -# or -gpgkey.delete() -# end gpgkey delete - -# email list -emails = user.emails.list() -# end email list - -# email get -email = gl.user_emails.list(1, user_id=1) -# or -email = user.emails.get(1) -# end email get - -# email create -k = user.emails.create({'email': 'foo@bar.com'}) -# end email create - -# email delete -user.emails.delete(1) -# or -email.delete() -# end email delete - -# currentuser get -gl.auth() -current_user = gl.user -# end currentuser get - -# it list -i_t = user.impersonationtokens.list(state='active') -i_t = user.impersonationtokens.list(state='inactive') -# end it list - -# it get -i_t = user.impersonationtokens.get(i_t_id) -# end it get - -# it create -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) -# end it create - -# it delete -i_t.delete() -# end it delete diff --git a/docs/gl_objects/users.rst b/docs/gl_objects/users.rst index bbb96ee..a1d6dd6 100644 --- a/docs/gl_objects/users.rst +++ b/docs/gl_objects/users.rst @@ -19,58 +19,47 @@ References + :class:`gitlab.v4.objects.UserManager` + :attr:`gitlab.Gitlab.users` -* v3 API: - - + :class:`gitlab.v3.objects.User` - + :class:`gitlab.v3.objects.UserManager` - + :attr:`gitlab.Gitlab.users` - * GitLab API: https://docs.gitlab.com/ce/api/users.html Examples -------- -Get the list of users: +Get the list of users:: -.. literalinclude:: users.py - :start-after: # list - :end-before: # end list + users = gl.users.list() -Search users whose username match the given string: +Search users whose username match a given string:: -.. literalinclude:: users.py - :start-after: # search - :end-before: # end search + users = gl.users.list(search='foo') -Get a single user: +Get a single user:: -.. literalinclude:: users.py - :start-after: # get - :end-before: # end get + # by ID + user = gl.users.get(2) + # by username + user = gl.users.list(username='root')[0] -Create a user: +Create a user:: -.. literalinclude:: users.py - :start-after: # create - :end-before: # end create + user = gl.users.create({'email': 'john@doe.com', + 'password': 's3cur3s3cr3T', + 'username': 'jdoe', + 'name': 'John Doe'}) -Update a user: +Update a user:: -.. literalinclude:: users.py - :start-after: # update - :end-before: # end update + user.name = 'Real Name' + user.save() -Delete a user: +Delete a user:: -.. literalinclude:: users.py - :start-after: # delete - :end-before: # end delete + gl.users.delete(2) + user.delete() -Block/Unblock a user: +Block/Unblock a user:: -.. literalinclude:: users.py - :start-after: # block - :end-before: # end block + user.block() + user.unblock() User custom attributes ====================== @@ -126,29 +115,24 @@ References * GitLab API: https://docs.gitlab.com/ce/api/users.html#get-all-impersonation-tokens-of-a-user -List impersonation tokens for a user: +List impersonation tokens for a user:: -.. literalinclude:: users.py - :start-after: # it list - :end-before: # end it list + i_t = user.impersonationtokens.list(state='active') + i_t = user.impersonationtokens.list(state='inactive') -Get an impersonation token for a user: +Get an impersonation token for a user:: -.. literalinclude:: users.py - :start-after: # it get - :end-before: # end it get + i_t = user.impersonationtokens.get(i_t_id) -Create and use an impersonation token for a user: +Create and use an impersonation token for a user:: -.. literalinclude:: users.py - :start-after: # it create - :end-before: # end it create + 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: +Revoke (delete) an impersonation token for a user:: -.. literalinclude:: users.py - :start-after: # it delete - :end-before: # end it delete + i_t.delete() Current User ============ @@ -162,22 +146,15 @@ References + :class:`gitlab.v4.objects.CurrentUserManager` + :attr:`gitlab.Gitlab.user` -* v3 API: - - + :class:`gitlab.v3.objects.CurrentUser` - + :class:`gitlab.v3.objects.CurrentUserManager` - + :attr:`gitlab.Gitlab.user` - * GitLab API: https://docs.gitlab.com/ce/api/users.html Examples -------- -Get the current user: +Get the current user:: -.. literalinclude:: users.py - :start-after: # currentuser get - :end-before: # end currentuser get + gl.auth() + current_user = gl.user GPG keys ======== @@ -202,29 +179,24 @@ are admin. Exemples -------- -List GPG keys for a user: +List GPG keys for a user:: -.. literalinclude:: users.py - :start-after: # gpgkey list - :end-before: # end gpgkey list + gpgkeys = user.gpgkeys.list() -Get a GPG gpgkey for a user: +Get a GPG gpgkey for a user:: -.. literalinclude:: users.py - :start-after: # gpgkey get - :end-before: # end gpgkey get + gpgkey = user.gpgkeys.get(1) -Create a GPG gpgkey for a user: +Create a GPG gpgkey for a user:: -.. literalinclude:: users.py - :start-after: # gpgkey create - :end-before: # end gpgkey create + # 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: +Delete a GPG gpgkey for a user:: -.. literalinclude:: users.py - :start-after: # gpgkey delete - :end-before: # end gpgkey delete + user.gpgkeys.delete(1) + # or + gpgkey.delete() SSH keys ======== @@ -244,45 +216,25 @@ are admin. + :class:`gitlab.v4.objects.UserKeyManager` + :attr:`gitlab.v4.objects.User.keys` -* v3 API: - - + :class:`gitlab.v3.objects.CurrentUserKey` - + :class:`gitlab.v3.objects.CurrentUserKeyManager` - + :attr:`gitlab.v3.objects.CurrentUser.keys` - + :attr:`gitlab.Gitlab.user.keys` - + :class:`gitlab.v3.objects.UserKey` - + :class:`gitlab.v3.objects.UserKeyManager` - + :attr:`gitlab.v3.objects.User.keys` - + :attr:`gitlab.Gitlab.user_keys` - * GitLab API: https://docs.gitlab.com/ce/api/users.html#list-ssh-keys Exemples -------- -List SSH keys for a user: +List SSH keys for a user:: -.. literalinclude:: users.py - :start-after: # key list - :end-before: # end key list + keys = user.keys.list() -Get an SSH key for a user: +Create an SSH key for a user:: -.. literalinclude:: users.py - :start-after: # key get - :end-before: # end key get + k = user.keys.create({'title': 'my_key', + 'key': open('/home/me/.ssh/id_rsa.pub').read()}) -Create an SSH key for a user: +Delete an SSH key for a user:: -.. literalinclude:: users.py - :start-after: # key create - :end-before: # end key create - -Delete an SSH key for a user: - -.. literalinclude:: users.py - :start-after: # key delete - :end-before: # end key delete + user.keys.delete(1) + # or + key.delete() Emails ====== @@ -302,45 +254,30 @@ are admin. + :class:`gitlab.v4.objects.UserEmailManager` + :attr:`gitlab.v4.objects.User.emails` -* v3 API: - - + :class:`gitlab.v3.objects.CurrentUserEmail` - + :class:`gitlab.v3.objects.CurrentUserEmailManager` - + :attr:`gitlab.v3.objects.CurrentUser.emails` - + :attr:`gitlab.Gitlab.user.emails` - + :class:`gitlab.v3.objects.UserEmail` - + :class:`gitlab.v3.objects.UserEmailManager` - + :attr:`gitlab.v3.objects.User.emails` - + :attr:`gitlab.Gitlab.user_emails` - * GitLab API: https://docs.gitlab.com/ce/api/users.html#list-emails Exemples -------- -List emails for a user: +List emails for a user:: -.. literalinclude:: users.py - :start-after: # email list - :end-before: # end email list + emails = user.emails.list() -Get an email for a user: +Get an email for a user:: -.. literalinclude:: users.py - :start-after: # email get - :end-before: # end email get + email = gl.user_emails.list(1, user_id=1) + # or + email = user.emails.get(1) -Create an email for a user: +Create an email for a user:: -.. literalinclude:: users.py - :start-after: # email create - :end-before: # end email create + k = user.emails.create({'email': 'foo@bar.com'}) -Delete an email for a user: +Delete an email for a user:: -.. literalinclude:: users.py - :start-after: # email delete - :end-before: # end email delete + user.emails.delete(1) + # or + email.delete() Users activities ================ @@ -348,7 +285,6 @@ Users activities References ---------- -* v4 only * admin only * v4 API: @@ -362,8 +298,6 @@ References Examples -------- -Get the users activities: - -.. code-block:: python +Get the users activities:: - activities = gl.user_activities.list(all=True, as_list=False) + activities = gl.user_activities.list(all=True, as_list=False) diff --git a/docs/gl_objects/wikis.py b/docs/gl_objects/wikis.py deleted file mode 100644 index 0c92fe6..0000000 --- a/docs/gl_objects/wikis.py +++ /dev/null @@ -1,21 +0,0 @@ -# list -pages = project.wikis.list() -# end list - -# get -page = project.wikis.get(page_slug) -# end get - -# create -page = project.wikis.create({'title': 'Wiki Page 1', - 'content': open(a_file).read()}) -# end create - -# update -page.content = 'My new content' -page.save() -# end update - -# delete -page.delete() -# end delete diff --git a/docs/gl_objects/wikis.rst b/docs/gl_objects/wikis.rst index 0934654..622c3a2 100644 --- a/docs/gl_objects/wikis.rst +++ b/docs/gl_objects/wikis.rst @@ -12,35 +12,29 @@ References + :class:`gitlab.v4.objects.ProjectWikiManager` + :attr:`gitlab.v4.objects.Project.wikis` +* GitLab API: https://docs.gitlab.com/ce/api/wikis.html + Examples -------- -Get the list of wiki pages for a project: +Get the list of wiki pages for a project:: -.. literalinclude:: wikis.py - :start-after: # list - :end-before: # end list + pages = project.wikis.list() -Get a single wiki page: +Get a single wiki page:: -.. literalinclude:: wikis.py - :start-after: # get - :end-before: # end get + page = project.wikis.get(page_slug) -Create a wiki page: +Create a wiki page:: -.. literalinclude:: wikis.py - :start-after: # create - :end-before: # end create + page = project.wikis.create({'title': 'Wiki Page 1', + 'content': open(a_file).read()}) -Update a wiki page: +Update a wiki page:: -.. literalinclude:: wikis.py - :start-after: # update - :end-before: # end update + page.content = 'My new content' + page.save() -Delete a wiki page: +Delete a wiki page:: -.. literalinclude:: wikis.py - :start-after: # delete - :end-before: # end delete + page.delete() |