Merge pull request #21 from LinkedEarth/add-skip-param

Adding `skip` param for pagination support. Fixes #18

Author: khider

examples/Usage_NOAAStudyWrapper.ipynb

@@ -250,7 +250,15 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "dataset.search_studies(min_lat=68, max_lat=69, limit=1000)"
+    "from pyleotups import Dataset\n",
+    "\n",
+    "dataset = Dataset()\n",
+    "ds1 = dataset.search_studies(min_lat=68, max_lat=69, limit=10)\n",
+    "print(dataset.studies)\n",
+    "ds2 = dataset.search_studies(min_lat=68, max_lat=69, limit=10, skip=10)\n",
+    "print(dataset.studies)\n",
+    "ds3 = dataset.search_studies(min_lat=68, max_lat=69, limit=20)\n",
+    "print(dataset.studies)\n"
    ]
   },
   {

pyleotups/core/Dataset.py

@@ -230,6 +230,11 @@ def search_studies(self, **kwargs):
         display : bool, default False
             If True, render a small preview after parsing. 
 
+         
+        skip : int, optional
+            Number of studies to skip (for pagination). Use with ``limit`` to page through results.
+            Example: ``limit=10, skip=10`` returns items 11–20.
+
         Returns
         -------
         pandas.DataFrame
@@ -383,12 +388,23 @@ def search_studies(self, **kwargs):
 
             df_recent = ds.search_studies(recent=True, limit=25)
             df_recent.head()
+
+        Limit and Skipping (for pagination)
+        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+        .. jupyter-execute::
+
+            # Limit up to first 10 results 
+            df_limit = ds.search_studies(earliest_year=12000, time_format="BP", time_method="overAny", limit=10)
+            df_limit.head()
+
+            # Skip the first 10 results (i.e., get results 11-20)
+            df_skip = ds.search_studies(earliest_year=12000, time_format="BP", time_method="overAny", limit=10, skip=10)
+            df_skip.head()
         """
 
-        for param in ("headerheaders_only", "skip"):
-            if param in kwargs:
-                log.warning("%s is not supported and will be ignored.", param)
-                kwargs.pop(param, None)
+        if "headers_only" in kwargs:
+            log.warning("%s is not supported and will be ignored.", param)
+            kwargs.pop("headers_only", None)
 
         if not any([
         kwargs.get("xml_id"), kwargs.get("noaa_id"),
@@ -402,7 +418,7 @@ def search_studies(self, **kwargs):
         kwargs.get("cv_whats"), kwargs.get("min_elevation"),
         kwargs.get("max_elevation"), kwargs.get("time_format"),
         kwargs.get("time_method"), kwargs.get("reconstruction"),
-        kwargs.get("species"), kwargs.get("recent"),
+        kwargs.get("species"), kwargs.get("recent"), kwargs.get("skip")
         ]):
             raise ValueError(
                 "At least one search parameter must be specified to initiate a query. "

pyleotups/utils/api/query_builder.py

@@ -51,6 +51,8 @@ def build_payload(**kwargs) -> Tuple[dict, List[str]]:
         notes.append(f"Limit set to {payload['limit']}.")
     else:
         notes.append(f"Limit defaulted to {DEFAULT_LIMIT} (PyleoTUPS).")
+    if (v := kwargs.get("skip")) is not None:
+        payload["skip"] = validate_int("skip", v)
 
     # search_text
     st = kwargs.get("search_text")