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

var author : str

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 or trunk).

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()
def get_tags(self) ‑> list['GitTag']

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 userGitUser

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

var author : str

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 statusIssueStatus

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 issueIssue

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 issueIssue

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_requestPullRequest

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_requestPullRequest

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

var author : str

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_statusMergeCommitStatus

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_projectGitProject

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 statusPRStatus

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_projectGitProject

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_tagGitTag

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()