Introduce Rfc3339.now_utc() and deprecate utcnow usage #760

Author: soxofaan

CHANGELOG.md

@@ -11,6 +11,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
+- Eliminate deprecated `utcnow` usage patterns. Introduce `Rfc3339.now_utc()` method (as replacement for deprecated `utcnow()` method) to simplify finding deprecated `utcnow` usage in user code. ([#760](https://github.com/Open-EO/openeo-python-client/issues/760))
+
 ### Removed
 
 ### Fixed

docs/conf.py

@@ -58,7 +58,7 @@
 
 # General information about the project.
 project = 'openEO Python Client'
-copyright = '2017 - {d}, Jeroen Dries'.format(d=datetime.datetime.utcnow().strftime("%Y"))
+copyright = '2017 - {d}, Jeroen Dries'.format(d=datetime.date.today().strftime("%Y"))
 author = 'Jeroen Dries'
 
 # The version info for the project you're documenting, acts as replacement for

openeo/extra/job_management/__init__.py

@@ -595,7 +595,7 @@ def _launch_job(self, start_job, df, i, backend_name, stats: Optional[dict] = No
             df.loc[i, "status"] = "start_failed"
             stats["start_job error"] += 1
         else:
-            df.loc[i, "start_time"] = rfc3339.utcnow()
+            df.loc[i, "start_time"] = rfc3339.now_utc()
             if job:
                 df.loc[i, "id"] = job.job_id
                 with ignore_connection_errors(context="get status"):
@@ -675,7 +675,7 @@ def _cancel_prolonged_job(self, job: BatchJob, row):
             job_running_start_time = rfc3339.parse_datetime(row.get("running_start_time"), with_timezone=True)
 
             # Parse the current time into a datetime object with timezone info
-            current_time = rfc3339.parse_datetime(rfc3339.utcnow(), with_timezone=True)
+            current_time = rfc3339.parse_datetime(rfc3339.now_utc(), with_timezone=True)
 
             # Calculate the elapsed time between job start and now
             elapsed = current_time - job_running_start_time
@@ -751,15 +751,15 @@ def _track_statuses(self, job_db: JobDatabaseInterface, stats: Optional[dict] =
 
                 if previous_status in {"created", "queued"} and new_status == "running":
                     stats["job started running"] += 1
-                    active.loc[i, "running_start_time"] = rfc3339.utcnow()
+                    active.loc[i, "running_start_time"] = rfc3339.now_utc()
 
                 if self._cancel_running_job_after and new_status == "running":
                     if  (not active.loc[i, "running_start_time"] or pd.isna(active.loc[i, "running_start_time"])):
                         _log.warning(
                             f"Unknown 'running_start_time' for running job {job_id}. Using current time as an approximation."
                             )
                         stats["job started running"] += 1
-                        active.loc[i, "running_start_time"] = rfc3339.utcnow()
+                        active.loc[i, "running_start_time"] = rfc3339.now_utc()
 
                     self._cancel_prolonged_job(the_job, active.loc[i])
 

openeo/rest/auth/config.py

@@ -59,11 +59,6 @@ def assert_private_file(path: Path):
             raise PermissionError(message)
 
 
-def utcnow_rfc3339() -> str:
-    """Current datetime formatted as RFC-3339 string."""
-    return rfc3339.datetime(datetime.utcnow())
-
-
 def _normalize_url(url: str) -> str:
     """Normalize a url (trim trailing slash), to simplify equality checking."""
     return url.rstrip("/") or "/"
@@ -146,7 +141,7 @@ def _write(self, data: dict):
         if "metadata" not in data:
             data["metadata"] = {
                 "type": "AuthConfig",
-                "created": utcnow_rfc3339(),
+                "created": rfc3339.now_utc(),
                 "created_by": "openeo-python-client {v}".format(v=__version__),
                 "version": 1,
             }
@@ -169,7 +164,7 @@ def set_basic_auth(self, backend: str, username: str, password: Union[str, None]
             "basic",
         )
         # TODO: support multiple basic auth credentials? (pick latest by default for example)
-        deep_set(data, *keys, "date", value=utcnow_rfc3339())
+        deep_set(data, *keys, "date", value=rfc3339.now_utc())
         deep_set(data, *keys, "username", value=username)
         if password:
             deep_set(data, *keys, "password", value=password)
@@ -203,7 +198,7 @@ def set_oidc_client_config(
         data = self.load()
         keys = ("backends", _normalize_url(backend), "oidc", "providers", provider_id)
         # TODO: support multiple clients? (pick latest by default for example)
-        deep_set(data, *keys, "date", value=utcnow_rfc3339())
+        deep_set(data, *keys, "date", value=rfc3339.now_utc())
         deep_set(data, *keys, "client_id", value=client_id)
         deep_set(data, *keys, "client_secret", value=client_secret)
         if issuer:
@@ -233,7 +228,7 @@ def set_refresh_token(self, issuer: str, client_id: str, refresh_token: str):
             _normalize_url(issuer),
             client_id,
             value={
-                "date": utcnow_rfc3339(),
+                "date": rfc3339.now_utc(),
                 "refresh_token": refresh_token,
             },
         )

openeo/util.py

@@ -23,6 +23,8 @@
 import shapely.geometry.base
 from deprecated import deprecated
 
+from openeo.internal.warnings import legacy_alias
+
 try:
     # pyproj is an optional dependency
     import pyproj
@@ -194,12 +196,15 @@ def today(self) -> str:
         """Today (date) in RFC3339 format"""
         return self.date(dt.date.today())
 
-    def utcnow(self) -> str:
-        """Current UTC datetime in RFC3339 format."""
+    def now_utc(self) -> str:
+        """Current datetime (in UTC timezone) in RFC3339 format."""
         # Current time in UTC timezone (instead of naive `datetime.datetime.utcnow()`, per `datetime` documentation)
         now = dt.datetime.now(tz=dt.timezone.utc)
         return self.datetime(now)
 
+    # Legacy alias
+    utcnow = legacy_alias(now_utc, name="utcnow", since="0.41.0")
+
 
 # Default RFC3339 date-time formatter
 rfc3339 = Rfc3339()

tests/extra/job_management/test_job_management.py

@@ -573,9 +573,9 @@ def test_automatic_cancel_of_too_long_running_jobs(
         job_manager_root_dir,
     ):
         def get_status(job_id, current_status):
-            if rfc3339.utcnow() < start_time:
+            if rfc3339.now_utc() < start_time:
                 return "queued"
-            elif rfc3339.utcnow() < end_time:
+            elif rfc3339.now_utc() < end_time:
                 return "running"
             return end_status
 
@@ -685,9 +685,9 @@ def test_ensure_running_start_time_is_datetime(
         job_manager_root_dir,
     ):
         def get_status(job_id, current_status):
-            if rfc3339.utcnow() < start_time:
+            if rfc3339.now_utc() < start_time:
                 return "queued"
-            elif rfc3339.utcnow() < end_time:
+            elif rfc3339.now_utc() < end_time:
                 return "running"
             return end_status
 

tests/rest/auth/test_config.py

@@ -113,10 +113,10 @@ def test_start_empty(self, tmp_path):
         assert config.get_basic_auth("foo") == (None, None)
         assert config.get_oidc_client_configs("oeo.test", "default") == (None, None)
 
-    def test_basic_auth(self, tmp_path):
+    def test_basic_auth(self, tmp_path, time_machine):
+        time_machine.move_to("2020-06-08T11:18:27Z")
         config = AuthConfig(path=tmp_path)
-        with mock.patch.object(openeo.rest.auth.config, "utcnow_rfc3339", return_value="2020-06-08T11:18:27Z"):
-            config.set_basic_auth("oeo.test", "John", "j0hn123")
+        config.set_basic_auth("oeo.test", "John", "j0hn123")
         assert config.path.exists()
         assert [p.name for p in tmp_path.iterdir()] == [AuthConfig.DEFAULT_FILENAME]
         with config.path.open("r") as f:
@@ -137,10 +137,10 @@ def test_basic_auth_url_normalization(self, tmp_path, to_set, to_get):
         assert config.get_basic_auth(to_set) == ("John", "j0hn123")
         assert config.get_basic_auth(to_get) == ("John", "j0hn123")
 
-    def test_oidc(self, tmp_path):
+    def test_oidc(self, tmp_path, time_machine):
+        time_machine.move_to("2020-06-08T11:18:27Z")
         config = AuthConfig(path=tmp_path)
-        with mock.patch.object(openeo.rest.auth.config, "utcnow_rfc3339", return_value="2020-06-08T11:18:27Z"):
-            config.set_oidc_client_config("oeo.test", "default", client_id="client123", client_secret="$6cr67")
+        config.set_oidc_client_config("oeo.test", "default", client_id="client123", client_secret="$6cr67")
         assert config.path.exists()
         assert [p.name for p in tmp_path.iterdir()] == [AuthConfig.DEFAULT_FILENAME]
         with config.path.open("r") as f:
@@ -157,10 +157,10 @@ def test_oidc(self, tmp_path):
         ("https://oeo.test", "https://oeo.test/"),
         ("https://oeo.test/", "https://oeo.test"),
     ])
-    def test_oidc_backend_normalization(self, tmp_path, to_set, to_get):
+    def test_oidc_backend_normalization(self, tmp_path, to_set, to_get, time_machine):
+        time_machine.move_to("2020-06-08T11:18:27Z")
         config = AuthConfig(path=tmp_path)
-        with mock.patch.object(openeo.rest.auth.config, "utcnow_rfc3339", return_value="2020-06-08T11:18:27Z"):
-            config.set_oidc_client_config(to_set, "default", client_id="client123", client_secret="$6cr67")
+        config.set_oidc_client_config(to_set, "default", client_id="client123", client_secret="$6cr67")
         for backend in [to_set, to_get]:
             assert config.get_oidc_client_configs(backend, "default") == ("client123", "$6cr67")
             assert config.get_oidc_provider_configs(backend) == {

tests/test_util.py

@@ -12,6 +12,7 @@
 import pytest
 import shapely.geometry
 
+from openeo.internal.warnings import UserDeprecationWarning
 from openeo.util import (
     BBoxDict,
     ContextTimer,
@@ -284,11 +285,16 @@ def test_today(self, time_machine):
         time_machine.move_to("2023-02-10T12:34:56Z")
         assert rfc3339.today() == "2023-02-10"
 
-    def test_utcnow(self, time_machine):
+    def test_now_utc(self, time_machine):
         time_machine.move_to("2023-02-10T12:34:56Z")
-        assert rfc3339.utcnow() == "2023-02-10T12:34:56Z"
+        assert rfc3339.now_utc() == "2023-02-10T12:34:56Z"
         time_machine.move_to("2023-02-10T12:34:56+03")
-        assert rfc3339.utcnow() == "2023-02-10T09:34:56Z"
+        assert rfc3339.now_utc() == "2023-02-10T09:34:56Z"
+
+    def test_legacy_utcnow(self, time_machine):
+        time_machine.move_to("2023-02-10T12:34:56Z")
+        with pytest.warns(UserDeprecationWarning, match=r"Call to deprecated method utcnow.*Use `\.now_utc` instead"):
+            assert rfc3339.utcnow() == "2023-02-10T12:34:56Z"
 
 
 def test_dict_no_none_kwargs():