Temporal Data Types¶

Temporal data types are implemented by the neo4j.time module.

It provides a set of types compliant with ISO-8601 and Cypher, which are similar to those found in the built-in datetime module. Sub-second values are measured to nanosecond precision and the types are compatible with pytz.

The table below shows the general mappings between Cypher and the temporal types provided by the driver.

In addition, the built-in temporal types can be passed as parameters and will be mapped appropriately.

Cypher	Python driver type	Python built-in type	`tzinfo`
Date	`neo4j.time.Date`	`datetime.date`
Time	`neo4j.time.Time`	`datetime.time`	`not None`
LocalTime	`neo4j.time.Time`	`datetime.time`	`None`
DateTime	`neo4j.time.DateTime`	`datetime.datetime`	`not None`
LocalDateTime	`neo4j.time.DateTime`	`datetime.datetime`	`None`
Duration	`neo4j.time.Duration`	`datetime.timedelta`

Sub-second values are measured to nanosecond precision and the types are compatible with pytz.

Note

Cypher has built-in support for handling temporal values, and the underlying database supports storing these temporal values as properties on nodes and relationships, see https://neo4j.com/docs/cypher-manual/current/syntax/temporal/

Constants¶

neo4j.time.MIN_YEAR = 1¶: The smallest year number allowed in a Date or DateTime object to be compatible with datetime.date and datetime.datetime.

neo4j.time.MAX_YEAR = 9999¶: The largest year number allowed in a Date or DateTime object to be compatible with datetime.date and datetime.datetime.

Date¶

class neo4j.time.Date(year, month, day)¶

Idealized date representation.

A Date object represents a date (year, month, and day) in the proleptic Gregorian Calendar.

Years between 0001 and 9999 are supported, with additional support for the “zero date” used in some contexts.

Each date is based on a proleptic Gregorian ordinal, which models 1 Jan 0001 as day 1 and counts each subsequent day up to, and including, 31 Dec 9999. The standard year, month and day value of each date is also available.

Internally, the day of the month is always stored as-is, with the exception of the last three days of that month. These are always stored as -1, -2 and -3 (counting from the last day). This system allows some temporal arithmetic (particularly adding or subtracting months) to produce a more desirable outcome than would otherwise be produced. Externally, the day number is always the same as would be written on a calendar.

Parameters:

year (int) – the year. Minimum MIN_YEAR (0001), maximum MAX_YEAR (9999).
month (int) – the month. Minimum 1, maximum 12.
day (int) – the day. Minimum 1, maximum Date.days_in_month(year, month).

A zero date can also be acquired by passing all zeroes to the neo4j.time.Date constructor or by using the ZeroDate constant.

Class methods¶

classmethod Date.today(tz=None)¶

Get the current date.

Parameters:: tz (datetime.tzinfo or None) – timezone or None to get the local Date.
Return type:: Date
Raises:: OverflowError – if the timestamp is out of the range of values supported by the platform C localtime() function. It’s common for this to be restricted to years from 1970 through 2038.

classmethod Date.utc_today()¶

Get the current date as UTC local date.

Return type:: Date

classmethod Date.from_timestamp(timestamp, tz=None)¶

Date from a time stamp (seconds since unix epoch).

Parameters:

timestamp (float) – the unix timestamp (seconds since unix epoch).
tz (datetime.tzinfo or None) – timezone. Set to None to create a local Date.

Return type:

Date

Raises:

OverflowError – if the timestamp is out of the range of values supported by the platform C localtime() function. It’s common for this to be restricted to years from 1970 through 2038.

classmethod Date.utc_from_timestamp(timestamp)¶

Date from a time stamp (seconds since unix epoch).

Returns the Date as local date Date in UTC.

Return type:: Date

classmethod Date.from_ordinal(ordinal)¶

The Date that corresponds to the proleptic Gregorian ordinal.

0001-01-01 has ordinal 1 and 9999-12-31 has ordinal 3,652,059. Values outside of this range trigger a ValueError. The corresponding instance method for the reverse date-to-ordinal transformation is to_ordinal(). The ordinal 0 has a special semantic and will return ZeroDate.

Return type:: Date
Raises:: ValueError – if the ordinal is outside the range [0, 3652059] (both values included).

classmethod Date.parse(s)¶

Parse a string to produce a Date.

Accepted formats:: ‘Y-M-D’

Parameters:: s (str) – the string to be parsed.
Return type:: Date
Raises:: ValueError – if the string could not be parsed.

classmethod Date.from_native(d)¶

Convert from a native Python datetime.date value.

Parameters:: d (datetime.date) – the date to convert.
Return type:: Date

classmethod Date.from_clock_time(clock_time, epoch)¶

Convert from a ClockTime relative to a given epoch.

Parameters:

clock_time (ClockTime or (float, int)) – the clock time as ClockTime or as tuple of (seconds, nanoseconds)
epoch (DateTime) – the epoch to which clock_time is relative

Return type:

Date

classmethod Date.is_leap_year(year)¶

Indicates whether or not year is a leap year.

Parameters:: year (int) – the year to look up
Return type:: bool
Raises:: ValueError – if year is out of range: MIN_YEAR <= year <= MAX_YEAR

classmethod Date.days_in_year(year)¶

Return the number of days in year.

Parameters:: year (int) – the year to look up
Return type:: int
Raises:: ValueError – if year is out of range: MIN_YEAR <= year <= MAX_YEAR

classmethod Date.days_in_month(year, month)¶

Return the number of days in month of year.

Parameters:

year (int) – the year to look up
month – the month to look up

Return type:

int

Raises:

ValueError – if year or month is out of range: MIN_YEAR <= year <= MAX_YEAR; 1 <= year <= 12

Class attributes¶

Date.min = neo4j.time.Date(1, 1, 1)¶: The earliest date value possible.

Date.max = neo4j.time.Date(9999, 12, 31)¶: The latest date value possible.

Date.resolution = (0, 1, 0, 0)¶: The minimum resolution supported.

Instance attributes¶

Date.year¶

The year of the date.

Type:: int

Date.month¶

The month of the date.

Type:: int

Date.day¶

The day of the date.

Type:: int

Date.year_month_day¶

3-tuple of (year, month, day) describing the date.

Return type:: (int, int, int)

Date.year_week_day¶

3-tuple of (year, week_of_year, day_of_week) describing the date.

day_of_week will be 1 for Monday and 7 for Sunday.

Return type:: (int, int, int)

Date.year_day¶

2-tuple of (year, day_of_the_year) describing the date.

This is the number of the day relative to the start of the year, with 1 Jan corresponding to 1.

Return type:: (int, int)

Operations¶

Date.__hash__()¶

Date.__eq__(other)¶: == comparison with Date or datetime.date.

Date.__ne__(other)¶: != comparison with Date or datetime.date.

Date.__lt__(other)¶: < comparison with Date or datetime.date.

Date.__gt__(other)¶: > comparison with Date or datetime.date.

Date.__le__(other)¶: <= comparison with Date or datetime.date.

Date.__ge__(other)¶: >= comparison with Date or datetime.date.

Date.__add__(other)¶

Add a Duration.

Return type:: Date
Raises:: ValueError – if the added duration has a time component.

Date.__sub__(other)¶

Subtract a Date or Duration.

Returns:: If a Date is subtracted, the time between the two dates is returned as Duration. If a Duration is subtracted, a new Date is returned.
Return type:: Date or Duration
Raises:: ValueError – if the added duration has a time component.

Instance methods¶

Date.replace(**kwargs)¶

Return a Date with one or more components replaced.

Keyword Arguments:

year (int): overwrite the year - default: self.year
month (int): overwrite the month - default: self.month
day (int): overwrite the day - default: self.day

Date.time_tuple()¶

Convert the date to time.struct_time.

Return type:: time.struct_time

Date.to_ordinal()¶

The date’s proleptic Gregorian ordinal.

The corresponding class method for the reverse ordinal-to-date transformation is Date.from_ordinal().

Return type:: int

Date.to_clock_time(epoch)¶

Convert the date to ClockTime relative to epoch.

Parameters:: epoch (Date) – the epoch to which the date is relative
Return type:: ClockTime

Date.to_native()¶

Convert to a native Python datetime.date value.

Return type:: datetime.date

Date.weekday()¶

The day of the week where Monday is 0 and Sunday is 6.

Return type:: int

Date.iso_weekday()¶

The day of the week where Monday is 1 and Sunday is 7.

Return type:: int

Date.iso_calendar()¶: Alias for year_week_day

Date.iso_format()¶

Return the Date as ISO formatted string.

Return type:: str

Date.__repr__()¶

Date.__str__()¶

Date.__format__(format_spec)¶

Special values¶

neo4j.time.ZeroDate = neo4j.time.ZeroDate¶: A neo4j.time.Date instance set to 0000-00-00. This has an ordinal value of 0.

Time¶

class neo4j.time.Time(hour=0, minute=0, second=0, nanosecond=0, tzinfo=None)¶

Time of day.

The Time class is a nanosecond-precision drop-in replacement for the standard library datetime.time class.

A high degree of API compatibility with the standard library classes is provided.

neo4j.time.Time objects introduce the concept of ticks. This is simply a count of the number of seconds since midnight, in many ways analogous to the neo4j.time.Date ordinal. ticks values can be fractional, with a minimum value of 0 and a maximum of 86399.999999999.

Local times are represented by Time with no tzinfo.

Note

Staring with version 5.0, ticks will change to be integers counting nanoseconds since midnight. Currently available as ticks_ns.

Parameters:

hour (int) – the hour of the time. Must be in range 0 <= hour < 24.
minute (int) – the minute of the time. Must be in range 0 <= minute < 60.
second (float) –
the second of the time. Here, a float is accepted to denote sub-second precision up to nanoseconds. Must be in range 0 <= second < 60.

Starting with version 5 0, this parameter will only accept int.
nanosecond (int) – the nanosecond .Must be in range 0 <= nanosecond < 999999999.
tzinfo (datetime.tzinfo or None) – timezone or None to get a local Time.

Raises:

ValueError – if one of the parameters is out of range.

Class methods¶

classmethod Time.now(tz=None)¶

Get the current time.

Parameters:: tz (datetime.tzinfo) – optional timezone
Return type:: Time
Raises:: OverflowError – if the timestamp is out of the range of values supported by the platform C localtime() function. It’s common for this to be restricted to years from 1970 through 2038.

classmethod Time.utc_now()¶

Get the current time as UTC local time.

Return type:: Time

classmethod Time.from_ticks(ticks, tz=None)¶

Create a time from legacy ticks (seconds since midnight).

Deprecated since version 4.4: Staring from 5.0, this method’s signature will be replaced with that of from_ticks_ns().

Parameters:

ticks (float) – seconds since midnight
tz (datetime.tzinfo) – optional timezone

Return type:

Time

Raises:

ValueError – if ticks is out of bounds (0 <= ticks < 86400)

classmethod Time.from_ticks_ns(ticks, tz=None)¶

Create a time from ticks (nanoseconds since midnight).

Parameters:

ticks (int) – nanoseconds since midnight
tz (datetime.tzinfo) – optional timezone

Return type:

Time

Raises:

ValueError – if ticks is out of bounds (0 <= ticks < 86400000000000)

classmethod Time.from_native(t)¶

Convert from a native Python datetime.time value.

Parameters:: t (datetime.time) – time to convert from
Return type:: Time

classmethod Time.from_clock_time(clock_time, epoch)¶

Convert from a ClockTime relative to a given epoch.

This method, in contrast to most others of this package, assumes days of exactly 24 hours.

Parameters:

clock_time (ClockTime or (float, int)) – the clock time as ClockTime or as tuple of (seconds, nanoseconds)
epoch (DateTime) – the epoch to which clock_time is relative

Return type:

Time

Class attributes¶

Time.min = neo4j.time.Time(0, 0, 0, 0)¶: The earliest time value possible.

Time.max = neo4j.time.Time(23, 59, 59, 999999999)¶: The latest time value possible.

Time.resolution = (0, 0, 0, 1)¶: The minimum resolution supported.

Instance attributes¶

Time.ticks¶

The total number of seconds since midnight.

Deprecated since version 4.4: will return ticks_ns starting with version 5.0.

Type:: float

Time.ticks_ns¶

The total number of nanoseconds since midnight.

Note

This will be removed in 5.0 and replace ticks.

Type:: int

Time.hour¶

The hours of the time.

Type:: int

Time.minute¶

The minutes of the time.

Type:: int

Time.second¶

The seconds of the time.

This contains seconds and nanoseconds of the time. int(:attr:.seconds`)` will yield the seconds without nanoseconds.

Type:: decimal.Decimal

Changed in version 4.4: The property’s type changed from float to decimal.Decimal to mitigate rounding issues.

Time.hour_minute_second¶

The time as a tuple of (hour, minute, second).

Type:: (int, int, decimal.Decimal)

Changed in version 4.4: Last element of the property changed from float to decimal.Decimal to mitigate rounding issues.

Time.hour_minute_second_nanosecond¶

The time as a tuple of (hour, minute, second, nanosecond).

Type:: (int, int, int, int)

Time.tzinfo¶

The timezone of this time.

Type:: datetime.tzinfo or None

Operations¶

Time.__hash__()¶

Time.__eq__(other)¶: == comparison with Time or datetime.time.

Time.__ne__(other)¶: != comparison with Time or datetime.time.

Time.__lt__(other)¶: < comparison with Time or datetime.time.

Time.__gt__(other)¶: > comparison with Time or datetime.time.

Time.__le__(other)¶: <= comparison with Time or datetime.time.

Time.__ge__(other)¶: >= comparison with Time or datetime.time.

Instance methods¶

Time.replace(**kwargs)¶

Return a Time with one or more components replaced.

Keyword Arguments:

hour (int): overwrite the hour - default: self.hour
minute (int): overwrite the minute - default: self.minute
second (int): overwrite the second - default: int(self.second)
nanosecond (int): overwrite the nanosecond - default: self.nanosecond
tzinfo (datetime.tzinfo or None): overwrite the timezone - default: self.tzinfo

Return type:

Time

Time.utc_offset()¶

Return the UTC offset of this time.

Returns:

None if this is a local time (tzinfo is None), else returns self.tzinfo.utcoffset(self).

Return type:

datetime.timedelta

Raises:

ValueError – if self.tzinfo.utcoffset(self) is not None and a timedelta with a magnitude greater equal 1 day or that is not a whole number of minutes.
TypeError – if self.tzinfo.utcoffset(self) does return anything but None or a datetime.timedelta.

Time.dst()¶

Get the daylight saving time adjustment (DST).

Returns:

None if this is a local time (tzinfo is None), else returns self.tzinfo.dst(self).

Return type:

datetime.timedelta

Raises:

ValueError – if self.tzinfo.dst(self) is not None and a timedelta with a magnitude greater equal 1 day or that is not a whole number of minutes.
TypeError – if self.tzinfo.dst(self) does return anything but None or a datetime.timedelta.

Time.tzname()¶

Get the name of the Time’s timezone.

Returns:: None if the time is local (i.e., has no timezone), else return self.tzinfo.tzname(self)
Return type:: str or None

Time.to_clock_time()¶

Convert to ClockTime.

Return type:: ClockTime

Time.to_native()¶

Convert to a native Python datetime.time value.

This conversion is lossy as the native time implementation only supports a resolution of microseconds instead of nanoseconds.

Return type:: datetime.time

Time.iso_format()¶

Return the Time as ISO formatted string.

Return type:: str

Time.__repr__()¶

Time.__str__()¶

Time.__format__(format_spec)¶

Special values¶

neo4j.time.Midnight = neo4j.time.Time(0, 0, 0, 0)¶: A Time instance set to 00:00:00. This has a ticks_ns value of 0.

neo4j.time.Midday = neo4j.time.Time(12, 0, 0, 0)¶: A Time instance set to 12:00:00. This has a ticks_ns value of 43200000000000.

DateTime¶

class neo4j.time.DateTime(year, month, day, hour=0, minute=0, second=0, nanosecond=0, tzinfo=None)¶

A point in time represented as a date and a time.

The DateTime class is a nanosecond-precision drop-in replacement for the standard library datetime.datetime class.

As such, it contains both Date and Time information and draws functionality from those individual classes.

A DateTime object is fully compatible with the Python time zone library pytz. Functions such as normalize and localize can be used in the same way as they are with the standard library classes.

Regular construction of a DateTime object requires at least the year, month and day arguments to be supplied. The optional hour, minute and second arguments default to zero and tzinfo defaults to None.

year, month, and day are passed to the constructor of Date. hour, minute, second, nanosecond, and tzinfo are passed to the constructor of Time. See their documentation for more details.

>>> dt = DateTime(2018, 4, 30, 12, 34, 56, 789123456); dt
neo4j.time.DateTime(2018, 4, 30, 12, 34, 56, 789123456)
>>> dt.second
56.789123456

Class methods¶

classmethod DateTime.now(tz=None)¶

Get the current date and time.

Parameters:: tz (datetime.tzinfo` or None) – timezone. Set to None to create a local DateTime.
Return type:: DateTime
Raises:: OverflowError – if the timestamp is out of the range of values supported by the platform C localtime() function. It’s common for this to be restricted to years from 1970 through 2038.

classmethod DateTime.utc_now()¶

Get the current date and time in UTC

Return type:: DateTime

classmethod DateTime.from_timestamp(timestamp, tz=None)¶

DateTime from a time stamp (seconds since unix epoch).

Parameters:

timestamp (float) – the unix timestamp (seconds since unix epoch).
tz (datetime.tzinfo or None) – timezone. Set to None to create a local DateTime.

Return type:

DateTime

Raises:

OverflowError – if the timestamp is out of the range of values supported by the platform C localtime() function. It’s common for this to be restricted to years from 1970 through 2038.

classmethod DateTime.utc_from_timestamp(timestamp)¶

DateTime from a time stamp (seconds since unix epoch).

Returns the DateTime as local date DateTime in UTC.

Return type:: DateTime

classmethod DateTime.from_ordinal(ordinal)¶

DateTime from an ordinal.

For more info about ordinals see Date.from_ordinal().

Return type:: DateTime

classmethod DateTime.combine(date, time)¶

Combine a Date and a Time to a DateTime.

Parameters:

date (Date) – the date
time (Time) – the time

Return type:

DateTime

Raises:

AssertionError – if the parameter types don’t match.

classmethod DateTime.from_native(dt)¶

Convert from a native Python datetime.datetime value.

Parameters:: dt (datetime.datetime) – the datetime to convert
Return type:: DateTime

classmethod DateTime.from_clock_time(clock_time, epoch)¶

Convert from a ClockTime relative to a given epoch.

Parameters:

clock_time (ClockTime or (float, int)) – the clock time as ClockTime or as tuple of (seconds, nanoseconds)
epoch (DateTime) – the epoch to which clock_time is relative

Return type:

DateTime

Raises:

ValueError – if clock_time is invalid.

Class attributes¶

DateTime.min = neo4j.time.DateTime(1, 1, 1, 0, 0, 0, 0)¶: The earliest date time value possible.

DateTime.max = neo4j.time.DateTime(9999, 12, 31, 23, 59, 59, 999999999)¶: The latest date time value possible.

DateTime.resolution = (0, 0, 0, 1)¶: The minimum resolution supported.

Instance attributes¶

DateTime.year¶

The year of the DateTime.

See Date.year.

DateTime.month¶

The year of the DateTime.

See Date.year.

DateTime.day¶

The day of the DateTime’s date.

See Date.day.

DateTime.year_month_day¶

The year_month_day of the DateTime’s date.

See Date.year_month_day.

DateTime.year_week_day¶

The year_week_day of the DateTime’s date.

See Date.year_week_day.

DateTime.year_day¶

The year_day of the DateTime’s date.

See Date.year_day.

DateTime.hour¶

The hour of the DateTime’s time.

See Time.hour.

DateTime.minute¶

The minute of the DateTime’s time.

See Time.minute.

DateTime.second¶

The second of the DateTime’s time.

See Time.second.

DateTime.nanosecond¶

The nanosecond of the DateTime’s time.

See Time.nanosecond.

DateTime.tzinfo¶

The tzinfo of the DateTime’s time.

See Time.tzinfo.

DateTime.hour_minute_second¶

The hour_minute_second of the DateTime’s time.

See Time.hour_minute_second.

DateTime.hour_minute_second_nanosecond¶

The hour_minute_second_nanosecond of the DateTime’s time.

See Time.hour_minute_second_nanosecond.

Operations¶

DateTime.__hash__()¶

DateTime.__eq__(other)¶: == comparison with DateTime or datetime.datetime.

DateTime.__ne__(other)¶: != comparison with DateTime or datetime.datetime.

DateTime.__lt__(other)¶: < comparison with DateTime or datetime.datetime.

DateTime.__gt__(other)¶: > comparison with DateTime or datetime.datetime.

DateTime.__le__(other)¶: <= comparison with DateTime or datetime.datetime.

DateTime.__ge__(other)¶: >= comparison with DateTime or datetime.datetime.

DateTime.__add__(other)¶

Add a datetime.timedelta.

Return type:: DateTime

DateTime.__sub__(other)¶

Subtract a datetime or a timedelta.

Supported DateTime (returns Duration), datetime.datetime (returns datetime.timedelta), and datetime.timedelta (returns DateTime).

Return type:: Duration or datetime.timedelta or DateTime

Instance methods¶

DateTime.date()¶

The date

Return type:: Date

DateTime.time()¶

The time without timezone info

Return type:: Time

DateTime.timetz()¶

The time with timezone info

Return type:: Time

DateTime.replace(**kwargs)¶

Return a DateTime with one or more components replaced.

See Date.replace() and Time.replace() for available arguments.

Return type:: DateTime

DateTime.as_timezone(tz)¶

Convert this DateTime to another timezone.

Parameters:: tz (datetime.tzinfo or None) – the new timezone
Returns:: the same object if tz is None. Else, a new DateTime that’s the same point in time but in a different timezone.
Return type:: DateTime

DateTime.utc_offset()¶

Get the date times utc offset.

See Time.utc_offset().

DateTime.dst()¶

Get the daylight saving time adjustment (DST).

See Time.dst().

DateTime.tzname()¶

Get the timezone name.

See Time.tzname().

DateTime.to_ordinal()¶

Get the ordinal of the DateTime’s date.

See Date.to_ordinal()

DateTime.to_clock_time()¶

Convert to ClockTime.

Return type:: ClockTime

DateTime.to_native()¶

Convert to a native Python datetime.datetime value.

This conversion is lossy as the native time implementation only supports a resolution of microseconds instead of nanoseconds.

Return type:: datetime.datetime

DateTime.weekday()¶

Get the weekday.

See Date.weekday()

DateTime.iso_weekday()¶

Get the ISO weekday.

See Date.iso_weekday()

DateTime.iso_calendar()¶

Get date as ISO tuple.

See Date.iso_calendar()

DateTime.iso_format(sep='T')¶

Return the DateTime as ISO formatted string.

This method joins self.date().iso_format() (see Date.iso_format()) and self.timetz().iso_format() (see Time.iso_format()) with sep in between.

Parameters:: sep (str) – the separator between the formatted date and time.
Return type:: str

DateTime.__repr__()¶

DateTime.__str__()¶

DateTime.__format__(format_spec)¶

Special values¶

neo4j.time.Never = neo4j.time.DateTime(0, 0, 0, 0, 0, 0, 0)¶: A DateTime instance set to 0000-00-00T00:00:00. This has a Date component equal to ZeroDate and a Time component equal to Midnight.

neo4j.time.UnixEpoch = neo4j.time.DateTime(1970, 1, 1, 0, 0, 0, 0)¶: A DateTime instance set to 1970-01-01T00:00:00.

Duration¶

class neo4j.time.Duration(years=0, months=0, weeks=0, days=0, hours=0, minutes=0, seconds=0, subseconds=0, milliseconds=0, microseconds=0, nanoseconds=0)¶

A difference between two points in time.

A Duration represents the difference between two points in time. Duration objects store a composite value of months, days, seconds, and nanoseconds. Unlike datetime.timedelta however, days, and seconds/nanoseconds are never interchanged. All values except seconds and nanoseconds are applied separately in calculations.

A Duration stores four primary instance attributes internally: months, days, seconds and nanoseconds. These are maintained as individual values and are immutable. Each of these four attributes can carry its own siggn, with the exception of nanoseconds, which always has the same sign as seconds. The constructor will establish this state, should the duration be initialized with conflicting seconds and nanoseconds signs. This structure allows the modelling of durations such as 3 months minus 2 days.

To determine if a Duration d is overflowing the accepted values of the database, first, all nanoseconds outside the range -999_999_999 and 999_999_999 are transferred into the seconds field. Then, months, days, and seconds are summed up like so: months * 2629746 + days * 86400 + d.seconds + d.nanoseconds // 1000000000. (Like the integer division in Python, this one is to be understood as rounding down rather than towards 0.) This value must be between -(2⁶³) and (2⁶³ - 1) inclusive.

Parameters:

years (float) – will be added times 12 to months
months (float) – will be truncated to int (int(months))
weeks (float) – will be added times 7 to days
days (float) – will be truncated to int (int(days))
hours (float) – will be added times 3,600,000,000,000 to nanoseconds
minutes (float) – will be added times 60,000,000,000 to nanoseconds
seconds (float) – will be added times 1,000,000,000 to nanoseconds`
subseconds (float) –
will be added times 1,000,000,000 to nanosubseconds`

Deprecated since version 4.4: Will be removed in 5.0. Use milliseconds, microseconds, or nanoseconds instead or add subseconds to seconds
milliseconds (float) – will be added times 1,000,000 to nanoseconds
microseconds (float) – will be added times 1,000 to nanoseconds
nanoseconds (float) – will be truncated to int (int(nanoseconds))

Raises:

ValueError – the components exceed the limits as described above.

Class attributes¶

Duration.min = (0, 0, -9223372036854775808, 0)¶: The lowest duration value possible.

Duration.max = (0, 0, 9223372036854775807, 999999999)¶: The highest duration value possible.

Instance attributes¶

Duration.months¶

The months of the Duration.

Type:: int

Duration.days¶

The days of the Duration.

Type:: int

Duration.seconds¶

The seconds of the Duration.

Type:: int

Duration.subseconds¶

The subseconds of the Duration.

Deprecated since version 4.4: Will be removed in 5.0. Use nanoseconds instead.

Type:: decimal.Decimal

Duration.nanoseconds¶

The nanoseconds of the Duration.

Type:: int

Duration.years_months_days¶

Returns:

Duration.hours_minutes_seconds¶

A 3-tuple of (hours, minutes, seconds).

Where seconds is a decimal.Decimal that combines seconds and nanoseconds.

Deprecated since version 4.4: Will be removed in 5.0. Use hours_minutes_seconds_nanoseconds instead.

Type:: (int, int, decimal.Decimal)

Duration.hours_minutes_seconds_nanoseconds¶

A 4-tuple of (hours, minutes, seconds, nanoseconds).

Type:: (int, int, int, int)

Operations¶

Duration.__bool__()¶: Falsy if all primary instance attributes are.

Duration.__add__(other)¶

Add a Duration or datetime.timedelta.

Return type:: Duration

Duration.__sub__(other)¶

Subtract a Duration or datetime.timedelta.

Return type:: Duration

Duration.__mul__(other)¶

Multiply by an int.

Return type:: Duration

Duration.__pos__()¶

Duration.__neg__()¶

Duration.__abs__()¶

Duration.__repr__()¶

Duration.__str__()¶

Instance methods¶

Duration.iso_format(sep='T')¶

Return the Duration as ISO formatted string.

Parameters:: sep (str) – the separator before the time components.
Return type:: str

Temporal Data Types¶

Constants¶

Date¶

Class methods¶

Class attributes¶

Instance attributes¶

Operations¶

Instance methods¶

Special values¶

Time¶

Class methods¶

Class attributes¶

Instance attributes¶

Operations¶

Instance methods¶

Special values¶

DateTime¶

Class methods¶

Class attributes¶

Instance attributes¶

Operations¶

Instance methods¶

Special values¶

Duration¶

Class attributes¶

Instance attributes¶

Operations¶

Instance methods¶

Table of Contents

Previous topic

Next topic

This Page