HDXDSYS-2132 Create HDXState class in HDX Python API for pipelines with state in Jenkins

requirements.txt

@@ -32,7 +32,7 @@ click==8.1.8
     #   typer
 colorama==0.4.6
     # via mkdocs-material
-coverage==7.8.0
+coverage==7.8.1
     # via pytest-cov
 defopt==6.4.0
     # via hdx-python-api (pyproject.toml)
@@ -56,7 +56,7 @@ frictionless==5.18.1
     # via hdx-python-utilities
 ghp-import==2.1.0
     # via mkdocs
-google-auth==2.40.1
+google-auth==2.40.2
     # via
     #   google-auth-oauthlib
     #   gspread
@@ -181,7 +181,7 @@ pyasn1==0.6.1
     #   rsa
 pyasn1-modules==0.4.2
     # via google-auth
-pydantic==2.11.4
+pydantic==2.11.5
     # via frictionless
 pydantic-core==2.33.2
     # via pydantic
@@ -250,7 +250,7 @@ rfc3986==2.0.0
     # via frictionless
 rich==14.0.0
     # via typer
-rpds-py==0.25.0
+rpds-py==0.25.1
     # via
     #   jsonschema
     #   referencing
@@ -296,7 +296,7 @@ typing-extensions==4.13.2
     #   typeguard
     #   typer
     #   typing-inspection
-typing-inspection==0.4.0
+typing-inspection==0.4.1
     # via pydantic
 unidecode==1.4.0
     # via

src/hdx/api/configuration.py

@@ -10,7 +10,7 @@
 import ckanapi
 import requests
 
-from . import __version__
+from hdx.api import __version__
 from hdx.utilities.dictandlist import merge_two_dictionaries
 from hdx.utilities.email import Email
 from hdx.utilities.loader import load_json, load_yaml

src/hdx/api/utilities/hdx_state.py

@@ -0,0 +1,69 @@
+"""Utility to save state to a dataset and read it back."""
+
+import logging
+from os.path import join
+from typing import Any, Callable, Optional
+
+from hdx.api.configuration import Configuration
+from hdx.data.dataset import Dataset
+from hdx.utilities.loader import load_text
+from hdx.utilities.saver import save_text
+from hdx.utilities.state import State
+
+logger = logging.getLogger(__name__)
+
+
+class HDXState(State):
+    """State class that allows the reading and writing of state to a given HDX
+    dataset. Input and output state transformations can be supplied in read_fn and
+    write_fn respectively. The input state transformation takes in a string
+    while the output transformation outputs a string.
+
+    Args:
+        dataset_name_or_id (str): Dataset name or ID
+        path (str): Path to temporary folder for state
+        read_fn (Callable[[str], Any]): Input state transformation. Defaults to lambda x: x.
+        write_fn: Callable[[Any], str]: Output state transformation. Defaults to lambda x: x.
+        configuration (Optional[Configuration]): HDX configuration. Defaults to global configuration.
+    """
+
+    def __init__(
+        self,
+        dataset_name_or_id: str,
+        path: str,
+        read_fn: Callable[[str], Any] = lambda x: x,
+        write_fn: Callable[[Any], str] = lambda x: x,
+        configuration: Optional[Configuration] = None,
+    ) -> None:
+        self._dataset_name_or_id = dataset_name_or_id
+        self._resource = None
+        self._configuration = configuration
+        super().__init__(path, read_fn, write_fn)
+
+    def read(self) -> Any:
+        """Read state from HDX dataset
+
+        Returns:
+            Any: State
+        """
+        dataset = Dataset.read_from_hdx(
+            self._dataset_name_or_id, configuration=self._configuration
+        )
+        self._resource = dataset.get_resource()
+        _, path = self._resource.download()
+        value = self.read_fn(load_text(path))
+        logger.info(f"State read from {self._dataset_name_or_id} = {value}")
+        return value
+
+    def write(self) -> None:
+        """Write state to HDX dataset
+
+        Returns:
+            None
+        """
+        logger.info(f"State written to {self._dataset_name_or_id} = {self.state}")
+        filename = self._resource["name"]
+        file_to_upload = join(self.path, filename)
+        save_text(self.write_fn(self.state), file_to_upload)
+        self._resource.set_file_to_upload(file_to_upload)
+        self._resource.update_in_hdx()

tests/fixtures/state/analysis_dates.txt

@@ -0,0 +1 @@
+DEFAULT=2020-09-23

tests/fixtures/state/last_build_date.txt

@@ -0,0 +1 @@
+2020-09-23