2.10. ISO 8601 Dates and Times

This module defines special classes for handling ISO 8601 dates and times.

class pyslet.iso8601.Date(src=None, base=None, century=None, decade=None, year=None, month=None, day=None, week=None, weekday=None, ordinalDay=None, absoluteDay=None)

Bases: object

A class for representing ISO dates.

Values can be represent dates with reduced precision, for example:

Date(century=20,year=13,month=12)

represents December 2013, no specific day.

There are a number of different forms of the constructor based on named parameters, the simplest is:

Date(century=19,year=69,month=7,day=20)

You can also use weekday format (note that decade must be provided separately):

Date(century=19,decade=6,year=9,week=29,weekday=7)

Ordinal format (where day 1 is 1st Jan):

Date(century=19,year=69,ordinalDay=201)

Absolute format (where day 1 is the notional 1st Jan 0001):

Date(absoluteDay=718998)

An empty constructor is equivalent to:

Date()==Date(absoluteDay=1)

All constructors except the absolute form allow the passing of a base date which allows the most-significant values to be omitted, for example:

base=Date(century=19,year=69,month=7,day=20)
newDate=Date(day=21,base=base)  #: 21st July 1969

Note that base always represents a date before the newly constructed date, so:

base=Date(century=19,year=99,month=12,day=31)
newDate=Date(day=5,base=base)

constructs a Date representing the 5th January 2000

century = None

the century, 0..99

year = None

the year, 0..99

month = None

the month, 1..12 (for dates stored in calendar form)

week = None

the week (for dates stored in week form)

day = None

the day, 1..31 (or 1..7 when week is not None)

GetAbsoluteDay()

Return a notional day number - with 1 being the 0001-01-01 which is the base day of our calendar.

GetCalendarDay()

Returns a tuple of: (century,year,month,day)

GetOrdinalDay()

Returns a tuple of (century,year,ordinalDay)

GetWeekDay()

Returns a tuple of (century,decade,year,week,weekday), note that Monday is 1 and Sunday is 7

classmethod FromStructTime(t)

Constructs a Date from a struct_time, such as might be returned from time.gmtime() and related functions.

UpdateStructTime(t)

UpdateStructTime changes the year, month, date, wday and ydat fields of t, a struct_time, to match the values in this date.

classmethod FromNow()

Constructs a Date from the current local time.

Offset(centuries=0, years=0, months=0, weeks=0, days=0)

Constructs a Date from the current date + a given offset

classmethod from_str(src, base=None)

Parses a Date instance from a src string.

classmethod FromStringFormat(src, base=None)

Similar to from_str() except that a tuple is returned, the first item is the resulting Date instance, the second is a string describing the format parsed. For example:

d,f=Date.FromStringFormat("1969-07-20")
# f is set to "YYYY-MM-DD". 
GetCalendarString(basic=False, truncation=0)

Formats this date using calendar form, for example 1969-07-20

basic
True/False, selects basic form, e.g., 19690720. Default is False
truncation
One of the Truncation constants used to select truncated forms of the date. For example, if you specify Truncation.Year you’ll get –07-20 or –0720. Default is NoTruncation.

Note that Calendar format only supports Century, Year and Month truncated forms.

GetOrdinalString(basic=False, truncation=0)

Formats this date using ordinal form, for example 1969-201

basic
True/False, selects basic form, e.g., 1969201. Default is False
truncation
One of the Truncation constants used to select truncated forms of the date. For example, if you specify Truncation.Year you’ll get -201. Default is NoTruncation.

Note that ordinal format only supports century and year truncated forms.

GetWeekString(basic=False, truncation=0)

Formats this date using week form, for example 1969-W29-7

basic
True/False, selects basic form, e.g., 1969W297. Default is False
truncation
One of the Truncation constants used to select truncated forms of the date. For example, if you specify Truncation.Year you’ll get -W297. Default is NoTruncation.

Note that week format only supports century, decade, year and week truncated forms.

classmethod FromJulian(year, month, day)

Constructs a Date from a year, month and day expressed in the Julian calendar.

GetJulianDay()

Returns a tuple of: (year,month,day) representing the equivalent date in the Julian calendar.

LeapYear()

LeapYear returns True if this date is (in) a leap year and False otherwise.

Note that leap years fall on all years that divide by 4 except those that divide by 100 but including those that divide by 400.

Complete()

Returns True if this date has a complete representation, i.e., does not use one of the reduced precision forms.

GetPrecision()

Returns one of the Precision constants representing the precision of this date.

class pyslet.iso8601.Time(src=None, hour=None, minute=None, second=None, totalSeconds=None, zDirection=None, zHour=None, zMinute=None)

Bases: object

A class for representing ISO times

Values can be represent times with reduced precision, for example:

Time(hour=20)

represents 8pm without a specific minute/seconds value.

There are a number of different forms of the constructor based on named parameters, the simplest is:

Time(hour=20,minute=17,second=40)

To indicate UTC (Zulu time) by providing a zone direction of 0:

Time(hour=20,minute=17,second=40,zDirection=0)

To indicate a UTC offset provide additional values for hours (and optionally minutes):

Time(hour=15,minute=17,second=40,zDirection=-1,zHour=5,zMinute=0)

A UTC offset of 0 hours and minutes results in a value that compares as equal to the corresponding Zulu time but is formatted using an explicit offset by str() or unicode() rather than using the canonical “Z” form.

You may also specify a total number of seconds past midnight (no zone):

Time(totalSeconds=73060)

If totalSeconds overflows an error is raised. To create a time from an arbitrary number of seconds and catch overflow use Offset instead:

Time(totalSeconds=159460)
# raises DateTimeError

t,overflow=Time().Offset(seconds=159460)
# sets t to 20:40:17 and overflow=1

Time supports two representations of midnight: 00:00:00 and 24:00:00 in keeping with the ISO specification. These are considered equivalent by comparisons!

Truncated forms can be created directly from the base time, see Extend() for more information.

hour = None

the hour, 0..24

minute = None

the minute, 0..59

second = None

the seconds, 0..60 (to include leap seconds)

zOffset = None

the difference in minutes to UTC

GetTotalSeconds()

Note that leap seconds are handled as if they were invisible, e.g., 23:00:60 returns the same total seconds as 23:00:59.

GetTime()

Returns a tuple of (hour,minute,second).

Times with reduced precision will return None for second and or minute.

GetZone()

Returns a tuple of:

(zDirection,zOffset)

zDirection is defined as per Time’s constructor, zOffset is a non-negative integer minute offset or None, if the zone is unspecified for this Time.

GetZoneOffset()

Returns a single integer representing the zone offset (in minutes) or None if this time does not have a time zone offset.

GetZone3()

Returns a tuple of:

(zDirection,zHour,zMinute)

These values are defined as per Time’s constructor.

GetCanonicalZone()

Returns a tuple of:

(zDirection,zHour,zMinute)

These values are defined as per Time’s constructor but zero offsets always return zDirection=0. If present, the zone is always returned with complete (minute) precision.

GetTimeAndZone()

Returns a tuple of (hour,minute,second,zone direction,zone offset) as defined in GetTime and GetZone.

Extend(hour=None, minute=None, second=None)

Constructs a Time instance from an existing time, extended a (possibly) truncated hour/minute/second value.

The time zone is always copied if present. The result is a tuple of (<Time instance>,overflow) where overflow 0 or 1 indicating whether or not the time overflowed. For example:

# set base to 20:17:40Z
base=Time(hour=20,minute=17,second=40,zDirection=0)
t,overflow=base.Extend(minute=37)
# t is 20:37:40Z, overflow is 0
t,overflow=base.Extend(minute=7)
# t is 21:07:40Z, overflow is 0
t,overflow=base.Extend(hour=19,minute=7)
# t is 19:07:40Z, overflow is 1
Offset(hours=0, minutes=0, seconds=0)

Constructs a Time instance from an existing time and an offset number of hours, minutes and or seconds.

The time zone is always copied (if present). The result is a tuple of (<Time instance>,overflow) where overflow is 0 or 1 indicating whether or not the time overflowed. For example:

# set base to 20:17:40Z
base=Time(hour=20,minute=17,second=40,zDirection=0)
t,overflow=base.Offset(minutes=37)
# t is 20:54:40Z, overflow is 0
t,overflow=base.Offset(hours=4,minutes=37)
# t is 00:54:40Z, overflow is 1
WithZone(zDirection, zHour=None, zMinute=None)

Constructs a Time instance from an existing time but with the time zone specified.

The time zone of the existing time is ignored. Pass zDirection=None to strip the zone information completely.

ShiftZone(zDirection, zHour=None, zMinute=None)

Constructs a Time instance from an existing time but shifted so that it is in the time zone specified. The return value is a tuple of:

(<Time instance>, overflow)

overflow is one of -1, 0 or 1 indicating if the time over- or under-flowed as a result of the time zone shift.

classmethod FromStructTime(t)

Constructs a zone-less Time from a struct_time, such as might be returned from time.gmtime() and related functions.

UpdateStructTime(t)

UpdateStructTime changes the hour, minute, second and isdst fields of t, a struct_time, to match the values in this time.

isdst is always set to -1

classmethod FromNow()

Constructs a Time from the current local time.

classmethod from_str(src, base=None)

Constructs a Time instance from a string representation, truncated forms are returned as the earliest time on or after base and may have overflowed. See FromStringFormat() for more.

WithZoneString(zoneStr)

Constructs a Time instance from an existing time but with the time zone parsed from zoneStr. The time zone of the existing time is ignored.

WithZoneStringFormat(zoneStr)

Constructs a Time instance from an existing time but with the time zone parsed from zoneStr. The time zone of the existing time is ignored.

Returns a tuple of: (<Time instance>,format)

classmethod FromStringFormat(src, base=None)

Constructs a Time instance from a string representation, truncated forms are returned as the earliest time on or after base.

Returns a tuple of (<Time instance>,overflow,format) where overflow is 0 or 1 indicating whether or not a truncated form overflowed and format is a string representation of the format parsed, e.g., “hhmmss”.

GetString(basic=False, truncation=0, ndp=0, zonePrecision=7, dp=', ')

Formats this time, including zone, for example 20:17:40

basic
True/False, selects basic form, e.g., 201740. Default is False
truncation
One of the Truncation constants used to select truncated forms of the time. For example, if you specify Truncation.Hour you’ll get -17:40 or -1740. Default is NoTruncation.
ndp
Specifies the number of decimal places to display for the least significant component, the default is 0.
dp
The character to use as the decimal point, the default is the comma, as per the ISO standard.
zonePrecision
One of Precision.Hour or Precision.Complete to control the precision of the zone offset.

Note that time formats only support Minute and Second truncated forms.

GetZoneString(basic=False, zonePrecision=7)

Formats this time’s zone, for example -05:00.

basic
True/False, selects basic form, e.g., -0500. Default is False
zonePrecision
One of Precision.Hour or Precision.Complete to control the precision of the zone offset.

Times constructed with a zDirection value of 0 are always rendered using “Z” for Zulu time (the name is taken from the phonetic alphabet). To force use of the offset format you must construct the time with a non-zero value for zDirection.

Complete()

Returns True if this date has a complete representation, i.e., does not use one of the reduced precision forms.

(Whether or not a time is complete refers only to the precision of the time value, it says nothing about the presence or absence of a time zone offset.)

GetPrecision()

Returns one of the Precision constants representing the precision of this time.

WithPrecision(precision, truncate=False)

Constructs a Time instance from an existing time but with the precision specified by precision.

precision is one of the Precision constants, only hour, minute and complete precision are valid.

truncate is True/False indicating whether or not the time value should be truncated so that all values are integers. For example:

t=Time(hour=20,minute=17,second=40)
tm=t.WithPrecision(Precision.Minute,False)
print tm.GetString(ndp=3)
#   20:17,667
tm=t.WithPrecision(Precision.Minute,True)
print tm.GetString(ndp=3)
#   20:17,000       
class pyslet.iso8601.TimePoint(src=None, date=None, time=None)

Bases: object

A class for representing ISO timepoints

TimePoints are constructed from a date and a time (which may or may not have a time zone), for example:

TimePoint(date=Date(year=1969,month=7,day=20),
                time=Time(hour=20,minute=17,second=40,zDirection=0))

If the date is missing then the date origin is used, Date() or 0001-01-01. Similarly, if the time is missing then the time origin is used, Time() or 00:00:00

Times may be given with reduced precision but the date must be complete. In other words, there is no such thing as a timepoint with, month precision, use Date instead.

GetCalendarTimePoint()

Returns a tuple of:

(century,year,month,day,hour,minute,second)
GetOrdinalTimePoint()

Returns a tuple of:

(century,year,ordinalDay,hour,minute,second)
GetWeekDayTimePoint()

Returns a tuple of:

(century,decade,year,week,weekday,hour,minute,second)
GetZone()

Returns a tuple of

(zDirection,zOffset)

See Time.GetZone() for details.

WithZone(zDirection, zHour=None, zMinute=None)

Constructs a TimePoint instance from an existing TimePoint but with the time zone specified. The time zone of the existing TimePoint is ignored.

ShiftZone(zDirection, zHour=None, zMinute=None)

Constructs a TimePoint instance from an existing TimePoint but shifted so that it is in the time zone specified.

UpdateStructTime(t)

UpdateStructTime changes the year, month, date, hour, minute and second fields of t, a struct_time, to match the values in this date.

classmethod FromStructTime(t)

Constructs a TimePoint from a struct_time, such as might be returned from time.gmtime() and related functions.

classmethod from_str(src, base=None, tDesignators='T')

Constructs a TimePoint from a string representation. Truncated forms are parsed with reference to base.

classmethod FromStringFormat(src, base=None, tDesignators='T')

Similar to from_str() except that a tuple is returned, the first item is the resulting TimePoint instance, the second is a string describing the format parsed. For example:

tp,f=TimePoint.FromStringFormat("1969-07-20T20:40:17")
# f is set to "YYYY-MM-DDTmm:hh:ss".
GetCalendarString(basic=False, truncation=0, ndp=0, zonePrecision=7, dp=', ', tDesignator='T')

Formats this TimePoint using calendar form, for example 1969-07-20T20:17:40

basic
True/False, selects basic form, e.g., 19690720T201740. Default is False
truncation
One of the Truncation constants used to select truncated forms of the date. For example, if you specify Truncation.Year you’ll get –07-20T20:17:40 or –0720T201740. Default is NoTruncation. Note that Calendar format only :supports Century, Year and Month truncated forms, the time component cannot be truncated.
ndp, dp and zonePrecision
As specified in Time.GetString()
GetOrdinalString(basic=0, truncation=0, ndp=0, zonePrecision=7, dp=', ', tDesignator='T')

Formats this TimePoint using ordinal form, for example 1969-201T20-17-40

basic
True/False, selects basic form, e.g., 1969201T201740. Default is False
truncation
One of the Truncation constants used to select truncated forms of the date. For example, if you specify Truncation.Year you’ll get -201T20-17-40. Default is NoTruncation. Note that ordinal format only supports century and year truncated forms, the time component cannot be truncated.
ndp, dp and zonePrecision
As specified in Time.GetString()
GetWeekString(basic=0, truncation=0, ndp=0, zonePrecision=7, dp=', ', tDesignator='T')

Formats this TimePoint using week form, for example 1969-W29-7T20:17:40

basic
True/False, selects basic form, e.g., 1969W297T201740. Default is False
truncation
One of the Truncation constants used to select truncated forms of the date. For example, if you specify Truncation.Year you’ll get -W297T20-17-40. Default is NoTruncation. Note that week format only supports century, decade, year and week truncated forms, the time component cannot be truncated.
ndp, dp and zonePrecision
As specified in Time.GetString()
classmethod FromUnixTime(unixTime)

Constructs a TimePoint from unixTime, the number of seconds since the time origin. The resulting time has no zone.

This method uses python’s gmtime(0) to obtain the Unix origin time.

get_unixtime()

Returns a unix time value representing this time point.

classmethod FromNow()

Constructs a TimePoint from the current local date and time.

classmethod FromNowUTC()

Constructs a TimePoint from the current UTC date and time.

Complete()

Returns True if this TimePoint has a complete representation, i.e., does not use one of the reduced precision forms.

(Whether or not a TimePoint is complete refers only to the precision of the time value, it says nothing about the presence or absence of a time zone offset.)

GetPrecision()

Returns one of the Precision constants representing the precision of this TimePoint.

WithPrecision()

Constructs a TimePoint instance from an existing TimePoint but with the precision specified by precision. For more details see Time.WithPrecision()

class pyslet.iso8601.Duration(value=None)

A class for representing ISO durations

2.10.1. Supporting Constants

class pyslet.iso8601.Truncation

Defines constants to use when formatting to truncated forms.

No = 0

constant for no truncation

Year = 3

constant for truncating to year

Month = 4

constant for truncating to month

Week = 5

constant for truncating to week

Hour = 6

constant for truncating to hour

class pyslet.iso8601.Precision

Defines constants for representing reduced precision.

Year = 2

constant for year precision

Month = 3

constant for month precision

Week = 4

constant for week precision

Hour = 5

constant for hour precision

2.10.2. Utility Functions

pyslet.iso8601.LeapYear(year)

LeapYear returns True if year is a leap year and False otherwise.

Note that leap years famously fall on all years that divide by 4 except those that divide by 100 but including those that divide by 400.

pyslet.iso8601.DayOfWeek(year, month, day)

DayOfWeek returns the day of week 1-7, 1 being Monday for the given year, month and day

pyslet.iso8601.WeekCount(year)

Week count returns the number of calendar weeks in a year. Most years have 52 weeks of course, but if the year begins on a Thursday or a leap year begins on a Wednesday then it has 53.