fix inaccuracies in RFC3339 method docs

ariebovenberg · Nov 8, 2024 · 2cf6722 · 2cf6722
1 parent 8f65970
commit 2cf6722
Show file tree

Hide file tree

Showing 4 changed files with 30 additions and 10 deletions.
diff --git a/CHANGELOG.rst b/CHANGELOG.rst
@@ -1,6 +1,12 @@
 🚀 Changelog
 ============
 
+0.6.12 (2024-11-08)
+-------------------
+
+- Fixed ``format_rfc3339()`` docstrings that incorrectly included a ``T`` separator.
+  Clarified that ``T`` can be added by using the ``format_common_iso()`` method instead. (#185)
+
 0.6.11 (2024-11-04)
 -------------------
 

diff --git a/docs/overview.rst b/docs/overview.rst
@@ -691,10 +691,13 @@ to this format, respectively:
 
 >>> d = OffsetDateTime(2023, 12, 28, 11, 30, offset=+5)
 >>> d.format_rfc3339()
-'2023-12-28T11:30:00+05:00'
->>> OffsetDateTime.parse_rfc3339('2021-07-13 09:45:00Z')
+'2023-12-28 11:30:00+05:00'
+>>> OffsetDateTime.parse_rfc3339('2021-07-13_09:45:00Z')
 OffsetDateTime(2021-07-13 09:45:00Z)
 
+The RFC3339 formatter uses a space separator by default.
+If you prefer the ``T`` separator, use ``format_common_iso()`` instead.
+
 RFC 2822
 ~~~~~~~~
 

diff --git a/pyproject.toml b/pyproject.toml
@@ -7,7 +7,7 @@ maintainers = [
     {name = "Arie Bovenberg", email = "[email protected]"},
 ]
 readme = "README.md"
-version = "0.6.11"
+version = "0.6.12"
 description = "Modern datetime library for Python"
 requires-python = ">=3.9"
 classifiers = [

diff --git a/pysrc/whenever/_pywhenever.py b/pysrc/whenever/_pywhenever.py
@@ -32,7 +32,7 @@
 #   - It saves some overhead
 from __future__ import annotations
 
-__version__ = "0.6.11"
+__version__ = "0.6.12"
 
 import enum
 import re
@@ -3090,14 +3090,16 @@ def parse_rfc2822(cls, s: str, /) -> Instant:
         return cls._from_py_unchecked(parsed, 0)
 
     def format_rfc3339(self) -> str:
-        """Format as an RFC 3339 string
+        """Format as an RFC 3339 string ``YYYY-MM-DD HH:MM:SSZ``
+
+        If you prefer the ``T`` separator, use `format_common_iso()` instead.
 
         The inverse of the ``parse_rfc3339()`` method.
 
         Example
         -------
         >>> Instant.from_utc(2020, 8, 15, hour=23, minute=12).format_rfc3339()
-        "2020-08-15T23:12:00Z"
+        "2020-08-15 23:12:00Z"
         """
         return (
             self._py_dt.isoformat(sep=" ")[:-6]
@@ -3113,7 +3115,7 @@ def parse_rfc3339(cls, s: str, /) -> Instant:
 
         Example
         -------
-        >>> Instant.parse_rfc3339("2020-08-15T23:12:00Z")
+        >>> Instant.parse_rfc3339("2020-08-15 23:12:00Z")
         Instant(2020-08-15 23:12:00Z)
         >>>
         >>> # also valid:
@@ -3647,14 +3649,23 @@ def parse_rfc2822(cls, s: str, /) -> OffsetDateTime:
         return cls._from_py_unchecked(parsed, 0)
 
     def format_rfc3339(self) -> str:
-        """Format as an RFC 3339 string
+        """Format as an RFC 3339 string ``YYYY-MM-DD HH:MM:SS±HH:MM``
+
+        If you prefer the ``T`` separator, use ``format_common_iso()`` instead.
 
         The inverse of the ``parse_rfc3339()`` method.
 
         Example
         -------
         >>> OffsetDateTime(2020, 8, 15, hour=23, minute=12, offset=hours(4)).format_rfc3339()
-        "2020-08-15T23:12:00+04:00"
+        "2020-08-15 23:12:00+04:00"
+
+        Note
+        ----
+        The RFC3339 format does not allow for second-level precision of the UTC offset.
+        This should not be a problem in practice, unless you're dealing with
+        pre-1950s timezones.
+        The ``format_common_iso()`` does support this precision.
         """
         py_isofmt = self._py_dt.isoformat(" ")
         return (
@@ -3671,7 +3682,7 @@ def parse_rfc3339(cls, s: str, /) -> OffsetDateTime:
 
         Example
         -------
-        >>> OffsetDateTime.parse_rfc3339("2020-08-15T23:12:00+02:00")
+        >>> OffsetDateTime.parse_rfc3339("2020-08-15 23:12:00+02:00")
         OffsetDateTime(2020-08-15 23:12:00+02:00)
         >>> # also valid:
         >>> OffsetDateTime.parse_rfc3339("2020-08-15T23:12:00Z")