Appveyor was stuck. I'll close and re-open the PR to retrigger it.

Thanks, the changes LGTM. If no objection from@abalkin I'll merge it.

Thanks a lot for reviewing this old PRs :) really appreciated

If we are going to update these examples, I think we should make themPEP 495 compliant and I don't think this PR achieves it.

@abalkin not sure I understand what you mean. The examples are moved form UTC naming to GMT, there is no geographical timezone involved and therefore the fold attribute is not relevant. Isn't it?

@mariocj89 - the fold attribute is only irrelevant for a TZ with a never changing offset. As soon as you have DST changes as is the case in these examples, you have to take fold into account when implementing the.utcoffset() and.dst() methods and the.fromutc() method should properly set the fold attribute. SeeGuidelines for New tzinfo Implementations.

@abalkin absolutely right, missed theUTC +2" if self.dst(dt) else "UTC +1 in the example. I'll have a look into updating the PR to include that

A Python core developer has requested some changes be made to your pull request before we can consider merging it. If you could please address their requests along with any other requests in other reviews from core developers that would be appreciated.

Once you have made the requested changes, please leave a comment on this pull request containing the phraseI have made the requested changes; please review again. I will then notify any core developers who have left a review that you're ready for them to take another look at this pull request.

And if you don't make the requested changes,you will be poked with soft cushions!

@abalkin I trust Mario to come up with something here, but I do think writing a fold-aware example implementation would be way easier ifthis issue were resolved. I think that would also makefromutc implementations that wraptzinfo.fromutc much faster, since most of the code would be executed in C (though I could be wrong on that point).

I think the fact that it's actually fairly difficult to write afromutc that's simple enough for a documentation example might be a sign that we should try to alleviate that cognitive overhead by having basicfold support intzinfo.fromutc.

I am currently quite overwhelmed with work and other organisations, but as soon as I have time i’d Like to get into it and update the examples. I realised when doing it that it is not a 10 minutes job :p

TL;DR
I haven’t forgotten, will get into it “soon”

@abalkin The code for the timezone classes with support for dst and fold attributes is rather complex.

Given the section is to illustrate how to work with datetime and tzinfo objects, what about moving to timezone.utc and a user-defined timezone class based on Kabul? I chose Kabul as it moved its offset once but has no ambiguous times (only imaginary).

This still showcases how datetime and tzinfo interact and the code is much simpler!

Note there are examples on how to work with tzinfo further down the file.

Example implementation:mariocj89@c132630

I can push this to this PR for review if the idea looks good.

@mariocj89 - Using Asia/Kabul for the documentation example sounds fine, but your implementation is incomplete. For the "imaginary" times the result of utcoffset() must depend on the fold value. SeeMind the Gap section in PEP 495.

Good point! Always thought that the PEP referred only to DST but indeed apply to all “variable offsets”.

Will then update it and push it to this branch. Thanks.

As a note, if something like#7425 (which addsfold support directly into the defaultfromutc implementation) were to be merged, you could write a super-basic fold-aware implementation like this:

fromdatetimeimportdatetime,timedelta,tzinfo,timezoneUTC=timezone.utcclassExampleFold(tzinfo):deftzname(self,dt):ifself.dst(dt):return"DST"else:return"STD"defutcoffset(self,dt):returntimedelta(hours=0)+self.dst(dt)defdst(self,dt):dt_start=datetime(1,3,17,1).replace(year=dt.year)dt_end=datetime(1,11,4,1).replace(year=dt.year)naive_dt=dt.replace(tzinfo=None)dst_offset=timedelta(hours=1)ifdt_start<=naive_dt<dt_end:returndst_offsetelse:ifnaive_dt<dt_end+dt_offset:ifdt.fold:returntimedelta(0)else:returndst_offsetreturntimedelta(0)

Obviously that's a sorta weird case because there's no timezone that uses fixed days of the year for offsets, but you can see how easy the "add fold support" part is oncefromutc respects it.

@abalkin I've pushed a potential example implementation. Had to overridefromutc as well, maybe there is a simpler way :/ Let me know if anything needs changing.

Also updated the content to pass doctests (only the modified part).

Tested that Kabul implementation against the dateutil one before at and after the move.

I removed the " needs backport to 3.6" label, the 3.6 branch no longer accept bugfixes (only security fixes are accepted):https://devguide.python.org/#status-of-python-branches

@mariocj89@pganssle
There was a lot of activity on this issue and 2 approvals, but I'm not quite sure where it's at. Can you take another look and comment if it's ready to merge? Thanks!

Wow! Totally forgot about this PR 😆 .

@abalkinrequested to make this PEP 495 complient.

There were some suggestions by@pganssle as well but were the opposite of what@abalkin was proposing when formatting offsets.

Let me know if there is any change to make!

We can ignore any of my comments that contradict@abalkin's. This is clearly an improvement over the previous state of affairs, and we can always change it later.

@pganssle: You didn't approve this PR. Does it mean that it still lacks someone, or is it good as it is? If yes, can you please officially approve it?

Thanks@mariocj89 for the PR, and@vstinner for merging it 🌮🎉.. I'm working now to backport this PR to: 3.7.
🐍🍒⛏🤖 I'm not a witch! I'm not a witch!

I think documentation backports are only going back to 3.7 now anyway, but in case they aren't, this relies on PEP 495, so it can't be backported any further than 3.6. I think it's fine to backport to 3.7 unless@mariocj89 disagrees.

Python 3.6 no longer accept doc changes, only security fixes:https://devguide.python.org/#status-of-python-branches

GH-13811 is a backport of this pull request to the3.7 branch.

Thanks Mario Corchero for the doc enhancement, and Paul for the review!