Module ogr.abstract
Expand source code
# Copyright Contributors to the Packit project.
# SPDX-License-Identifier: MIT
import datetime
import functools
from collections.abc import Sequence
from enum import Enum, IntEnum
from re import Match
from typing import (
Any,
Callable,
ClassVar,
Optional,
TypeVar,
Union,
)
import github
import gitlab
import requests
from ogr.deprecation import deprecate_and_set_removal
from ogr.exceptions import (
APIException,
GitForgeInternalError,
GithubAPIException,
GitlabAPIException,
OgrException,
OgrNetworkError,
)
from ogr.parsing import parse_git_repo
try:
from functools import cached_property as _cached_property
except ImportError:
from functools import lru_cache
def _cached_property(func): # type: ignore
return property(lru_cache()(func))
AnyComment = TypeVar("AnyComment", bound="Comment")
def __check_for_internal_failure(ex: APIException):
"""
Checks if exception is caused by internal failure from git forge.
Args:
ex: Wrapped exception.
Raises:
GitForgeInternalError, when exception was cause by an internal failure.
APIException, exception itself when not an internal failure.
"""
if ex.response_code is not None and ex.response_code >= 500:
raise GitForgeInternalError from ex.__cause__
raise ex
def __wrap_exception(
ex: Union[github.GithubException, gitlab.GitlabError],
) -> APIException:
"""
Wraps uncaught exception in one of ogr exceptions.
Args:
ex: Unhandled exception from GitHub or GitLab.
Returns:
Wrapped `ex` in respective `APIException`.
Raises:
TypeError, when given unexpected type of exception.
"""
MAPPING = {
github.GithubException: GithubAPIException,
gitlab.GitlabError: GitlabAPIException,
}
for caught_exception, ogr_exception in MAPPING.items():
if isinstance(ex, caught_exception):
exc = ogr_exception()
exc.__cause__ = ex
return exc
raise TypeError("Unknown type of uncaught exception passed") from ex
def catch_common_exceptions(function: Callable) -> Any:
"""
Decorator catching common exceptions.
Args:
function (Callable): Function or method to decorate.
Raises:
GithubAPIException, if authentication to Github failed.
GitlabAPIException, if authentication to Gitlab failed.
OgrNetworkError, if network problems occurred while performing a request.
"""
@functools.wraps(function)
def wrapper(*args, **kwargs):
try:
return function(*args, **kwargs)
except github.BadCredentialsException as ex:
raise GithubAPIException("Invalid Github credentials") from ex
except gitlab.GitlabAuthenticationError as ex:
raise GitlabAPIException("Invalid Gitlab credentials") from ex
except requests.exceptions.ConnectionError as ex:
raise OgrNetworkError(
"Could not perform the request due to a network error",
) from ex
except APIException as ex:
__check_for_internal_failure(ex)
except (github.GithubException, gitlab.GitlabError) as ex:
__check_for_internal_failure(__wrap_exception(ex))
return wrapper
class CatchCommonErrors(type):
"""
A metaclass wrapping methods with a common exception handler.
This handler catches exceptions which can occur almost anywhere
and catching them manually would be tedious and converts them
to an appropriate ogr exception for the user. This includes
exceptions such as:
- authentication (from Github/Gitlab)
- network errors
"""
def __new__(cls, name, bases, namespace):
for key, value in namespace.items():
# There is an anticipated change in behaviour in Python 3.10
# for static/class methods. From Python 3.10 they will be callable.
# We need to achieve consistent behaviour with older versions,
# hence the explicit handling is needed here (isinstance checking
# works the same). Moreover, static/class method decorator must
# be used last, especially prior to Python 3.10 since they return
# descriptor objects and not functions.
# See: https://bugs.python.org/issue43682
if isinstance(value, staticmethod):
namespace[key] = staticmethod(catch_common_exceptions(value.__func__))
elif isinstance(value, classmethod):
namespace[key] = classmethod(catch_common_exceptions(value.__func__))
elif callable(namespace[key]):
namespace[key] = catch_common_exceptions(namespace[key])
return super().__new__(cls, name, bases, namespace)
class OgrAbstractClass(metaclass=CatchCommonErrors):
def __repr__(self) -> str:
return f"<{self!s}>"
class Reaction(OgrAbstractClass):
def __init__(self, raw_reaction: Any) -> None:
self._raw_reaction = raw_reaction
def __str__(self):
return f"Reaction(raw_reaction={self._raw_reaction})"
def delete(self) -> None:
"""Delete a reaction."""
raise NotImplementedError()
class Comment(OgrAbstractClass):
def __init__(
self,
raw_comment: Optional[Any] = None,
parent: Optional[Any] = None,
body: Optional[str] = None,
id_: Optional[int] = None,
author: Optional[str] = None,
created: Optional[datetime.datetime] = None,
edited: Optional[datetime.datetime] = None,
) -> None:
if raw_comment:
self._from_raw_comment(raw_comment)
elif body and author:
self._body = body
self._id = id_
self._author = author
self._created = created
self._edited = edited
else:
raise ValueError("cannot construct comment without body and author")
self._parent = parent
def __str__(self) -> str:
body = f"{self.body[:10]}..." if self.body is not None else "None"
return (
f"Comment("
f"comment='{body}', "
f"author='{self.author}', "
f"created='{self.created}', "
f"edited='{self.edited}')"
)
def _from_raw_comment(self, raw_comment: Any) -> None:
"""Constructs Comment object from raw_comment given from API."""
raise NotImplementedError()
@property
def body(self) -> str:
"""Body of the comment."""
return self._body
@body.setter
def body(self, new_body: str) -> None:
self._body = new_body
@property
def id(self) -> int:
return self._id
@property
def author(self) -> str:
"""Login of the author of the comment."""
return self._author
@property
def created(self) -> datetime.datetime:
"""Datetime of creation of the comment."""
return self._created
@property
def edited(self) -> datetime.datetime:
"""Datetime of last edit of the comment."""
return self._edited
def get_reactions(self) -> list[Reaction]:
"""Returns list of reactions."""
raise NotImplementedError()
def add_reaction(self, reaction: str) -> Reaction:
"""
Reacts to a comment.
Colons in between reaction are not needed, e.g. `comment.add_reaction("+1")`.
Args:
reaction: String representing specific reaction to be added.
Returns:
Object representing newly added reaction.
"""
raise NotImplementedError()
class IssueComment(Comment):
@property
def issue(self) -> "Issue":
"""Issue of issue comment."""
return self._parent
def __str__(self) -> str:
return "Issue" + super().__str__()
class PRComment(Comment):
@property
def pull_request(self) -> "PullRequest":
"""Pull request of pull request comment."""
return self._parent
def __str__(self) -> str:
return "PR" + super().__str__()
class IssueStatus(IntEnum):
"""Enumeration for issue statuses."""
open = 1
closed = 2
all = 3
class Issue(OgrAbstractClass):
"""
Attributes:
project (GitProject): Project of the issue.
"""
def __init__(self, raw_issue: Any, project: "GitProject") -> None:
self._raw_issue = raw_issue
self.project = project
@property
def title(self) -> str:
"""Title of the issue."""
raise NotImplementedError()
@property
def private(self) -> bool:
"""`True` if issue is confidential, `False` otherwise."""
raise NotImplementedError()
@property
def id(self) -> int:
"""ID of the issue."""
raise NotImplementedError()
@property
def status(self) -> IssueStatus:
"""Status of the issue."""
raise NotImplementedError()
@property
def url(self) -> str:
"""Web URL of the issue."""
raise NotImplementedError()
@property
def description(self) -> str:
"""Description of the issue."""
raise NotImplementedError()
@property
def author(self) -> str:
"""Username of the author of the issue."""
raise NotImplementedError()
@property
def created(self) -> datetime.datetime:
"""Datetime of the creation of the issue."""
raise NotImplementedError()
@property
def labels(self) -> list["IssueLabel"]:
"""Labels of the issue."""
raise NotImplementedError()
def __str__(self) -> str:
description = (
f"{self.description[:10]}..." if self.description is not None else "None"
)
return (
f"Issue("
f"title='{self.title}', "
f"id={self.id}, "
f"status='{self.status.name}', "
f"url='{self.url}', "
f"description='{description}', "
f"author='{self.author}', "
f"created='{self.created}')"
)
@staticmethod
def create(
project: Any,
title: str,
body: str,
private: Optional[bool] = None,
labels: Optional[list[str]] = None,
assignees: Optional[list[str]] = None,
) -> "Issue":
"""
Open new issue.
Args:
project (GitProject): Project where the issue is to be opened.
title: Title of the issue.
body: Description of the issue.
private: Is the new issue supposed to be confidential?
**Supported only by GitLab and Pagure.**
Defaults to unset.
labels: List of labels that are to be added to
the issue.
Defaults to no labels.
assignees: List of usernames of the assignees.
Defaults to no assignees.
Returns:
Object that represents newly created issue.
"""
raise NotImplementedError()
@staticmethod
def get(project: Any, id: int) -> "Issue":
"""
Get issue.
Args:
project (GitProject): Project where the issue is to be opened.
issue_id: ID of the issue.
Returns:
Object that represents requested issue.
"""
raise NotImplementedError()
@staticmethod
def get_list(
project: Any,
status: IssueStatus = IssueStatus.open,
author: Optional[str] = None,
assignee: Optional[str] = None,
labels: Optional[list[str]] = None,
) -> list["Issue"]:
"""
List of issues.
Args:
project (GitProject): Project where the issue is to be opened.
status: Status of the issues that are to be
included in the list.
Defaults to `IssueStatus.open`.
author: Username of the author of the issues.
Defaults to no filtering by author.
assignee: Username of the assignee on the issues.
Defaults to no filtering by assignees.
labels: Filter issues that have set specific labels.
Defaults to no filtering by labels.
Returns:
List of objects that represent requested issues.
"""
raise NotImplementedError()
def _get_all_comments(self) -> list[IssueComment]:
"""
Get list of all issue comments.
Returns:
List of all comments on the issue.
"""
raise NotImplementedError()
def get_comments(
self,
filter_regex: Optional[str] = None,
reverse: bool = False,
author: Optional[str] = None,
) -> list[IssueComment]:
"""
Get list of issue comments.
Args:
filter_regex: Filter the comments' content with `re.search`.
Defaults to `None`, which means no filtering.
reverse: Whether the comments are to be returned in
reversed order.
Defaults to `False`.
author: Filter the comments by author.
Defaults to `None`, which means no filtering.
Returns:
List of issue comments.
"""
raise NotImplementedError()
def can_close(self, username: str) -> bool:
"""
Check if user have permissions to modify an issue.
Args:
username: Login of the user.
Returns:
`True` if user can close the issue, `False` otherwise.
"""
raise NotImplementedError()
def comment(self, body: str) -> IssueComment:
"""
Add new comment to the issue.
Args:
body: Text contents of the comment.
Returns:
Object that represents posted comment.
"""
raise NotImplementedError()
def close(self) -> "Issue":
"""
Close an issue.
Returns:
Issue itself.
"""
raise NotImplementedError()
def add_label(self, *labels: str) -> None:
"""
Add labels to the issue.
Args:
*labels: Labels to be added.
"""
raise NotImplementedError()
def add_assignee(self, *assignees: str) -> None:
"""
Assign users to an issue.
Args:
*assignees: List of logins of the assignees.
"""
raise NotImplementedError()
def get_comment(self, comment_id: int) -> IssueComment:
"""
Returns an issue comment.
Args:
comment_id: id of a comment
Returns:
Object representing an issue comment.
"""
raise NotImplementedError()
class PRStatus(IntEnum):
"""Enumeration that represents statuses of pull requests."""
open = 1
closed = 2
merged = 3
all = 4
class CommitStatus(Enum):
"""Enumeration that represents possible state of commit statuses."""
pending = 1
success = 2
failure = 3
error = 4
canceled = 5
running = 6
class MergeCommitStatus(Enum):
"""Enumeration that represents possible states of merge states of PR/MR."""
can_be_merged = 1
cannot_be_merged = 2
unchecked = 3
checking = 4
cannot_be_merged_recheck = 5
class PullRequest(OgrAbstractClass):
"""
Attributes:
project (GitProject): Project of the pull request.
"""
def __init__(self, raw_pr: Any, project: "GitProject") -> None:
self._raw_pr = raw_pr
self._target_project = project
@property
def title(self) -> str:
"""Title of the pull request."""
raise NotImplementedError()
@title.setter
def title(self, new_title: str) -> None:
raise NotImplementedError()
@property
def id(self) -> int:
"""ID of the pull request."""
raise NotImplementedError()
@property
def status(self) -> PRStatus:
"""Status of the pull request."""
raise NotImplementedError()
@property
def url(self) -> str:
"""Web URL of the pull request."""
raise NotImplementedError()
@property
def description(self) -> str:
"""Description of the pull request."""
raise NotImplementedError()
@description.setter
def description(self, new_description: str) -> None:
raise NotImplementedError
@property
def author(self) -> str:
"""Login of the author of the pull request."""
raise NotImplementedError()
@property
def source_branch(self) -> str:
"""Name of the source branch (from which the changes are pulled)."""
raise NotImplementedError()
@property
def target_branch(self) -> str:
"""Name of the target branch (where the changes are being merged)."""
raise NotImplementedError()
@property
def created(self) -> datetime.datetime:
"""Datetime of creating the pull request."""
raise NotImplementedError()
@property
def labels(self) -> list["PRLabel"]:
"""Labels of the pull request."""
raise NotImplementedError()
@property
def diff_url(self) -> str:
"""Web URL to the diff of the pull request."""
raise NotImplementedError()
@property
def patch(self) -> bytes:
"""Patch of the pull request."""
raise NotImplementedError()
@property
def head_commit(self) -> str:
"""Commit hash of the HEAD commit of the pull request."""
raise NotImplementedError()
@property
def target_branch_head_commit(self) -> str:
"""Commit hash of the HEAD commit of the target branch."""
raise NotImplementedError()
@property
def merge_commit_sha(self) -> str:
"""
Commit hash of the merge commit of the pull request.
Before merging represents test merge commit, if git forge supports it.
"""
raise NotImplementedError()
@property
def merge_commit_status(self) -> MergeCommitStatus:
"""Current status of the test merge commit."""
raise NotImplementedError()
@property
def source_project(self) -> "GitProject":
"""Object that represents source project (from which the changes are pulled)."""
raise NotImplementedError()
@property
def target_project(self) -> "GitProject":
"""Object that represents target project (where changes are merged)."""
return self._target_project
@property
def commits_url(self) -> str:
"""Web URL to the list of commits in the pull request."""
raise NotImplementedError()
@property
def closed_by(self) -> Optional[str]:
"""Login of the account that closed the pull request."""
raise NotImplementedError
def __str__(self) -> str:
description = (
f"{self.description[:10]}..." if self.description is not None else "None"
)
return (
f"PullRequest("
f"title='{self.title}', "
f"id={self.id}, "
f"status='{self.status.name}', "
f"url='{self.url}', "
f"diff_url='{self.diff_url}', "
f"description='{description}', "
f"author='{self.author}', "
f"source_branch='{self.source_branch}', "
f"target_branch='{self.target_branch}', "
f"created='{self.created}')"
)
@staticmethod
def create(
project: Any,
title: str,
body: str,
target_branch: str,
source_branch: str,
fork_username: Optional[str] = None,
) -> "PullRequest":
"""
Create new pull request.
Args:
project (GitProject): Project where the pull request will be created.
title: Title of the pull request.
body: Description of the pull request.
target_branch: Branch in the project where the changes are being
merged.
source_branch: Branch from which the changes are being pulled.
fork_username: The username/namespace of the forked repository.
Returns:
Object that represents newly created pull request.
"""
raise NotImplementedError()
@staticmethod
def get(project: Any, id: int) -> "PullRequest":
"""
Get pull request.
Args:
project (GitProject): Project where the pull request is located.
id: ID of the pull request.
Returns:
Object that represents pull request.
"""
raise NotImplementedError()
@staticmethod
def get_list(project: Any, status: PRStatus = PRStatus.open) -> list["PullRequest"]:
"""
List of pull requests.
Args:
project (GitProject): Project where the pull requests are located.
status: Filters out the pull requests.
Defaults to `PRStatus.open`.
Returns:
List of pull requests with requested status.
"""
raise NotImplementedError()
def update_info(
self,
title: Optional[str] = None,
description: Optional[str] = None,
) -> "PullRequest":
"""
Update pull request information.
Args:
title: The new title of the pull request.
Defaults to `None`, which means no updating.
description: The new description of the pull request.
Defaults to `None`, which means no updating.
Returns:
Pull request itself.
"""
raise NotImplementedError()
def _get_all_comments(self) -> list[PRComment]:
"""
Get list of all pull request comments.
Returns:
List of all comments on the pull request.
"""
raise NotImplementedError()
def get_comments(
self,
filter_regex: Optional[str] = None,
reverse: bool = False,
author: Optional[str] = None,
) -> list["PRComment"]:
"""
Get list of pull request comments.
Args:
filter_regex: Filter the comments' content with `re.search`.
Defaults to `None`, which means no filtering.
reverse: Whether the comments are to be returned in
reversed order.
Defaults to `False`.
author: Filter the comments by author.
Defaults to `None`, which means no filtering.
Returns:
List of pull request comments.
"""
raise NotImplementedError()
def get_all_commits(self) -> list[str]:
"""
Returns:
List of commit hashes of commits in pull request.
"""
raise NotImplementedError()
def search(
self,
filter_regex: str,
reverse: bool = False,
description: bool = True,
) -> Optional[Match[str]]:
"""
Find match in pull request description or comments.
Args:
filter_regex: Regex that is used to filter the comments' content with `re.search`.
reverse: Reverse order of the comments.
Defaults to `False`.
description: Whether description is included in the search.
Defaults to `True`.
Returns:
`re.Match` if found, `None` otherwise.
"""
raise NotImplementedError()
def comment(
self,
body: str,
commit: Optional[str] = None,
filename: Optional[str] = None,
row: Optional[int] = None,
) -> "PRComment":
"""
Add new comment to the pull request.
Args:
body: Body of the comment.
commit: Commit hash to which comment is related.
Defaults to generic comment.
filename: Path to the file to which comment is related.
Defaults to no relation to the file.
row: Line number to which the comment is related.
Defaults to no relation to the line.
Returns:
Newly created comment.
"""
raise NotImplementedError()
def close(self) -> "PullRequest":
"""
Close the pull request.
Returns:
Pull request itself.
"""
raise NotImplementedError()
def merge(self) -> "PullRequest":
"""
Merge the pull request.
Returns:
Pull request itself.
"""
raise NotImplementedError()
def add_label(self, *labels: str) -> None:
"""
Add labels to the pull request.
Args:
*labels: Labels to be added.
"""
raise NotImplementedError()
def get_statuses(self) -> list["CommitFlag"]:
"""
Returns statuses for latest commit on pull request.
Returns:
List of commit statuses of the latest commit.
"""
raise NotImplementedError()
def get_comment(self, comment_id: int) -> PRComment:
"""
Returns a PR comment.
Args:
comment_id: id of comment
Returns:
Object representing a PR comment.
"""
raise NotImplementedError()
class CommitFlag(OgrAbstractClass):
_states: ClassVar[dict[str, CommitStatus]] = {}
def __init__(
self,
raw_commit_flag: Optional[Any] = None,
project: Optional["GitProject"] = None,
commit: Optional[str] = None,
state: Optional[CommitStatus] = None,
context: Optional[str] = None,
comment: Optional[str] = None,
uid: Optional[str] = None,
url: Optional[str] = None,
) -> None:
self.uid = uid
self.project = project
self.commit = commit
if commit and state and context:
self.state = state
self.context = context
self.comment = comment
self.url = url
else:
self._raw_commit_flag = raw_commit_flag
self._from_raw_commit_flag()
def __str__(self) -> str:
return (
f"CommitFlag("
f"commit='{self.commit}', "
f"state='{self.state.name}', "
f"context='{self.context}', "
f"uid='{self.uid}', "
f"comment='{self.comment}', "
f"url='{self.url}', "
f"created='{self.created}', "
f"edited='{self.edited}')"
)
@classmethod
def _state_from_str(cls, state: str) -> CommitStatus:
"""
Transforms state from string to enumeration.
Args:
state: String representation of a state.
Returns:
Commit status.
"""
raise NotImplementedError()
@classmethod
def _validate_state(cls, state: CommitStatus) -> CommitStatus:
"""
Validates state of the commit status (if it can be used with forge).
"""
raise NotImplementedError()
def _from_raw_commit_flag(self) -> None:
"""
Sets attributes based on the raw flag that has been given through constructor.
"""
raise NotImplementedError()
@staticmethod
def get(project: Any, commit: str) -> list["CommitFlag"]:
"""
Acquire commit statuses for given commit in the project.
Args:
project (GitProject): Project where the commit is located.
commit: Commit hash for which we request statuses.
Returns:
List of commit statuses for the commit.
"""
raise NotImplementedError()
@staticmethod
def set(
project: Any,
commit: str,
state: CommitStatus,
target_url: str,
description: str,
context: str,
) -> "CommitFlag":
"""
Set a new commit status.
Args:
project (GitProject): Project where the commit is located.
commit: Commit hash for which we set status.
state: State for the commit status.
target_url: URL for the commit status.
description: Description of the commit status.
context: Identifier to group related commit statuses.
"""
raise NotImplementedError()
@property
def created(self) -> datetime.datetime:
"""Datetime of creating the commit status."""
raise NotImplementedError()
@property
def edited(self) -> datetime.datetime:
"""Datetime of editing the commit status."""
raise NotImplementedError()
class CommitComment(OgrAbstractClass):
"""
Attributes:
sha (str): Hash of the related commit.
body (str): Body of the comment.
author (str): Login of the author.
"""
def __init__(self, sha: str, body: str, author: str) -> None:
self.sha = sha
self.body = body
self.author = author
@property # type: ignore
@deprecate_and_set_removal(
since="0.41.0",
remove_in="0.46.0 (or 1.0.0 if it comes sooner)",
message="Use body",
)
def comment(self) -> str:
return self.body
def __str__(self) -> str:
return (
f"CommitComment(commit={self.sha}, author={self.author}, body={self.body})"
)
class GitTag(OgrAbstractClass):
"""
Class representing a git tag.
Attributes:
name (str): Name of the tag.
commit_sha (str): Commit hash of the tag.
"""
def __init__(self, name: str, commit_sha: str) -> None:
self.name = name
self.commit_sha = commit_sha
def __str__(self) -> str:
return f"GitTag(name={self.name}, commit_sha={self.commit_sha})"
class AccessLevel(IntEnum):
"""
Enumeration representing an access level to the repository.
| Value from enumeration | GitHub | GitLab | Pagure |
| ---------------------- | -------- | ----------------------- | ------ |
| `AccessLevel.pull` | pull | guest | ticket |
| `AccessLevel.triage` | triage | reporter | ticket |
| `AccessLevel.push` | push | developer | commit |
| `AccessLevel.admin` | admin | maintainer | commit |
| `AccessLevel.maintain` | maintain | owner (only for groups) | admin |
"""
pull = 1
triage = 2
push = 3
admin = 4
maintain = 5
class Release(OgrAbstractClass):
"""
Object that represents release.
Attributes:
project (GitProject): Project on which the release is created.
"""
def __init__(
self,
raw_release: Any,
project: "GitProject",
) -> None:
self._raw_release = raw_release
self.project = project
def __str__(self) -> str:
return (
f"Release("
f"title='{self.title}', "
f"body='{self.body}', "
f"tag_name='{self.tag_name}', "
f"url='{self.url}', "
f"created_at='{self.created_at}', "
f"tarball_url='{self.tarball_url}')"
)
@property
def title(self) -> str:
"""Title of the release."""
raise NotImplementedError()
@property
def body(self) -> str:
"""Body of the release."""
raise NotImplementedError()
@property
def git_tag(self) -> GitTag:
"""Object that represents tag tied to the release."""
raise NotImplementedError()
@property
def tag_name(self) -> str:
"""Tag tied to the release."""
raise NotImplementedError()
@property
def url(self) -> Optional[str]:
"""URL of the release."""
raise NotImplementedError()
# TODO: Check if should really be string
@property
def created_at(self) -> datetime.datetime:
"""Datetime of creating the release."""
raise NotImplementedError()
@property
def tarball_url(self) -> str:
"""URL of the tarball."""
raise NotImplementedError()
@staticmethod
def get(
project: Any,
identifier: Optional[int] = None,
name: Optional[str] = None,
tag_name: Optional[str] = None,
) -> "Release":
"""
Get a single release.
Args:
identifier: Identifier of the release.
Defaults to `None`, which means not being used.
name: Name of the release.
Defaults to `None`, which means not being used.
tag_name: Tag that the release is tied to.
Defaults to `None`, which means not being used.
Returns:
Object that represents release that satisfies requested condition.
"""
raise NotImplementedError()
@staticmethod
def get_latest(project: Any) -> Optional["Release"]:
"""
Returns:
Object that represents the latest release.
"""
raise NotImplementedError()
@staticmethod
def get_list(project: Any) -> list["Release"]:
"""
Returns:
List of the objects that represent releases.
"""
raise NotImplementedError()
@staticmethod
def create(
project: Any,
tag: str,
name: str,
message: str,
ref: Optional[str] = None,
) -> "Release":
"""
Create new release.
Args:
project: Project where the release is to be created.
tag: Tag which is the release based off.
name: Name of the release.
message: Message or description of the release.
ref: Git reference, mainly commit hash for the release. If provided
git tag is created prior to creating a release.
Defaults to `None`.
Returns:
Object that represents newly created release.
"""
raise NotImplementedError()
def save_archive(self, filename: str) -> None:
"""
Save tarball of the release to requested `filename`.
Args:
filename: Path to the file to save archive to.
"""
raise NotImplementedError()
def edit_release(self, name: str, message: str) -> None:
"""
Edit name and message of a release.
Args:
name: Name of the release.
message: Description of the release.
"""
raise NotImplementedError()
class AuthMethod(str, Enum):
tokman = "tokman"
github_app = "github_app"
token = "token"
class GitService(OgrAbstractClass):
"""
Attributes:
instance_url (str): URL of the git forge instance.
"""
instance_url: Optional[str] = None
def __init__(self, **_: Any) -> None:
pass
def __str__(self) -> str:
return f"GitService(instance_url={self.instance_url})"
def get_project(self, **kwargs: Any) -> "GitProject":
"""
Get the requested project.
Args:
namespace (str): Namespace of the project.
user (str): Username of the project's owner.
repo (str): Repository name.
Returns:
Object that represents git project.
"""
raise NotImplementedError
def get_project_from_url(self, url: str) -> "GitProject":
"""
Args:
url: URL of the git repository.
Returns:
Object that represents project from the parsed URL.
"""
repo_url = parse_git_repo(potential_url=url)
if not repo_url:
raise OgrException(f"Failed to find repository for url: {url}")
return self.get_project(repo=repo_url.repo, namespace=repo_url.namespace)
@_cached_property
def hostname(self) -> Optional[str]:
"""Hostname of the service."""
raise NotImplementedError
@property
def user(self) -> "GitUser":
"""User authenticated through the service."""
raise NotImplementedError
def change_token(self, new_token: str) -> None:
"""
Change an API token. Only for the current instance and newly created projects.
Args:
new_token: New token to be set.
"""
raise NotImplementedError
def set_auth_method(self, method: AuthMethod) -> None:
"""
Override the default auth method.
Can be used when the service has more auth methods available.
Args:
method: the method identifier (a str name)
"""
raise NotImplementedError()
def reset_auth_method(self) -> None:
"""
Set the auth method to the default one.
"""
raise NotImplementedError()
def project_create(
self,
repo: str,
namespace: Optional[str] = None,
description: Optional[str] = None,
) -> "GitProject":
"""
Create new project.
Args:
repo: Name of the newly created project.
namespace: Namespace of the newly created project.
Defaults to currently authenticated user.
description: Description of the newly created project.
Returns:
Object that represents newly created project.
"""
raise NotImplementedError()
def list_projects(
self,
namespace: Optional[str] = None,
user: Optional[str] = None,
search_pattern: Optional[str] = None,
language: Optional[str] = None,
) -> list["GitProject"]:
"""
List projects for given criteria.
Args:
namespace: Namespace to list projects from.
user: Login of the owner of the projects.
search_pattern: Regular expression that repository name should match.
language: Language to be present in the project, e.g. `"python"` or
`"html"`.
"""
raise NotImplementedError
def get_group(self, group_name: str):
"""
Get a group by name.
"""
raise NotImplementedError
class GitProject(OgrAbstractClass):
def __init__(self, repo: str, service: GitService, namespace: str) -> None:
"""
Args:
repo: Name of the project.
service: GitService instance.
namespace: Namespace of the project.
- GitHub: username or org name.
- GitLab: username or org name.
- Pagure: namespace (e.g. `"rpms"`).
In case of forks: `"fork/{username}/{namespace}"`.
"""
self.service = service
self.repo = repo
self.namespace = namespace
def __str__(self) -> str:
return f"GitProject(namespace={self.namespace}, repo={self.repo}, service={self.service})"
@property
def description(self) -> str:
"""
Returns:
Project description.
"""
raise NotImplementedError()
@description.setter
def description(self, new_description: str) -> None:
"""
Args:
new_description: description to set for project.
"""
raise NotImplementedError()
def delete(self) -> None:
"""Delete the project."""
raise NotImplementedError()
def exists(self) -> bool:
"""
Check the existence of the repo.
Returns:
`True` if the project exists, `False` otherwise.
"""
raise NotImplementedError()
def is_private(self) -> bool:
"""
Is this repository private (accessible only by users with permissions).
Returns:
`True`, if the repository is private.
"""
raise NotImplementedError()
def is_forked(self) -> bool:
"""
Is this repository forked by the authenticated user?
Returns:
`True`, if the repository is fork.
"""
raise NotImplementedError()
@property
def is_fork(self) -> bool:
"""`True` if the project is a fork."""
raise NotImplementedError()
@property
def full_repo_name(self) -> str:
"""Get repo name with namespace, e.g. `rpms/python-docker-py`."""
raise NotImplementedError()
@property
def parent(self) -> Optional["GitProject"]:
"""Parent project if the project is a fork, otherwise `None`."""
raise NotImplementedError()
@property
def has_issues(self) -> bool:
"""`True` if issues are enabled on the project."""
raise NotImplementedError()
def get_branches(self) -> list[str]:
"""
Returns:
List with names of branches in the project.
"""
raise NotImplementedError()
@property
def default_branch(self) -> str:
"""Default branch (usually `main`, `master` or `trunk`)."""
raise NotImplementedError()
def get_description(self) -> str:
"""
Returns:
Project description.
"""
raise NotImplementedError()
def get_fork(self, create: bool = True) -> Optional["GitProject"]:
"""
Provide GitProject instance of a fork of this project.
Args:
create: Create fork if it does not exist.
Returns:
`None` if the project is fork itself or there is no fork, otherwise
instance of a fork if is to be created or exists already.
"""
raise NotImplementedError()
def get_owners(self) -> list[str]:
"""
Returns:
List of usernames of project owners.
"""
raise NotImplementedError()
def who_can_close_issue(self) -> set[str]:
"""
Returns:
Names of all users who have permission to modify an issue.
"""
raise NotImplementedError()
def who_can_merge_pr(self) -> set[str]:
"""
Returns:
Names of all users who have permission to modify pull request.
"""
raise NotImplementedError()
def which_groups_can_merge_pr(self) -> set[str]:
"""
Returns:
Names of all groups that have permission to modify pull request.
"""
raise NotImplementedError()
def can_merge_pr(self, username: str) -> bool:
"""
Args:
username: Username.
Returns:
`True` if user merge pull request, `False` otherwise.
"""
raise NotImplementedError()
def get_users_with_given_access(self, access_levels: list[AccessLevel]) -> set[str]:
"""
Args:
access_levels: list of access levels
Returns:
set of users with given access levels
"""
raise NotImplementedError()
def add_user(self, user: str, access_level: AccessLevel) -> None:
"""
Add user to project.
Args:
user: Username of the user.
access_level: Permissions for the user.
"""
raise NotImplementedError()
def remove_user(self, user: str) -> None:
"""
Remove user from project.
Args:
user: Username of the user.
"""
raise NotImplementedError()
def request_access(self) -> None:
"""
Request an access to the project (cannot specify access level to be granted;
needs to be approved and specified by the user with maintainer/admin rights).
"""
raise NotImplementedError()
def add_group(self, group: str, access_level: AccessLevel) -> None:
"""
Add group to project.
Args:
group: Name of the group.
access_level: Permissions for the group.
"""
raise NotImplementedError()
def remove_group(self, group: str) -> None:
"""
Remove group from project.
Args:
group: Name of the group.
"""
raise NotImplementedError()
def get_issue_list(
self,
status: IssueStatus = IssueStatus.open,
author: Optional[str] = None,
assignee: Optional[str] = None,
labels: Optional[list[str]] = None,
) -> list["Issue"]:
"""
List of issues.
Args:
status: Status of the issues that are to be
included in the list.
Defaults to `IssueStatus.open`.
author: Username of the author of the issues.
Defaults to no filtering by author.
assignee: Username of the assignee on the issues.
Defaults to no filtering by assignees.
labels: Filter issues that have set specific labels.
Defaults to no filtering by labels.
Returns:
List of objects that represent requested issues.
"""
raise NotImplementedError()
def get_issue(self, issue_id: int) -> "Issue":
"""
Get issue.
Args:
issue_id: ID of the issue.
Returns:
Object that represents requested issue.
"""
raise NotImplementedError()
def get_issue_info(self, issue_id: int) -> "Issue":
"""
Get issue info.
Args:
issue_id: ID of the issue.
Returns:
Object that represents requested issue.
"""
raise NotImplementedError()
def create_issue(
self,
title: str,
body: str,
private: Optional[bool] = None,
labels: Optional[list[str]] = None,
assignees: Optional[list[str]] = None,
) -> Issue:
"""
Open new issue.
Args:
title: Title of the issue.
body: Description of the issue.
private: Is the new issue supposed to be confidential?
**Supported only by GitLab and Pagure.**
Defaults to unset.
labels: List of labels that are to be added to
the issue.
Defaults to no labels.
assignees: List of usernames of the assignees.
Defaults to no assignees.
Returns:
Object that represents newly created issue.
Raises:
IssueTrackerDisabled, if issue tracker is disabled.
"""
raise NotImplementedError()
def get_pr_list(self, status: PRStatus = PRStatus.open) -> list["PullRequest"]:
"""
List of pull requests.
Args:
status: Status of the pull requests that are to be included in the list.
Defaults to `PRStatus.open`.
Returns:
List of objects that represent pull requests with requested status.
"""
raise NotImplementedError()
def get_pr(self, pr_id: int) -> "PullRequest":
"""
Get pull request.
Args:
pr_id: ID of the pull request.
Returns:
Object that represents requested pull request.
"""
raise NotImplementedError()
def get_pr_files_diff(
self,
pr_id: int,
retries: int = 0,
wait_seconds: int = 3,
) -> dict:
"""
Get files diff of a pull request.
Args:
pr_id: ID of the pull request.
Returns:
Dictionary representing files diff.
"""
raise NotImplementedError()
def get_tags(self) -> list["GitTag"]:
"""
Returns:
List of objects that represent tags.
"""
raise NotImplementedError()
def get_sha_from_tag(self, tag_name: str) -> str:
"""
Args:
tag_name: Name of the tag.
Returns:
Commit hash of the commit from the requested tag.
"""
raise NotImplementedError()
def get_release(
self,
identifier: Optional[int] = None,
name: Optional[str] = None,
tag_name: Optional[str] = None,
) -> Release:
"""
Get a single release.
Args:
identifier: Identifier of the release.
Defaults to `None`, which means not being used.
name: Name of the release.
Defaults to `None`, which means not being used.
tag_name: Tag that the release is tied to.
Defaults to `None`, which means not being used.
Returns:
Object that represents release that satisfies requested condition.
"""
raise NotImplementedError()
def get_latest_release(self) -> Optional[Release]:
"""
Returns:
Object that represents the latest release.
"""
raise NotImplementedError()
def get_releases(self) -> list[Release]:
"""
Returns:
List of the objects that represent releases.
"""
raise NotImplementedError()
def create_release(
self,
tag: str,
name: str,
message: str,
ref: Optional[str] = None,
) -> Release:
"""
Create new release.
Args:
tag: Tag which is the release based off.
name: Name of the release.
message: Message or description of the release.
ref: Git reference, mainly commit hash for the release. If provided
git tag is created prior to creating a release.
Defaults to `None`.
Returns:
Object that represents newly created release.
"""
raise NotImplementedError()
def create_pr(
self,
title: str,
body: str,
target_branch: str,
source_branch: str,
fork_username: Optional[str] = None,
) -> "PullRequest":
"""
Create new pull request.
Args:
title: Title of the pull request.
body: Description of the pull request.
target_branch: Name of the branch where the changes are merged.
source_branch: Name of the branch from which the changes are pulled.
fork_username: The username of forked repository.
Defaults to `None`.
Returns:
Object that represents newly created pull request.
"""
raise NotImplementedError()
def commit_comment(
self,
commit: str,
body: str,
filename: Optional[str] = None,
row: Optional[int] = None,
) -> "CommitComment":
"""
Add new comment to a commit.
Args:
commit: Hash of the commit.
body: Body of the comment.
filename: Name of the file that is related to the comment.
Defaults to `None`, which means no relation to file.
row: Number of the row that the comment is related to.
Defaults to `None`, which means no relation to the row.
Returns:
Object that represents newly created commit comment.
"""
raise NotImplementedError()
def get_commit_comments(self, commit: str) -> list[CommitComment]:
"""
Get comments for a commit.
Args:
commit: The hash of the commit.
Returns:
List of all comments for the commit.
"""
raise NotImplementedError()
def set_commit_status(
self,
commit: str,
state: Union[CommitStatus, str],
target_url: str,
description: str,
context: str,
trim: bool = False,
) -> "CommitFlag":
"""
Create a status on a commit.
Args:
commit: The hash of the commit.
state: The state of the status.
target_url: The target URL to associate with this status.
description: A short description of the status.
context: A label to differentiate this status from the status of other systems.
trim: Whether to trim the description to 140 characters.
Defaults to `False`.
Returns:
Object that represents created commit status.
"""
raise NotImplementedError()
def get_commit_statuses(self, commit: str) -> list[CommitFlag]:
"""
Get statuses of the commit.
Args:
commit: Hash of the commit.
Returns:
List of all commit statuses on the commit.
"""
raise NotImplementedError()
def get_git_urls(self) -> dict[str, str]:
"""
Get git URLs for the project.
Returns:
Dictionary with at least SSH and HTTP URLs for the current project.
"""
raise NotImplementedError()
def fork_create(self, namespace: Optional[str] = None) -> "GitProject":
"""
Fork this project using the authenticated user.
Args:
namespace: Namespace where the project should be forked.
Defaults to `None`, which means forking to the namespace of
currently authenticated user.
Returns:
Fork of the current project.
Raises:
In case the fork already exists.
"""
raise NotImplementedError()
def change_token(self, new_token: str) -> None:
"""
Change an API token. Only for the current instance.
Args:
new_token: New token to be set.
"""
raise NotImplementedError
def get_file_content(self, path: str, ref: Optional[str] = None) -> str:
"""
Get a content of the file in the repo.
Args:
path: Path to the file.
ref: Branch or commit.
Defaults to repo's default branch.
Returns:
Contents of the file as string.
Raises:
FileNotFoundError: if there is no such file.
"""
raise NotImplementedError
def get_files(
self,
ref: Optional[str] = None,
filter_regex: Optional[str] = None,
recursive: bool = False,
) -> list[str]:
"""
Get a list of file paths of the repo.
Args:
ref: Branch or commit.
Defaults to repo's default branch.
filter_regex: Filter the paths with `re.search`.
Defaults to `None`, which means no filtering.
recursive: Whether to return only top directory files
or all files recursively.
Defaults to `False`, which means only top-level directory.
Returns:
List of paths of the files in the repo.
"""
raise NotImplementedError
def get_forks(self) -> Sequence["GitProject"]:
"""
Returns:
All forks of the project.
"""
raise NotImplementedError()
def get_web_url(self) -> str:
"""
Returns:
Web URL of the project.
"""
raise NotImplementedError()
def get_sha_from_branch(self, branch: str) -> Optional[str]:
"""
Returns:
Commit SHA of head of the branch. `None` if no branch was found.
"""
raise NotImplementedError()
def get_contributors(self) -> set[str]:
"""
Returns:
Set of all contributors to the given project.
"""
raise NotImplementedError()
def users_with_write_access(self) -> set[str]:
"""
Returns:
List of users who have write access to the project
"""
raise NotImplementedError("Use subclass instead.")
def has_write_access(self, user: str) -> bool:
"""
Decides whether a given user has write access to the project.
Args:
user: The user we are going to check to see if he/she has access
"""
return user in self.users_with_write_access()
class GitUser(OgrAbstractClass):
"""
Represents currently authenticated user through service.
"""
def __init__(self, service: GitService) -> None:
self.service = service
def get_username(self) -> str:
"""
Returns:
Login of the user.
"""
raise NotImplementedError()
def get_email(self) -> str:
"""
Returns:
Email of the user.
"""
raise NotImplementedError()
def get_projects(self) -> Sequence["GitProject"]:
"""
Returns:
Sequence of projects in user's namespace.
"""
raise NotImplementedError()
def get_forks(self) -> Sequence["GitProject"]:
"""
Returns:
Sequence of forks in user's namespace.
"""
raise NotImplementedError()
class Label(OgrAbstractClass):
"""
Represents labels on PRs and issues.
"""
def __init__(self, parent: Any) -> None:
self._parent = parent
@property
def name(self) -> str:
"""Name of the label."""
raise NotImplementedError()
class IssueLabel(Label):
@property
def issue(self) -> "Issue":
"""Issue of issue label."""
return self._parent
def __str__(self) -> str:
return "Issue" + super().__str__()
class PRLabel(Label):
@property
def pull_request(self) -> "PullRequest":
"""Pull request of pull request label."""
return self._parent
def __str__(self) -> str:
return "PR" + super().__str__()
Functions
def catch_common_exceptions(function: Callable) ‑> Any
-
Decorator catching common exceptions.
Args
function
:Callable
- Function or method to decorate.
Raises
GithubAPIException, if authentication to Github failed. GitlabAPIException, if authentication to Gitlab failed. OgrNetworkError, if network problems occurred while performing a request.
Expand source code
def catch_common_exceptions(function: Callable) -> Any: """ Decorator catching common exceptions. Args: function (Callable): Function or method to decorate. Raises: GithubAPIException, if authentication to Github failed. GitlabAPIException, if authentication to Gitlab failed. OgrNetworkError, if network problems occurred while performing a request. """ @functools.wraps(function) def wrapper(*args, **kwargs): try: return function(*args, **kwargs) except github.BadCredentialsException as ex: raise GithubAPIException("Invalid Github credentials") from ex except gitlab.GitlabAuthenticationError as ex: raise GitlabAPIException("Invalid Gitlab credentials") from ex except requests.exceptions.ConnectionError as ex: raise OgrNetworkError( "Could not perform the request due to a network error", ) from ex except APIException as ex: __check_for_internal_failure(ex) except (github.GithubException, gitlab.GitlabError) as ex: __check_for_internal_failure(__wrap_exception(ex)) return wrapper
Classes
class AccessLevel (value, names=None, *, module=None, qualname=None, type=None, start=1)
-
Enumeration representing an access level to the repository.
Value from enumeration GitHub GitLab Pagure AccessLevel.pull
pull guest ticket AccessLevel.triage
triage reporter ticket AccessLevel.push
push developer commit AccessLevel.admin
admin maintainer commit AccessLevel.maintain
maintain owner (only for groups) admin Expand source code
class AccessLevel(IntEnum): """ Enumeration representing an access level to the repository. | Value from enumeration | GitHub | GitLab | Pagure | | ---------------------- | -------- | ----------------------- | ------ | | `AccessLevel.pull` | pull | guest | ticket | | `AccessLevel.triage` | triage | reporter | ticket | | `AccessLevel.push` | push | developer | commit | | `AccessLevel.admin` | admin | maintainer | commit | | `AccessLevel.maintain` | maintain | owner (only for groups) | admin | """ pull = 1 triage = 2 push = 3 admin = 4 maintain = 5
Ancestors
- enum.IntEnum
- builtins.int
- enum.Enum
Class variables
var admin
var maintain
var pull
var push
var triage
class AuthMethod (value, names=None, *, module=None, qualname=None, type=None, start=1)
-
An enumeration.
Expand source code
class AuthMethod(str, Enum): tokman = "tokman" github_app = "github_app" token = "token"
Ancestors
- builtins.str
- enum.Enum
Class variables
var github_app
var token
var tokman
class CatchCommonErrors (*args, **kwargs)
-
A metaclass wrapping methods with a common exception handler.
This handler catches exceptions which can occur almost anywhere and catching them manually would be tedious and converts them to an appropriate ogr exception for the user. This includes exceptions such as: - authentication (from Github/Gitlab) - network errors
Expand source code
class CatchCommonErrors(type): """ A metaclass wrapping methods with a common exception handler. This handler catches exceptions which can occur almost anywhere and catching them manually would be tedious and converts them to an appropriate ogr exception for the user. This includes exceptions such as: - authentication (from Github/Gitlab) - network errors """ def __new__(cls, name, bases, namespace): for key, value in namespace.items(): # There is an anticipated change in behaviour in Python 3.10 # for static/class methods. From Python 3.10 they will be callable. # We need to achieve consistent behaviour with older versions, # hence the explicit handling is needed here (isinstance checking # works the same). Moreover, static/class method decorator must # be used last, especially prior to Python 3.10 since they return # descriptor objects and not functions. # See: https://bugs.python.org/issue43682 if isinstance(value, staticmethod): namespace[key] = staticmethod(catch_common_exceptions(value.__func__)) elif isinstance(value, classmethod): namespace[key] = classmethod(catch_common_exceptions(value.__func__)) elif callable(namespace[key]): namespace[key] = catch_common_exceptions(namespace[key]) return super().__new__(cls, name, bases, namespace)
Ancestors
- builtins.type
class Comment (raw_comment: Optional[Any] = None, parent: Optional[Any] = None, body: Optional[str] = None, id_: Optional[int] = None, author: Optional[str] = None, created: Optional[datetime.datetime] = None, edited: Optional[datetime.datetime] = None)
-
Expand source code
class Comment(OgrAbstractClass): def __init__( self, raw_comment: Optional[Any] = None, parent: Optional[Any] = None, body: Optional[str] = None, id_: Optional[int] = None, author: Optional[str] = None, created: Optional[datetime.datetime] = None, edited: Optional[datetime.datetime] = None, ) -> None: if raw_comment: self._from_raw_comment(raw_comment) elif body and author: self._body = body self._id = id_ self._author = author self._created = created self._edited = edited else: raise ValueError("cannot construct comment without body and author") self._parent = parent def __str__(self) -> str: body = f"{self.body[:10]}..." if self.body is not None else "None" return ( f"Comment(" f"comment='{body}', " f"author='{self.author}', " f"created='{self.created}', " f"edited='{self.edited}')" ) def _from_raw_comment(self, raw_comment: Any) -> None: """Constructs Comment object from raw_comment given from API.""" raise NotImplementedError() @property def body(self) -> str: """Body of the comment.""" return self._body @body.setter def body(self, new_body: str) -> None: self._body = new_body @property def id(self) -> int: return self._id @property def author(self) -> str: """Login of the author of the comment.""" return self._author @property def created(self) -> datetime.datetime: """Datetime of creation of the comment.""" return self._created @property def edited(self) -> datetime.datetime: """Datetime of last edit of the comment.""" return self._edited def get_reactions(self) -> list[Reaction]: """Returns list of reactions.""" raise NotImplementedError() def add_reaction(self, reaction: str) -> Reaction: """ Reacts to a comment. Colons in between reaction are not needed, e.g. `comment.add_reaction("+1")`. Args: reaction: String representing specific reaction to be added. Returns: Object representing newly added reaction. """ raise NotImplementedError()
Ancestors
Subclasses
Instance variables
-
Login of the author of the comment.
Expand source code
@property def author(self) -> str: """Login of the author of the comment.""" return self._author
var body : str
-
Body of the comment.
Expand source code
@property def body(self) -> str: """Body of the comment.""" return self._body
var created : datetime.datetime
-
Datetime of creation of the comment.
Expand source code
@property def created(self) -> datetime.datetime: """Datetime of creation of the comment.""" return self._created
var edited : datetime.datetime
-
Datetime of last edit of the comment.
Expand source code
@property def edited(self) -> datetime.datetime: """Datetime of last edit of the comment.""" return self._edited
var id : int
-
Expand source code
@property def id(self) -> int: return self._id
Methods
def add_reaction(self, reaction: str) ‑> Reaction
-
Reacts to a comment.
Colons in between reaction are not needed, e.g.
comment.add_reaction("+1")
.Args
reaction
- String representing specific reaction to be added.
Returns
Object representing newly added reaction.
Expand source code
def add_reaction(self, reaction: str) -> Reaction: """ Reacts to a comment. Colons in between reaction are not needed, e.g. `comment.add_reaction("+1")`. Args: reaction: String representing specific reaction to be added. Returns: Object representing newly added reaction. """ raise NotImplementedError()
def get_reactions(self) ‑> list[Reaction]
-
Returns list of reactions.
Expand source code
def get_reactions(self) -> list[Reaction]: """Returns list of reactions.""" raise NotImplementedError()
-
class CommitComment (sha: str, body: str, author: str)
-
Attributes
sha
:str
- Hash of the related commit.
body
:str
- Body of the comment.
author
:str
- Login of the author.
Expand source code
class CommitComment(OgrAbstractClass): """ Attributes: sha (str): Hash of the related commit. body (str): Body of the comment. author (str): Login of the author. """ def __init__(self, sha: str, body: str, author: str) -> None: self.sha = sha self.body = body self.author = author @property # type: ignore @deprecate_and_set_removal( since="0.41.0", remove_in="0.46.0 (or 1.0.0 if it comes sooner)", message="Use body", ) def comment(self) -> str: return self.body def __str__(self) -> str: return ( f"CommitComment(commit={self.sha}, author={self.author}, body={self.body})" )
Ancestors
Instance variables
var comment : str
-
Expand source code
@property # type: ignore @deprecate_and_set_removal( since="0.41.0", remove_in="0.46.0 (or 1.0.0 if it comes sooner)", message="Use body", ) def comment(self) -> str: return self.body
class CommitFlag (raw_commit_flag: Optional[Any] = None, project: Optional[ForwardRef('GitProject')] = None, commit: Optional[str] = None, state: Optional[CommitStatus] = None, context: Optional[str] = None, comment: Optional[str] = None, uid: Optional[str] = None, url: Optional[str] = None)
-
Expand source code
class CommitFlag(OgrAbstractClass): _states: ClassVar[dict[str, CommitStatus]] = {} def __init__( self, raw_commit_flag: Optional[Any] = None, project: Optional["GitProject"] = None, commit: Optional[str] = None, state: Optional[CommitStatus] = None, context: Optional[str] = None, comment: Optional[str] = None, uid: Optional[str] = None, url: Optional[str] = None, ) -> None: self.uid = uid self.project = project self.commit = commit if commit and state and context: self.state = state self.context = context self.comment = comment self.url = url else: self._raw_commit_flag = raw_commit_flag self._from_raw_commit_flag() def __str__(self) -> str: return ( f"CommitFlag(" f"commit='{self.commit}', " f"state='{self.state.name}', " f"context='{self.context}', " f"uid='{self.uid}', " f"comment='{self.comment}', " f"url='{self.url}', " f"created='{self.created}', " f"edited='{self.edited}')" ) @classmethod def _state_from_str(cls, state: str) -> CommitStatus: """ Transforms state from string to enumeration. Args: state: String representation of a state. Returns: Commit status. """ raise NotImplementedError() @classmethod def _validate_state(cls, state: CommitStatus) -> CommitStatus: """ Validates state of the commit status (if it can be used with forge). """ raise NotImplementedError() def _from_raw_commit_flag(self) -> None: """ Sets attributes based on the raw flag that has been given through constructor. """ raise NotImplementedError() @staticmethod def get(project: Any, commit: str) -> list["CommitFlag"]: """ Acquire commit statuses for given commit in the project. Args: project (GitProject): Project where the commit is located. commit: Commit hash for which we request statuses. Returns: List of commit statuses for the commit. """ raise NotImplementedError() @staticmethod def set( project: Any, commit: str, state: CommitStatus, target_url: str, description: str, context: str, ) -> "CommitFlag": """ Set a new commit status. Args: project (GitProject): Project where the commit is located. commit: Commit hash for which we set status. state: State for the commit status. target_url: URL for the commit status. description: Description of the commit status. context: Identifier to group related commit statuses. """ raise NotImplementedError() @property def created(self) -> datetime.datetime: """Datetime of creating the commit status.""" raise NotImplementedError() @property def edited(self) -> datetime.datetime: """Datetime of editing the commit status.""" raise NotImplementedError()
Ancestors
Subclasses
Static methods
def get(project: Any, commit: str) ‑> list['CommitFlag']
-
Acquire commit statuses for given commit in the project.
Args
project
:GitProject
- Project where the commit is located.
commit
- Commit hash for which we request statuses.
Returns
List of commit statuses for the commit.
Expand source code
@staticmethod def get(project: Any, commit: str) -> list["CommitFlag"]: """ Acquire commit statuses for given commit in the project. Args: project (GitProject): Project where the commit is located. commit: Commit hash for which we request statuses. Returns: List of commit statuses for the commit. """ raise NotImplementedError()
def set(project: Any, commit: str, state: CommitStatus, target_url: str, description: str, context: str) ‑> CommitFlag
-
Set a new commit status.
Args
project
:GitProject
- Project where the commit is located.
commit
- Commit hash for which we set status.
state
- State for the commit status.
target_url
- URL for the commit status.
description
- Description of the commit status.
context
- Identifier to group related commit statuses.
Expand source code
@staticmethod def set( project: Any, commit: str, state: CommitStatus, target_url: str, description: str, context: str, ) -> "CommitFlag": """ Set a new commit status. Args: project (GitProject): Project where the commit is located. commit: Commit hash for which we set status. state: State for the commit status. target_url: URL for the commit status. description: Description of the commit status. context: Identifier to group related commit statuses. """ raise NotImplementedError()
Instance variables
var created : datetime.datetime
-
Datetime of creating the commit status.
Expand source code
@property def created(self) -> datetime.datetime: """Datetime of creating the commit status.""" raise NotImplementedError()
var edited : datetime.datetime
-
Datetime of editing the commit status.
Expand source code
@property def edited(self) -> datetime.datetime: """Datetime of editing the commit status.""" raise NotImplementedError()
class CommitStatus (value, names=None, *, module=None, qualname=None, type=None, start=1)
-
Enumeration that represents possible state of commit statuses.
Expand source code
class CommitStatus(Enum): """Enumeration that represents possible state of commit statuses.""" pending = 1 success = 2 failure = 3 error = 4 canceled = 5 running = 6
Ancestors
- enum.Enum
Class variables
var canceled
var error
var failure
var pending
var running
var success
class GitProject (repo: str, service: GitService, namespace: str)
-
Args
repo
- Name of the project.
service
- GitService instance.
namespace
-
Namespace of the project.
- GitHub: username or org name.
- GitLab: username or org name.
- Pagure: namespace (e.g.
"rpms"
).
In case of forks:
"fork/{username}/{namespace}"
.
Expand source code
class GitProject(OgrAbstractClass): def __init__(self, repo: str, service: GitService, namespace: str) -> None: """ Args: repo: Name of the project. service: GitService instance. namespace: Namespace of the project. - GitHub: username or org name. - GitLab: username or org name. - Pagure: namespace (e.g. `"rpms"`). In case of forks: `"fork/{username}/{namespace}"`. """ self.service = service self.repo = repo self.namespace = namespace def __str__(self) -> str: return f"GitProject(namespace={self.namespace}, repo={self.repo}, service={self.service})" @property def description(self) -> str: """ Returns: Project description. """ raise NotImplementedError() @description.setter def description(self, new_description: str) -> None: """ Args: new_description: description to set for project. """ raise NotImplementedError() def delete(self) -> None: """Delete the project.""" raise NotImplementedError() def exists(self) -> bool: """ Check the existence of the repo. Returns: `True` if the project exists, `False` otherwise. """ raise NotImplementedError() def is_private(self) -> bool: """ Is this repository private (accessible only by users with permissions). Returns: `True`, if the repository is private. """ raise NotImplementedError() def is_forked(self) -> bool: """ Is this repository forked by the authenticated user? Returns: `True`, if the repository is fork. """ raise NotImplementedError() @property def is_fork(self) -> bool: """`True` if the project is a fork.""" raise NotImplementedError() @property def full_repo_name(self) -> str: """Get repo name with namespace, e.g. `rpms/python-docker-py`.""" raise NotImplementedError() @property def parent(self) -> Optional["GitProject"]: """Parent project if the project is a fork, otherwise `None`.""" raise NotImplementedError() @property def has_issues(self) -> bool: """`True` if issues are enabled on the project.""" raise NotImplementedError() def get_branches(self) -> list[str]: """ Returns: List with names of branches in the project. """ raise NotImplementedError() @property def default_branch(self) -> str: """Default branch (usually `main`, `master` or `trunk`).""" raise NotImplementedError() def get_description(self) -> str: """ Returns: Project description. """ raise NotImplementedError() def get_fork(self, create: bool = True) -> Optional["GitProject"]: """ Provide GitProject instance of a fork of this project. Args: create: Create fork if it does not exist. Returns: `None` if the project is fork itself or there is no fork, otherwise instance of a fork if is to be created or exists already. """ raise NotImplementedError() def get_owners(self) -> list[str]: """ Returns: List of usernames of project owners. """ raise NotImplementedError() def who_can_close_issue(self) -> set[str]: """ Returns: Names of all users who have permission to modify an issue. """ raise NotImplementedError() def who_can_merge_pr(self) -> set[str]: """ Returns: Names of all users who have permission to modify pull request. """ raise NotImplementedError() def which_groups_can_merge_pr(self) -> set[str]: """ Returns: Names of all groups that have permission to modify pull request. """ raise NotImplementedError() def can_merge_pr(self, username: str) -> bool: """ Args: username: Username. Returns: `True` if user merge pull request, `False` otherwise. """ raise NotImplementedError() def get_users_with_given_access(self, access_levels: list[AccessLevel]) -> set[str]: """ Args: access_levels: list of access levels Returns: set of users with given access levels """ raise NotImplementedError() def add_user(self, user: str, access_level: AccessLevel) -> None: """ Add user to project. Args: user: Username of the user. access_level: Permissions for the user. """ raise NotImplementedError() def remove_user(self, user: str) -> None: """ Remove user from project. Args: user: Username of the user. """ raise NotImplementedError() def request_access(self) -> None: """ Request an access to the project (cannot specify access level to be granted; needs to be approved and specified by the user with maintainer/admin rights). """ raise NotImplementedError() def add_group(self, group: str, access_level: AccessLevel) -> None: """ Add group to project. Args: group: Name of the group. access_level: Permissions for the group. """ raise NotImplementedError() def remove_group(self, group: str) -> None: """ Remove group from project. Args: group: Name of the group. """ raise NotImplementedError() def get_issue_list( self, status: IssueStatus = IssueStatus.open, author: Optional[str] = None, assignee: Optional[str] = None, labels: Optional[list[str]] = None, ) -> list["Issue"]: """ List of issues. Args: status: Status of the issues that are to be included in the list. Defaults to `IssueStatus.open`. author: Username of the author of the issues. Defaults to no filtering by author. assignee: Username of the assignee on the issues. Defaults to no filtering by assignees. labels: Filter issues that have set specific labels. Defaults to no filtering by labels. Returns: List of objects that represent requested issues. """ raise NotImplementedError() def get_issue(self, issue_id: int) -> "Issue": """ Get issue. Args: issue_id: ID of the issue. Returns: Object that represents requested issue. """ raise NotImplementedError() def get_issue_info(self, issue_id: int) -> "Issue": """ Get issue info. Args: issue_id: ID of the issue. Returns: Object that represents requested issue. """ raise NotImplementedError() def create_issue( self, title: str, body: str, private: Optional[bool] = None, labels: Optional[list[str]] = None, assignees: Optional[list[str]] = None, ) -> Issue: """ Open new issue. Args: title: Title of the issue. body: Description of the issue. private: Is the new issue supposed to be confidential? **Supported only by GitLab and Pagure.** Defaults to unset. labels: List of labels that are to be added to the issue. Defaults to no labels. assignees: List of usernames of the assignees. Defaults to no assignees. Returns: Object that represents newly created issue. Raises: IssueTrackerDisabled, if issue tracker is disabled. """ raise NotImplementedError() def get_pr_list(self, status: PRStatus = PRStatus.open) -> list["PullRequest"]: """ List of pull requests. Args: status: Status of the pull requests that are to be included in the list. Defaults to `PRStatus.open`. Returns: List of objects that represent pull requests with requested status. """ raise NotImplementedError() def get_pr(self, pr_id: int) -> "PullRequest": """ Get pull request. Args: pr_id: ID of the pull request. Returns: Object that represents requested pull request. """ raise NotImplementedError() def get_pr_files_diff( self, pr_id: int, retries: int = 0, wait_seconds: int = 3, ) -> dict: """ Get files diff of a pull request. Args: pr_id: ID of the pull request. Returns: Dictionary representing files diff. """ raise NotImplementedError() def get_tags(self) -> list["GitTag"]: """ Returns: List of objects that represent tags. """ raise NotImplementedError() def get_sha_from_tag(self, tag_name: str) -> str: """ Args: tag_name: Name of the tag. Returns: Commit hash of the commit from the requested tag. """ raise NotImplementedError() def get_release( self, identifier: Optional[int] = None, name: Optional[str] = None, tag_name: Optional[str] = None, ) -> Release: """ Get a single release. Args: identifier: Identifier of the release. Defaults to `None`, which means not being used. name: Name of the release. Defaults to `None`, which means not being used. tag_name: Tag that the release is tied to. Defaults to `None`, which means not being used. Returns: Object that represents release that satisfies requested condition. """ raise NotImplementedError() def get_latest_release(self) -> Optional[Release]: """ Returns: Object that represents the latest release. """ raise NotImplementedError() def get_releases(self) -> list[Release]: """ Returns: List of the objects that represent releases. """ raise NotImplementedError() def create_release( self, tag: str, name: str, message: str, ref: Optional[str] = None, ) -> Release: """ Create new release. Args: tag: Tag which is the release based off. name: Name of the release. message: Message or description of the release. ref: Git reference, mainly commit hash for the release. If provided git tag is created prior to creating a release. Defaults to `None`. Returns: Object that represents newly created release. """ raise NotImplementedError() def create_pr( self, title: str, body: str, target_branch: str, source_branch: str, fork_username: Optional[str] = None, ) -> "PullRequest": """ Create new pull request. Args: title: Title of the pull request. body: Description of the pull request. target_branch: Name of the branch where the changes are merged. source_branch: Name of the branch from which the changes are pulled. fork_username: The username of forked repository. Defaults to `None`. Returns: Object that represents newly created pull request. """ raise NotImplementedError() def commit_comment( self, commit: str, body: str, filename: Optional[str] = None, row: Optional[int] = None, ) -> "CommitComment": """ Add new comment to a commit. Args: commit: Hash of the commit. body: Body of the comment. filename: Name of the file that is related to the comment. Defaults to `None`, which means no relation to file. row: Number of the row that the comment is related to. Defaults to `None`, which means no relation to the row. Returns: Object that represents newly created commit comment. """ raise NotImplementedError() def get_commit_comments(self, commit: str) -> list[CommitComment]: """ Get comments for a commit. Args: commit: The hash of the commit. Returns: List of all comments for the commit. """ raise NotImplementedError() def set_commit_status( self, commit: str, state: Union[CommitStatus, str], target_url: str, description: str, context: str, trim: bool = False, ) -> "CommitFlag": """ Create a status on a commit. Args: commit: The hash of the commit. state: The state of the status. target_url: The target URL to associate with this status. description: A short description of the status. context: A label to differentiate this status from the status of other systems. trim: Whether to trim the description to 140 characters. Defaults to `False`. Returns: Object that represents created commit status. """ raise NotImplementedError() def get_commit_statuses(self, commit: str) -> list[CommitFlag]: """ Get statuses of the commit. Args: commit: Hash of the commit. Returns: List of all commit statuses on the commit. """ raise NotImplementedError() def get_git_urls(self) -> dict[str, str]: """ Get git URLs for the project. Returns: Dictionary with at least SSH and HTTP URLs for the current project. """ raise NotImplementedError() def fork_create(self, namespace: Optional[str] = None) -> "GitProject": """ Fork this project using the authenticated user. Args: namespace: Namespace where the project should be forked. Defaults to `None`, which means forking to the namespace of currently authenticated user. Returns: Fork of the current project. Raises: In case the fork already exists. """ raise NotImplementedError() def change_token(self, new_token: str) -> None: """ Change an API token. Only for the current instance. Args: new_token: New token to be set. """ raise NotImplementedError def get_file_content(self, path: str, ref: Optional[str] = None) -> str: """ Get a content of the file in the repo. Args: path: Path to the file. ref: Branch or commit. Defaults to repo's default branch. Returns: Contents of the file as string. Raises: FileNotFoundError: if there is no such file. """ raise NotImplementedError def get_files( self, ref: Optional[str] = None, filter_regex: Optional[str] = None, recursive: bool = False, ) -> list[str]: """ Get a list of file paths of the repo. Args: ref: Branch or commit. Defaults to repo's default branch. filter_regex: Filter the paths with `re.search`. Defaults to `None`, which means no filtering. recursive: Whether to return only top directory files or all files recursively. Defaults to `False`, which means only top-level directory. Returns: List of paths of the files in the repo. """ raise NotImplementedError def get_forks(self) -> Sequence["GitProject"]: """ Returns: All forks of the project. """ raise NotImplementedError() def get_web_url(self) -> str: """ Returns: Web URL of the project. """ raise NotImplementedError() def get_sha_from_branch(self, branch: str) -> Optional[str]: """ Returns: Commit SHA of head of the branch. `None` if no branch was found. """ raise NotImplementedError() def get_contributors(self) -> set[str]: """ Returns: Set of all contributors to the given project. """ raise NotImplementedError() def users_with_write_access(self) -> set[str]: """ Returns: List of users who have write access to the project """ raise NotImplementedError("Use subclass instead.") def has_write_access(self, user: str) -> bool: """ Decides whether a given user has write access to the project. Args: user: The user we are going to check to see if he/she has access """ return user in self.users_with_write_access()
Ancestors
Subclasses
Instance variables
var default_branch : str
-
Default branch (usually
main
,master
ortrunk
).Expand source code
@property def default_branch(self) -> str: """Default branch (usually `main`, `master` or `trunk`).""" raise NotImplementedError()
var description : str
-
Returns
Project description.
Expand source code
@property def description(self) -> str: """ Returns: Project description. """ raise NotImplementedError()
var full_repo_name : str
-
Get repo name with namespace, e.g.
rpms/python-docker-py
.Expand source code
@property def full_repo_name(self) -> str: """Get repo name with namespace, e.g. `rpms/python-docker-py`.""" raise NotImplementedError()
var has_issues : bool
-
True
if issues are enabled on the project.Expand source code
@property def has_issues(self) -> bool: """`True` if issues are enabled on the project.""" raise NotImplementedError()
var is_fork : bool
-
True
if the project is a fork.Expand source code
@property def is_fork(self) -> bool: """`True` if the project is a fork.""" raise NotImplementedError()
var parent : Optional[GitProject]
-
Parent project if the project is a fork, otherwise
None
.Expand source code
@property def parent(self) -> Optional["GitProject"]: """Parent project if the project is a fork, otherwise `None`.""" raise NotImplementedError()
Methods
def add_group(self, group: str, access_level: AccessLevel) ‑> None
-
Add group to project.
Args
group
- Name of the group.
access_level
- Permissions for the group.
Expand source code
def add_group(self, group: str, access_level: AccessLevel) -> None: """ Add group to project. Args: group: Name of the group. access_level: Permissions for the group. """ raise NotImplementedError()
def add_user(self, user: str, access_level: AccessLevel) ‑> None
-
Add user to project.
Args
user
- Username of the user.
access_level
- Permissions for the user.
Expand source code
def add_user(self, user: str, access_level: AccessLevel) -> None: """ Add user to project. Args: user: Username of the user. access_level: Permissions for the user. """ raise NotImplementedError()
def can_merge_pr(self, username: str) ‑> bool
-
Args
username
- Username.
Returns
True
if user merge pull request,False
otherwise.Expand source code
def can_merge_pr(self, username: str) -> bool: """ Args: username: Username. Returns: `True` if user merge pull request, `False` otherwise. """ raise NotImplementedError()
def change_token(self, new_token: str) ‑> None
-
Change an API token. Only for the current instance.
Args
new_token
- New token to be set.
Expand source code
def change_token(self, new_token: str) -> None: """ Change an API token. Only for the current instance. Args: new_token: New token to be set. """ raise NotImplementedError
def commit_comment(self, commit: str, body: str, filename: Optional[str] = None, row: Optional[int] = None) ‑> CommitComment
-
Add new comment to a commit.
Args
commit
- Hash of the commit.
body
- Body of the comment.
filename
-
Name of the file that is related to the comment.
Defaults to
None
, which means no relation to file. row
-
Number of the row that the comment is related to.
Defaults to
None
, which means no relation to the row.
Returns
Object that represents newly created commit comment.
Expand source code
def commit_comment( self, commit: str, body: str, filename: Optional[str] = None, row: Optional[int] = None, ) -> "CommitComment": """ Add new comment to a commit. Args: commit: Hash of the commit. body: Body of the comment. filename: Name of the file that is related to the comment. Defaults to `None`, which means no relation to file. row: Number of the row that the comment is related to. Defaults to `None`, which means no relation to the row. Returns: Object that represents newly created commit comment. """ raise NotImplementedError()
def create_issue(self, title: str, body: str, private: Optional[bool] = None, labels: Optional[list[str]] = None, assignees: Optional[list[str]] = None) ‑> Issue
-
Open new issue.
Args
title
- Title of the issue.
body
- Description of the issue.
private
-
Is the new issue supposed to be confidential?
Supported only by GitLab and Pagure.
Defaults to unset.
labels
-
List of labels that are to be added to the issue.
Defaults to no labels.
assignees
-
List of usernames of the assignees.
Defaults to no assignees.
Returns
Object that represents newly created issue.
Raises
IssueTrackerDisabled, if issue tracker is disabled.
Expand source code
def create_issue( self, title: str, body: str, private: Optional[bool] = None, labels: Optional[list[str]] = None, assignees: Optional[list[str]] = None, ) -> Issue: """ Open new issue. Args: title: Title of the issue. body: Description of the issue. private: Is the new issue supposed to be confidential? **Supported only by GitLab and Pagure.** Defaults to unset. labels: List of labels that are to be added to the issue. Defaults to no labels. assignees: List of usernames of the assignees. Defaults to no assignees. Returns: Object that represents newly created issue. Raises: IssueTrackerDisabled, if issue tracker is disabled. """ raise NotImplementedError()
def create_pr(self, title: str, body: str, target_branch: str, source_branch: str, fork_username: Optional[str] = None) ‑> PullRequest
-
Create new pull request.
Args
title
- Title of the pull request.
body
- Description of the pull request.
target_branch
- Name of the branch where the changes are merged.
source_branch
- Name of the branch from which the changes are pulled.
fork_username
-
The username of forked repository.
Defaults to
None
.
Returns
Object that represents newly created pull request.
Expand source code
def create_pr( self, title: str, body: str, target_branch: str, source_branch: str, fork_username: Optional[str] = None, ) -> "PullRequest": """ Create new pull request. Args: title: Title of the pull request. body: Description of the pull request. target_branch: Name of the branch where the changes are merged. source_branch: Name of the branch from which the changes are pulled. fork_username: The username of forked repository. Defaults to `None`. Returns: Object that represents newly created pull request. """ raise NotImplementedError()
def create_release(self, tag: str, name: str, message: str, ref: Optional[str] = None) ‑> Release
-
Create new release.
Args
tag
- Tag which is the release based off.
name
- Name of the release.
message
- Message or description of the release.
ref
-
Git reference, mainly commit hash for the release. If provided git tag is created prior to creating a release.
Defaults to
None
.
Returns
Object that represents newly created release.
Expand source code
def create_release( self, tag: str, name: str, message: str, ref: Optional[str] = None, ) -> Release: """ Create new release. Args: tag: Tag which is the release based off. name: Name of the release. message: Message or description of the release. ref: Git reference, mainly commit hash for the release. If provided git tag is created prior to creating a release. Defaults to `None`. Returns: Object that represents newly created release. """ raise NotImplementedError()
def delete(self) ‑> None
-
Delete the project.
Expand source code
def delete(self) -> None: """Delete the project.""" raise NotImplementedError()
def exists(self) ‑> bool
-
Check the existence of the repo.
Returns
True
if the project exists,False
otherwise.Expand source code
def exists(self) -> bool: """ Check the existence of the repo. Returns: `True` if the project exists, `False` otherwise. """ raise NotImplementedError()
def fork_create(self, namespace: Optional[str] = None) ‑> GitProject
-
Fork this project using the authenticated user.
Args
namespace
-
Namespace where the project should be forked.
Defaults to
None
, which means forking to the namespace of currently authenticated user.
Returns
Fork of the current project.
Raises
In case the fork already exists.
Expand source code
def fork_create(self, namespace: Optional[str] = None) -> "GitProject": """ Fork this project using the authenticated user. Args: namespace: Namespace where the project should be forked. Defaults to `None`, which means forking to the namespace of currently authenticated user. Returns: Fork of the current project. Raises: In case the fork already exists. """ raise NotImplementedError()
def get_branches(self) ‑> list[str]
-
Returns
List with names of branches in the project.
Expand source code
def get_branches(self) -> list[str]: """ Returns: List with names of branches in the project. """ raise NotImplementedError()
def get_commit_comments(self, commit: str) ‑> list[CommitComment]
-
Get comments for a commit.
Args
commit
- The hash of the commit.
Returns
List of all comments for the commit.
Expand source code
def get_commit_comments(self, commit: str) -> list[CommitComment]: """ Get comments for a commit. Args: commit: The hash of the commit. Returns: List of all comments for the commit. """ raise NotImplementedError()
def get_commit_statuses(self, commit: str) ‑> list[CommitFlag]
-
Get statuses of the commit.
Args
commit
- Hash of the commit.
Returns
List of all commit statuses on the commit.
Expand source code
def get_commit_statuses(self, commit: str) -> list[CommitFlag]: """ Get statuses of the commit. Args: commit: Hash of the commit. Returns: List of all commit statuses on the commit. """ raise NotImplementedError()
def get_contributors(self) ‑> set[str]
-
Returns
Set of all contributors to the given project.
Expand source code
def get_contributors(self) -> set[str]: """ Returns: Set of all contributors to the given project. """ raise NotImplementedError()
def get_description(self) ‑> str
-
Returns
Project description.
Expand source code
def get_description(self) -> str: """ Returns: Project description. """ raise NotImplementedError()
def get_file_content(self, path: str, ref: Optional[str] = None) ‑> str
-
Get a content of the file in the repo.
Args
path
- Path to the file.
ref
-
Branch or commit.
Defaults to repo's default branch.
Returns
Contents of the file as string.
Raises
FileNotFoundError
- if there is no such file.
Expand source code
def get_file_content(self, path: str, ref: Optional[str] = None) -> str: """ Get a content of the file in the repo. Args: path: Path to the file. ref: Branch or commit. Defaults to repo's default branch. Returns: Contents of the file as string. Raises: FileNotFoundError: if there is no such file. """ raise NotImplementedError
def get_files(self, ref: Optional[str] = None, filter_regex: Optional[str] = None, recursive: bool = False) ‑> list[str]
-
Get a list of file paths of the repo.
Args
ref
-
Branch or commit.
Defaults to repo's default branch.
filter_regex
-
Filter the paths with
re.search
.Defaults to
None
, which means no filtering. recursive
-
Whether to return only top directory files or all files recursively.
Defaults to
False
, which means only top-level directory.
Returns
List of paths of the files in the repo.
Expand source code
def get_files( self, ref: Optional[str] = None, filter_regex: Optional[str] = None, recursive: bool = False, ) -> list[str]: """ Get a list of file paths of the repo. Args: ref: Branch or commit. Defaults to repo's default branch. filter_regex: Filter the paths with `re.search`. Defaults to `None`, which means no filtering. recursive: Whether to return only top directory files or all files recursively. Defaults to `False`, which means only top-level directory. Returns: List of paths of the files in the repo. """ raise NotImplementedError
def get_fork(self, create: bool = True) ‑> Optional[GitProject]
-
Provide GitProject instance of a fork of this project.
Args
create
- Create fork if it does not exist.
Returns
None
if the project is fork itself or there is no fork, otherwise instance of a fork if is to be created or exists already.Expand source code
def get_fork(self, create: bool = True) -> Optional["GitProject"]: """ Provide GitProject instance of a fork of this project. Args: create: Create fork if it does not exist. Returns: `None` if the project is fork itself or there is no fork, otherwise instance of a fork if is to be created or exists already. """ raise NotImplementedError()
def get_forks(self) ‑> collections.abc.Sequence['GitProject']
-
Returns
All forks of the project.
Expand source code
def get_forks(self) -> Sequence["GitProject"]: """ Returns: All forks of the project. """ raise NotImplementedError()
def get_git_urls(self) ‑> dict[str, str]
-
Get git URLs for the project.
Returns
Dictionary with at least SSH and HTTP URLs for the current project.
Expand source code
def get_git_urls(self) -> dict[str, str]: """ Get git URLs for the project. Returns: Dictionary with at least SSH and HTTP URLs for the current project. """ raise NotImplementedError()
def get_issue(self, issue_id: int) ‑> Issue
-
Get issue.
Args
issue_id
- ID of the issue.
Returns
Object that represents requested issue.
Expand source code
def get_issue(self, issue_id: int) -> "Issue": """ Get issue. Args: issue_id: ID of the issue. Returns: Object that represents requested issue. """ raise NotImplementedError()
def get_issue_info(self, issue_id: int) ‑> Issue
-
Get issue info.
Args
issue_id
- ID of the issue.
Returns
Object that represents requested issue.
Expand source code
def get_issue_info(self, issue_id: int) -> "Issue": """ Get issue info. Args: issue_id: ID of the issue. Returns: Object that represents requested issue. """ raise NotImplementedError()
def get_issue_list(self, status: IssueStatus = IssueStatus.open, author: Optional[str] = None, assignee: Optional[str] = None, labels: Optional[list[str]] = None) ‑> list['Issue']
-
List of issues.
Args
status
-
Status of the issues that are to be included in the list.
Defaults to
IssueStatus.open
. author
-
Username of the author of the issues.
Defaults to no filtering by author.
assignee
-
Username of the assignee on the issues.
Defaults to no filtering by assignees.
labels
-
Filter issues that have set specific labels.
Defaults to no filtering by labels.
Returns
List of objects that represent requested issues.
Expand source code
def get_issue_list( self, status: IssueStatus = IssueStatus.open, author: Optional[str] = None, assignee: Optional[str] = None, labels: Optional[list[str]] = None, ) -> list["Issue"]: """ List of issues. Args: status: Status of the issues that are to be included in the list. Defaults to `IssueStatus.open`. author: Username of the author of the issues. Defaults to no filtering by author. assignee: Username of the assignee on the issues. Defaults to no filtering by assignees. labels: Filter issues that have set specific labels. Defaults to no filtering by labels. Returns: List of objects that represent requested issues. """ raise NotImplementedError()
def get_latest_release(self) ‑> Optional[Release]
-
Returns
Object that represents the latest release.
Expand source code
def get_latest_release(self) -> Optional[Release]: """ Returns: Object that represents the latest release. """ raise NotImplementedError()
def get_owners(self) ‑> list[str]
-
Returns
List of usernames of project owners.
Expand source code
def get_owners(self) -> list[str]: """ Returns: List of usernames of project owners. """ raise NotImplementedError()
def get_pr(self, pr_id: int) ‑> PullRequest
-
Get pull request.
Args
pr_id
- ID of the pull request.
Returns
Object that represents requested pull request.
Expand source code
def get_pr(self, pr_id: int) -> "PullRequest": """ Get pull request. Args: pr_id: ID of the pull request. Returns: Object that represents requested pull request. """ raise NotImplementedError()
def get_pr_files_diff(self, pr_id: int, retries: int = 0, wait_seconds: int = 3) ‑> dict
-
Get files diff of a pull request.
Args
pr_id
- ID of the pull request.
Returns
Dictionary representing files diff.
Expand source code
def get_pr_files_diff( self, pr_id: int, retries: int = 0, wait_seconds: int = 3, ) -> dict: """ Get files diff of a pull request. Args: pr_id: ID of the pull request. Returns: Dictionary representing files diff. """ raise NotImplementedError()
def get_pr_list(self, status: PRStatus = PRStatus.open) ‑> list['PullRequest']
-
List of pull requests.
Args
status
-
Status of the pull requests that are to be included in the list.
Defaults to
PRStatus.open
.
Returns
List of objects that represent pull requests with requested status.
Expand source code
def get_pr_list(self, status: PRStatus = PRStatus.open) -> list["PullRequest"]: """ List of pull requests. Args: status: Status of the pull requests that are to be included in the list. Defaults to `PRStatus.open`. Returns: List of objects that represent pull requests with requested status. """ raise NotImplementedError()
def get_release(self, identifier: Optional[int] = None, name: Optional[str] = None, tag_name: Optional[str] = None) ‑> Release
-
Get a single release.
Args
identifier
-
Identifier of the release.
Defaults to
None
, which means not being used. name
-
Name of the release.
Defaults to
None
, which means not being used. tag_name
-
Tag that the release is tied to.
Defaults to
None
, which means not being used.
Returns
Object that represents release that satisfies requested condition.
Expand source code
def get_release( self, identifier: Optional[int] = None, name: Optional[str] = None, tag_name: Optional[str] = None, ) -> Release: """ Get a single release. Args: identifier: Identifier of the release. Defaults to `None`, which means not being used. name: Name of the release. Defaults to `None`, which means not being used. tag_name: Tag that the release is tied to. Defaults to `None`, which means not being used. Returns: Object that represents release that satisfies requested condition. """ raise NotImplementedError()
def get_releases(self) ‑> list[Release]
-
Returns
List of the objects that represent releases.
Expand source code
def get_releases(self) -> list[Release]: """ Returns: List of the objects that represent releases. """ raise NotImplementedError()
def get_sha_from_branch(self, branch: str) ‑> Optional[str]
-
Returns
Commit SHA of head of the branch.
None
if no branch was found.Expand source code
def get_sha_from_branch(self, branch: str) -> Optional[str]: """ Returns: Commit SHA of head of the branch. `None` if no branch was found. """ raise NotImplementedError()
def get_sha_from_tag(self, tag_name: str) ‑> str
-
Args
tag_name
- Name of the tag.
Returns
Commit hash of the commit from the requested tag.
Expand source code
def get_sha_from_tag(self, tag_name: str) -> str: """ Args: tag_name: Name of the tag. Returns: Commit hash of the commit from the requested tag. """ raise NotImplementedError()
-
Returns
List of objects that represent tags.
Expand source code
def get_tags(self) -> list["GitTag"]: """ Returns: List of objects that represent tags. """ raise NotImplementedError()
def get_users_with_given_access(self, access_levels: list[AccessLevel]) ‑> set[str]
-
Args
access_levels
- list of access levels
Returns
set of users with given access levels
Expand source code
def get_users_with_given_access(self, access_levels: list[AccessLevel]) -> set[str]: """ Args: access_levels: list of access levels Returns: set of users with given access levels """ raise NotImplementedError()
def get_web_url(self) ‑> str
-
Returns
Web URL of the project.
Expand source code
def get_web_url(self) -> str: """ Returns: Web URL of the project. """ raise NotImplementedError()
def has_write_access(self, user: str) ‑> bool
-
Decides whether a given user has write access to the project.
Args
user
- The user we are going to check to see if he/she has access
Expand source code
def has_write_access(self, user: str) -> bool: """ Decides whether a given user has write access to the project. Args: user: The user we are going to check to see if he/she has access """ return user in self.users_with_write_access()
def is_forked(self) ‑> bool
-
Is this repository forked by the authenticated user?
Returns
True
, if the repository is fork.Expand source code
def is_forked(self) -> bool: """ Is this repository forked by the authenticated user? Returns: `True`, if the repository is fork. """ raise NotImplementedError()
def is_private(self) ‑> bool
-
Is this repository private (accessible only by users with permissions).
Returns
True
, if the repository is private.Expand source code
def is_private(self) -> bool: """ Is this repository private (accessible only by users with permissions). Returns: `True`, if the repository is private. """ raise NotImplementedError()
def remove_group(self, group: str) ‑> None
-
Remove group from project.
Args
group
- Name of the group.
Expand source code
def remove_group(self, group: str) -> None: """ Remove group from project. Args: group: Name of the group. """ raise NotImplementedError()
def remove_user(self, user: str) ‑> None
-
Remove user from project.
Args
user
- Username of the user.
Expand source code
def remove_user(self, user: str) -> None: """ Remove user from project. Args: user: Username of the user. """ raise NotImplementedError()
def request_access(self) ‑> None
-
Request an access to the project (cannot specify access level to be granted; needs to be approved and specified by the user with maintainer/admin rights).
Expand source code
def request_access(self) -> None: """ Request an access to the project (cannot specify access level to be granted; needs to be approved and specified by the user with maintainer/admin rights). """ raise NotImplementedError()
def set_commit_status(self, commit: str, state: Union[CommitStatus, str], target_url: str, description: str, context: str, trim: bool = False) ‑> CommitFlag
-
Create a status on a commit.
Args
commit
- The hash of the commit.
state
- The state of the status.
target_url
- The target URL to associate with this status.
description
- A short description of the status.
context
- A label to differentiate this status from the status of other systems.
trim
-
Whether to trim the description to 140 characters.
Defaults to
False
.
Returns
Object that represents created commit status.
Expand source code
def set_commit_status( self, commit: str, state: Union[CommitStatus, str], target_url: str, description: str, context: str, trim: bool = False, ) -> "CommitFlag": """ Create a status on a commit. Args: commit: The hash of the commit. state: The state of the status. target_url: The target URL to associate with this status. description: A short description of the status. context: A label to differentiate this status from the status of other systems. trim: Whether to trim the description to 140 characters. Defaults to `False`. Returns: Object that represents created commit status. """ raise NotImplementedError()
def users_with_write_access(self) ‑> set[str]
-
Returns
List of users who have write access to the project
Expand source code
def users_with_write_access(self) -> set[str]: """ Returns: List of users who have write access to the project """ raise NotImplementedError("Use subclass instead.")
def which_groups_can_merge_pr(self) ‑> set[str]
-
Returns
Names of all groups that have permission to modify pull request.
Expand source code
def which_groups_can_merge_pr(self) -> set[str]: """ Returns: Names of all groups that have permission to modify pull request. """ raise NotImplementedError()
def who_can_close_issue(self) ‑> set[str]
-
Returns
Names of all users who have permission to modify an issue.
Expand source code
def who_can_close_issue(self) -> set[str]: """ Returns: Names of all users who have permission to modify an issue. """ raise NotImplementedError()
def who_can_merge_pr(self) ‑> set[str]
-
Returns
Names of all users who have permission to modify pull request.
Expand source code
def who_can_merge_pr(self) -> set[str]: """ Returns: Names of all users who have permission to modify pull request. """ raise NotImplementedError()
class GitService (**_: Any)
-
Attributes
instance_url
:str
- URL of the git forge instance.
Expand source code
class GitService(OgrAbstractClass): """ Attributes: instance_url (str): URL of the git forge instance. """ instance_url: Optional[str] = None def __init__(self, **_: Any) -> None: pass def __str__(self) -> str: return f"GitService(instance_url={self.instance_url})" def get_project(self, **kwargs: Any) -> "GitProject": """ Get the requested project. Args: namespace (str): Namespace of the project. user (str): Username of the project's owner. repo (str): Repository name. Returns: Object that represents git project. """ raise NotImplementedError def get_project_from_url(self, url: str) -> "GitProject": """ Args: url: URL of the git repository. Returns: Object that represents project from the parsed URL. """ repo_url = parse_git_repo(potential_url=url) if not repo_url: raise OgrException(f"Failed to find repository for url: {url}") return self.get_project(repo=repo_url.repo, namespace=repo_url.namespace) @_cached_property def hostname(self) -> Optional[str]: """Hostname of the service.""" raise NotImplementedError @property def user(self) -> "GitUser": """User authenticated through the service.""" raise NotImplementedError def change_token(self, new_token: str) -> None: """ Change an API token. Only for the current instance and newly created projects. Args: new_token: New token to be set. """ raise NotImplementedError def set_auth_method(self, method: AuthMethod) -> None: """ Override the default auth method. Can be used when the service has more auth methods available. Args: method: the method identifier (a str name) """ raise NotImplementedError() def reset_auth_method(self) -> None: """ Set the auth method to the default one. """ raise NotImplementedError() def project_create( self, repo: str, namespace: Optional[str] = None, description: Optional[str] = None, ) -> "GitProject": """ Create new project. Args: repo: Name of the newly created project. namespace: Namespace of the newly created project. Defaults to currently authenticated user. description: Description of the newly created project. Returns: Object that represents newly created project. """ raise NotImplementedError() def list_projects( self, namespace: Optional[str] = None, user: Optional[str] = None, search_pattern: Optional[str] = None, language: Optional[str] = None, ) -> list["GitProject"]: """ List projects for given criteria. Args: namespace: Namespace to list projects from. user: Login of the owner of the projects. search_pattern: Regular expression that repository name should match. language: Language to be present in the project, e.g. `"python"` or `"html"`. """ raise NotImplementedError def get_group(self, group_name: str): """ Get a group by name. """ raise NotImplementedError
Ancestors
Subclasses
Class variables
var instance_url : Optional[str]
Instance variables
var hostname
-
Hostname of the service.
Expand source code
def __get__(self, instance, owner=None): if instance is None: return self if self.attrname is None: raise TypeError( "Cannot use cached_property instance without calling __set_name__ on it.") try: cache = instance.__dict__ except AttributeError: # not all objects have __dict__ (e.g. class defines slots) msg = ( f"No '__dict__' attribute on {type(instance).__name__!r} " f"instance to cache {self.attrname!r} property." ) raise TypeError(msg) from None val = cache.get(self.attrname, _NOT_FOUND) if val is _NOT_FOUND: with self.lock: # check if another thread filled cache while we awaited lock val = cache.get(self.attrname, _NOT_FOUND) if val is _NOT_FOUND: val = self.func(instance) try: cache[self.attrname] = val except TypeError: msg = ( f"The '__dict__' attribute on {type(instance).__name__!r} instance " f"does not support item assignment for caching {self.attrname!r} property." ) raise TypeError(msg) from None return val
var user : GitUser
-
User authenticated through the service.
Expand source code
@property def user(self) -> "GitUser": """User authenticated through the service.""" raise NotImplementedError
Methods
def change_token(self, new_token: str) ‑> None
-
Change an API token. Only for the current instance and newly created projects.
Args
new_token
- New token to be set.
Expand source code
def change_token(self, new_token: str) -> None: """ Change an API token. Only for the current instance and newly created projects. Args: new_token: New token to be set. """ raise NotImplementedError
def get_group(self, group_name: str)
-
Get a group by name.
Expand source code
def get_group(self, group_name: str): """ Get a group by name. """ raise NotImplementedError
def get_project(self, **kwargs: Any) ‑> GitProject
-
Get the requested project.
Args
namespace
:str
- Namespace of the project.
user
:str
- Username of the project's owner.
repo
:str
- Repository name.
Returns
Object that represents git project.
Expand source code
def get_project(self, **kwargs: Any) -> "GitProject": """ Get the requested project. Args: namespace (str): Namespace of the project. user (str): Username of the project's owner. repo (str): Repository name. Returns: Object that represents git project. """ raise NotImplementedError
def get_project_from_url(self, url: str) ‑> GitProject
-
Args
url
- URL of the git repository.
Returns
Object that represents project from the parsed URL.
Expand source code
def get_project_from_url(self, url: str) -> "GitProject": """ Args: url: URL of the git repository. Returns: Object that represents project from the parsed URL. """ repo_url = parse_git_repo(potential_url=url) if not repo_url: raise OgrException(f"Failed to find repository for url: {url}") return self.get_project(repo=repo_url.repo, namespace=repo_url.namespace)
def list_projects(self, namespace: Optional[str] = None, user: Optional[str] = None, search_pattern: Optional[str] = None, language: Optional[str] = None) ‑> list['GitProject']
-
List projects for given criteria.
Args
namespace
- Namespace to list projects from.
user
- Login of the owner of the projects.
search_pattern
- Regular expression that repository name should match.
language
- Language to be present in the project, e.g.
"python"
or"html"
.
Expand source code
def list_projects( self, namespace: Optional[str] = None, user: Optional[str] = None, search_pattern: Optional[str] = None, language: Optional[str] = None, ) -> list["GitProject"]: """ List projects for given criteria. Args: namespace: Namespace to list projects from. user: Login of the owner of the projects. search_pattern: Regular expression that repository name should match. language: Language to be present in the project, e.g. `"python"` or `"html"`. """ raise NotImplementedError
def project_create(self, repo: str, namespace: Optional[str] = None, description: Optional[str] = None) ‑> GitProject
-
Create new project.
Args
repo
- Name of the newly created project.
namespace
-
Namespace of the newly created project.
Defaults to currently authenticated user.
description
- Description of the newly created project.
Returns
Object that represents newly created project.
Expand source code
def project_create( self, repo: str, namespace: Optional[str] = None, description: Optional[str] = None, ) -> "GitProject": """ Create new project. Args: repo: Name of the newly created project. namespace: Namespace of the newly created project. Defaults to currently authenticated user. description: Description of the newly created project. Returns: Object that represents newly created project. """ raise NotImplementedError()
def reset_auth_method(self) ‑> None
-
Set the auth method to the default one.
Expand source code
def reset_auth_method(self) -> None: """ Set the auth method to the default one. """ raise NotImplementedError()
def set_auth_method(self, method: AuthMethod) ‑> None
-
Override the default auth method. Can be used when the service has more auth methods available.
Args
method
- the method identifier (a str name)
Expand source code
def set_auth_method(self, method: AuthMethod) -> None: """ Override the default auth method. Can be used when the service has more auth methods available. Args: method: the method identifier (a str name) """ raise NotImplementedError()
class GitTag (name: str, commit_sha: str)
-
Class representing a git tag.
Attributes
name
:str
- Name of the tag.
commit_sha
:str
- Commit hash of the tag.
Expand source code
class GitTag(OgrAbstractClass): """ Class representing a git tag. Attributes: name (str): Name of the tag. commit_sha (str): Commit hash of the tag. """ def __init__(self, name: str, commit_sha: str) -> None: self.name = name self.commit_sha = commit_sha def __str__(self) -> str: return f"GitTag(name={self.name}, commit_sha={self.commit_sha})"
Ancestors
class GitUser (service: GitService)
-
Represents currently authenticated user through service.
Expand source code
class GitUser(OgrAbstractClass): """ Represents currently authenticated user through service. """ def __init__(self, service: GitService) -> None: self.service = service def get_username(self) -> str: """ Returns: Login of the user. """ raise NotImplementedError() def get_email(self) -> str: """ Returns: Email of the user. """ raise NotImplementedError() def get_projects(self) -> Sequence["GitProject"]: """ Returns: Sequence of projects in user's namespace. """ raise NotImplementedError() def get_forks(self) -> Sequence["GitProject"]: """ Returns: Sequence of forks in user's namespace. """ raise NotImplementedError()
Ancestors
Subclasses
Methods
def get_email(self) ‑> str
-
Returns
Email of the user.
Expand source code
def get_email(self) -> str: """ Returns: Email of the user. """ raise NotImplementedError()
def get_forks(self) ‑> collections.abc.Sequence['GitProject']
-
Returns
Sequence of forks in user's namespace.
Expand source code
def get_forks(self) -> Sequence["GitProject"]: """ Returns: Sequence of forks in user's namespace. """ raise NotImplementedError()
def get_projects(self) ‑> collections.abc.Sequence['GitProject']
-
Returns
Sequence of projects in user's namespace.
Expand source code
def get_projects(self) -> Sequence["GitProject"]: """ Returns: Sequence of projects in user's namespace. """ raise NotImplementedError()
def get_username(self) ‑> str
-
Returns
Login of the user.
Expand source code
def get_username(self) -> str: """ Returns: Login of the user. """ raise NotImplementedError()
class Issue (raw_issue: Any, project: GitProject)
-
Attributes
project
:GitProject
- Project of the issue.
Expand source code
class Issue(OgrAbstractClass): """ Attributes: project (GitProject): Project of the issue. """ def __init__(self, raw_issue: Any, project: "GitProject") -> None: self._raw_issue = raw_issue self.project = project @property def title(self) -> str: """Title of the issue.""" raise NotImplementedError() @property def private(self) -> bool: """`True` if issue is confidential, `False` otherwise.""" raise NotImplementedError() @property def id(self) -> int: """ID of the issue.""" raise NotImplementedError() @property def status(self) -> IssueStatus: """Status of the issue.""" raise NotImplementedError() @property def url(self) -> str: """Web URL of the issue.""" raise NotImplementedError() @property def description(self) -> str: """Description of the issue.""" raise NotImplementedError() @property def author(self) -> str: """Username of the author of the issue.""" raise NotImplementedError() @property def created(self) -> datetime.datetime: """Datetime of the creation of the issue.""" raise NotImplementedError() @property def labels(self) -> list["IssueLabel"]: """Labels of the issue.""" raise NotImplementedError() def __str__(self) -> str: description = ( f"{self.description[:10]}..." if self.description is not None else "None" ) return ( f"Issue(" f"title='{self.title}', " f"id={self.id}, " f"status='{self.status.name}', " f"url='{self.url}', " f"description='{description}', " f"author='{self.author}', " f"created='{self.created}')" ) @staticmethod def create( project: Any, title: str, body: str, private: Optional[bool] = None, labels: Optional[list[str]] = None, assignees: Optional[list[str]] = None, ) -> "Issue": """ Open new issue. Args: project (GitProject): Project where the issue is to be opened. title: Title of the issue. body: Description of the issue. private: Is the new issue supposed to be confidential? **Supported only by GitLab and Pagure.** Defaults to unset. labels: List of labels that are to be added to the issue. Defaults to no labels. assignees: List of usernames of the assignees. Defaults to no assignees. Returns: Object that represents newly created issue. """ raise NotImplementedError() @staticmethod def get(project: Any, id: int) -> "Issue": """ Get issue. Args: project (GitProject): Project where the issue is to be opened. issue_id: ID of the issue. Returns: Object that represents requested issue. """ raise NotImplementedError() @staticmethod def get_list( project: Any, status: IssueStatus = IssueStatus.open, author: Optional[str] = None, assignee: Optional[str] = None, labels: Optional[list[str]] = None, ) -> list["Issue"]: """ List of issues. Args: project (GitProject): Project where the issue is to be opened. status: Status of the issues that are to be included in the list. Defaults to `IssueStatus.open`. author: Username of the author of the issues. Defaults to no filtering by author. assignee: Username of the assignee on the issues. Defaults to no filtering by assignees. labels: Filter issues that have set specific labels. Defaults to no filtering by labels. Returns: List of objects that represent requested issues. """ raise NotImplementedError() def _get_all_comments(self) -> list[IssueComment]: """ Get list of all issue comments. Returns: List of all comments on the issue. """ raise NotImplementedError() def get_comments( self, filter_regex: Optional[str] = None, reverse: bool = False, author: Optional[str] = None, ) -> list[IssueComment]: """ Get list of issue comments. Args: filter_regex: Filter the comments' content with `re.search`. Defaults to `None`, which means no filtering. reverse: Whether the comments are to be returned in reversed order. Defaults to `False`. author: Filter the comments by author. Defaults to `None`, which means no filtering. Returns: List of issue comments. """ raise NotImplementedError() def can_close(self, username: str) -> bool: """ Check if user have permissions to modify an issue. Args: username: Login of the user. Returns: `True` if user can close the issue, `False` otherwise. """ raise NotImplementedError() def comment(self, body: str) -> IssueComment: """ Add new comment to the issue. Args: body: Text contents of the comment. Returns: Object that represents posted comment. """ raise NotImplementedError() def close(self) -> "Issue": """ Close an issue. Returns: Issue itself. """ raise NotImplementedError() def add_label(self, *labels: str) -> None: """ Add labels to the issue. Args: *labels: Labels to be added. """ raise NotImplementedError() def add_assignee(self, *assignees: str) -> None: """ Assign users to an issue. Args: *assignees: List of logins of the assignees. """ raise NotImplementedError() def get_comment(self, comment_id: int) -> IssueComment: """ Returns an issue comment. Args: comment_id: id of a comment Returns: Object representing an issue comment. """ raise NotImplementedError()
Ancestors
Subclasses
Static methods
def create(project: Any, title: str, body: str, private: Optional[bool] = None, labels: Optional[list[str]] = None, assignees: Optional[list[str]] = None) ‑> Issue
-
Open new issue.
Args
project
:GitProject
- Project where the issue is to be opened.
title
- Title of the issue.
body
- Description of the issue.
private
-
Is the new issue supposed to be confidential?
Supported only by GitLab and Pagure.
Defaults to unset.
labels
-
List of labels that are to be added to the issue.
Defaults to no labels.
assignees
-
List of usernames of the assignees.
Defaults to no assignees.
Returns
Object that represents newly created issue.
Expand source code
@staticmethod def create( project: Any, title: str, body: str, private: Optional[bool] = None, labels: Optional[list[str]] = None, assignees: Optional[list[str]] = None, ) -> "Issue": """ Open new issue. Args: project (GitProject): Project where the issue is to be opened. title: Title of the issue. body: Description of the issue. private: Is the new issue supposed to be confidential? **Supported only by GitLab and Pagure.** Defaults to unset. labels: List of labels that are to be added to the issue. Defaults to no labels. assignees: List of usernames of the assignees. Defaults to no assignees. Returns: Object that represents newly created issue. """ raise NotImplementedError()
def get(project: Any, id: int) ‑> Issue
-
Get issue.
Args
project
:GitProject
- Project where the issue is to be opened.
issue_id
- ID of the issue.
Returns
Object that represents requested issue.
Expand source code
@staticmethod def get(project: Any, id: int) -> "Issue": """ Get issue. Args: project (GitProject): Project where the issue is to be opened. issue_id: ID of the issue. Returns: Object that represents requested issue. """ raise NotImplementedError()
def get_list(project: Any, status: IssueStatus = IssueStatus.open, author: Optional[str] = None, assignee: Optional[str] = None, labels: Optional[list[str]] = None) ‑> list['Issue']
-
List of issues.
Args
project
:GitProject
- Project where the issue is to be opened.
status
-
Status of the issues that are to be included in the list.
Defaults to
IssueStatus.open
. author
-
Username of the author of the issues.
Defaults to no filtering by author.
assignee
-
Username of the assignee on the issues.
Defaults to no filtering by assignees.
labels
-
Filter issues that have set specific labels.
Defaults to no filtering by labels.
Returns
List of objects that represent requested issues.
Expand source code
@staticmethod def get_list( project: Any, status: IssueStatus = IssueStatus.open, author: Optional[str] = None, assignee: Optional[str] = None, labels: Optional[list[str]] = None, ) -> list["Issue"]: """ List of issues. Args: project (GitProject): Project where the issue is to be opened. status: Status of the issues that are to be included in the list. Defaults to `IssueStatus.open`. author: Username of the author of the issues. Defaults to no filtering by author. assignee: Username of the assignee on the issues. Defaults to no filtering by assignees. labels: Filter issues that have set specific labels. Defaults to no filtering by labels. Returns: List of objects that represent requested issues. """ raise NotImplementedError()
Instance variables
-
Username of the author of the issue.
Expand source code
@property def author(self) -> str: """Username of the author of the issue.""" raise NotImplementedError()
var created : datetime.datetime
-
Datetime of the creation of the issue.
Expand source code
@property def created(self) -> datetime.datetime: """Datetime of the creation of the issue.""" raise NotImplementedError()
var description : str
-
Description of the issue.
Expand source code
@property def description(self) -> str: """Description of the issue.""" raise NotImplementedError()
var id : int
-
ID of the issue.
Expand source code
@property def id(self) -> int: """ID of the issue.""" raise NotImplementedError()
var labels : list['IssueLabel']
-
Labels of the issue.
Expand source code
@property def labels(self) -> list["IssueLabel"]: """Labels of the issue.""" raise NotImplementedError()
var private : bool
-
True
if issue is confidential,False
otherwise.Expand source code
@property def private(self) -> bool: """`True` if issue is confidential, `False` otherwise.""" raise NotImplementedError()
var status : IssueStatus
-
Status of the issue.
Expand source code
@property def status(self) -> IssueStatus: """Status of the issue.""" raise NotImplementedError()
var title : str
-
Title of the issue.
Expand source code
@property def title(self) -> str: """Title of the issue.""" raise NotImplementedError()
var url : str
-
Web URL of the issue.
Expand source code
@property def url(self) -> str: """Web URL of the issue.""" raise NotImplementedError()
Methods
def add_assignee(self, *assignees: str) ‑> None
-
Assign users to an issue.
Args
*assignees
- List of logins of the assignees.
Expand source code
def add_assignee(self, *assignees: str) -> None: """ Assign users to an issue. Args: *assignees: List of logins of the assignees. """ raise NotImplementedError()
def add_label(self, *labels: str) ‑> None
-
Add labels to the issue.
Args
*labels
- Labels to be added.
Expand source code
def add_label(self, *labels: str) -> None: """ Add labels to the issue. Args: *labels: Labels to be added. """ raise NotImplementedError()
def can_close(self, username: str) ‑> bool
-
Check if user have permissions to modify an issue.
Args
username
- Login of the user.
Returns
True
if user can close the issue,False
otherwise.Expand source code
def can_close(self, username: str) -> bool: """ Check if user have permissions to modify an issue. Args: username: Login of the user. Returns: `True` if user can close the issue, `False` otherwise. """ raise NotImplementedError()
def close(self) ‑> Issue
-
Close an issue.
Returns
Issue itself.
Expand source code
def close(self) -> "Issue": """ Close an issue. Returns: Issue itself. """ raise NotImplementedError()
def comment(self, body: str) ‑> IssueComment
-
Add new comment to the issue.
Args
body
- Text contents of the comment.
Returns
Object that represents posted comment.
Expand source code
def comment(self, body: str) -> IssueComment: """ Add new comment to the issue. Args: body: Text contents of the comment. Returns: Object that represents posted comment. """ raise NotImplementedError()
def get_comment(self, comment_id: int) ‑> IssueComment
-
Returns an issue comment.
Args
comment_id
- id of a comment
Returns
Object representing an issue comment.
Expand source code
def get_comment(self, comment_id: int) -> IssueComment: """ Returns an issue comment. Args: comment_id: id of a comment Returns: Object representing an issue comment. """ raise NotImplementedError()
def get_comments(self, filter_regex: Optional[str] = None, reverse: bool = False, author: Optional[str] = None) ‑> list[IssueComment]
-
Get list of issue comments.
Args
filter_regex
-
Filter the comments' content with
re.search
.Defaults to
None
, which means no filtering. reverse
-
Whether the comments are to be returned in reversed order.
Defaults to
False
. author
-
Filter the comments by author.
Defaults to
None
, which means no filtering.
Returns
List of issue comments.
Expand source code
def get_comments( self, filter_regex: Optional[str] = None, reverse: bool = False, author: Optional[str] = None, ) -> list[IssueComment]: """ Get list of issue comments. Args: filter_regex: Filter the comments' content with `re.search`. Defaults to `None`, which means no filtering. reverse: Whether the comments are to be returned in reversed order. Defaults to `False`. author: Filter the comments by author. Defaults to `None`, which means no filtering. Returns: List of issue comments. """ raise NotImplementedError()
class IssueComment (raw_comment: Optional[Any] = None, parent: Optional[Any] = None, body: Optional[str] = None, id_: Optional[int] = None, author: Optional[str] = None, created: Optional[datetime.datetime] = None, edited: Optional[datetime.datetime] = None)
-
Expand source code
class IssueComment(Comment): @property def issue(self) -> "Issue": """Issue of issue comment.""" return self._parent def __str__(self) -> str: return "Issue" + super().__str__()
Ancestors
Subclasses
Instance variables
var issue : Issue
-
Issue of issue comment.
Expand source code
@property def issue(self) -> "Issue": """Issue of issue comment.""" return self._parent
Inherited members
class IssueLabel (parent: Any)
-
Represents labels on PRs and issues.
Expand source code
class IssueLabel(Label): @property def issue(self) -> "Issue": """Issue of issue label.""" return self._parent def __str__(self) -> str: return "Issue" + super().__str__()
Ancestors
Subclasses
Instance variables
var issue : Issue
-
Issue of issue label.
Expand source code
@property def issue(self) -> "Issue": """Issue of issue label.""" return self._parent
Inherited members
class IssueStatus (value, names=None, *, module=None, qualname=None, type=None, start=1)
-
Enumeration for issue statuses.
Expand source code
class IssueStatus(IntEnum): """Enumeration for issue statuses.""" open = 1 closed = 2 all = 3
Ancestors
- enum.IntEnum
- builtins.int
- enum.Enum
Class variables
var all
var closed
var open
class Label (parent: Any)
-
Represents labels on PRs and issues.
Expand source code
class Label(OgrAbstractClass): """ Represents labels on PRs and issues. """ def __init__(self, parent: Any) -> None: self._parent = parent @property def name(self) -> str: """Name of the label.""" raise NotImplementedError()
Ancestors
Subclasses
Instance variables
var name : str
-
Name of the label.
Expand source code
@property def name(self) -> str: """Name of the label.""" raise NotImplementedError()
class MergeCommitStatus (value, names=None, *, module=None, qualname=None, type=None, start=1)
-
Enumeration that represents possible states of merge states of PR/MR.
Expand source code
class MergeCommitStatus(Enum): """Enumeration that represents possible states of merge states of PR/MR.""" can_be_merged = 1 cannot_be_merged = 2 unchecked = 3 checking = 4 cannot_be_merged_recheck = 5
Ancestors
- enum.Enum
Class variables
var can_be_merged
var cannot_be_merged
var cannot_be_merged_recheck
var checking
var unchecked
class OgrAbstractClass
-
Expand source code
class OgrAbstractClass(metaclass=CatchCommonErrors): def __repr__(self) -> str: return f"<{self!s}>"
Subclasses
class PRComment (raw_comment: Optional[Any] = None, parent: Optional[Any] = None, body: Optional[str] = None, id_: Optional[int] = None, author: Optional[str] = None, created: Optional[datetime.datetime] = None, edited: Optional[datetime.datetime] = None)
-
Expand source code
class PRComment(Comment): @property def pull_request(self) -> "PullRequest": """Pull request of pull request comment.""" return self._parent def __str__(self) -> str: return "PR" + super().__str__()
Ancestors
Subclasses
Instance variables
var pull_request : PullRequest
-
Pull request of pull request comment.
Expand source code
@property def pull_request(self) -> "PullRequest": """Pull request of pull request comment.""" return self._parent
Inherited members
class PRLabel (parent: Any)
-
Represents labels on PRs and issues.
Expand source code
class PRLabel(Label): @property def pull_request(self) -> "PullRequest": """Pull request of pull request label.""" return self._parent def __str__(self) -> str: return "PR" + super().__str__()
Ancestors
Subclasses
Instance variables
var pull_request : PullRequest
-
Pull request of pull request label.
Expand source code
@property def pull_request(self) -> "PullRequest": """Pull request of pull request label.""" return self._parent
Inherited members
class PRStatus (value, names=None, *, module=None, qualname=None, type=None, start=1)
-
Enumeration that represents statuses of pull requests.
Expand source code
class PRStatus(IntEnum): """Enumeration that represents statuses of pull requests.""" open = 1 closed = 2 merged = 3 all = 4
Ancestors
- enum.IntEnum
- builtins.int
- enum.Enum
Class variables
var all
var closed
var merged
var open
class PullRequest (raw_pr: Any, project: GitProject)
-
Attributes
project
:GitProject
- Project of the pull request.
Expand source code
class PullRequest(OgrAbstractClass): """ Attributes: project (GitProject): Project of the pull request. """ def __init__(self, raw_pr: Any, project: "GitProject") -> None: self._raw_pr = raw_pr self._target_project = project @property def title(self) -> str: """Title of the pull request.""" raise NotImplementedError() @title.setter def title(self, new_title: str) -> None: raise NotImplementedError() @property def id(self) -> int: """ID of the pull request.""" raise NotImplementedError() @property def status(self) -> PRStatus: """Status of the pull request.""" raise NotImplementedError() @property def url(self) -> str: """Web URL of the pull request.""" raise NotImplementedError() @property def description(self) -> str: """Description of the pull request.""" raise NotImplementedError() @description.setter def description(self, new_description: str) -> None: raise NotImplementedError @property def author(self) -> str: """Login of the author of the pull request.""" raise NotImplementedError() @property def source_branch(self) -> str: """Name of the source branch (from which the changes are pulled).""" raise NotImplementedError() @property def target_branch(self) -> str: """Name of the target branch (where the changes are being merged).""" raise NotImplementedError() @property def created(self) -> datetime.datetime: """Datetime of creating the pull request.""" raise NotImplementedError() @property def labels(self) -> list["PRLabel"]: """Labels of the pull request.""" raise NotImplementedError() @property def diff_url(self) -> str: """Web URL to the diff of the pull request.""" raise NotImplementedError() @property def patch(self) -> bytes: """Patch of the pull request.""" raise NotImplementedError() @property def head_commit(self) -> str: """Commit hash of the HEAD commit of the pull request.""" raise NotImplementedError() @property def target_branch_head_commit(self) -> str: """Commit hash of the HEAD commit of the target branch.""" raise NotImplementedError() @property def merge_commit_sha(self) -> str: """ Commit hash of the merge commit of the pull request. Before merging represents test merge commit, if git forge supports it. """ raise NotImplementedError() @property def merge_commit_status(self) -> MergeCommitStatus: """Current status of the test merge commit.""" raise NotImplementedError() @property def source_project(self) -> "GitProject": """Object that represents source project (from which the changes are pulled).""" raise NotImplementedError() @property def target_project(self) -> "GitProject": """Object that represents target project (where changes are merged).""" return self._target_project @property def commits_url(self) -> str: """Web URL to the list of commits in the pull request.""" raise NotImplementedError() @property def closed_by(self) -> Optional[str]: """Login of the account that closed the pull request.""" raise NotImplementedError def __str__(self) -> str: description = ( f"{self.description[:10]}..." if self.description is not None else "None" ) return ( f"PullRequest(" f"title='{self.title}', " f"id={self.id}, " f"status='{self.status.name}', " f"url='{self.url}', " f"diff_url='{self.diff_url}', " f"description='{description}', " f"author='{self.author}', " f"source_branch='{self.source_branch}', " f"target_branch='{self.target_branch}', " f"created='{self.created}')" ) @staticmethod def create( project: Any, title: str, body: str, target_branch: str, source_branch: str, fork_username: Optional[str] = None, ) -> "PullRequest": """ Create new pull request. Args: project (GitProject): Project where the pull request will be created. title: Title of the pull request. body: Description of the pull request. target_branch: Branch in the project where the changes are being merged. source_branch: Branch from which the changes are being pulled. fork_username: The username/namespace of the forked repository. Returns: Object that represents newly created pull request. """ raise NotImplementedError() @staticmethod def get(project: Any, id: int) -> "PullRequest": """ Get pull request. Args: project (GitProject): Project where the pull request is located. id: ID of the pull request. Returns: Object that represents pull request. """ raise NotImplementedError() @staticmethod def get_list(project: Any, status: PRStatus = PRStatus.open) -> list["PullRequest"]: """ List of pull requests. Args: project (GitProject): Project where the pull requests are located. status: Filters out the pull requests. Defaults to `PRStatus.open`. Returns: List of pull requests with requested status. """ raise NotImplementedError() def update_info( self, title: Optional[str] = None, description: Optional[str] = None, ) -> "PullRequest": """ Update pull request information. Args: title: The new title of the pull request. Defaults to `None`, which means no updating. description: The new description of the pull request. Defaults to `None`, which means no updating. Returns: Pull request itself. """ raise NotImplementedError() def _get_all_comments(self) -> list[PRComment]: """ Get list of all pull request comments. Returns: List of all comments on the pull request. """ raise NotImplementedError() def get_comments( self, filter_regex: Optional[str] = None, reverse: bool = False, author: Optional[str] = None, ) -> list["PRComment"]: """ Get list of pull request comments. Args: filter_regex: Filter the comments' content with `re.search`. Defaults to `None`, which means no filtering. reverse: Whether the comments are to be returned in reversed order. Defaults to `False`. author: Filter the comments by author. Defaults to `None`, which means no filtering. Returns: List of pull request comments. """ raise NotImplementedError() def get_all_commits(self) -> list[str]: """ Returns: List of commit hashes of commits in pull request. """ raise NotImplementedError() def search( self, filter_regex: str, reverse: bool = False, description: bool = True, ) -> Optional[Match[str]]: """ Find match in pull request description or comments. Args: filter_regex: Regex that is used to filter the comments' content with `re.search`. reverse: Reverse order of the comments. Defaults to `False`. description: Whether description is included in the search. Defaults to `True`. Returns: `re.Match` if found, `None` otherwise. """ raise NotImplementedError() def comment( self, body: str, commit: Optional[str] = None, filename: Optional[str] = None, row: Optional[int] = None, ) -> "PRComment": """ Add new comment to the pull request. Args: body: Body of the comment. commit: Commit hash to which comment is related. Defaults to generic comment. filename: Path to the file to which comment is related. Defaults to no relation to the file. row: Line number to which the comment is related. Defaults to no relation to the line. Returns: Newly created comment. """ raise NotImplementedError() def close(self) -> "PullRequest": """ Close the pull request. Returns: Pull request itself. """ raise NotImplementedError() def merge(self) -> "PullRequest": """ Merge the pull request. Returns: Pull request itself. """ raise NotImplementedError() def add_label(self, *labels: str) -> None: """ Add labels to the pull request. Args: *labels: Labels to be added. """ raise NotImplementedError() def get_statuses(self) -> list["CommitFlag"]: """ Returns statuses for latest commit on pull request. Returns: List of commit statuses of the latest commit. """ raise NotImplementedError() def get_comment(self, comment_id: int) -> PRComment: """ Returns a PR comment. Args: comment_id: id of comment Returns: Object representing a PR comment. """ raise NotImplementedError()
Ancestors
Subclasses
Static methods
def create(project: Any, title: str, body: str, target_branch: str, source_branch: str, fork_username: Optional[str] = None) ‑> PullRequest
-
Create new pull request.
Args
project
:GitProject
- Project where the pull request will be created.
title
- Title of the pull request.
body
- Description of the pull request.
target_branch
- Branch in the project where the changes are being merged.
source_branch
- Branch from which the changes are being pulled.
fork_username
- The username/namespace of the forked repository.
Returns
Object that represents newly created pull request.
Expand source code
@staticmethod def create( project: Any, title: str, body: str, target_branch: str, source_branch: str, fork_username: Optional[str] = None, ) -> "PullRequest": """ Create new pull request. Args: project (GitProject): Project where the pull request will be created. title: Title of the pull request. body: Description of the pull request. target_branch: Branch in the project where the changes are being merged. source_branch: Branch from which the changes are being pulled. fork_username: The username/namespace of the forked repository. Returns: Object that represents newly created pull request. """ raise NotImplementedError()
def get(project: Any, id: int) ‑> PullRequest
-
Get pull request.
Args
project
:GitProject
- Project where the pull request is located.
id
- ID of the pull request.
Returns
Object that represents pull request.
Expand source code
@staticmethod def get(project: Any, id: int) -> "PullRequest": """ Get pull request. Args: project (GitProject): Project where the pull request is located. id: ID of the pull request. Returns: Object that represents pull request. """ raise NotImplementedError()
def get_list(project: Any, status: PRStatus = PRStatus.open) ‑> list['PullRequest']
-
List of pull requests.
Args
project
:GitProject
- Project where the pull requests are located.
status
-
Filters out the pull requests.
Defaults to
PRStatus.open
.
Returns
List of pull requests with requested status.
Expand source code
@staticmethod def get_list(project: Any, status: PRStatus = PRStatus.open) -> list["PullRequest"]: """ List of pull requests. Args: project (GitProject): Project where the pull requests are located. status: Filters out the pull requests. Defaults to `PRStatus.open`. Returns: List of pull requests with requested status. """ raise NotImplementedError()
Instance variables
-
Login of the author of the pull request.
Expand source code
@property def author(self) -> str: """Login of the author of the pull request.""" raise NotImplementedError()
var closed_by : Optional[str]
-
Login of the account that closed the pull request.
Expand source code
@property def closed_by(self) -> Optional[str]: """Login of the account that closed the pull request.""" raise NotImplementedError
var commits_url : str
-
Web URL to the list of commits in the pull request.
Expand source code
@property def commits_url(self) -> str: """Web URL to the list of commits in the pull request.""" raise NotImplementedError()
var created : datetime.datetime
-
Datetime of creating the pull request.
Expand source code
@property def created(self) -> datetime.datetime: """Datetime of creating the pull request.""" raise NotImplementedError()
var description : str
-
Description of the pull request.
Expand source code
@property def description(self) -> str: """Description of the pull request.""" raise NotImplementedError()
var diff_url : str
-
Web URL to the diff of the pull request.
Expand source code
@property def diff_url(self) -> str: """Web URL to the diff of the pull request.""" raise NotImplementedError()
var head_commit : str
-
Commit hash of the HEAD commit of the pull request.
Expand source code
@property def head_commit(self) -> str: """Commit hash of the HEAD commit of the pull request.""" raise NotImplementedError()
var id : int
-
ID of the pull request.
Expand source code
@property def id(self) -> int: """ID of the pull request.""" raise NotImplementedError()
var labels : list['PRLabel']
-
Labels of the pull request.
Expand source code
@property def labels(self) -> list["PRLabel"]: """Labels of the pull request.""" raise NotImplementedError()
var merge_commit_sha : str
-
Commit hash of the merge commit of the pull request.
Before merging represents test merge commit, if git forge supports it.
Expand source code
@property def merge_commit_sha(self) -> str: """ Commit hash of the merge commit of the pull request. Before merging represents test merge commit, if git forge supports it. """ raise NotImplementedError()
var merge_commit_status : MergeCommitStatus
-
Current status of the test merge commit.
Expand source code
@property def merge_commit_status(self) -> MergeCommitStatus: """Current status of the test merge commit.""" raise NotImplementedError()
var patch : bytes
-
Patch of the pull request.
Expand source code
@property def patch(self) -> bytes: """Patch of the pull request.""" raise NotImplementedError()
var source_branch : str
-
Name of the source branch (from which the changes are pulled).
Expand source code
@property def source_branch(self) -> str: """Name of the source branch (from which the changes are pulled).""" raise NotImplementedError()
var source_project : GitProject
-
Object that represents source project (from which the changes are pulled).
Expand source code
@property def source_project(self) -> "GitProject": """Object that represents source project (from which the changes are pulled).""" raise NotImplementedError()
var status : PRStatus
-
Status of the pull request.
Expand source code
@property def status(self) -> PRStatus: """Status of the pull request.""" raise NotImplementedError()
var target_branch : str
-
Name of the target branch (where the changes are being merged).
Expand source code
@property def target_branch(self) -> str: """Name of the target branch (where the changes are being merged).""" raise NotImplementedError()
var target_branch_head_commit : str
-
Commit hash of the HEAD commit of the target branch.
Expand source code
@property def target_branch_head_commit(self) -> str: """Commit hash of the HEAD commit of the target branch.""" raise NotImplementedError()
var target_project : GitProject
-
Object that represents target project (where changes are merged).
Expand source code
@property def target_project(self) -> "GitProject": """Object that represents target project (where changes are merged).""" return self._target_project
var title : str
-
Title of the pull request.
Expand source code
@property def title(self) -> str: """Title of the pull request.""" raise NotImplementedError()
var url : str
-
Web URL of the pull request.
Expand source code
@property def url(self) -> str: """Web URL of the pull request.""" raise NotImplementedError()
Methods
def add_label(self, *labels: str) ‑> None
-
Add labels to the pull request.
Args
*labels
- Labels to be added.
Expand source code
def add_label(self, *labels: str) -> None: """ Add labels to the pull request. Args: *labels: Labels to be added. """ raise NotImplementedError()
def close(self) ‑> PullRequest
-
Close the pull request.
Returns
Pull request itself.
Expand source code
def close(self) -> "PullRequest": """ Close the pull request. Returns: Pull request itself. """ raise NotImplementedError()
def comment(self, body: str, commit: Optional[str] = None, filename: Optional[str] = None, row: Optional[int] = None) ‑> PRComment
-
Add new comment to the pull request.
Args
body
- Body of the comment.
commit
-
Commit hash to which comment is related.
Defaults to generic comment.
filename
-
Path to the file to which comment is related.
Defaults to no relation to the file.
row
-
Line number to which the comment is related.
Defaults to no relation to the line.
Returns
Newly created comment.
Expand source code
def comment( self, body: str, commit: Optional[str] = None, filename: Optional[str] = None, row: Optional[int] = None, ) -> "PRComment": """ Add new comment to the pull request. Args: body: Body of the comment. commit: Commit hash to which comment is related. Defaults to generic comment. filename: Path to the file to which comment is related. Defaults to no relation to the file. row: Line number to which the comment is related. Defaults to no relation to the line. Returns: Newly created comment. """ raise NotImplementedError()
def get_all_commits(self) ‑> list[str]
-
Returns
List of commit hashes of commits in pull request.
Expand source code
def get_all_commits(self) -> list[str]: """ Returns: List of commit hashes of commits in pull request. """ raise NotImplementedError()
def get_comment(self, comment_id: int) ‑> PRComment
-
Returns a PR comment.
Args
comment_id
- id of comment
Returns
Object representing a PR comment.
Expand source code
def get_comment(self, comment_id: int) -> PRComment: """ Returns a PR comment. Args: comment_id: id of comment Returns: Object representing a PR comment. """ raise NotImplementedError()
def get_comments(self, filter_regex: Optional[str] = None, reverse: bool = False, author: Optional[str] = None) ‑> list['PRComment']
-
Get list of pull request comments.
Args
filter_regex
-
Filter the comments' content with
re.search
.Defaults to
None
, which means no filtering. reverse
-
Whether the comments are to be returned in reversed order.
Defaults to
False
. author
-
Filter the comments by author.
Defaults to
None
, which means no filtering.
Returns
List of pull request comments.
Expand source code
def get_comments( self, filter_regex: Optional[str] = None, reverse: bool = False, author: Optional[str] = None, ) -> list["PRComment"]: """ Get list of pull request comments. Args: filter_regex: Filter the comments' content with `re.search`. Defaults to `None`, which means no filtering. reverse: Whether the comments are to be returned in reversed order. Defaults to `False`. author: Filter the comments by author. Defaults to `None`, which means no filtering. Returns: List of pull request comments. """ raise NotImplementedError()
def get_statuses(self) ‑> list['CommitFlag']
-
Returns statuses for latest commit on pull request.
Returns
List of commit statuses of the latest commit.
Expand source code
def get_statuses(self) -> list["CommitFlag"]: """ Returns statuses for latest commit on pull request. Returns: List of commit statuses of the latest commit. """ raise NotImplementedError()
def merge(self) ‑> PullRequest
-
Merge the pull request.
Returns
Pull request itself.
Expand source code
def merge(self) -> "PullRequest": """ Merge the pull request. Returns: Pull request itself. """ raise NotImplementedError()
def search(self, filter_regex: str, reverse: bool = False, description: bool = True) ‑> Optional[re.Match[str]]
-
Find match in pull request description or comments.
Args
filter_regex
- Regex that is used to filter the comments' content with
re.search
. reverse
-
Reverse order of the comments.
Defaults to
False
. description
-
Whether description is included in the search.
Defaults to
True
.
Returns
re.Match
if found,None
otherwise.Expand source code
def search( self, filter_regex: str, reverse: bool = False, description: bool = True, ) -> Optional[Match[str]]: """ Find match in pull request description or comments. Args: filter_regex: Regex that is used to filter the comments' content with `re.search`. reverse: Reverse order of the comments. Defaults to `False`. description: Whether description is included in the search. Defaults to `True`. Returns: `re.Match` if found, `None` otherwise. """ raise NotImplementedError()
def update_info(self, title: Optional[str] = None, description: Optional[str] = None) ‑> PullRequest
-
Update pull request information.
Args
title
-
The new title of the pull request.
Defaults to
None
, which means no updating. description
-
The new description of the pull request.
Defaults to
None
, which means no updating.
Returns
Pull request itself.
Expand source code
def update_info( self, title: Optional[str] = None, description: Optional[str] = None, ) -> "PullRequest": """ Update pull request information. Args: title: The new title of the pull request. Defaults to `None`, which means no updating. description: The new description of the pull request. Defaults to `None`, which means no updating. Returns: Pull request itself. """ raise NotImplementedError()
class Reaction (raw_reaction: Any)
-
Expand source code
class Reaction(OgrAbstractClass): def __init__(self, raw_reaction: Any) -> None: self._raw_reaction = raw_reaction def __str__(self): return f"Reaction(raw_reaction={self._raw_reaction})" def delete(self) -> None: """Delete a reaction.""" raise NotImplementedError()
Ancestors
Subclasses
Methods
def delete(self) ‑> None
-
Delete a reaction.
Expand source code
def delete(self) -> None: """Delete a reaction.""" raise NotImplementedError()
class Release (raw_release: Any, project: GitProject)
-
Object that represents release.
Attributes
project
:GitProject
- Project on which the release is created.
Expand source code
class Release(OgrAbstractClass): """ Object that represents release. Attributes: project (GitProject): Project on which the release is created. """ def __init__( self, raw_release: Any, project: "GitProject", ) -> None: self._raw_release = raw_release self.project = project def __str__(self) -> str: return ( f"Release(" f"title='{self.title}', " f"body='{self.body}', " f"tag_name='{self.tag_name}', " f"url='{self.url}', " f"created_at='{self.created_at}', " f"tarball_url='{self.tarball_url}')" ) @property def title(self) -> str: """Title of the release.""" raise NotImplementedError() @property def body(self) -> str: """Body of the release.""" raise NotImplementedError() @property def git_tag(self) -> GitTag: """Object that represents tag tied to the release.""" raise NotImplementedError() @property def tag_name(self) -> str: """Tag tied to the release.""" raise NotImplementedError() @property def url(self) -> Optional[str]: """URL of the release.""" raise NotImplementedError() # TODO: Check if should really be string @property def created_at(self) -> datetime.datetime: """Datetime of creating the release.""" raise NotImplementedError() @property def tarball_url(self) -> str: """URL of the tarball.""" raise NotImplementedError() @staticmethod def get( project: Any, identifier: Optional[int] = None, name: Optional[str] = None, tag_name: Optional[str] = None, ) -> "Release": """ Get a single release. Args: identifier: Identifier of the release. Defaults to `None`, which means not being used. name: Name of the release. Defaults to `None`, which means not being used. tag_name: Tag that the release is tied to. Defaults to `None`, which means not being used. Returns: Object that represents release that satisfies requested condition. """ raise NotImplementedError() @staticmethod def get_latest(project: Any) -> Optional["Release"]: """ Returns: Object that represents the latest release. """ raise NotImplementedError() @staticmethod def get_list(project: Any) -> list["Release"]: """ Returns: List of the objects that represent releases. """ raise NotImplementedError() @staticmethod def create( project: Any, tag: str, name: str, message: str, ref: Optional[str] = None, ) -> "Release": """ Create new release. Args: project: Project where the release is to be created. tag: Tag which is the release based off. name: Name of the release. message: Message or description of the release. ref: Git reference, mainly commit hash for the release. If provided git tag is created prior to creating a release. Defaults to `None`. Returns: Object that represents newly created release. """ raise NotImplementedError() def save_archive(self, filename: str) -> None: """ Save tarball of the release to requested `filename`. Args: filename: Path to the file to save archive to. """ raise NotImplementedError() def edit_release(self, name: str, message: str) -> None: """ Edit name and message of a release. Args: name: Name of the release. message: Description of the release. """ raise NotImplementedError()
Ancestors
Subclasses
Static methods
def create(project: Any, tag: str, name: str, message: str, ref: Optional[str] = None) ‑> Release
-
Create new release.
Args
project
- Project where the release is to be created.
tag
- Tag which is the release based off.
name
- Name of the release.
message
- Message or description of the release.
ref
-
Git reference, mainly commit hash for the release. If provided git tag is created prior to creating a release.
Defaults to
None
.
Returns
Object that represents newly created release.
Expand source code
@staticmethod def create( project: Any, tag: str, name: str, message: str, ref: Optional[str] = None, ) -> "Release": """ Create new release. Args: project: Project where the release is to be created. tag: Tag which is the release based off. name: Name of the release. message: Message or description of the release. ref: Git reference, mainly commit hash for the release. If provided git tag is created prior to creating a release. Defaults to `None`. Returns: Object that represents newly created release. """ raise NotImplementedError()
def get(project: Any, identifier: Optional[int] = None, name: Optional[str] = None, tag_name: Optional[str] = None) ‑> Release
-
Get a single release.
Args
identifier
-
Identifier of the release.
Defaults to
None
, which means not being used. name
-
Name of the release.
Defaults to
None
, which means not being used. tag_name
-
Tag that the release is tied to.
Defaults to
None
, which means not being used.
Returns
Object that represents release that satisfies requested condition.
Expand source code
@staticmethod def get( project: Any, identifier: Optional[int] = None, name: Optional[str] = None, tag_name: Optional[str] = None, ) -> "Release": """ Get a single release. Args: identifier: Identifier of the release. Defaults to `None`, which means not being used. name: Name of the release. Defaults to `None`, which means not being used. tag_name: Tag that the release is tied to. Defaults to `None`, which means not being used. Returns: Object that represents release that satisfies requested condition. """ raise NotImplementedError()
def get_latest(project: Any) ‑> Optional[Release]
-
Returns
Object that represents the latest release.
Expand source code
@staticmethod def get_latest(project: Any) -> Optional["Release"]: """ Returns: Object that represents the latest release. """ raise NotImplementedError()
def get_list(project: Any) ‑> list['Release']
-
Returns
List of the objects that represent releases.
Expand source code
@staticmethod def get_list(project: Any) -> list["Release"]: """ Returns: List of the objects that represent releases. """ raise NotImplementedError()
Instance variables
var body : str
-
Body of the release.
Expand source code
@property def body(self) -> str: """Body of the release.""" raise NotImplementedError()
var created_at : datetime.datetime
-
Datetime of creating the release.
Expand source code
@property def created_at(self) -> datetime.datetime: """Datetime of creating the release.""" raise NotImplementedError()
var git_tag : GitTag
-
Object that represents tag tied to the release.
Expand source code
@property def git_tag(self) -> GitTag: """Object that represents tag tied to the release.""" raise NotImplementedError()
var tag_name : str
-
Tag tied to the release.
Expand source code
@property def tag_name(self) -> str: """Tag tied to the release.""" raise NotImplementedError()
var tarball_url : str
-
URL of the tarball.
Expand source code
@property def tarball_url(self) -> str: """URL of the tarball.""" raise NotImplementedError()
var title : str
-
Title of the release.
Expand source code
@property def title(self) -> str: """Title of the release.""" raise NotImplementedError()
var url : Optional[str]
-
URL of the release.
Expand source code
@property def url(self) -> Optional[str]: """URL of the release.""" raise NotImplementedError()
Methods
def edit_release(self, name: str, message: str) ‑> None
-
Edit name and message of a release.
Args
name
- Name of the release.
message
- Description of the release.
Expand source code
def edit_release(self, name: str, message: str) -> None: """ Edit name and message of a release. Args: name: Name of the release. message: Description of the release. """ raise NotImplementedError()
def save_archive(self, filename: str) ‑> None
-
Save tarball of the release to requested
filename
.Args
filename
- Path to the file to save archive to.
Expand source code
def save_archive(self, filename: str) -> None: """ Save tarball of the release to requested `filename`. Args: filename: Path to the file to save archive to. """ raise NotImplementedError()