improve DST-related error messages

CHANGELOG.rst

@@ -1,6 +1,11 @@
 🚀 Changelog
 ============
 
+0.6.9 (2024-09-12)
+------------------
+
+- Clarify DST-related error messages (#169)
+
 0.6.8 (2024-09-05)
 ------------------
 

docs/overview.rst

@@ -502,7 +502,7 @@ DST-safe arithmetic
 Date and time arithmetic can be tricky due to daylight saving time (DST)
 and other timezone changes.
 The API of the different classes is designed to avoid implicitly ignoring these.
-The type annotations and descriptive error messages should automatically guide you
+The type annotations and descriptive error messages should guide you
 to the correct usage.
 
 - :class:`~whenever.Instant` has no calendar, so it doesn't support

pyproject.toml

@@ -4,7 +4,7 @@ authors = [
     {name = "Arie Bovenberg", email = "a.c.bovenberg@gmail.com"},
 ]
 readme = "README.md"
-version = "0.6.8"
+version = "0.6.9"
 description = "Modern datetime library for Python, written in Rust"
 requires-python = ">=3.9"
 classifiers = [

pysrc/whenever/_pywhenever.py

@@ -32,7 +32,7 @@
 #   - It saves some overhead
 from __future__ import annotations
 
-__version__ = "0.6.8"
+__version__ = "0.6.9"
 
 import enum
 import re
@@ -2942,7 +2942,8 @@ def now(
                 "and other timezone changes. Instead, use `Instant.now()` or "
                 "`ZonedDateTime.now(<tz name>)` if you know the timezone. "
                 "Or, if you want to ignore DST and accept potentially incorrect offsets, "
-                "pass `ignore_dst=True` to this method."
+                "pass `ignore_dst=True` to this method. For more information, see "
+                "whenever.rtfd.io/en/latest/overview.html#dst-safe-arithmetic"
             )
         secs, nanos = divmod(time_ns(), 1_000_000_000)
         return cls._from_py_unchecked(
@@ -4425,15 +4426,17 @@ class ImplicitlyIgnoringDST(TypeError):
     "and other timezone changes. To perform a DST-safe conversion, use "
     "ZonedDateTime.from_timestamp() instead. "
     "Or, if you don't know the timezone and accept potentially incorrect results "
-    "during DST transitions, pass `ignore_dst=True`."
+    "during DST transitions, pass `ignore_dst=True`. For more information, see "
+    "whenever.rtfd.io/en/latest/overview.html#dst-safe-arithmetic"
 )
 
 
-# FUTURE: docs link
 _IGNORE_DST_SUGGESTION = """\
 To perform DST-safe operations, convert to a ZonedDateTime first. \
 Or, if you don't know the timezone and accept potentially incorrect results \
-during DST transitions, pass `ignore_dst=True`."""
+during DST transitions, pass `ignore_dst=True`. For more information, see \
+whenever.rtfd.io/en/latest/overview.html#dst-safe-arithmetic"
+"""
 
 
 _EXC_ADJUST_OFFSET_DATETIME = ImplicitlyIgnoringDST(

src/local_datetime.rs

@@ -482,7 +482,8 @@ unsafe fn _shift_method(
             "Adding time units to a LocalDateTime implicitly ignores \
             Daylight Saving Time. Instead, convert to a ZonedDateTime first \
             using assume_tz(). Or, if you're sure you want to ignore DST, \
-            explicitly pass ignore_dst=True."
+            explicitly pass ignore_dst=True. For more information, see \
+            whenever.rtfd.io/en/latest/overview.html#dst-safe-arithmetic"
         ))?
     }
     DateTime::extract(slf)
@@ -505,7 +506,8 @@ unsafe fn difference(
         "The difference between two local datetimes implicitly ignores DST transitions. \
         and other timezone changes. To perform DST-safe arithmetic, convert to a ZonedDateTime \
         first using assume_tz(). Or, if you're sure you want to ignore DST, explicitly pass \
-        ignore_dst=True.",
+        ignore_dst=True. For more information, see \
+        whenever.rtfd.io/en/latest/overview.html#dst-safe-arithmetic",
     )?;
     let [arg] = *args else {
         Err(type_err!("difference() takes exactly 1 argument"))?

src/offset_datetime.rs

@@ -363,10 +363,11 @@ unsafe fn __sub__(obj_a: *mut PyObject, obj_b: *mut PyObject) -> PyReturn {
             {
                 Err(py_err!(
                     state.exc_implicitly_ignoring_dst,
-                    "Subtracting a delta from a LocalDateTime implicitly ignores \
+                    "Subtracting a delta from an OffsetDateTime implicitly ignores \
                      Daylight Saving Time. Instead, convert to a ZonedDateTime first \
                      using to_tz(). Or, if you're sure you want to ignore DST, \
-                     explicitly pass ignore_dst=True."
+                     explicitly pass ignore_dst=True. For more information, see \
+                     whenever.rtfd.io/en/latest/overview.html#dst-safe-arithmetic"
                 ))?
             } else {
                 return Ok(newref(Py_NotImplemented()));
@@ -659,7 +660,8 @@ unsafe fn now(
          and other timezone changes. Instead, use `Instant.now()` or \
          `ZonedDateTime.now(<tz name>)` if you know the timezone. \
          Or, if you want to ignore DST and accept potentially incorrect offsets, \
-         pass `ignore_dst=True` to this method.",
+         pass `ignore_dst=True` to this method. For more information, see \
+         whenever.rtfd.io/en/latest/overview.html#dst-safe-arithmetic",
     )?;
 
     let offset_secs = extract_offset(offset, state.time_delta_type)?;
@@ -796,10 +798,11 @@ unsafe fn _shift_method(
     if !ignore_dst {
         Err(py_err!(
             state.exc_implicitly_ignoring_dst,
-            "Adding time units to a LocalDateTime implicitly ignores \
+            "Adding time units to an OffsetDateTime implicitly ignores \
             Daylight Saving Time. Instead, convert to a ZonedDateTime first \
             using assume_tz(). Or, if you're sure you want to ignore DST, \
-            explicitly pass ignore_dst=True."
+            explicitly pass ignore_dst=True. For more information, see \
+            whenever.rtfd.io/en/latest/overview.html#dst-safe-arithmetic"
         ))?
     }
     let OffsetDateTime {
@@ -1264,9 +1267,10 @@ static mut GETSETTERS: &[PyGetSetDef] = &[
 ];
 
 static IGNORE_DST_MSG: &str =
-    "Adjusting a fixed offset datetime implicitly ignores DST and other timezone changes. \
+    "Adjusting a fixed-offset datetime implicitly ignores DST and other timezone changes. \
     To perform DST-safe operations, convert to a ZonedDateTime first using `to_tz()`. \
     Or, if you don't know the timezone and accept potentially incorrect results \
-    during DST transitions, pass `ignore_dst=True`.";
+    during DST transitions, pass `ignore_dst=True`. For more information, see \
+    whenever.rtfd.io/en/latest/overview.html#dst-safe-arithmetic";
 
 type_spec!(OffsetDateTime, SLOTS);