feat: add caching for timezone offsets, significantly speeds up import

this is different from pr #1181. that pr only makes import faster but
still incurs cost on the first usage. this one leverages an optional
cache.

closes #533

Author: tobymao

.gitignore

@@ -52,3 +52,4 @@ docs/_build
 
 # Other
 raw_data
+*.pkl

dateparser/timezone_parser.py

@@ -1,4 +1,7 @@
+import os
+import pickle
 from datetime import datetime, timedelta, timezone, tzinfo
+from pathlib import Path
 
 import regex as re
 
@@ -85,7 +88,52 @@ def get_local_tz_offset():
 
 
 _search_regex_parts = []
-_tz_offsets = list(build_tz_offsets(_search_regex_parts))
-_search_regex = re.compile("|".join(_search_regex_parts))
-_search_regex_ignorecase = re.compile("|".join(_search_regex_parts), re.IGNORECASE)
 local_tz_offset = get_local_tz_offset()
+
+DEFAULT_CACHE_PATH = ".dateparser_tz_cache.pkl"
+
+_tz_offsets = None
+_search_regex = None
+_search_regex_ignorecase = None
+
+
+def _load_offsets(cache=False):
+    from dateparser import __version__
+
+    global _tz_offsets, _search_regex, _search_regex_ignorecase
+
+    if cache:
+        path = Path(os.environ.get("DATEPARSER_TZ_CACHE_PATH", DEFAULT_CACHE_PATH))
+        path.parents[0].mkdir(parents=True, exist_ok=True)
+
+        try:
+            with open(path, mode="rb") as file:
+                (
+                    version,
+                    _tz_offsets,
+                    _search_regex,
+                    _search_regex_ignorecase,
+                ) = pickle.load(file)
+
+                if version == __version__:
+                    return
+        except FileNotFoundError:
+            pass
+        except (ValueError, TypeError) as ex:
+            from .utils import get_logger
+
+            get_logger().error("Error loading tz cache: %s", ex)
+
+    _tz_offsets = list(build_tz_offsets(_search_regex_parts))
+    _search_regex = re.compile("|".join(_search_regex_parts))
+    _search_regex_ignorecase = re.compile("|".join(_search_regex_parts), re.IGNORECASE)
+
+    if cache:
+        with open(path, mode="wb") as file:
+            pickle.dump(
+                (__version__, _tz_offsets, _search_regex, _search_regex_ignorecase),
+                file,
+            )
+
+
+_load_offsets("DATEPARSER_TZ_CACHE" in os.environ)

docs/settings.rst

@@ -225,3 +225,10 @@ Dateparser in the future. For example, to ignore relative times:
 
 ``CACHE_SIZE_LIMIT``: limits the size of caches, that store data for already processed dates.
 Default to ``1000``, but you can set ``0`` for turning off the limit.
+
+
+Environment variables
+++++++++++++++
+
+```DATEPARSER_TZ_CACHE```: Whether or not to cache tz offsets and related search regexes. This speeds up the initialization time of dateparser. Defaults to False.
+```DATEPARSER_TZ_CACHE_PATH```: The path to use for the tz cache file. Defaults to ``.dateparser_tz_cache.pkl``.

tests/test_timezone_parser.py

@@ -1,5 +1,7 @@
 import datetime as dt
+import pickle
 from datetime import datetime, timedelta
+from pathlib import Path
 from unittest import SkipTest
 from unittest.mock import Mock, patch
 
@@ -240,3 +242,33 @@ def when_date_is_localized(self, given_date):
     def then_localized_date_is(self, expected_date, expected_tzname):
         self.assertEqual(self.localized_date.date(), expected_date.date())
         self.assertEqual(self.localized_date.tzname(), expected_tzname)
+
+
+class TestOffsetCaching(BaseTestCase):
+    def setUp(self):
+        super().setUp()
+
+        self.cache_file = Path(dateparser.timezone_parser.DEFAULT_CACHE_PATH)
+        self.cache_file.unlink(missing_ok=True)
+
+    def test_no_cache(self):
+        dateparser.timezone_parser._load_offsets()
+        self.assertFalse(self.cache_file.exists())
+
+    def test_cache(self):
+        dateparser.timezone_parser._tz_offsets = None
+        dateparser.timezone_parser._load_offsets(True)
+        self.assertTrue(self.cache_file.exists())
+        self.assertTrue(dateparser.timezone_parser._tz_offsets)
+
+        dateparser.timezone_parser._tz_offsets = None
+        dateparser.timezone_parser._load_offsets(True)
+        self.assertTrue(dateparser.timezone_parser._tz_offsets)
+
+    def test_cache_error(self):
+        with open(self.cache_file, "wb") as file:
+            pickle.dump(1, file)
+        self.assertTrue(self.cache_file.exists())
+        dateparser.timezone_parser._tz_offsets = None
+        dateparser.timezone_parser._load_offsets(True)
+        self.assertTrue(dateparser.timezone_parser._tz_offsets)