Performance enhancements

.github/workflows/ci.yml

@@ -18,7 +18,7 @@ jobs:
         runs-on: ubuntu-latest
         strategy:
             matrix:
-                python-version: ["3.8", "3.9", "3.10", "3.11", "3.12", "3.13"]
+                python-version: ["3.10", "3.11", "3.12", "3.13"]
         defaults:
             run:
                 working-directory: .

.github/workflows/coverage_readme.yml

@@ -22,10 +22,10 @@ jobs:
           persist-credentials: false
           fetch-depth: 0
 
-      - name: Set up Python 3.12
+      - name: Set up Python 3.13
         uses: actions/setup-python@v5
         with:
-          python-version: 3.12
+          python-version: 3.13
           cache: 'pip'
           cache-dependency-path: '**/pyproject.toml'
 

.gitignore

@@ -64,3 +64,5 @@ docs/_build/
 
 # PyBuilder
 target/
+.idea
+.DS_Store

README.md

@@ -514,6 +514,6 @@ Since the `EDTFField` and the `_earliest` and `_latest` field values are set aut
 * Fix formatting: `ruff format --config pyproject.toml`
 * Linting and formatting checks and attempted fixes are also run as precommit hooks if you installed them.
 
-### Coverage and benchmraks
+### Coverage and benchmarks
 
 Coverage reports are generated and added as comments to commits, and also visible in the actions log. Benchmarks are run on pull requests and are published [here]( https://ixc.github.io/python-edtf/dev/bench/) and also visible in the actions log.

edtf/__init__.py

@@ -22,6 +22,7 @@
     UncertainOrApproximate,
     Unspecified,
     UnspecifiedIntervalSection,
+    is_valid_edtf,
     parse_edtf,
 )
 
@@ -46,6 +47,7 @@
     "trim_struct_time",
     "text_to_edtf",
     "parse_edtf",
+    "is_valid_edtf",
     # parser_exceptions
     "EDTFParseException",
     # parser_classes

edtf/appsettings.py

@@ -12,7 +12,7 @@
 except ImportError:
     EDTF = {}
 
-SEASON_MONTHS_RANGE = EDTF.get(
+SEASON_MONTHS_RANGE: dict[int, list[int]] = EDTF.get(
     "SEASON_MONTHS_RANGE",
     {
         # season id: [earliest_month, last_month]
@@ -27,7 +27,7 @@
     },
 )
 
-SEASON_L2_MONTHS_RANGE = EDTF.get(
+SEASON_L2_MONTHS_RANGE: dict[int, list[int]] = EDTF.get(
     "SEASON_L2_MONTHS_RANGE",
     {
         # season id: [earliest_month, last_month]
@@ -67,9 +67,9 @@
     },
 )
 
-DAY_FIRST = EDTF.get("DAY_FIRST", False)  # Americans!
+DAY_FIRST: bool = EDTF.get("DAY_FIRST", False)  # Americans!
 
-SEASONS = EDTF.get(
+SEASONS: dict[int, str] = EDTF.get(
     "SEASONS",
     {
         21: "spring",
@@ -78,25 +78,38 @@
         24: "winter",
     },
 )
-INVERSE_SEASONS = EDTF.get("INVERSE_SEASONS", {v: k for k, v in SEASONS.items()})
+INVERSE_SEASONS: dict[str, int] = EDTF.get(
+    "INVERSE_SEASONS", {v: k for k, v in SEASONS.items()}
+)
 # also need to interpret `fall`
 INVERSE_SEASONS["fall"] = 23
 
 # changing these will break tests
-PADDING_DAY_PRECISION = EDTF.get("PADDING_DAY_PRECISION", relativedelta(days=1))
-PADDING_MONTH_PRECISION = EDTF.get("PADDING_MONTH_PRECISION", relativedelta(months=1))
-PADDING_YEAR_PRECISION = EDTF.get("PADDING_YEAR_PRECISION", relativedelta(years=1))
-PADDING_SEASON_PRECISION = EDTF.get("PADDING_SEASON_PRECISION", relativedelta(weeks=12))
-PADDING_DECADE_PRECISION = EDTF.get("PADDING_DECADE_PRECISION", relativedelta(years=10))
-PADDING_CENTURY_PRECISION = EDTF.get(
+PADDING_DAY_PRECISION: relativedelta = EDTF.get(
+    "PADDING_DAY_PRECISION", relativedelta(days=1)
+)
+PADDING_MONTH_PRECISION: relativedelta = EDTF.get(
+    "PADDING_MONTH_PRECISION", relativedelta(months=1)
+)
+PADDING_YEAR_PRECISION: relativedelta = EDTF.get(
+    "PADDING_YEAR_PRECISION", relativedelta(years=1)
+)
+PADDING_SEASON_PRECISION: relativedelta = EDTF.get(
+    "PADDING_SEASON_PRECISION", relativedelta(weeks=12)
+)
+PADDING_DECADE_PRECISION: relativedelta = EDTF.get(
+    "PADDING_DECADE_PRECISION", relativedelta(years=10)
+)
+PADDING_CENTURY_PRECISION: relativedelta = EDTF.get(
     "PADDING_CENTURY_PRECISION", relativedelta(years=100)
 )
-PADDING_MILLENNIUM_PRECISION = EDTF.get(
+PADDING_MILLENNIUM_PRECISION: relativedelta = EDTF.get(
     "PADDING_MILLENNIUM_PRECISION", relativedelta(years=1000)
 )
-MULTIPLIER_IF_UNCERTAIN = EDTF.get("MULTIPLIER_IF_UNCERTAIN", 1.0)
-MULTIPLIER_IF_APPROXIMATE = EDTF.get("MULTIPLIER_IF_APPROXIMATE", 1.0)
-MULTIPLIER_IF_BOTH = EDTF.get("MULTIPLIER_IF_BOTH", 2.0)
-DELTA_IF_UNKNOWN = EDTF.get("DELTA_IF_UNKNOWN", relativedelta(years=10))
+MULTIPLIER_IF_UNCERTAIN: float = EDTF.get("MULTIPLIER_IF_UNCERTAIN", 1.0)
+MULTIPLIER_IF_APPROXIMATE: float = EDTF.get("MULTIPLIER_IF_APPROXIMATE", 1.0)
+MULTIPLIER_IF_BOTH: float = EDTF.get("MULTIPLIER_IF_BOTH", 2.0)
+DELTA_IF_UNKNOWN: relativedelta = EDTF.get("DELTA_IF_UNKNOWN", relativedelta(years=10))
+DELTA_IF_EMPTY: relativedelta = relativedelta(None)
 
-DEBUG_PYPARSING = False
+DEBUG_PYPARSING: bool = False

edtf/convert.py

@@ -21,7 +21,7 @@ def old_specs_to_new_specs_expression(expression):
     return expression
 
 
-def dt_to_struct_time(dt):
+def dt_to_struct_time(dt) -> struct_time:
     """
     Convert a `datetime.date` or `datetime.datetime` to a `struct_time`
     representation *with zero values* for data fields that we cannot always
@@ -70,8 +70,7 @@ def trim_struct_time(st: struct_time, strip_time: bool = False) -> struct_time:
     """
     if strip_time:
         return struct_time(list(st[:3]) + TIME_EMPTY_TIME + TIME_EMPTY_EXTRAS)
-    else:
-        return struct_time(list(st[:6]) + TIME_EMPTY_EXTRAS)
+    return struct_time(list(st[:6]) + TIME_EMPTY_EXTRAS)
 
 
 def struct_time_to_jd(st: struct_time) -> float:
@@ -116,7 +115,7 @@ def jd_to_struct_time(jd: float) -> struct_time:
     return struct_time([year, month, day, hour, minute, second] + TIME_EMPTY_EXTRAS)
 
 
-def _roll_negative_time_fields(year, month, day, hour, minute, second):
+def _roll_negative_time_fields(year, month, day, hour, minute, second) -> tuple:
     """
     Fix date/time fields which have nonsense negative values for any field
     except for year by rolling the overall date/time value backwards, treating
@@ -152,4 +151,5 @@ def _roll_negative_time_fields(year, month, day, hour, minute, second):
         year += int(month / 12.0)  # Adjust by whole year in months
         year -= 1  # Subtract 1 for negative minutes
         month %= 12  # Convert negative month to positive remainder
-    return (year, month, day, hour, minute, second)
+
+    return year, month, day, hour, minute, second

edtf/jdutil.py

@@ -396,7 +396,7 @@ def __sub__(self, other):
 
             return jd_to_datetime(combined)
 
-        elif isinstance(other, (datetime, dt.datetime)):
+        elif isinstance(other, datetime | dt.datetime):
             diff = datetime_to_jd(self) - datetime_to_jd(other)
 
             return dt.timedelta(diff)
@@ -407,7 +407,7 @@ def __sub__(self, other):
             raise TypeError(s)
 
     def __rsub__(self, other):
-        if not isinstance(other, (datetime, dt.datetime)):
+        if not isinstance(other, datetime | dt.datetime):
             s = "jdutil.datetime supports '-' with: "
             s += "jdutil.datetime and datetime.datetime"
             raise TypeError(s)