frames and session iterators

README.md

@@ -15,6 +15,9 @@ GridMQTTClient - Client for GRID MQTT API. It useful for realtime connection (re
 # Examples how to use
 ## GridAuthClient
 ```
+from keycloak import KeycloakOpenID
+from gridgs.sdk.auth import Client as GridAuthClient
+
 keycloak_openid = KeycloakOpenID(server_url="https://login.gridgs.com", client_id="grid-api", realm_name="grid")
 grid_auth_client = GridAuthClient(open_id_client=keycloak_openid, username="user@gridgs.com", password="userpass", company_id=1, logger=logging.getLogger('grid_auth_client'))
 ```
@@ -29,18 +32,35 @@ grid_api_client = GridApiClient(base_url="https://api.gridgs.com" auth_client=gr
 
 ### Get sessions
 ```
-from gridgs.sdk.api import SortOrder, SessionQueryParams, SessionSortParam, SessionSortField
+from gridgs.sdk.api import SortOrder, SessionQueryParams, SessionSortField
 
 params = SessionQueryParams(
         satellite=1,
         ground_station=13,
         status=Session.STATUS_SUCCESS,
-        offset=0, limit=3, sort_by=SessionSortField.END_DATE, sort_order=SortOrder.ASC)
+        offset=0, limit=3, 
+        sort_by=SessionSortField.END_DATE, sort_order=SortOrder.ASC)
 sessions_result = grid_api_client.find_sessions(params)
 
 print(f'Total: {sessions_result.total}')
 ```
 
+### Get and Iterate ALL sessions
+it iterates using offset all sessions which can be found on api based on SessionQueryParams. Limit here is the size of the chunk.
+```
+from gridgs.sdk.api import SortOrder, SessionQueryParams, SessionSortField
+
+params = SessionQueryParams(
+        satellite=1,
+        ground_station=13,
+        status=Session.STATUS_SUCCESS,
+        offset=0, limit=10, 
+        sort_by=SessionSortField.END_DATE, sort_order=SortOrder.ASC)
+for session in grid_api_client.iterate_sessions(params):
+    print(session)
+```
+
+
 ### Get session by Id
 ```
 session = grid_api_client.find_session(session_uuid)
@@ -74,26 +94,46 @@ grid_api_client.delete_session(session_uuid)
 
 ### Get frames
 ```
-from gridgs.sdk.api import SortOrder, FrameSortField, FrameSortParam, FrameQueryParams
+from gridgs.sdk.api import SortOrder, FrameSortField, FrameQueryParams
 
 params = FrameQueryParams(
     satellite=2, 
     ground_station=13, 
     date_from=datetime.fromisoformat("2025-02-07 00:00:00"), 
     date_to=datetime.fromisoformat("2025-02-07 00:48:00"), 
-    offset=0, limit=5, sort_by=FrameSortField.TYPE, sort_order=SortOrder.ASC)
+    offset=0, limit=5, 
+    sort_by=FrameSortField.CREATED_AT, sort_order=SortOrder.ASC)
     )
 
 frames_result = grid_api_client.find_frames(params) 
 
 print(f'Total: {frames_result.total}')
 ```
 
+### Get and Iterate ALL frames
+it iterates using offset all frames which can be found on api based on FrameQueryParams. Limit here is the size of the chunk.
+```
+from gridgs.sdk.api import SortOrder, FrameSortField, FrameQueryParams
+
+params = FrameQueryParams(
+        satellite=1,
+        ground_station=13,
+        date_from=datetime.fromisoformat("2025-02-07 00:00:00"), 
+        date_to=datetime.fromisoformat("2025-02-07 00:48:00"), 
+        offset=0, limit=10, 
+        sort_by=FrameSortField.CREATED_AT, sort_order=SortOrder.ASC)
+for frame in grid_api_client.iterate_frames(params):
+    print(frame)
+```
+
 ## GridEventSubscriber
 
 Receive statuses of sessions
 
 ```
+from gridgs.sdk.entity import SessionEvent
+from gridgs.sdk.event import Subscriber as GridEventSubscriber
+
 grid_event_subscriber = GridEventSubscriber(host="api.gridgs.com", port=1883, auth_client=grid_auth_client, logger=logging.getLogger('grid_event_subscriber'))
 
 def on_event(event: SessionEvent):
@@ -108,6 +148,9 @@ grid_event_subscriber.run()
 ## GridMQTTClient
 
 ```
+from gridgs.sdk.entity import Frame
+from gridgs.sdk.mqtt import Client as GridMQTTClient
+
 grid_mqtt_client = GridMQTTClient(host="api.gridgs.com", port=1883, auth_client=grid_auth_client, logger=logging.getLogger('grid_event_subscriber'))
 
 def on_downlink_frame(frame: Frame):

src/gridgs/sdk/api/frame_client.py

@@ -1,8 +1,10 @@
-from dataclasses import dataclass
+from dataclasses import dataclass, replace
 from datetime import datetime
 from enum import Enum
 from http.client import HTTPException
-from typing import List
+from typing import List, Iterator
+
+import requests
 
 from gridgs.sdk.entity import frame_from_dict, Frame, FrameType
 from .base_client import BaseClient
@@ -51,14 +53,34 @@ class FramesResult:
 
 
 class FrameClient(BaseClient):
-    def find_frames(self, params: FrameQueryParams) -> FramesResult:
-        response = self.request('get', 'frames', params=params.to_dict())
+    __min_iterator_limit = 100
 
-        if response.status_code != 200:
-            raise HTTPException('Cannot get frames', response.reason, response.json())
+    def find_frames(self, params: FrameQueryParams) -> FramesResult:
+        response = self.__find_frames_request(params)
 
         frames = []
         for row in response.json():
             frames.append(frame_from_dict(row))
 
         return FramesResult(frames=frames, total=int(response.headers.get('Pagination-Count')))
+
+    def iterate_frames(self, params: FrameQueryParams) -> Iterator[Frame]:
+        total = params.offset + 1  # to run while loop it should be more than offset
+        params = replace(params, limit=max(params.limit, self.__min_iterator_limit))
+
+        while params.offset < total:
+            response = self.__find_frames_request(params)
+
+            for row in response.json():
+                yield frame_from_dict(row)
+
+            total = int(response.headers.get('Pagination-Count'))
+            params = replace(params, offset=params.offset + params.limit)
+
+    def __find_frames_request(self, params: FrameQueryParams) -> requests.Response:
+        response = self.request('get', 'frames', params=params.to_dict())
+
+        if response.status_code != 200:
+            raise HTTPException('Cannot get frames', response.reason, response.json())
+
+        return response

src/gridgs/sdk/api/params.py

@@ -4,8 +4,8 @@
 
 @dataclass(frozen=True)
 class PaginatedQueryParams:
-    limit: int | None = None
-    offset: int | None = None
+    limit: int = 100
+    offset: int  = 0
 
     def to_dict(self) -> dict:
         return {'offset': self.offset, 'limit': self.limit}

src/gridgs/sdk/api/session_client.py

@@ -1,9 +1,11 @@
 import uuid
-from dataclasses import dataclass
+from dataclasses import dataclass, replace
 from datetime import datetime
 from enum import Enum
 from http.client import HTTPException
-from typing import List
+from typing import List, Iterator
+
+import requests
 
 from gridgs.sdk.entity import Session, session_from_dict
 from .base_client import BaseClient
@@ -60,11 +62,10 @@ class SessionsResult:
 
 
 class SessionClient(BaseClient):
-    def find_sessions(self, params: SessionQueryParams) -> SessionsResult:
-        response = self.request('get', 'sessions', params=params.to_dict())
+    __min_iterator_limit = 100
 
-        if response.status_code != 200:
-            raise HTTPException('Cannot find sessions', response.reason, response.json())
+    def find_sessions(self, params: SessionQueryParams) -> SessionsResult:
+        response = self.__find_sessions_request(params)
 
         sessions = []
         for row in response.json():
@@ -75,6 +76,27 @@ def find_sessions(self, params: SessionQueryParams) -> SessionsResult:
             total=int(response.headers.get('Pagination-Count'))
         )
 
+    def iterate_sessions(self, params: SessionQueryParams) -> Iterator[Session]:
+        total = params.offset + 1  # to run while loop should be more than offset
+        params = replace(params, limit=max(params.limit, self.__min_iterator_limit))
+
+        while params.offset < total:
+            response = self.__find_sessions_request(params)
+
+            for row in response.json():
+                yield session_from_dict(row)
+
+            total = int(response.headers.get('Pagination-Count'))
+            params = replace(params, offset=params.offset + params.limit)
+
+    def __find_sessions_request(self, params: SessionQueryParams) -> requests.Response:
+        response = self.request('get', 'sessions', params=params.to_dict())
+
+        if response.status_code != 200:
+            raise HTTPException('Cannot find sessions', response.reason, response.json())
+
+        return response
+
     def find_session(self, id: uuid.UUID) -> Session | None:
         response = self.request('get', f'sessions/{str(id)}')