n6sdk.datetime_helpers

class n6sdk.datetime_helpers.FixedOffsetTimezone(offset)

Bases: datetime.tzinfo

TZ-info to represent fixed offset in minutes east from UTC.

The source code of the class has been copied from http://docs.python.org/2.7/library/datetime.html#tzinfo-objects, then adjusted, enriched and documented.

>>> tz = FixedOffsetTimezone(180)
>>> tz
FixedOffsetTimezone(180)

>>> import copy
>>> tz is copy.copy(tz)
True
>>> tz is copy.deepcopy(tz)
True

>>> dt = datetime.datetime(2014, 5, 31, 1, 2, 3, tzinfo=tz)
>>> dt.utcoffset()
datetime.timedelta(0, 10800)
>>> dt.dst()
datetime.timedelta(0)
>>> dt.tzname()
'<UTC Offset: +180>'
>>> dt.astimezone(FixedOffsetTimezone(-60))
datetime.datetime(2014, 5, 30, 21, 2, 3, tzinfo=FixedOffsetTimezone(-60))

dst(dt)

tzname(dt)

utcoffset(dt)

n6sdk.datetime_helpers.date_by_isoweekday(isoyear, isoweek, isoweekday)

Returns:

An equivalent datetime.date instance (see: http://en.wikipedia.org/wiki/ISO_week_date).

n6sdk.datetime_helpers.date_by_ordinalday(year, ordinalday)

Returns:

An equivalent datetime.date instance.

n6sdk.datetime_helpers.datetime_to_utc_timestamp(dt)

Convert a datetime.datetime to a UTC timestamp.

Args:

dt: A datetime.datetime instance (naive or TZ-aware).

Returns:

The equivalent timestamp as a float number.

>>> naive_dt = datetime.datetime(2013, 6, 6, 12, 13, 57, 251211)
>>> t = datetime_to_utc_timestamp(naive_dt)
>>> t
1370520837.251211
>>> datetime.datetime.utcfromtimestamp(t)
datetime.datetime(2013, 6, 6, 12, 13, 57, 251211)

>>> tzinfo = FixedOffsetTimezone(120)
>>> tz_aware_dt = datetime.datetime(2013, 6, 6, 14, 13, 57, 251211,
...                                 tzinfo=tzinfo)
>>> t2 = datetime_to_utc_timestamp(tz_aware_dt)
>>> t2 == t
True
>>> utc_naive_dt = datetime.datetime.utcfromtimestamp(t2)
>>> utc_tzinfo = FixedOffsetTimezone(0)  # just UTC
>>> utc_tz_aware_dt = utc_naive_dt.replace(tzinfo=utc_tzinfo)
>>> utc_tz_aware_dt.hour
12
>>> tz_aware_dt.hour
14
>>> utc_tz_aware_dt == tz_aware_dt
True

n6sdk.datetime_helpers.datetime_utc_normalize(dt)

Normalize a datetime.datetime to a naive UTC one.

Args:

dt: A datetime.datetime instance (naive or TZ-aware).

Returns:

An equivalent datetime.datetime instance (a naive one).

>>> naive_dt = datetime.datetime(2013, 6, 6, 12, 13, 57, 251211)
>>> datetime_utc_normalize(naive_dt)
datetime.datetime(2013, 6, 6, 12, 13, 57, 251211)

>>> tzinfo = FixedOffsetTimezone(120)
>>> tz_aware_dt = datetime.datetime(2013, 6, 6, 14, 13, 57, 251211,
...                                 tzinfo=tzinfo)
>>> datetime_utc_normalize(tz_aware_dt)
datetime.datetime(2013, 6, 6, 12, 13, 57, 251211)

n6sdk.datetime_helpers.is_datetime_format_normalized(s)

>>> is_datetime_format_normalized('2013-06-13 10:02:00')
True
>>> is_datetime_format_normalized('2013-06-13 10:02:00.123400')
True

>>> is_datetime_format_normalized('2013-06-13 10:02')
False
>>> is_datetime_format_normalized('2013-06-13 10:02:00.000000')
False
>>> is_datetime_format_normalized('2013-06-13 10:02:00.1234')
False
>>> is_datetime_format_normalized('2013-06-13 10:02:00.12345678')
False
>>> is_datetime_format_normalized('2013-06-13T10:02:00')
False
>>> is_datetime_format_normalized('2013-06-13 10:02:00Z')
False

n6sdk.datetime_helpers.parse_iso_date(s, prestrip=True)

Parse ISO-8601-formatted date.

Args:

s: ISO-8601-formatted date as a string.

Kwargs:

prestrip (default: True):

Whether the strip() method should be called on the input string before performing the actual processing.

Returns:

A datetime.date instance.

Raises:

ValueError for invalid input.

Intentional limitation: specified date must include unambiguous day specification (inputs such as '2013-05' or '2013' are not supported).

>>> parse_iso_date('2013-06-12')
datetime.date(2013, 6, 12)

>>> parse_iso_date('99991231')
datetime.date(9999, 12, 31)

>>> parse_iso_date('2013-W24-3')
datetime.date(2013, 6, 12)
>>> datetime.date(2013, 6, 12).isocalendar()    # checking this was OK...
(2013, 24, 3)

>>> parse_iso_date('2013-W01-1')
datetime.date(2012, 12, 31)
>>> datetime.date(2012, 12, 31).isocalendar()   # checking this was OK...
(2013, 1, 1)

>>> parse_iso_date('2011-W52-7')
datetime.date(2012, 1, 1)
>>> datetime.date(2012, 1, 1).isocalendar()     # checking this was OK...
(2011, 52, 7)

>>> parse_iso_date('2013-001')
datetime.date(2013, 1, 1)
>>> parse_iso_date('2013-365')
datetime.date(2013, 12, 31)
>>> parse_iso_date('2012-366')   # 2012 was a leap year
datetime.date(2012, 12, 31)

>>> parse_iso_date('0000-01-01')     
Traceback (most recent call last):
  ...
ValueError: ...
>>> parse_iso_date('13-01-01')       
Traceback (most recent call last):
  ...
ValueError: ...
>>> parse_iso_date('01-01-2013')     
Traceback (most recent call last):
  ...
ValueError: ...
>>> parse_iso_date('2013-6-01')      
Traceback (most recent call last):
  ...
ValueError: ...
>>> parse_iso_date('2013-02-31')     
Traceback (most recent call last):
  ...
ValueError: ...
>>> parse_iso_date('2013-W54-1')     
Traceback (most recent call last):
  ...
ValueError: ...
>>> parse_iso_date('2013-W22-8')     
Traceback (most recent call last):
  ...
ValueError: ...
>>> parse_iso_date('2013-W1-1')      
Traceback (most recent call last):
  ...
ValueError: ...
>>> parse_iso_date('2013-W01-01')    
Traceback (most recent call last):
  ...
ValueError: ...
>>> parse_iso_date('2013-000')       
Traceback (most recent call last):
  ...
ValueError: ...
>>> parse_iso_date('2013-366')       
Traceback (most recent call last):
  ...
ValueError: ...
>>> parse_iso_date('2013-1')         
Traceback (most recent call last):
  ...
ValueError: ...

n6sdk.datetime_helpers.parse_iso_datetime(s, prestrip=True)

Parse ISO-8601-formatted combined date and time.

Args:

s: ISO-8601-formatted combined date and time – as a string.

Kwargs:

prestrip (default: True):

Whether the strip() method should be called on the input string before performing the actual processing.

Returns:

A datetime.datetime instance (a TZ-aware one if the input does include time zone information, otherwise a naive one).

Raises:

exceptions.ValueError for invalid input.

For notes about some limitations – see parse_iso_date() and parse_iso_time().

n6sdk.datetime_helpers.parse_iso_datetime_to_utc(s, prestrip=True)

Parse ISO-8601-formatted combined date and time, and normalize it to UTC.

Args:

s: ISO-8601-formatted combined date and time – as a string.

Kwargs:

prestrip (default: True):

Whether the strip() method should be called on the input string before performing the actual processing.

Returns:

A datetime.datetime instance (a naive one, normalized to UTC).

Raises:

exceptions.ValueError for invalid input.

This function processes input by calling parse_iso_datetime() and datetime_utc_normalize().

>>> parse_iso_datetime_to_utc('2013-06-13T10:02Z')
datetime.datetime(2013, 6, 13, 10, 2)

>>> parse_iso_datetime_to_utc('2013-06-13 10:02')
datetime.datetime(2013, 6, 13, 10, 2)

>>> parse_iso_datetime_to_utc('2013-06-13 10:02+02:00')
datetime.datetime(2013, 6, 13, 8, 2)

>>> parse_iso_datetime_to_utc('2013-06-13T22:02:04.1234-07:00')
datetime.datetime(2013, 6, 14, 5, 2, 4, 123400)

>>> parse_iso_datetime_to_utc('2013-06-13 10:02:04.123456789Z')
datetime.datetime(2013, 6, 13, 10, 2, 4, 123456)

>>> parse_iso_datetime_to_utc('  2013-06-13T10:02Z          ')
datetime.datetime(2013, 6, 13, 10, 2)

>>> parse_iso_datetime_to_utc('  2013-06-13T10:02Z          ', prestrip=False)
... 
Traceback (most recent call last):
...
ValueError: ...

n6sdk.datetime_helpers.parse_iso_time(s, prestrip=True)

Parse ISO-8601-formatted time.

Args:

s: ISO-8601-formatted time as a string.

Kwargs:

prestrip (default: True):

Whether the strip() method should be called on the input string before performing the actual processing.

Returns:

A datetime.time instance (a TZ-aware one if the input does include time zone information, otherwise a naive one).

Raises:

exceptions.ValueError for invalid input.

Intentional limitation: specified time must include at least hour and minute. Second, microsecond and timezone information are optional.

ISO-8601-enabled “leap second” (60) is accepted but silently converted to 59 seconds + 999999 microseconds.

The optional fractional-part-of-second part can be specified with bigger or smaller precision – it will always be transformed to microseconds.

n6sdk.datetime_helpers.parse_python_formatted_datetime(s)

A limited version of parse_iso_datetime(): accepts only a string in the format: %Y-%m-%d %H:%M:%S or %Y-%m-%d %H:%M:%S.%f in terms of datetime.datetime.strptime().