From 7925a791bb76b87b93dd54776c7fb04dae9cf19e Mon Sep 17 00:00:00 2001
From: Mads Bisgaard <bisgaard@itis.swiss>
Date: Mon, 18 Nov 2024 11:46:20 +0100
Subject: [PATCH] improve docs for pagination iterable and make sure it
 inherrits from iterable

---
 clients/python/src/osparc/_api_files_api.py   | 6 +++---
 clients/python/src/osparc/_api_solvers_api.py | 8 ++++----
 clients/python/src/osparc/_api_studies_api.py | 8 ++++----
 clients/python/src/osparc/_utils.py           | 8 +++++---
 4 files changed, 16 insertions(+), 14 deletions(-)

diff --git a/clients/python/src/osparc/_api_files_api.py b/clients/python/src/osparc/_api_files_api.py
index dd668889..a1bc0ba4 100644
--- a/clients/python/src/osparc/_api_files_api.py
+++ b/clients/python/src/osparc/_api_files_api.py
@@ -31,7 +31,7 @@
 import shutil
 from ._utils import (
     DEFAULT_TIMEOUT_SECONDS,
-    PaginationGenerator,
+    PaginationIterable,
     compute_sha256,
     file_chunk_generator,
 )
@@ -271,7 +271,7 @@ def _search_files(
         file_id: Optional[str] = None,
         sha256_checksum: Optional[str] = None,
         timeout_seconds: int = DEFAULT_TIMEOUT_SECONDS,
-    ) -> PaginationGenerator:
+    ) -> PaginationIterable:
         def _pagination_method():
             return super(FilesApi, self).search_files_page(
                 file_id=file_id,
@@ -279,7 +279,7 @@ def _pagination_method():
                 _request_timeout=timeout_seconds,
             )
 
-        return PaginationGenerator(
+        return PaginationIterable(
             first_page_callback=_pagination_method,
             api_client=self.api_client,
             base_url=self.api_client.configuration.host,
diff --git a/clients/python/src/osparc/_api_solvers_api.py b/clients/python/src/osparc/_api_solvers_api.py
index cce71295..71c64f1d 100644
--- a/clients/python/src/osparc/_api_solvers_api.py
+++ b/clients/python/src/osparc/_api_solvers_api.py
@@ -11,7 +11,7 @@
 from ._utils import (
     _DEFAULT_PAGINATION_LIMIT,
     _DEFAULT_PAGINATION_OFFSET,
-    PaginationGenerator,
+    PaginationIterable,
 )
 
 import warnings
@@ -47,7 +47,7 @@ def list_solver_ports(
         )
         return page.items if page.items else []
 
-    def iter_jobs(self, solver_key: str, version: str, **kwargs) -> PaginationGenerator:
+    def iter_jobs(self, solver_key: str, version: str, **kwargs) -> PaginationIterable:
         """Returns an iterator through which one can iterate over
         all Jobs submitted to the solver
 
@@ -72,14 +72,14 @@ def _pagination_method():
                 **kwargs,
             )
 
-        return PaginationGenerator(
+        return PaginationIterable(
             first_page_callback=_pagination_method,
             api_client=self.api_client,
             base_url=self.api_client.configuration.host,
             auth=self._auth,
         )
 
-    def jobs(self, solver_key: str, version: str, **kwargs) -> PaginationGenerator:
+    def jobs(self, solver_key: str, version: str, **kwargs) -> PaginationIterable:
         warnings.warn(
             "The 'jobs' method is deprecated and will be removed in a future version. "
             "Please use 'iter_jobs' instead.",
diff --git a/clients/python/src/osparc/_api_studies_api.py b/clients/python/src/osparc/_api_studies_api.py
index cfb88e85..1d14a11a 100644
--- a/clients/python/src/osparc/_api_studies_api.py
+++ b/clients/python/src/osparc/_api_studies_api.py
@@ -17,7 +17,7 @@
 from ._utils import (
     _DEFAULT_PAGINATION_LIMIT,
     _DEFAULT_PAGINATION_OFFSET,
-    PaginationGenerator,
+    PaginationIterable,
 )
 import warnings
 
@@ -65,7 +65,7 @@ def clone_study(self, study_id: str, **kwargs):
         kwargs = {**kwargs, **ParentProjectInfo().model_dump(exclude_none=True)}
         return super().clone_study(study_id, **kwargs)
 
-    def iter_studies(self, **kwargs) -> PaginationGenerator:
+    def iter_studies(self, **kwargs) -> PaginationIterable:
         def _pagination_method():
             page_study = self.list_studies(
                 limit=_DEFAULT_PAGINATION_LIMIT,
@@ -75,14 +75,14 @@ def _pagination_method():
             assert isinstance(page_study, PageStudy)  # nosec
             return page_study
 
-        return PaginationGenerator(
+        return PaginationIterable(
             first_page_callback=_pagination_method,
             api_client=self.api_client,
             base_url=self.api_client.configuration.host,
             auth=self._auth,
         )
 
-    def studies(self, **kwargs) -> PaginationGenerator:
+    def studies(self, **kwargs) -> PaginationIterable:
         warnings.warn(
             "The 'studies' method is deprecated and will be removed in a future version. "
             "Please use 'iter_studies' instead.",
diff --git a/clients/python/src/osparc/_utils.py b/clients/python/src/osparc/_utils.py
index ea797aa1..3b6846c2 100644
--- a/clients/python/src/osparc/_utils.py
+++ b/clients/python/src/osparc/_utils.py
@@ -2,7 +2,7 @@
 import hashlib
 from pathlib import Path
 from typing import AsyncGenerator, Callable, Generator, Optional, Tuple, TypeVar, Union
-
+from collections.abc import Iterable
 import httpx
 from osparc_client import (
     ApiClient,
@@ -30,8 +30,10 @@
 T = TypeVar("T", Job, File, Solver, Study)
 
 
-class PaginationGenerator:
-    """Class for wrapping paginated http methods as generators"""
+class PaginationIterable(Iterable):
+    """Class for wrapping paginated http methods as iterables. It supports two simple operations:
+    - for elm in pagination_iterable:
+    - len(pagination_iterable)"""
 
     def __init__(
         self,