API Reference#

zulu.now()[source]#: Alias to Zulu.now().

zulu.create(year=1970, month=1, day=1, hour=0, minute=0, second=0, microsecond=0, tzinfo=None, *, fold=0)[source]#

Factory function to create a new Zulu datetime using the same arguments as the class.

Parameters:

year (int|dict) – Date year 1 <= year <= 9999 or dict containing keys corresponding to initialization parameter names.
month (int) – Date month 1 <= month <= 12.
day (int) – Date day 1 <= day <= number of days in the given month and year
hour (int, optional) – Time hour 0 <= hour < 24. Defaults to 0.
minute (int, optional) – Time minute 0 <= minute < 60. Defaults to 0.
second (int, optional) – Time second 0 <= second < 60. Defaults to 0.
microsecond (int, optional) – Time microsecond 0 <= microsecond < 1000000. Defaults to 0.
tzinfo (None|str|tzinfo, optional) – Timezone information as either a str or tzinfo subclass. If value is a str, it will be converted to a dateutil.tz timezone. If value is None, the datetime values given are assumed to in UTC. Defaults to None.

zulu.parse(obj, formats=None, default_tz=None)[source]#

Return Zulu object parsed from obj.

Parameters:

obj (mixed) – Object to parse into a Zulu object.
formats (str|list, optional) – List of string formats to use when parsing. Defaults to ["ISO8601", "timestamp"].
default_tz (None|str|tzinfo, optional) – Default timezone to use when parsed datetime object does not contain a timezone. Defaults to UTC.

Returns:

Zulu

zulu.range(frame, start, end)[source]#

Yield ranges of Zulu instances from start to end in steps of time frame, frame.

Parameters:

frame (str) – A time frame (e.g. year, month, day, minute, etc).
start (datetime) – The starting datetime.
end (datetime) – The ending datetime.

Yields:

Zulu – Datetime values ranging from the given start and end datetimes.

zulu.span_range(frame, start, end)[source]#

Return a range of time spans from start to end in steps of time frame, frame.

Parameters:

frame (str) – A time frame (e.g. year, month, day, minute, etc).
start (datetime) – The starting datetime.
end (datetime) – The ending datetime.

Yields:

tuple – 2-element tuple of Zulu time spans

zulu.parse_delta(obj)[source]#

Return Delta object parsed from obj.

Parameters:: obj (str|number|timedelta) – Object to parse into a Delta object.
Returns:: Delta

class zulu.Zulu(year=1970, month=1, day=1, hour=0, minute=0, second=0, microsecond=0, tzinfo=None, *, fold=0)[source]#

The Zulu class represents an immutable UTC datetime object. Any timezone information given to it during instantiation results in the datetime object being converted from that timezone to UTC. If timezone information is not given, then it’s assumed the datetime is a UTC value. All arithmetic is perform on the underlying UTC datetime object. Zulu has no concept of timezone shifting in this regard. Instead, localization occurs only when formatting a Zulu object as a string.

The Zulu class is a drop-in replacement for a native datetime object, but does not represent itself in any time zone other than UTC.

Parameters:

year (int|dict) – Date year 1 <= year <= 9999 or dict containing keys corresponding to initialization parameter names.
month (int) – Date month 1 <= month <= 12.
day (int) – Date day 1 <= day <= number of days in the given month and year
hour (int, optional) – Time hour 0 <= hour < 24. Defaults to 0.
minute (int, optional) – Time minute 0 <= minute < 60. Defaults to 0.
second (int, optional) – Time second 0 <= second < 60. Defaults to 0.
microsecond (int, optional) – Time microsecond 0 <= microsecond < 1000000. Defaults to 0.
tzinfo (None|str|tzinfo, optional) – Timezone information as either a str or tzinfo subclass. If value is a str, it will be converted to a dateutil.tz timezone. If value is None, the datetime values given are assumed to in UTC. Defaults to None.

add(other=None, years=0, months=0, weeks=0, days=0, hours=0, minutes=0, seconds=0, microseconds=0)[source]#

Add time using a timedelta created from the supplied arguments and return a new Zulu instance. The first argument can be a :class:`timedelta or dateutil.relativedelta object in which case all other arguments are ignored and the object is added to this datetime.

Parameters:

other (timedelta|relativedelta, optional) – A timedelta or dateutil.relativedelta object to add.
years (int) – Years to add.
months (int) – Months to add.
weeks (int) – Weeks to add.
days (int) – Days to add.
hours (int) – Hours to add.
minutes (int) – Minutes to add.
seconds (int) – Seconds to add.
microseconds (int) – Microseconds to add.

Returns:

Zulu

astimezone(tz='local')[source]#

Return datetime shifted to timezone tz.

Note

This returns a native datetime object.

Parameters:: tz (None|str|tzinfo, optional) – Timezone to shift to. Defaults to “local” which uses the local timezone.
Returns:: datetime

classmethod combine(date, time)[source]#

Return Zulu object by combining the date part from date and the time part from time.

Parameters:

date (mixed) – Either a Zulu, datetime.date, or datetime.datetime object to use as the date part.
date – Either a Zulu or datetime.time object to use as the time part.

Returns:

Zulu

copy()[source]#

Return a new :class`Zulu` instance with the same datetime value.

Returns:: Zulu

ctime()#: Return ctime() style string.

date()#: Return date object with same year, month and day.

property datetime#

The Zulu object as a native datetime.

Note

This returns a native datetime object.

Returns:: datetime

datetimetuple()[source]#

Return datetime tuple containing (year, month, day, hour, minute, second, microsecond, tzinfo).

Returns:: tuple

datetuple()[source]#

Return date tuple containing (year, month, day).

Returns:: tuple

days_in_month()[source]#

Return the number of days in the month.

Returns:: int

dst()#: Return self.tzinfo.dst(self).

end_of(frame, count=1)[source]#

Return the end of a given time frame for this datetime.

Parameters:

frame (str) – A time frame (e.g. year, month, day, minute, etc).
count (int) – Number of frames to span.

Returns:

Zulu

end_of_century(count=1)[source]#

Return a new Zulu set to the end of the century of this datetime.

Parameters:: count (int) – Number of frames to span.
Returns:: Zulu

end_of_day(count=1)[source]#

Return a new Zulu set to the end of the day of this datetime.

Parameters:: count (int) – Number of frames to span.
Returns:: Zulu

end_of_decade(count=1)[source]#

Return a new Zulu set to the end of the decade of this datetime.

Parameters:: count (int) – Number of frames to span.
Returns:: Zulu

end_of_hour(count=1)[source]#

Return a new Zulu set to the end of the hour of this datetime.

Parameters:: count (int) – Number of frames to span.
Returns:: Zulu

end_of_minute(count=1)[source]#

Return a new Zulu set to the end of the minute of this datetime.

Parameters:: count (int) – Number of frames to span.
Returns:: Zulu

end_of_month(count=1)[source]#

Return a new Zulu set to the end of the month of this datetime.

Parameters:: count (int) – Number of frames to span.
Returns:: Zulu

end_of_second(count=1)[source]#

Return a new Zulu set to the end of the second of this datetime.

Parameters:: count (int) – Number of frames to span.
Returns:: Zulu

end_of_week(count=1)[source]#

Return a new Zulu set to the end of the week of this datetime. uses ISO8601 definition of week: week start is monday.

Parameters:: count (int) – Number of frames to span.
Returns:: Zulu

end_of_year(count=1)[source]#

Return a new Zulu set to the end of the year of this datetime.

Parameters:: count (int) – Number of frames to span.
Returns:: Zulu

format(format=None, tz=None, locale='en_US_POSIX')[source]#

Return datetime as a string using the format string format while optionally converting to timezone tz first.

Note

A Locale object or string identifier can be provided to display the object in that particular locale but only when using date pattern tokens. Using a locale other than the current system locale is not supported for strftime tokens.

Parameters:

format (str) – Format to return string in. If None, ISO 8601 format is used. Defaults to None.
tz (None|str|tzinfo, optional) – Timezone to convert to before formatting. Defaults to None.
locale (str|Locale, optional) – A Locale object or locale identifier. Defaults to system default.

Returns:

str

classmethod fromdatetime(dt)[source]#

Return Zulu object from a native datetime object.

Returns:: Zulu

classmethod fromgmtime(struct)[source]#

Return Zulu object from a tuple like that returned by time.gmtime that represents a UTC datetime.

Parameters:: struct (tuple) – Tuple like that returned by time.gmtime.
Returns:: Zulu

fromisocalendar()#

int, int, int -> Construct a date from the ISO year, week number and weekday.

This is the inverse of the date.isocalendar() function

fromisoformat()#: string -> datetime from a string in most ISO 8601 formats

classmethod fromlocaltime(struct)[source]#

Return Zulu object from a tuple like that returned by time.localtime that represents a local datetime.

Parameters:: struct (tuple) – Tuple like that returned by time.localtime.
Returns:: Zulu

classmethod fromordinal(ordinal)[source]#

Return Zulu object from a proleptic Gregorian ordinal, where January 1 of year 1 has ordinal 1.

Parameters:: ordinal (int) – A proleptic Gregorian ordinal.
Returns:: Zulu

classmethod fromtimestamp(timestamp, tz=tzutc())[source]#

Return Zulu object from a POSIX timestamp.

Parameters:

timestamp (int|float) – POSIX timestamp such as is returned by time.time().
tz (UTC) – This argument is ignored and always set to UTC. It is present only for datetime class compatibility.

Returns:

Zulu

is_after(other)[source]#

Return whether this datetime is after other.

Parameters:: other (datetime) – Other datetime to compare.
Returns:: bool

is_before(other)[source]#

Return whether this datetime is before other.

Parameters:: other (datetime) – Other datetime to compare.
Returns:: bool

is_between(start, end)[source]#

Return whether this datetime is between start and end inclusively.

Parameters:

start (datetime) – Starting datetime to compare.
end (datetime) – Ending datetime to compare.

Returns:

bool

is_leap_year()[source]#

Return whether this datetime’s year is a leap year.

Returns:: bool

is_on_or_after(other)[source]#

Return whether this datetime is after or on other.

Parameters:: other (datetime) – Other datetime to compare.
Returns:: bool

is_on_or_before(other)[source]#

Return whether this datetime is before or on other.

Parameters:: other (datetime) – Other datetime to compare.
Returns:: bool

isocalendar()#: Return a named tuple containing ISO year, week number, and weekday.

isoformat()#: [sep] -> string in ISO 8601 format, YYYY-MM-DDT[HH[:MM[:SS[.mmm[uuu]]]]][+HH:MM]. sep is used to separate the year from the time, and defaults to ‘T’. The optional argument timespec specifies the number of additional terms of the time to include. Valid options are ‘auto’, ‘hours’, ‘minutes’, ‘seconds’, ‘milliseconds’ and ‘microseconds’.

isoweekday()#: Return the day of the week represented by the date. Monday == 1 … Sunday == 7

property naive#

The datetime object as a naive datetime (tzinfo=None).

Note

This returns a native datetime object.

Returns:: Zulu

classmethod now()[source]#

Return the current UTC date and time as Zulu object.

Returns:: Zulu

classmethod parse(obj, formats=None, default_tz=None)[source]#

Return Zulu object parsed from obj.

Parameters:

obj (mixed) – Object to parse into a Zulu object.
formats (str|list, optional) – List of string formats to use when parsing. Defaults to ["ISO8601", "timestamp"].
default_tz (None|str|tzinfo, optional) – Default timezone to use when parsed datetime object does not contain a timezone. Defaults to UTC.

Returns:

Zulu

classmethod range(frame, start, end)[source]#

Yield ranges of Zulu instances from start to end in steps of time frame, frame.

Parameters:

frame (str) – A time frame (e.g. year, month, day, minute, etc).
start (datetime) – The starting datetime.
end (datetime) – The ending datetime.

Yields:

Zulu – Datetime values ranging from the given start and end datetimes.

replace(year=None, month=None, day=None, hour=None, minute=None, second=None, microsecond=None, tzinfo=None, *, fold=None)[source]#

Replace datetime attributes and return a new Zulu instance.

Parameters:

year (None|int, optional) – Year to replace.
month (None|int, optional) – Month to replace.
week (None|int, optional) – Week to replace.
day (None|int, optional) – Day to replace.
hour (None|int, optional) – Hour to replace.
minute (None|int, optional) – Minute to replace.
second (None|int, optional) – Second to replace.
microsecond (None|int, optional) – Microsecond to replace.
tzinfo (None|str|tzinfo, optional) – Timezone to replace.
fold (None|int, optional) – Fold to replace.

Returns:

Zulu

shift(other=None, years=0, months=0, weeks=0, days=0, hours=0, minutes=0, seconds=0, microseconds=0)[source]#

Shift datetime forward or backward using a timedelta created from the supplied arguments and return a new Zulu instance.

Parameters:

other (timedelta|relativedelta, optional) – A timedelta or dateutil.relativedelta object to add.
years (int) – Years to shift.
months (int) – Months to shift.
weeks (int) – Weeks to shift.
days (int) – Days to shift.
hours (int) – Hours to shift.
minutes (int) – Minutes to shift.
seconds (int) – Seconds to shift.
microseconds (int) – Microseconds to shift.

Returns:

Zulu

span(frame, count=1)[source]#

Returns two new Zulu objects corresponding to the time span between this object and the given time frame.

Parameters:

frame (str) – A time frame (e.g. year, month, day, minute, etc).
count (int) – Number of frames to span.

Returns:

(start_of_frame, end_of_frame)

Return type:

tuple

classmethod span_range(frame, start, end)[source]#

Return a range of time spans from start to end in steps of time frame, frame.

Parameters:

frame (str) – A time frame (e.g. year, month, day, minute, etc).
start (datetime) – The starting datetime.
end (datetime) – The ending datetime.

Yields:

tuple – 2-element tuple of Zulu time spans

start_of(frame)[source]#

Return the start of the given time frame for this datetime.

Parameters:: frame (str) – A time frame (e.g. year, month, day, minute, etc).
Returns:: Zulu

start_of_century()[source]#

Return a new Zulu set to the start of the century of this datetime.

Returns:: Zulu

start_of_day()[source]#

Return a new Zulu set to the start of the day of this datetime.

Returns:: Zulu

start_of_decade()[source]#

Return a new Zulu set to the start of the decade of this datetime.

Returns:: Zulu

start_of_hour()[source]#

Return a new Zulu set to the start of the hour of this datetime.

Returns:: Zulu

start_of_minute()[source]#

Return a new Zulu set to the start of the minute of this datetime.

Returns:: Zulu

start_of_month()[source]#

Return a new Zulu set to the start of the month of this datetime.

Returns:: Zulu

start_of_second()[source]#

Return a new Zulu set to the start of the second of this datetime.

Returns:: Zulu

start_of_week()[source]#

Return a new Zulu set to the start of the week of this datetime. uses ISO8601 definition of week: week start is monday.

Returns:: Zulu

start_of_year()[source]#

Return a new Zulu set to the start of the year of this datetime.

Returns:: Zulu

strftime()#: format -> strftime() style string.

strptime()#: string, format -> new datetime parsed from a string (like time.strptime()).

subtract(other=None, years=0, months=0, weeks=0, days=0, hours=0, minutes=0, seconds=0, microseconds=0)[source]#

Subtract time using a timedelta created from the supplied arguments and return a new Zulu instance. The first argument can be a Zulu, datetime, timedelta, or dateutil.relativedelta object in which case all other arguments are ignored and the object is subtracted from this datetime.

Parameters:

other (datetime|timedelta|relativedelta, optional) – A datetime, timedelta, or dateutil.relativedelta object to subtract.
years (int) – Years to subtract.
months (int) – Months to subtract.
weeks (int) – Weeks to subtract.
days (int) – Days to subtract.
hours (int) – Hours to subtract.
minutes (int) – Minutes to subtract.
seconds (int) – Seconds to subtract.
microseconds (int) – Microseconds to subtract.

Returns:

if subtracting timedelta or timedelta. timedelta: if subtracting a datetime or Zulu.

Return type:

Zulu

time()#: Return time object with same time but with tzinfo=None.

time_from(dt, format='long', granularity='second', threshold=0.85, add_direction=True, locale=None)[source]#

Return “time ago” difference between this datetime and another as a humanized string.

Parameters:

dt (datetime) – A datetime object.
format (str, optional) – Can be one of “long”, “short”, or “narrow”. Defaults to “long”.
granularity (str, optional) – The smallest unit that should be displayed. The value can be one of “year”, “month”, “week”, “day”, “hour”, “minute” or “second”. Defaults to “second”.
threshold (float, optional) – Factor that determines at which point the presentation switches to the next higher unit. Defaults to 0.85.
add_direction (bool, optional) – If True the return value will include directional information (e.g. ‘1 hour ago’, ‘in 1 hour’). Defaults to False.
locale (str|Locale, optional) – A Locale object or locale identifier. Defaults to system default.

Returns:

str

time_from_now(format='long', granularity='second', threshold=0.85, add_direction=True, locale=None)[source]#

Return “time ago” difference between this datetime and now as a humanized string.

Parameters:

format (str, optional) – Can be one of “long”, “short”, or “narrow”. Defaults to “long”.
granularity (str, optional) – The smallest unit that should be displayed. The value can be one of “year”, “month”, “week”, “day”, “hour”, “minute” or “second”. Defaults to “second”.
threshold (float, optional) – Factor that determines at which point the presentation switches to the next higher unit. Defaults to 0.85.
add_direction (bool, optional) – If True the return value will include directional information (e.g. ‘1 hour ago’, ‘in 1 hour’). Defaults to False.
locale (str|Locale, optional) – A Locale object or locale identifier. Defaults to system default.

Returns:

str

time_to(dt, format='long', granularity='second', threshold=0.85, add_direction=True, locale=None)[source]#

Return “time to” difference between another datetime and this one as a humanized string.

Parameters:

dt (datetime) – A datetime object.
format (str, optional) – Can be one of “long”, “short”, or “narrow”. Defaults to “long”.
granularity (str, optional) – The smallest unit that should be displayed. The value can be one of “year”, “month”, “week”, “day”, “hour”, “minute” or “second”. Defaults to “second”.
threshold (float, optional) – Factor that determines at which point the presentation switches to the next higher unit. Defaults to 0.85.
add_direction (bool, optional) – If True the return value will include directional information (e.g. ‘1 hour ago’, ‘in 1 hour’). Defaults to False.
locale (str|Locale, optional) – A Locale object or locale identifier. Defaults to system default.

Returns:

str

time_to_now(format='long', granularity='second', threshold=0.85, add_direction=True, locale=None)[source]#

Return “time to” difference between now and this datetime as a humanized string.

Parameters:

format (str, optional) – Can be one of “long”, “short”, or “narrow”. Defaults to “long”.
granularity (str, optional) – The smallest unit that should be displayed. The value can be one of “year”, “month”, “week”, “day”, “hour”, “minute” or “second”. Defaults to “second”.
threshold (float, optional) – Factor that determines at which point the presentation switches to the next higher unit. Defaults to 0.85.
add_direction (bool, optional) – If True the return value will include directional information (e.g. ‘1 hour ago’, ‘in 1 hour’). Defaults to False.
locale (str|Locale, optional) – A Locale object or locale identifier. Defaults to system default.

Returns:

str

timestamp()[source]#

Return the POSIX timestamp.

Returns:: float

timetuple()#: Return time tuple, compatible with time.localtime().

timetz()#: Return time object with same time and tzinfo.

today()#: Current date or datetime: same as self.__class__.fromtimestamp(time.time()).

toordinal()#: Return proleptic Gregorian ordinal. January 1 of year 1 is day 1.

tzname()#: Return self.tzinfo.tzname(self).

classmethod utcfromtimestamp(timestamp)[source]#

Return Zulu object from a POSIX timestamp.

Parameters:: timestamp (int|float) – POSIX timestamp such as is returned by time.time().
Returns:: Zulu

classmethod utcnow()[source]#

Return the current UTC date and time as Zulu object.

Returns:: Zulu

utcoffset()#: Return self.tzinfo.utcoffset(self).

utctimetuple()#: Return UTC time tuple, compatible with time.localtime().

weekday()#: Return the day of the week represented by the date. Monday == 0 … Sunday == 6

class zulu.Delta[source]#

An extension of datetime.timedelta that provides additional functionality.

days#: Number of days.

format(format='long', granularity='second', threshold=0.85, add_direction=False, locale=None)[source]#

Return timedelta as a formatted string.

Parameters:

format (str, optional) – Can be one of “long”, “short”, or “narrow”. Defaults to “long”.
granularity (str, optional) – The smallest unit that should be displayed. The value can be one of “year”, “month”, “week”, “day”, “hour”, “minute” or “second”. Defaults to “second”.
threshold (float, optional) – Factor that determines at which point the presentation switches to the next higher unit. Defaults to 0.85.
add_direction (bool, optional) – If True the return value will include directional information (e.g. ‘1 hour ago’, ‘in 1 hour’). Defaults to False.
locale (str|Locale, optional) – A Locale object or locale identifier. Defaults to system default.

Returns:

str

classmethod fromtimedelta(delta)[source]#

Return Delta object from a native timedelta object.

Returns:: Delta

microseconds#: Number of microseconds (>= 0 and less than 1 second).

classmethod parse(obj)[source]#

Return Delta object parsed from obj.

Parameters:: obj (str|number|timedelta) – Object to parse into a Delta object.
Returns:: Delta

seconds#: Number of seconds (>= 0 and less than 1 day).

total_seconds()#: Total seconds in the duration.

class zulu.ParseError[source]#: Exception raised when an object cannot be parsed as a datetime.