From 2cf672203d67edb3f9c8637cd751e3f0f8df6759 Mon Sep 17 00:00:00 2001 From: Arie Bovenberg Date: Fri, 8 Nov 2024 22:35:34 +0100 Subject: [PATCH] fix inaccuracies in RFC3339 method docs --- CHANGELOG.rst | 6 ++++++ docs/overview.rst | 7 +++++-- pyproject.toml | 2 +- pysrc/whenever/_pywhenever.py | 25 ++++++++++++++++++------- 4 files changed, 30 insertions(+), 10 deletions(-) diff --git a/CHANGELOG.rst b/CHANGELOG.rst index d3550089..0d344bae 100644 --- 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 index 62ca5195..3994985a 100644 --- 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 index 97baaf44..a5cb2956 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -7,7 +7,7 @@ maintainers = [ {name = "Arie Bovenberg", email = "a.c.bovenberg@gmail.com"}, ] 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 index 14dc3b1e..7b7be7ca 100644 --- 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")