Make UTC transitions API public

[Eitan]

I just had to rewrite a script that generates .ics files from PHP to Python. PHP provides a tz->getTransitions(min, max) method, which is extremely helpful when creating .ics because you are required to define your own timezones based on a list of transitions to standard or daylight savings time. I was able to do this using pytz, but only by using the private and undocumented _utc_transition_times property. I'd like for this API to be made public so I can be sure that I'm using it right and that it won't be removed or changed in future releases.

[Stuart Bishop (stub)]

I'll need an example of the expected Python API.

What does tz.getTransitions(min, max) return?

What are min and max?

[Stuart Bishop (stub)]

I expect:

def getTransitions(self, min, max):
    '''
    Return a list of daylight savings transition times that occur during the given period, as a list of (utc_datetime, offset) tuples. offset is minutes offset from UTC.

   min and max are datetime instances. If no timezone information is attached, they are assumed to be UTC.
   '''

[Eitan (eitan-mosenkis)]

Looks pretty good. I made a few changes:
1. replaced camelCase getTransitions with lowercase transitions to match the style of the rest of the public API.
2. return 'sequence' instead of 'list' to allow it to be implemented as a generator if you so choose
3. return timedeltas instead of just a number of minutes
4. attempted to tersely make clear that it always returns at least one transition, starting from the latest transition that is <= min.

def transitions(self, min, max):
    '''
    Return a sequnce of one or more daylight savings transitions that cover the given period, as (utc_datetime, offset) tuples. offset is a datetime.timedelta from UTC.

    min and max are datetime instances. If no timezone information is attached, they are assumed to be UTC.

    The utc_datetime of the first transition returned will be less than or equal to min such that the first offset is equal to utcoffset(min). The utc_datetime of the last transition returned will be less than or equal to max such that the last offset is equal to utcoffset(max).

    If no transitions occur between min and max inclusive, a sequence will be returned containing the last transition that occurs before min.
   '''

[Jonathan Reed (jdreed)]

I'd also love to see this feature, for a similar reason. I'm dealing with scheduling data, and while the actual values are stored in UTC, I still need to display a big loud warning to the user when there's a transition that occurs in a given period. Right now I'm abusing the private attribute, but a public API would be awesome.

The only difference between what's proposed here and what I need is that I'd like the function to return None or something, if indeed there is no transition between min and max inclusive, but I suppose comparing the returned value to min is not difficult.

[Mike (mike-bd)]

+1