feat: allow returning “Iterable” along lists

Based on the discussion we had during the arch about ogr pagination,
let's start with relaxing the abstract interface to allow returning
iterables instead of full lists.

Signed-off-by: Matej Focko <[email protected]>

Author: mfocko

ogr/abstract.py

@@ -245,7 +245,7 @@ def edited(self) -> datetime.datetime:
         """Datetime of last edit of the comment."""
         return self._edited
 
-    def get_reactions(self) -> list[Reaction]:
+    def get_reactions(self) -> Union[list[Reaction], Iterable[Reaction]]:
         """Returns list of reactions."""
         raise NotImplementedError()
 
@@ -343,7 +343,7 @@ def created(self) -> datetime.datetime:
         raise NotImplementedError()
 
     @property
-    def labels(self) -> list["IssueLabel"]:
+    def labels(self) -> Union[list["IssueLabel"], Iterable["IssueLabel"]]:
         """Labels of the issue."""
         raise NotImplementedError()
 
@@ -417,7 +417,7 @@ def get_list(
         author: Optional[str] = None,
         assignee: Optional[str] = None,
         labels: Optional[list[str]] = None,
-    ) -> list["Issue"]:
+    ) -> Union[list["Issue"], Iterable["Issue"]]:
         """
         List of issues.
 
@@ -644,7 +644,7 @@ def created(self) -> datetime.datetime:
         raise NotImplementedError()
 
     @property
-    def labels(self) -> list["PRLabel"]:
+    def labels(self) -> Union[list["PRLabel"], Iterable["PRLabel"]]:
         """Labels of the pull request."""
         raise NotImplementedError()
 
@@ -761,7 +761,10 @@ def get(project: Any, id: int) -> "PullRequest":
         raise NotImplementedError()
 
     @staticmethod
-    def get_list(project: Any, status: PRStatus = PRStatus.open) -> list["PullRequest"]:
+    def get_list(
+        project: Any,
+        status: PRStatus = PRStatus.open,
+    ) -> Union[list["PullRequest"], Iterable["PullRequest"]]:
         """
         List of pull requests.
 
@@ -841,7 +844,7 @@ def get_comments(
         """
         raise NotImplementedError()
 
-    def get_all_commits(self) -> list[str]:
+    def get_all_commits(self) -> Union[list[str], Iterable[str]]:
         """
         Returns:
             List of commit hashes of commits in pull request.
@@ -925,7 +928,7 @@ def add_label(self, *labels: str) -> None:
         """
         raise NotImplementedError()
 
-    def get_statuses(self) -> list["CommitFlag"]:
+    def get_statuses(self) -> Union[list["CommitFlag"], Iterable["CommitFlag"]]:
         """
         Returns statuses for latest commit on pull request.
 
@@ -1014,7 +1017,10 @@ def _from_raw_commit_flag(self) -> None:
         raise NotImplementedError()
 
     @staticmethod
-    def get(project: Any, commit: str) -> list["CommitFlag"]:
+    def get(
+        project: Any,
+        commit: str,
+    ) -> Union[list["CommitFlag"], Iterable["CommitFlag"]]:
         """
         Acquire commit statuses for given commit in the project.
 
@@ -1226,7 +1232,7 @@ def get_latest(project: Any) -> Optional["Release"]:
         raise NotImplementedError()
 
     @staticmethod
-    def get_list(project: Any) -> list["Release"]:
+    def get_list(project: Any) -> Union[list["Release"], Iterable["Release"]]:
         """
         Returns:
             List of the objects that represent releases.
@@ -1388,7 +1394,7 @@ def list_projects(
         user: Optional[str] = None,
         search_pattern: Optional[str] = None,
         language: Optional[str] = None,
-    ) -> list["GitProject"]:
+    ) -> Union[list["GitProject"], Iterable["GitProject"]]:
         """
         List projects for given criteria.
 
@@ -1496,7 +1502,7 @@ def has_issues(self) -> bool:
         """`True` if issues are enabled on the project."""
         raise NotImplementedError()
 
-    def get_branches(self) -> list[str]:
+    def get_branches(self) -> Union[list[str], Iterable[str]]:
         """
         Returns:
             List with names of branches in the project.
@@ -1508,7 +1514,7 @@ def default_branch(self) -> str:
         """Default branch (usually `main`, `master` or `trunk`)."""
         raise NotImplementedError()
 
-    def get_commits(self, ref: Optional[str] = None) -> list[str]:
+    def get_commits(self, ref: Optional[str] = None) -> Union[list[str], Iterable[str]]:
         """
         Get list of commits for the project.
 
@@ -1540,7 +1546,7 @@ def get_fork(self, create: bool = True) -> Optional["GitProject"]:
         """
         raise NotImplementedError()
 
-    def get_owners(self) -> list[str]:
+    def get_owners(self) -> Union[list[str], Iterable[str]]:
         """
         Returns:
             List of usernames of project owners.
@@ -1639,7 +1645,7 @@ def get_issue_list(
         author: Optional[str] = None,
         assignee: Optional[str] = None,
         labels: Optional[list[str]] = None,
-    ) -> list["Issue"]:
+    ) -> Union[list["Issue"], Iterable["Issue"]]:
         """
         List of issues.
 
@@ -1722,7 +1728,10 @@ def create_issue(
         """
         raise NotImplementedError()
 
-    def get_pr_list(self, status: PRStatus = PRStatus.open) -> list["PullRequest"]:
+    def get_pr_list(
+        self,
+        status: PRStatus = PRStatus.open,
+    ) -> Union[list["PullRequest"], Iterable["PullRequest"]]:
         """
         List of pull requests.
 
@@ -1765,7 +1774,7 @@ def get_pr_files_diff(
         """
         raise NotImplementedError()
 
-    def get_tags(self) -> list["GitTag"]:
+    def get_tags(self) -> Union[list["GitTag"], Iterable["GitTag"]]:
         """
         Returns:
             List of objects that represent tags.
@@ -1814,7 +1823,7 @@ def get_latest_release(self) -> Optional[Release]:
         """
         raise NotImplementedError()
 
-    def get_releases(self) -> list[Release]:
+    def get_releases(self) -> Union[list[Release], Iterable[Release]]:
         """
         Returns:
             List of the objects that represent releases.
@@ -1895,7 +1904,10 @@ def commit_comment(
         """
         raise NotImplementedError()
 
-    def get_commit_comments(self, commit: str) -> list[CommitComment]:
+    def get_commit_comments(
+        self,
+        commit: str,
+    ) -> Union[list[CommitComment], Iterable[CommitComment]]:
         """
         Get comments for a commit.
 
@@ -1947,7 +1959,10 @@ def set_commit_status(
         """
         raise NotImplementedError()
 
-    def get_commit_statuses(self, commit: str) -> list[CommitFlag]:
+    def get_commit_statuses(
+        self,
+        commit: str,
+    ) -> Union[list[CommitFlag], Iterable[CommitFlag]]:
         """
         Get statuses of the commit.
 
@@ -2018,7 +2033,7 @@ def get_files(
         ref: Optional[str] = None,
         filter_regex: Optional[str] = None,
         recursive: bool = False,
-    ) -> list[str]:
+    ) -> Union[list[str], Iterable[str]]:
         """
         Get a list of file paths of the repo.
 
@@ -2039,7 +2054,7 @@ def get_files(
         """
         raise NotImplementedError
 
-    def get_forks(self) -> Sequence["GitProject"]:
+    def get_forks(self) -> Union[Sequence["GitProject"], Iterable["GitProject"]]:
         """
         Returns:
             All forks of the project.
@@ -2106,14 +2121,14 @@ def get_email(self) -> str:
         """
         raise NotImplementedError()
 
-    def get_projects(self) -> Sequence["GitProject"]:
+    def get_projects(self) -> Union[Sequence["GitProject"], Iterable["GitProject"]]:
         """
         Returns:
             Sequence of projects in user's namespace.
         """
         raise NotImplementedError()
 
-    def get_forks(self) -> Sequence["GitProject"]:
+    def get_forks(self) -> Union[Sequence["GitProject"], Iterable["GitProject"]]:
         """
         Returns:
             Sequence of forks in user's namespace.

ogr/services/base.py

@@ -78,7 +78,7 @@ def search(
             filter_regex=filter_regex,
         )
 
-    def get_statuses(self) -> list[CommitFlag]:
+    def get_statuses(self) -> Union[list[CommitFlag], Iterable[CommitFlag]]:
         commit = self.get_all_commits()[-1]
         return self.target_project.get_commit_statuses(commit)
 

ogr/services/pagure/pull_request.py

@@ -345,7 +345,7 @@ def merge(self) -> "PullRequest":
         self.__dirty = True
         return self
 
-    def get_statuses(self) -> list[CommitFlag]:
+    def get_statuses(self) -> Union[list[CommitFlag], Iterable[CommitFlag]]:
         self.__update()
         return self.target_project.get_commit_statuses(self._raw_pr["commit_stop"])