Add tests for time conversions in tools package

docs/sphinx/source/whatsnew/v0.11.3.rst

@@ -18,6 +18,7 @@ Documentation
 
 Testing
 ~~~~~~~
+* Add tests for time conversions in tools package. (:issue:`2340`, :pull:`2341`)
 
 
 Requirements
@@ -26,5 +27,4 @@ Requirements
 
 Contributors
 ~~~~~~~~~~~~
-
-
+* Mark Campanellli (:ghuser:`markcampanelli`)

pvlib/tests/test_tools.py

@@ -1,9 +1,12 @@
-import pytest
+from datetime import datetime
+from zoneinfo import ZoneInfo
 
-from pvlib import tools
 import numpy as np
-import pandas as pd
 from numpy.testing import assert_allclose
+import pandas as pd
+import pytest
+
+from pvlib import location, tools
 
 
 @pytest.mark.parametrize('keys, input_dict, expected', [
@@ -144,3 +147,192 @@ def test_get_pandas_index(args, args_idx):
 def test_normalize_max2one(data_in, expected):
     result = tools.normalize_max2one(data_in)
     assert_allclose(result, expected)
+
+
+@pytest.mark.parametrize(
+    'input,expected',
+    [
+        (
+            {
+                "time": datetime(
+                    1974, 6, 22, 18, 30, 15, tzinfo=ZoneInfo("Etc/GMT+5"),
+                ),
+                "location": location.Location(
+                    43.19262774396091, -77.58782907414867, tz="Etc/GMT+5"
+                )
+            },
+            datetime(1974, 6, 22, 23, 30, 15, tzinfo=ZoneInfo("UTC")),
+        ),
+        (
+            {
+                "time": datetime(1974, 6, 22, 18, 30, 15),
+                "location": location.Location(
+                    43.19262774396091, -77.58782907414867, tz="Etc/GMT+5"
+                )
+            },
+            datetime(1974, 6, 22, 23, 30, 15, tzinfo=ZoneInfo("UTC")),
+        ),
+        (
+            {
+                "time": pd.DatetimeIndex(
+                    ["1974-06-22T18:30:15"],
+                    tz=ZoneInfo("Etc/GMT+5"),
+                ),
+                "location": location.Location(
+                    43.19262774396091, -77.58782907414867, tz="Etc/GMT+5"
+                )
+            },
+            pd.DatetimeIndex(["1974-06-22T23:30:15"], tz=ZoneInfo("UTC")),
+        ),
+        (
+            {
+                "time": pd.DatetimeIndex(["1974-06-22T18:30:15"]),
+                "location": location.Location(
+                    43.19262774396091, -77.58782907414867, tz="Etc/GMT+5"
+                )
+            },
+            pd.DatetimeIndex(["1974-06-22T23:30:15"], tz=ZoneInfo("UTC")),
+        ),
+        (
+            {
+                "time": pd.Series(
+                    [24.42],
+                    index=pd.DatetimeIndex(
+                        ["1974-06-22T18:30:15"],
+                        tz=ZoneInfo("Etc/GMT+5"),
+                    ),
+                ),
+                "location": location.Location(
+                    43.19262774396091, -77.58782907414867, tz="Etc/GMT+5"
+                )
+            },
+            pd.Series(
+                [24.42],
+                pd.DatetimeIndex(["1974-06-22T23:30:15"], tz=ZoneInfo("UTC")),
+            ),
+        ),
+        (
+            {
+                "time": pd.Series(
+                    [24.42],
+                    index=pd.DatetimeIndex(["1974-06-22T18:30:15"]),
+                ),
+                "location": location.Location(
+                    43.19262774396091, -77.58782907414867, tz="Etc/GMT+5"
+                )
+            },
+            pd.Series(
+                [24.42],
+                pd.DatetimeIndex(["1974-06-22T23:30:15"], tz=ZoneInfo("UTC")),
+            ),
+        ),
+        (
+            {
+                "time": pd.DataFrame(
+                    [[24.42]],
+                    index=pd.DatetimeIndex(
+                        ["1974-06-22T18:30:15"],
+                        tz=ZoneInfo("Etc/GMT+5"),
+                    ),
+                ),
+                "location": location.Location(
+                    43.19262774396091, -77.58782907414867, tz="Etc/GMT+5"
+                )
+            },
+            pd.DataFrame(
+                [[24.42]],
+                pd.DatetimeIndex(["1974-06-22T23:30:15"], tz=ZoneInfo("UTC")),
+            ),
+        ),
+        (
+            {
+                "time": pd.DataFrame(
+                    [[24.42]],
+                    index=pd.DatetimeIndex(["1974-06-22T18:30:15"]),
+                ),
+                "location": location.Location(
+                    43.19262774396091, -77.58782907414867, tz="Etc/GMT+5"
+                )
+            },
+            pd.DataFrame(
+                [[24.42]],
+                pd.DatetimeIndex(["1974-06-22T23:30:15"], tz=ZoneInfo("UTC")),
+            ),
+        ),
+    ],
+    ids=[
+        "datetime.datetime with tzinfo",
+        "datetime.datetime",
+        "pandas.DatetimeIndex with tzinfo",
+        "pandas.DatetimeIndex",
+        "pandas.Series with tzinfo",
+        "pandas.Series",
+        "pandas.DataFrame with tzinfo",
+        "pandas.DataFrame",
+    ],
+)
+def test_localize_to_utc(input, expected):
+    got = tools.localize_to_utc(**input)
+
+    if isinstance(got, (pd.Series, pd.DataFrame)):
+        # Older pandas versions have wonky dtype equality check on timestamp
+        # index, so check the values as numpy.ndarray and indices one by one.
+        np.testing.assert_array_equal(got.to_numpy(), expected.to_numpy())
+
+        for index_got, index_expected in zip(got.index, expected.index):
+            assert index_got == index_expected
+    else:
+        assert got == expected
+
+
+@pytest.mark.parametrize(
+    'input,expected',
+    [
+        (
+            {
+                "time": datetime(
+                    1974, 6, 22, 18, 30, 15, tzinfo=ZoneInfo("Etc/GMT+5")
+                )
+            },
+            27201.47934027778,
+        ),
+        (
+            {
+                "time": datetime(1974, 6, 22, 23, 30, 15)
+            },
+            27201.47934027778,
+        ),
+    ],
+    ids=["datetime.datetime with tzinfo", "datetime.datetime"],
+)
+def test_datetime_to_djd(input, expected):
+    assert tools.datetime_to_djd(input["time"]) == expected
+
+
+@pytest.mark.parametrize(
+    'input,expected',
+    [
+        (
+            {
+                "djd": 27201.47934027778,
+                "tz": "Etc/GMT+5",
+            },
+            datetime(1974, 6, 22, 18, 30, 15, tzinfo=ZoneInfo("Etc/GMT+5")),
+        ),
+        (
+            {
+                "djd": 27201.47934027778,
+                "tz": None,
+            },
+            datetime(1974, 6, 22, 23, 30, 15, tzinfo=ZoneInfo("UTC")),
+        ),
+    ],
+    ids=["djd with tzinfo", "djd"],
+)
+def test_djd_to_datetime(input, expected):
+    if input["tz"] is not None:
+        got = tools.djd_to_datetime(input["djd"])
+    else:
+        got = tools.djd_to_datetime(input["djd"], tz="Etc/GMT+5")
+
+    assert got == expected

pvlib/tools.py

@@ -119,7 +119,7 @@ def atand(number):
 
 def localize_to_utc(time, location):
     """
-    Converts or localizes a time series to UTC.
+    Converts time to UTC, localizing if necessary using location.
 
     Parameters
     ----------
@@ -129,7 +129,7 @@ def localize_to_utc(time, location):
 
     Returns
     -------
-    pandas object localized to UTC.
+    datetime.datetime or pandas object localized to UTC.
     """
     if isinstance(time, dt.datetime):
         if time.tzinfo is None: