refactor: improve periods module doctests, documentation, and type hints

.gitignore

@@ -1,22 +1,23 @@
-.venv
+*.egg-info
+*.mo
+*.pyc
+*~
+.hypothesis
+.mypy_cache
+.noseids
 .project
-.spyderproject
 .pydevproject
-.vscode
+.pytest_cache
 .settings/
+.spyderproject
+.tags*
+.venv
+.vscode
 .vscode/
+/.coverage
+/cover
+/tags
 build/
 dist/
 doc/
-*.egg-info
-*.mo
-*.pyc
-*~
-/cover
-/.coverage
-/tags
-.tags*
-.noseids
-.pytest_cache
-.mypy_cache
 performance.json

Makefile

@@ -52,6 +52,7 @@ check-style: \
 	check-style-doc-commons \
 	check-style-doc-entities \
 	check-style-doc-indexed_enums \
+	check-style-doc-periods \
 	check-style-doc-types
 	@$(call pass,$@:)
 
@@ -72,6 +73,7 @@ check-types: \
 	check-types-strict-commons \
 	check-types-strict-entities \
 	check-types-strict-indexed_enums \
+	check-types-strict-periods \
 	check-types-strict-types
 	@$(call pass,$@:)
 

openfisca_core/periods/__init__.py

@@ -21,26 +21,50 @@
 #
 # See: https://www.python.org/dev/peps/pep-0008/#imports
 
-from .config import (  # noqa: F401
-    DAY,
-    MONTH,
-    YEAR,
-    ETERNITY,
-    INSTANT_PATTERN,
-    date_by_instant_cache,
-    str_by_instant_cache,
-    year_or_month_or_day_re,
-    )
+from typing import Any, Dict
+
+from .config import INSTANT_PATTERN, YEAR_OR_MONTH_OR_DAY_RE, DATE, LAST  # noqa: F401
+from .instant_ import Instant  # noqa: F401
+from .period_ import Period  # noqa: F401
+from .date_unit import DateUnit  # noqa: F401
 
 from .helpers import (  # noqa: F401
     N_,
     instant,
     instant_date,
-    period,
     key_period_size,
-    unit_weights,
-    unit_weight,
+    period,
     )
 
-from .instant_ import Instant  # noqa: F401
-from .period_ import Period  # noqa: F401
+# For backwards compatibility
+
+from .helpers import unit_weight, unit_weights  # noqa: F401
+
+for item in DateUnit:
+    globals()[item.name.upper()] = item.value
+
+str_by_instant_cache: Dict[Any, Any] = {}
+"""Cache to store :obj:`str` reprentations of :obj:`.Instant`.
+
+.. deprecated:: 35.9.0
+    This cache has been deprecated and will be removed in the future. The
+    functionality is now provided by :func:`functools.lru_cache`.
+
+"""
+
+date_by_instant_cache: Dict[Any, Any] = {}
+"""Cache to store :obj:`datetime.date` reprentations of :obj:`.Instant`.
+
+.. deprecated:: 35.9.0
+    This cache has been deprecated and will be removed in the future. The
+    functionality is now provided by :func:`functools.lru_cache`.
+
+"""
+
+year_or_month_or_day_re = YEAR_OR_MONTH_OR_DAY_RE
+"""???
+
+.. deprecated:: 35.9.0
+    ??? has been deprecated and it will be removed in 36.0.0.
+
+"""

openfisca_core/periods/config.py

@@ -1,15 +1,27 @@
+import calendar
+import datetime
+import functools
 import re
-import typing
+from typing import Pattern
 
-DAY = 'day'
-MONTH = 'month'
-YEAR = 'year'
-ETERNITY = 'eternity'
+INSTANT_PATTERN: Pattern = re.compile(r"^\d{4}(-(0[1-9]|1[012]))?(-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[01]))?$")
+"""Pattern to validate a valid :obj:`.Instant`.
 
-# Matches "2015", "2015-01", "2015-01-01"
-# Does not match "2015-13", "2015-12-32"
-INSTANT_PATTERN = re.compile(r"^\d{4}(-(0[1-9]|1[012]))?(-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[01]))?$")
+Matches: "2015", "2015-01", "2015-01-01"…
+Does not match: "2015-13", "2015-12-32"…
 
-date_by_instant_cache: typing.Dict = {}
-str_by_instant_cache: typing.Dict = {}
-year_or_month_or_day_re = re.compile(r'(18|19|20)\d{2}(-(0?[1-9]|1[0-2])(-([0-2]?\d|3[0-1]))?)?$')
+"""
+
+YEAR_OR_MONTH_OR_DAY_RE: Pattern = re.compile(r"(18|19|20)\d{2}(-(0?[1-9]|1[0-2])(-([0-2]?\d|3[0-1]))?)?$")
+"""???
+
+.. deprecated:: 35.9.0
+    ??? has been deprecated and it will be removed in 36.0.0.
+
+"""
+
+DATE = functools.lru_cache(maxsize = None)(datetime.date)
+"""A memoized date constructor."""
+
+LAST = functools.lru_cache(maxsize = None)(calendar.monthrange)
+"""A memoized date range constructor, useful for last-of month offsets."""