Alias ``IsoRegistry.get_calendar_class()`` to ``get()``

The ``get_calendar_class`` method will be dropped in a further release. In the meantime, they'll be both equivalent.

refs #375, closes #418.

Changelog.md

@@ -2,7 +2,8 @@
 
 ## master (unreleased)
 
-* **BREAKING CHANGE**: the ``IsoRegistry.items()`` method has been removed from the API. You must use the ``get_calendars()`` to perform the same registry queries (#375, #491).
+- **BREAKING CHANGE**: the ``IsoRegistry.items()`` method has been removed from the API. You must use the ``get_calendars()`` to perform the same registry queries (#375, #491).
+- *Deprecation notice*: The usage of ``IsoRegistry.get_calendar_class()`` is strongly discouraged, in favor of ``get()``. The ``get_calendar_class`` method will be dropped in a further release. In the meantime, they'll be both equivalent (#375, #418).
 
 ## v8.4.0 (2020-04-17)
 

docs/iso-registry.md

@@ -88,8 +88,7 @@ You can also get the full dict of all calendars registered in the ISO Registry w
 Let's say that we only know the ISO code for Switzerland (`CH`). If we want to compute holidays for Switzerland in 2018, we can do as follows:
 
 ```python
->>> registry.get_calendar_class('CH')
->>> CalendarClass = registry.get_calendar_class('CH')
+>>> CalendarClass = registry.get('CH')
 >>> calendar = CalendarClass()
 >>> calendar.holidays(2018)
 [(datetime.date(2018, 1, 1), 'New year'),

workalendar/registry.py

@@ -1,4 +1,5 @@
 from importlib import import_module
+import warnings
 
 from .core import Calendar
 from .exceptions import ISORegistryError
@@ -59,6 +60,17 @@ class IsoRegistry:
                     self.register(iso_code, cls)
 
     def get_calendar_class(self, iso_code):
+        """
+        Alias for the ``get(iso_code)`` method.
+
+        This alias will be deprecated in a further release.
+        """
+        warnings.warn("The ``get_calendar_class(iso_code)`` method will soon"
+                      " be deprecated. Please use ``get(iso_code)`` instead.",
+                      DeprecationWarning)
+        return self.get(iso_code)
+
+    def get(self, iso_code):
         """
         Retrieve calendar class associated with given ``iso_code``.
 

workalendar/registry_tools.py

@@ -16,7 +16,7 @@ def iso_register(iso_code):
 
     Region calendar is then retrievable from registry:
 
-    >>> calendar = registry.get_calendar_class('MC-MR')
+    >>> calendar = registry.get('MC-MR')
     """
     def wrapper(cls):
         cls.__iso_code = (iso_code, cls.__name__)

workalendar/tests/test_registry.py

@@ -1,4 +1,5 @@
 from unittest import TestCase
+import warnings
 
 from ..core import Calendar
 from ..exceptions import ISORegistryError
@@ -35,17 +36,39 @@ class NonStandardRegistryTest(TestCase):
         with self.assertRaises(ISORegistryError):
             registry.register("NAC", NotACalendarClass)
 
-    def test_get_calendar_class(self):
+    def test_get(self):
+        # get() is the new name for `get_calendar_class()`
         registry = IsoRegistry(load_standard_modules=False)
         registry.register('RE', self.region)
         registry.register('RE-SR', self.subregion)
-        calendar_class = registry.get_calendar_class('RE')
+        calendar_class = registry.get('RE')
         self.assertEqual(calendar_class, RegionCalendar)
         # Subregion
-        calendar_class = registry.get_calendar_class('RE-SR')
+        calendar_class = registry.get('RE-SR')
         self.assertEqual(calendar_class, SubRegionCalendar)
         # Unknown code/region
-        self.assertIsNone(registry.get_calendar_class('XX'))
+        self.assertIsNone(registry.get('XX'))
+
+    def test_get_calendar_class_alias(self):
+        registry = IsoRegistry(load_standard_modules=False)
+        registry.register('RE', self.region)
+        self.assertEqual(
+            registry.get('RE'),
+            registry.get_calendar_class('RE')
+        )
+
+    def test_get_calendar_class_deprecation(self):
+        registry = IsoRegistry(load_standard_modules=False)
+        with warnings.catch_warnings(record=True) as w:
+            # Cause all warnings to always be triggered.
+            warnings.simplefilter("always")
+            # Trigger a warning.
+            registry.get_calendar_class("RE")
+            # Verify some things
+            self.assertEqual(len(w), 1)
+            warning = w[0]
+            self.assertTrue(issubclass(warning.category, DeprecationWarning))
+            self.assertIn("deprecated", str(warning.message))
 
     def test_get_subregions(self):
         registry = IsoRegistry(load_standard_modules=False)