PEP 495 contains incorrect diagram for Mind the Gap section

[bxparks]

In PEP 495, the diagram in the Mind the Gap section is the same as the diagram in the In the Fold section just above it. I believe this is incorrect. The correct diagram should look like the following. I tried to reproduce the font and color scheme, but it's not perfect:

[bxparks]

Alternatively, maybe use this diagram which more complicated, but is closer to what the code does when the imaginary datetime in the gap is normalized into an actual time:

tz = zoneinfo.ZoneInfo('America/Los_Angeles')

# In the gap, fold=0 selects the first transition extended forward
t = datetime(2022, 3, 13, 2, 29, 0, tzinfo=tz, fold=0)
u0 = t.timestamp()
t0 = datetime.fromtimestamp(u0, tz=tz)
print(t0) # 2022-03-13 03:29:00-07:00

# In the gap, fold=1 selects the second transition extended backward
t = datetime(2022, 3, 13, 2, 29, 0, tzinfo=tz, fold=1)
u1 = t.timestamp()
t1 = datetime.fromtimestamp(u1, tz=tz)
print(t1) # 2022-03-13 01:29:00-08:00

[CAM-Gerlach]

Your interpretation would seem to be correct, at least as far as I can tell as a PEP editor.

However, as Final PEPs are generally considered historical records rather than living documentation or standards, and this PEP in particular was originally accepted 7 years ago for a Python version released 6 years ago and no longer officially supported, I'm not sure it's worth the effort to update. However, that's ultimately up to the authors @tim-one and @abalkin , though AFAIK neither of them are very active anymore these days.

[bxparks]

I think all Python versions >= 3.6 implement the fold parameter and follow the algorithms described in PEP 495.

I understand the reluctance to change stable documents. Can PEP documents be appended with an Errata section?

[CAM-Gerlach]

Thanks for understanding. There's no real precedent for that, especially for something that is just illustrative background rather than being a normative, substantive part of the specification—either it is fixed if worth fixing, or left alone. If the PEP is to be updated with a new image, then the incorrect image may as well just be replaced directly.

In general (with some existing exceptions), once a Standards Track PEP is Final, the canonical documentation or specification for it, if needed, should typically be hosted somewhere more appropriate (such as the Python docs) and updated there. The closest canonical place here AFAIK would be the datetime module docs, where the important parts are documented and the general concepts/background justifying the change (like these cartoons) are not included.

But again, with all that said, it's ultimately up to the PEP authors if they think it's worth fixing or not, presuming you'd be willing to submit a suitable replacement (in SVG format, like the originals) in a PR.

[bxparks]

The diagrams that I attached to this ticket are SVG files. If they are satisfactory, I can create a PR to replace https://github.com/python/peps/blob/main/pep-0495-gap.svg with one of those. Either of the 2 above.

Oh, I found the original commit that added the incorrect Gap diagram pep-0495-gap.svg. It looks like initially there were both PNG and SVG versions of these diagrams. The PNG version of the Gap diagram looks very close to my diagrams above. However, the SVG version of the Gap diagram in that commit (pep-0495-gap.svg) seems to be a duplicate of the Fold diagram (pep-0495-fold.png), which is clearly a mistake. I assume the PNG files were then deleted with a later commit. So that's how we got here with the incorrect diagram.

The reason that I am motivated to fix this is because the behavior of the datetime library (or any timezone library in any language) around the Gap is non-trivial, and it took me a long time (1-2 years) to understand all the nuances fully. The incorrect diagram in the PEP did not help. I would like to save people who come after me some grief.

[Rosuav]

This sounds like a bug fix, and I am in favour of fixing bugs. I for one would welcome that PR.

[bxparks]

Here is my reproduction of the correct Gap SVG file that was lost in the original commit. If this is acceptable, I can send a PR to replace the current pep-0495-gap.svg:

The reproduction is not perfect:

• I am not a graphics designer. My tool is Google Draw.
• My tool cannot recreate the very-sparse dotted line used by the original authors.
• I am leaving off the "UTC" label on the x-axis that was probably intended to be there. This is for consistency with the current Fold diagram which I do not intend to modify.
• I tried to match the original color palette by eye, but it's not identical. The RGB value probably somewhere in the Fold SVG file, but I'd rather not parse an XML file if I don't need to.

[Rosuav]

LGTM but I'm not a content expert.

[CAM-Gerlach]

LGTM, I'm also not a SME, but the background I do have in this area as well as the fact that it matches the original PNG seems to confirm the change is correct. I'd propose you go ahead your PR, and if Tim and Alexander don't object after a week or two, we can merge it.

I found the original commit that added the incorrect Gap diagram pep-0495-gap.svg. It looks like initially there were both PNG and SVG versions of these diagrams.

Ah, I was wondering if that was the case when we moved to the SVG version being displayed relatively recently, which is why it was never noticed at the time, but hadn't actually gone back to check yet. That makes a particularly strong and compelling case for accepting it, since not only is it a bug fix to the PEP itself, but is fixing a technical regression from how the PEP was originally displayed at the time of its acceptance.

The reason that I am motivated to fix this is because the behavior of the datetime library (or any timezone library in any language) around the Gap is non-trivial, and it took me a long time (1-2 years) to understand all the nuances fully. The incorrect diagram in the PEP did not help. I would like to save people who come after me some grief.

If text in the PEP was important to your understanding of the behavior of the datetime module, then perhaps it would be worth porting the relevant missing portions of the PEP's explanation to the Python docs, as an explanation-type section. Currently the docs cover the (API) "reference" topic thoroughly, but are somewhat more sparse in serving the other areas, particularly explanation. As the goal of explanation-type docs content is to serve understanding of the thing documented, this would seem like a good fit. if you're interested in something like that, I could help guide you through it (especially since I'm also on the Python Docs team).

[bxparks]

@CAM-Gerlach : Sent off a PR. With regards to the Python docs, are you referring to https://docs.python.org/3/library/datetime.html ? That is a beast of a page, I'd be reluctant to touch that one. But one obvious improvement might be to actually add a link to the PEP 495 document near the first occurrence of the fold parameter. Currently there is a single reference to PEP 495, buried in a comment, inside a code fragment, about 2/3 of the way down. Can you point me to the repo that contains the source text for this page? I spent a few minutes searching for it, but got lost in an exploding graph of hyperlinks.