Developer Interface¶

This part of the documentation covers all the interfaces of pGerrit

pGerrit.change.GerritClient¶

class pGerrit.change.GerritClient(host, auth=None, verify=True, adapter=None, cache=True, cache_expire=3)[source]¶

A class representing a Gerrit REST API client.

Parameters

host (str) – The full URL to the server, including the http(s):// prefix.
auth (requests.auth.HTTPDigestAuth or None) – (optional) Authentication handler. Must be derived from requests.auth.HTTPDigestAuth.
cookies (requests.cookies.RequestsCookieJar or dict) – (optional) Cookie jar to be used in the session.
verify (bool) – (optional) Set to False to disable verification of SSL certificates.
adapter (requests.adapters.BaseAdapter or None) – (optional) Custom connection adapter. Normally we use it to set urllib3.util.Rety object. By default, there is 5 times retry behaviour.
cache (bool) – (optional) Set to True to enable cache support. Defaults to True.
cache_expire (int) – (optional) The number of seconds to expire the cache after. Defaults to 3.

Returns

An instance of GerritClient.

Return type

pGerrit.GerritClient

property change¶

Provides an instance of GerritChange for the given Gerrit client configuration.

Parameters: id (str) – the Change-id of Gerrit
Returns: An instance of GerritChangeQueryDescriptor.
Return type: pGerrit.queryDescriptor.GerritChangeQueryDescriptor

Usage:

gerrit_client = GerritClient(...)
changes = gerrit_client.change.query(...)
change = gerrit_client.change(12345).detail()

property access¶

Provides an instance of GerritAccess for the given Gerrit client configuration.

Returns: An instance of GerritAccessQueryDescriptor.
Return type: pGerrit.queryDescriptor.GerritAccessQueryDescriptor

Usage:

gerrit_client = GerritClient(...)
access = gerrit_client.access.query(...)

property project¶

Provides an instance of GerritProject for the given Gerrit client configuration.

Returns: An instance of GerritProjectQueryDescriptor.
Return type: pGerrit.queryDescriptor.GerritProjectQueryDescriptor

Usage:

gerrit_client = GerritClient(...)
projects = gerrit_client.project.query(...)
project = gerrit_client.project("test")

pGerrit.change.GerritChange¶

class pGerrit.change.GerritChange(host, gerritID, auth=None, verify=True, adapter=None, cache=True, cache_expire=3)[source]¶

Class maps /changes/ endpoint of Gerrit REST API

Returns: An instance of GerritChange.
Return type: pGerrit.change.GerritChange

You won’t need to instantiate this Class directly. Use pGerrit.GerritClient.change

classmethod query(*args, **kwargs)[source]¶

Performs a GET request to query for changes from the Gerrit API.

API URL: /a/changes/

Input type: QueryOptions

Return type: List[ChangeInfo]

Usage:

change.query(
    q="owner:self status:merged",
    **{
        "no-limit": "",
        "o": [
            "CURRENT_REVISION",
            "CURRENT_COMMIT"
        ]
    }
)

classmethod create(payload=None, *args, **kwargs)[source]¶

Performs a POST request to create for changes from the Gerrit API.

API URL: /a/changes/

Input type: ChangeInput

Return type: List[ChangeInfo]

Usage:

change.create(payload=
    {
        "project": "xxx",
        "branch": "xxx",
        "subject": "xxx"
    }
)

info(*args, **kwargs)[source]¶

Performs a GET request to retrieve information about a change.

API URL: /a/changes/{change_id}

Input type: QueryOptions

Return type: ChangeInfo

Usage:

change.info(**{o":["CURRENT_REVISION", "CURRENT_COMMIT"]})

detail(*args, **kwargs)[source]¶

Performs a GET request to retrieve detailed information about a change.

API URL: /a/changes/{change_id}/detail

Input type: QueryOptions

Return type: ChangeInfo with additional fields

Usage:

change.detail(**{"o":["CURRENT_REVISION", "CURRENT_COMMIT"]})

topic(*args, **kwargs)[source]¶

Performs a GET request to retrieve the topic of a change.

API URL: /a/changes/{change_id}/topic

Input type: None

Return type: str

Usage:

change.topic()

set_topic(*args, **kwargs)[source]¶

Performs a PUT request to set the topic of a change.

API URL: /a/changes/{change_id}/topic

Input type: TopicInput

Return type: str

Usage:

change.set_topic({"topic": "new-topic"})

delete_topic(*args, **kwargs)[source]¶

Performs a PUT request to set the topic of a change.

API URL: /a/changes/{change_id}/topic

Input type: None

Return type: None

Usage:

change.delete_topic()

submitted_together(*args, **kwargs)[source]¶

Performs a GET request to retrieve the list of changes that would be submitted together with a change.

API URL: /a/changes/{change_id}/submitted_together

Input type: None

Return type: SubmittedTogetherInfo

Usage:

change.submitted_together()

in_(*args, **kwargs)[source]¶

Performs a GET request to retrieve the list of changes that are included in a change.

API URL: /a/changes/{change_id}/in

Input type: None

Return type: RelatedChangesInfo

Usage:

change.in_()

comments(*args, **kwargs)[source]¶

Performs a GET request to retrieve comments on a change.

API URL: /a/changes/{change_id}/comments

Input type: None

Return type: Dict[str, List[CommentInfo]]

Usage:

change.comments()

robotcomments(*args, **kwargs)[source]¶

Performs a GET request to retrieve robot comments on a change.

API URL: /a/changes/{change_id}/robotcomments

Input type: None

Return type: Dict[str, List[RobotCommentInfo]]

Usage:

change.robotcomments()

drafts(*args, **kwargs)[source]¶

Performs a GET request to retrieve draft comments on a change.

API URL: /a/changes/{change_id}/drafts

Input type: None

Return type: Dict[str, List[CommentInfo]]

Usage:

change.drafts()

check(*args, **kwargs)[source]¶

Performs a GET request to check the consistency of a change.

API URL: /a/changes/{change_id}/check

Input type: None

Return type: List[ChangeInfo with problems fields]

Usage:

change.check()

hashtags(*args, **kwargs)[source]¶

Performs a GET request to retrieve the hashtags associated with a change.

API URL: /a/changes/{change_id}/hashtags

Input type: None

Return type: List[str]

Usage:

change.hashtags()

set_hashtags(payload=None, *args, **kwargs)[source]¶

Performs a POST request to add or remove hashtags from a change.

API URL: /a/changes/{change_id}/hashtags

Input type: HashtagsInput

Return type: List[str]

Usage:

change.set_hashtags(payload={"add":["tag1"], "remove":["tag2"]})

rebase(payload=None, headers=None)[source]¶

Performs a POST request to rebase a change.

API URL: /a/changes/{change_id}/rebase

Input type: RebaseInput (optional)

Return type: ChangeInfo

Usage:

change.rebase()

merge(payload=None, headers=None)[source]¶

Performs a POST request to create merge patch set for change.

API URL: /a/changes/{change_id}/merge

Input type: MergePatchSetInput

Return type: ChangeInfo

Usage:

change.merge()

delete_change(payload=None, headers=None)[source]¶

Performs a DELETE request to delete a change.

API URL: /a/changes/{change_id}

Input type: None

Return type: None

Usage:

change.delete_change()

is_merge()[source]¶

Checks if the change is a merge change.

Usage:

is_merge_change = change.is_merge()

revision(revisionID)[source]¶

Creates a GerritChangeRevision object for a specific revision of the change.

Parameters: revisionID – The revision ID (commit SHA1 or numeric ID)

Usage:

change_revision = change.revision(revisionID)

current_revision()[source]¶

Creates a GerritChangeRevision object for the current revision of the change.

Usage:

current_revision = change.current_revision()

property edit¶

Provides an instance of GerritChangeEditQueryDescriptor for the given Gerrit client configuration.

Returns: An instance of GerritChangeEditQueryDescriptor.
Return type: pGerrit.queryDescriptor.GerritChangeEditQueryDescriptor

Usage:

change = GerritChange(...)
edit_info = change.edit.info()
edited_content = change.edit("COMMIT_MSG").edit_retrieve()

property reviewer¶

Provides an instance of GerritChangeReviewerQueryDescriptor for the given Gerrit client configuration.

Returns: An instance of GerritChangeReviewerQueryDescriptor.
Return type: pGerrit.queryDescriptor.GerritChangeReviewerQueryDescriptor

Usage:

change = GerritChange(...)
reviewers = change.reviewer.query()
suggested_reviewers = change.reviewer.suggest_reviewers(q="john")
result = change.reviewer.add_reviewer({"reviewer": "example@example.com"})

pGerrit.change.GerritChangeRevision¶

class pGerrit.change.GerritChangeRevision(host, gerritID, revisionID, auth=None, verify=True, adapter=None, cache=True, cache_expire=3)[source]¶

Class maps /a/changes/{change_id}/revisions/{revision_id} endpoint of Gerrit REST API

Returns: An instance of GerritChangeRevision.
Return type: pGerrit.change.GerritChangeRevision

You won’t need to instantiate this Class directly. Use pGerrit.change.GerritChange.revision

commit(*args, **kwargs)[source]¶

Performs a GET request to retrieve the commit associated with the change revision.

API URL: /a/changes/{change_id}/revisions/{revision_id}/commit

Input type: None

Return type: CommitInfo

Usage:

commit_info = revision.commit()

actions(*args, **kwargs)[source]¶

Performs a GET request to retrieve the available actions for the change revision.

API URL: /a/changes/{change_id}/revisions/{revision_id}/actions

Input type: None

Return type: Dict[str, ActionInfo]

Usage:

actions = revision.actions()

review(*args, **kwargs)[source]¶

Performs a GET request to retrieve the review labels for the change revision.

API URL: /a/changes/{change_id}/revisions/{revision_id}/review

Input type: None

Return type: ReviewInfo

Usage:

review_info = revision.review()

set_review(payload=None, headers=None)[source]¶

Performs a POST request to set a review for the change revision.

API URL: /a/changes/{change_id}/revisions/{revision_id}/review

Input type: ReviewInput

Return type: ReviewResult

Usage:

review_result = revision.set_review(payload)

related(*args, **kwargs)[source]¶

Performs a GET request to retrieve related changes and revisions for the change revision.

API URL: /a/changes/{change_id}/revisions/{revision_id}/related

Input type: None

Return type: RelatedChangesInfo

Usage:

related_changes = revision.related()

patch(*args, **kwargs)[source]¶

Performs a GET request to retrieve the patch for the change revision.

API URL: /a/changes/{change_id}/revisions/{revision_id}/patch

Input type: None

Return type: str (Base64-encoded patch text)

Usage:

patch_text = revision.patch()

mergeable(*args, **kwargs)[source]¶

Performs a GET request to check if the change revision is mergeable.

API URL: /a/changes/{change_id}/revisions/{revision_id}/mergeable

Input type: None

Return type: MergeableInfo

Usage:

mergeable_info = revision.mergeable()

submit_type(*args, **kwargs)[source]¶

Performs a GET request to retrieve the submit type of the change revision.

API URL: /a/changes/{change_id}/revisions/{revision_id}/submit_type

Input type: None

Return type: str (Submit type)

Usage:

submit_type = revision.submit_type()

drafts(*args, **kwargs)[source]¶

Performs a GET request to retrieve the draft comments on the change revision.

API URL: /a/changes/{change_id}/revisions/{revision_id}/drafts

Input type: None

Return type: List[CommentInfo]

Usage:

drafts = revision.drafts()

comments(*args, **kwargs)[source]¶

Performs a GET request to retrieve the published comments on the change revision.

API URL: /a/changes/{change_id}/revisions/{revision_id}/comments

Input type: None

Return type: Dict[str, List[CommentInfo]]

Usage:

comments = revision.comments()

files(*args, **kwargs)[source]¶

Performs a GET request to retrieve the files of the change revision.

API URL: /a/changes/{change_id}/revisions/{revision_id}/files

Input type: None

Return type: Dict[str, FileInfo]

Usage:

files = revision.files()

cherrypick(payload=None, headers=None)[source]¶

Performs a POST request to cherry-pick the change revision.

API URL: /a/changes/{change_id}/revisions/{revision_id}/cherrypick

Input type: CherryPickInput

Return type: ChangeInfo

Usage:

cherrypick_result = revision.cherrypick(payload={"destination": "branch_name"})

file(fileID)[source]¶

Get the GerritChangeRevisionFile instance for a specific file in the change revision.

Parameters: fileID (str) – The ID of the file.
Returns: A GerritChangeRevisionFile instance for the specified file.
Return type: pGerrit.change.GerritChangeRevisionFile

Usage:

file_instance = revision.file(fileID)

reviewer(accountID)[source]¶

Get the GerritChangeRevisionReviewer instance for a specific reviewer of the change revision.

Parameters: accountID (str) – The ID of the reviewer.
Returns: A GerritChangeRevisionReviewer instance for the specified reviewer.
Return type: pGerrit.change.GerritChangeRevisionReviewer

Usage:

reviewer_instance = revision.reviewer(accountID)

pGerrit.change.GerritChangeEdit¶

class pGerrit.change.GerritChangeEdit(host, gerritID, fileID, auth=None, verify=True, adapter=None, cache=True, cache_expire=3)[source]¶

Class maps /a/changes/{change_id}/edit endpoint of Gerrit REST API

Returns: An instance of GerritChangeEdit.
Return type: pGerrit.change.GerritChangeEdit

You won’t need to instantiate this Class directly. Use pGerrit.change.GerritChange.revision

classmethod info(*args, **kwargs)[source]¶

Performs a GET request to retrieve information about the change edit.

API URL: /a/changes/{change_id}/edit

Input type: None

Return type: EditInfo

Usage:

edit.info()

classmethod edit_publish(payload=None, headers=None)[source]¶

Performs a POST request to publish a change edit.

API URL: /a/changes/{change_id}/edit/edit:publish

Input type: PublishChangeEditInput (optional)

Return type: None

Usage:

edit.edit_publish()

classmethod edit_restore(payload=None, headers=None)[source]¶

Performs a POST request to restore a change edit.

API URL: /a/changes/{change_id}/edit

Input type: ChangeEditInput

Return type: None

Usage:

edit.edit_restore({"restore_path": "foo"})

classmethod edit_delete(headers=None)[source]¶

Performs a DELETE request to delete a change edit.

API URL: /a/changes/{change_id}/edit

Input type: None

Return type: None

Usage:

edit.edit_delete()

edit_file(payload, headers=None)[source]¶

Performs a PUT request to edit a specific file in a change revision.

API URL: /a/changes/{change_id}/edit/{file_id}

Input type: str

Return type: None

Usage:

edit_file.edit(payload='new_file_content')

edit_retrieve(headers=None)[source]¶

Performs a GET request to retrieve the content of a specific file in a change revision after editing.

API URL: /a/changes/{change_id}/edit/{file_id}

Input type: None

Return type: str

Usage:

edited_content = edit_file.edit_retrieve()

pGerrit.change.GerritChangeReviewer¶

class pGerrit.change.GerritChangeReviewer(host, gerritID, account_id, auth=None, verify=True, adapter=None, cache=True, cache_expire=3)[source]¶

Class maps /a/changes/{change_id}/reviewers/{account_id} endpoint of Gerrit REST API

Returns: An instance of GerritChangeReviewer.
Return type: pGerrit.change.GerritChangeReviewer

You won’t need to instantiate this Class directly. Use pGerrit.change.GerritChange.reviewer

classmethod query(*args, **kwargs)[source]¶

Performs a GET request to retrieve information about the change edit.

API URL: /a/changes/{change_id}/reviewers/

Input type: None

classmethod suggest_reviewers(*args, **kwargs)[source]¶

Performs a GET request to retrieve a list of suggested reviewers for a change.

API URL: /a/changes/{change_id}/suggest_reviewers

Input type: SuggestReviewersOptions

Return type: List[SuggestedReviewerInfo]

Usage:

reviewer.suggest_reviewers(q="john")

classmethod add_reviewer(payload=None, *args, **kwargs)[source]¶

Performs a POST request to add a reviewer to a change.

API URL: /a/changes/{change_id}/reviewers

Input type: ReviewerInput

Return type: ReviewerResult

Usage:

reviewer.add_reviewer({"reviewer": "example@example.com"})

pGerrit.change.GerritChangeRevisionReviewer¶

class pGerrit.change.GerritChangeRevisionReviewer(host, gerritID, revisionID, accountID, auth=None, verify=True, adapter=None, cache=True, cache_expire=3)[source]¶

Class maps /a/changes/{change_id}/revisions/{revision_id}/reviewers/{account_id} endpoint of Gerrit REST API

Returns: An instance of GerritChangeRevisionReviewer.
Return type: pGerrit.change.GerritChangeRevisionReviewer

You won’t need to instantiate this Class directly. Use pGerrit.change.GerritChangeRevision.reviwer

list(*args, **kwargs)[source]¶

List reviewers of a specific change revision.

API URL: /a/changes/{change_id}/revisions/{revision_id}/reviewers/

Returns: A list of reviewers for the specified change revision.
Return type: list

Usage:

reviewers = revision_reviewer.list()

delete_vote(label, *args, **kwargs)[source]¶

Delete a vote from a specific reviewer on a change revision.

API URL: /a/changes/{change_id}/revisions/{revision_id}/reviewers/{account_id}/votes/{label}

Parameters: label (str) – The label of the vote to be deleted.
Returns: None

Usage:

revision_reviewer.delete_vote(label)

pGerrit.change.GerritChangeRevisionFile¶

class pGerrit.change.GerritChangeRevisionFile(host, gerritID, revisionID, fileID, auth=None, verify=True, adapter=None, cache=True, cache_expire=3)[source]¶

Class maps /a/changes/{change_id}/revisions/{revision_id}/files/{file_id} endpoint of Gerrit REST API

Returns: An instance of GerritChangeRevisionFile.
Return type: pGerrit.change.GerritChangeRevisionFile

You won’t need to instantiate this Class directly. Use pGerrit.change.GerritChangeRevision.file

content(*args, **kwargs)[source]¶

Retrieve the content of a specific file in a change revision.

API URL: /a/changes/{change_id}/revisions/{revision_id}/files/{file_id}/content

Returns: The content of the specified file in the change revision.
Return type: str

Usage:

file_content = revision_file.content()

diff(*args, **kwargs)[source]¶

Retrieve the diff of a specific file in a change revision.

API URL: /a/changes/{change_id}/revisions/{revision_id}/files/{file_id}/diff

Returns: The diff of the specified file in the change revision.
Return type: dict

Usage:

file_diff = revision_file.diff()

download(*args, **kwargs)[source]¶

Download the content of a specific file in a change revision.

API URL: /a/changes/{change_id}/revisions/{revision_id}/files/{file_id}/download

Returns: The downloaded content of the specified file in the change revision.
Return type: bytes

Usage:

downloaded_content = revision_file.download()

blame(*args, **kwargs)[source]¶

Retrieve the blame information for a specific file in a change revision.

API URL: /a/changes/{change_id}/revisions/{revision_id}/files/{file_id}/blame

Returns: The blame information of the specified file in the change revision.
Return type: list

Usage:

blame_info = revision_file.blame()

is_binary()[source]¶

Check if the file is a binary file.

Returns: True if the file is a binary file, False otherwise.
Return type: bool

Usage:

is_binary_file = revision_file.is_binary()

get_history_log(commit=None, *args, **kwargs)[source]¶

Retrieve the history log of a specific file in a change revision.

Parameters: commit (str) – (optional) The commit hash to get the history log from. If not provided, the current commit will be used.
Returns: The history log of the specified file in the change revision.
Return type: str

Usage:

history_log = revision_file.get_history_log(commit='commit_hash')

pGerrit.Access.GerritAccess¶

class pGerrit.Access.GerritAccess(host, auth=None, verify=True, adapter=None, cache=True, cache_expire=3)[source]¶

Class maps /access/ endpoint of Gerrit REST API

Returns: An instance of GerritAccess.
Return type: pGerrit.GerritAccess

You won’t need to instantiate this Class directly. Use pGerrit.GerritClient.access

classmethod query(*args, **kwargs)[source]¶

Performs a GET request to query for access rights from the Gerrit API.

API URL: /a/access/

Input type: QueryOptions

Return type: Dict[str, ProjectAccessInfo]

Usage:

access_rights = gerrit_access.query(**{"project": "All-Projects"})

pGerrit.project.GerritProject¶

class pGerrit.project.GerritProject(host, project, auth=None, verify=True, adapter=None, cache=True, cache_expire=3)[source]¶

Class maps /projects/ endpoint of Gerrit REST API

Returns: An instance of GerritProject.
Return type: pGerrit.project.GerritProject

You won’t need to instantiate this Class directly. Use pGerrit.GerritClient.project

classmethod query(*args, **kwargs)[source]¶

Performs a GET request to query for projects from the Gerrit API.

API URL: /a/projects/

Input type: QueryOptions

Return type: ProjectInfo

Usage:

project.query(
    query="name:test"
)

access(*args, **kwargs)[source]¶

Performs a GET request to list access rights for project from the Gerrit API.

API URL: /a/projects/

Input type: QueryOptions

Return type: ProjectAccessInfo

Usage::: project.access()

Developer Interface¶

pGerrit.change.GerritClient¶

pGerrit.change.GerritChange¶

pGerrit.change.GerritChangeRevision¶

pGerrit.change.GerritChangeEdit¶

pGerrit.change.GerritChangeReviewer¶

pGerrit.change.GerritChangeRevisionReviewer¶

pGerrit.change.GerritChangeRevisionFile¶

pGerrit.Access.GerritAccess¶

pGerrit.project.GerritProject¶

Useful Links

Table of Contents

Related Topics