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)
- 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.
- Offset(centuries=0, years=0, months=0, weeks=0, days=0)¶
Constructs a Date from the current date + a given offset
- 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.
- 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 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.)
- 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¶
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.