Rename get_seasonality to get_seasonality_for_frequency

src/gluonts/time_feature/__init__.py

@@ -35,7 +35,7 @@
 )
 from .holiday import SPECIAL_DATE_FEATURES, SpecialDateFeatureSet
 from .lag import get_lags_for_frequency
-from .seasonality import get_seasonality
+from .seasonality import get_seasonality, get_seasonality_for_frequency
 
 __all__ = [
     "Constant",
@@ -47,6 +47,7 @@
     "day_of_year_index",
     "get_lags_for_frequency",
     "get_seasonality",
+    "get_seasonality_for_frequency",
     "hour_of_day",
     "hour_of_day_index",
     "minute_of_hour",

src/gluonts/time_feature/seasonality.py

@@ -12,6 +12,7 @@
 # permissions and limitations under the License.
 
 import logging
+import warnings
 
 import pandas as pd
 
@@ -37,12 +38,34 @@
 }
 
 
-def get_seasonality(freq: str, seasonalities=DEFAULT_SEASONALITIES) -> int:
+def get_seasonality_for_frequency(
+    freq: str, seasonalities=DEFAULT_SEASONALITIES
+) -> int:
     """
-    Return the seasonality of a given frequency:
+    Return a calendar-based default seasonality for the given frequency.
+
+    This function does **not** inspect or analyse any time-series data.
+    It maps a pandas frequency alias (e.g. ``"H"``, ``"D"``, ``"M"``) to a
+    hard-coded calendar convention and divides by the interval multiplier.
 
-    >>> get_seasonality("2h")
+    Examples
+    --------
+    >>> get_seasonality_for_frequency("2h")
     12
+
+    Parameters
+    ----------
+    freq
+        A pandas-compatible frequency string (e.g. ``"H"``, ``"30min"``,
+        ``"D"``, ``"W"``, ``"M"``).
+    seasonalities
+        Optional override of the default seasonality mapping.
+
+    Returns
+    -------
+    int
+        The default seasonal period for the given frequency.  Falls back to
+        ``1`` when the multiplier does not evenly divide the base seasonality.
     """
     offset = pd.tseries.frequencies.to_offset(freq)
 
@@ -57,3 +80,20 @@ def get_seasonality(freq: str, seasonalities=DEFAULT_SEASONALITIES) -> int:
         f"{base_seasonality}. Falling back to seasonality 1."
     )
     return 1
+
+
+def get_seasonality(freq: str, seasonalities=DEFAULT_SEASONALITIES) -> int:
+    """
+    Deprecated alias for :func:`get_seasonality_for_frequency`.
+
+    .. deprecated::
+        Use :func:`get_seasonality_for_frequency` instead.  This function
+        will be removed in a future release.
+    """
+    warnings.warn(
+        "get_seasonality is deprecated; use "
+        "get_seasonality_for_frequency instead.",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+    return get_seasonality_for_frequency(freq, seasonalities)

test/time_feature/test_seasonality.py

@@ -11,9 +11,12 @@
 # express or implied. See the License for the specific language governing
 # permissions and limitations under the License.
 
+import warnings
+
 import pytest
 
 from gluonts.time_feature import get_seasonality
+from gluonts.time_feature.seasonality import get_seasonality_for_frequency
 
 from .common import H, M, Q, Y
 
@@ -54,3 +57,29 @@
 @pytest.mark.parametrize("freq, expected_seasonality", TEST_CASES)
 def test_get_seasonality(freq, expected_seasonality):
     assert get_seasonality(freq) == expected_seasonality
+
+
+def test_get_seasonality_for_frequency():
+    """The new canonical function should return the same values."""
+    assert get_seasonality_for_frequency("H") == 24
+    assert get_seasonality_for_frequency("2H") == 12
+    assert get_seasonality_for_frequency("30min") == 48
+    assert get_seasonality_for_frequency("D") == 1
+    assert get_seasonality_for_frequency("W") == 1
+    assert get_seasonality_for_frequency("M") == 12
+    assert get_seasonality_for_frequency("3M") == 4
+    assert get_seasonality_for_frequency("1B") == 5
+
+
+def test_get_seasonality_deprecation_warning():
+    """The old get_seasonality should emit a DeprecationWarning."""
+    with warnings.catch_warnings(record=True) as caught:
+        warnings.simplefilter("always")
+        get_seasonality("H")
+        deprecation_warnings = [
+            warning
+            for warning in caught
+            if issubclass(warning.category, DeprecationWarning)
+            and "get_seasonality_for_frequency" in str(warning.message)
+        ]
+        assert len(deprecation_warnings) == 1