Interface

Delorean

class delorean.Delorean(datetime=None, timezone=None)

The class Delorean <Delorean> object. This method accepts naive datetime objects, with a string timezone.

property date

Returns the actual date object associated with the Delorean object.

>>> d = Delorean(datetime(2015, 1, 1, 12, 15), timezone='US/Pacific')
>>> d.date
datetime.date(2015, 1, 1)
property datetime

Returns the actual datetime object associated with the Delorean object.

>>> d = Delorean(datetime(2015, 1, 1, 12, 15), timezone='UTC')
>>> d.datetime
datetime.datetime(2015, 1, 1, 12, 15, tzinfo=zoneinfo.ZoneInfo(key='UTC'))
property end_of_day

Returns a new Delorean object for the end of the day associated with this object. This object is left unchanged.

>>> d = Delorean(datetime(2015, 1, 1, 12), timezone='UTC')
>>> d.end_of_day
Delorean(datetime=datetime.datetime(2015, 1, 1, 23, 59, 59, 999999), timezone='UTC')
property end_of_month

Returns a new Delorean object for the last moment of the month associated with this object, accounting for month length and leap years. This object is left unchanged.

>>> d = Delorean(datetime(2015, 2, 15, 14, 30), timezone='UTC')
>>> d.end_of_month
Delorean(datetime=datetime.datetime(2015, 2, 28, 23, 59, 59, 999999), timezone='UTC')
property end_of_year

Returns a new Delorean object for the last moment of the year associated with this object. This object is left unchanged.

>>> d = Delorean(datetime(2015, 5, 15, 14, 30), timezone='UTC')
>>> d.end_of_year
Delorean(datetime=datetime.datetime(2015, 12, 31, 23, 59, 59, 999999), timezone='UTC')
property epoch

Alias of timestamp, kept for backwards compatibility.

The value is seconds since the Unix epoch, so timestamp is the more accurate name; the epoch itself is the fixed point the count starts from.

>>> d = Delorean(datetime(2015, 1, 1), timezone='US/Pacific')
>>> d.epoch
1420099200.0
format_datetime(format='medium', locale='en_US')

Return a date string formatted to the given pattern.

Note that CLDR separates the time from the AM/PM marker with a narrow no-break space (\u202f), not a plain space.

>>> d = Delorean(datetime(2015, 1, 1, 12, 30), timezone='US/Pacific')
>>> d.format_datetime(locale='en_US')
'Jan 1, 2015, 12:30:00\u202fPM'

>>> d.format_datetime(format='long', locale='de_DE')
'1. Januar 2015, 12:30:00 -0800'
Parameters:
  • format – one of “full”, “long”, “medium”, “short”, or a custom datetime pattern

  • locale – a locale identifier

humanize()

Humanize relative to now:

>>> past = Delorean.utcnow() - timedelta(hours=1)
>>> past.humanize()
'an hour ago'
property midnight

Returns a new Delorean object for midnight of the day associated with this object. This object is left unchanged.

>>> d = Delorean(datetime(2015, 1, 1, 12), timezone='UTC')
>>> d.midnight
Delorean(datetime=datetime.datetime(2015, 1, 1, 0, 0), timezone='UTC')
property naive

Returns a naive datetime object associated with the Delorean object, this method simply converts the localize datetime to UTC and removes the tzinfo that is associated with it modifying the Delorean object.

>>> d = Delorean(datetime(2015, 1, 1), timezone='US/Pacific')
>>> d.naive
datetime.datetime(2015, 1, 1, 8, 0)
replace(**kwargs)

Returns a new Delorean object after applying replace on the existing datetime object.

>>> d = Delorean(datetime(2015, 1, 1, 12, 15), timezone='UTC')
>>> d.replace(hour=8)
Delorean(datetime=datetime.datetime(2015, 1, 1, 8, 15), timezone='UTC')
shift(timezone)

Shifts the timezone from the current timezone to the specified timezone associated with the Delorean object, modifying the Delorean object and returning the modified object.

>>> d = Delorean(datetime(2015, 1, 1), timezone='US/Pacific')
>>> d.shift('UTC')
Delorean(datetime=datetime.datetime(2015, 1, 1, 8, 0), timezone='UTC')
property start_of_day

Returns a new Delorean object for the start of the day associated with this object. This object is left unchanged.

>>> d = Delorean(datetime(2015, 1, 1, 12), timezone='UTC')
>>> d.start_of_day
Delorean(datetime=datetime.datetime(2015, 1, 1, 0, 0), timezone='UTC')
property start_of_month

Returns a new Delorean object for the first moment of the month associated with this object. This object is left unchanged.

>>> d = Delorean(datetime(2015, 5, 15, 14, 30), timezone='UTC')
>>> d.start_of_month
Delorean(datetime=datetime.datetime(2015, 5, 1, 0, 0), timezone='UTC')
property start_of_year

Returns a new Delorean object for the first moment of the year associated with this object. This object is left unchanged.

>>> d = Delorean(datetime(2015, 5, 15, 14, 30), timezone='UTC')
>>> d.start_of_year
Delorean(datetime=datetime.datetime(2015, 1, 1, 0, 0), timezone='UTC')
property timestamp

Returns the total seconds since the Unix epoch associated with the Delorean object.

>>> d = Delorean(datetime(2015, 1, 1), timezone='US/Pacific')
>>> d.timestamp
1420099200.0
property timezone

Returns the tzinfo object associated with the Delorean object: a zoneinfo.ZoneInfo for a named zone, or a datetime.timezone for a fixed offset.

>>> d = Delorean(datetime(2015, 1, 1), timezone='UTC')
>>> d.timezone
zoneinfo.ZoneInfo(key='UTC')

Changed in version 2.0: Timezones are standard library objects. Earlier versions returned pytz objects, so comparisons against pytz.utc and friends need updating to delorean.timezone() or zoneinfo.ZoneInfo.

truncate(s)

Truncate the delorean object to the nearest s (second, minute, hour, day, month, year)

This is a destructive method, modifies the internal datetime object associated with the Delorean object.

>>> d = Delorean(datetime(2015, 1, 1, 12, 10), timezone='US/Pacific')
>>> d.truncate('hour')
Delorean(datetime=datetime.datetime(2015, 1, 1, 12, 0), timezone='US/Pacific')
exception delorean.DeloreanError(msg)

Base Delorean Exception class

Subclasses ValueError so that a caller handling bad input can catch both these and the ValueError the underlying parser raises for unreadable strings.

exception delorean.DeloreanInvalidDatetime(msg)

Exception that is raised when an improper datetime object is passed in.

exception delorean.DeloreanInvalidTimezone(msg)

Exception that is raised when an invalid timezone is passed in.

delorean.datetime_timezone(tz)

This method given a timezone returns a localized datetime object.

delorean.epoch(s)

Alias of from_timestamp(), kept for backwards compatibility.

The argument is seconds since the Unix epoch rather than an epoch, so from_timestamp is the more accurate name. It also avoids epoch meaning two opposite things, since Delorean.epoch converts the other way.

delorean.from_timestamp(s)

Return a Delorean object for the given seconds since the Unix epoch.

>>> from_timestamp(1420099200.0)
Delorean(datetime=datetime.datetime(2015, 1, 1, 8, 0), timezone='UTC')
delorean.localize(dt, tz)

Given a naive datetime object this method will return a localized datetime object

delorean.move_datetime_month(dt, direction, num_shifts)

Move datetime 1 month in the chosen direction. unit is a no-op, to keep the API the same as the day case

delorean.move_datetime_week(dt, direction, num_shifts)

Move datetime 1 week in the chosen direction. unit is a no-op, to keep the API the same as the day case

delorean.move_datetime_year(dt, direction, num_shifts)

Move datetime 1 year in the chosen direction. unit is a no-op, to keep the API the same as the day case

delorean.normalize(dt, tz)

Given a object with a timezone return a datetime object normalized to the proper timezone.

This means take the give localized datetime and returns the datetime normalized to match the specified timezone.

delorean.now(timezone=None)

Return a Delorean object for the current local date and time, setting the timezone to the local timezone of the caller by default.

Parameters:

timezone (Optional[datetime.tzinfo]) – A custom timezone to use when computing the time.

Return type:

delorean.dates.Delorean

delorean.parse(datetime_str, timezone=None, isofirst=True, dayfirst=True, yearfirst=True, *, assume_timezone='UTC')

Parse a datetime string and return a Delorean object.

Parameters:
  • datetime_str – The string to interpret.

  • timezone – Force the parsed clock reading into this timezone. Any offset in datetime_str is discarded. To supply a timezone only when the string has none, use assume_timezone instead.

  • isofirst – Try ISO parsing before the general-purpose parser.

  • dayfirst – Interpret the first value in an ambiguous three-integer date (for example, 01/05/09) as the day rather than the month. When yearfirst is true, this distinguishes YDM from YMD.

  • yearfirst – Interpret the first value in an ambiguous three-integer date as the year. Otherwise, interpret the last value as the year.

  • assume_timezone – A timezone name or tzinfo object to apply when datetime_str contains no timezone or UTC offset. It defaults to "UTC" for compatibility with earlier versions. Pass None to assume nothing, which turns timezone-less input into an error.

Raises:

DeloreanInvalidDatetime – If the string contains no timezone and assume_timezone is None. DeloreanInvalidDatetime is a ValueError, as is the error raised for an unreadable string.

Added in version 1.1.0: The assume_timezone parameter makes the existing UTC assumption configurable and allows strict handling of timezone-less input.

>>> parse('2015-01-01 00:01:02')
Delorean(datetime=datetime.datetime(2015, 1, 1, 0, 1, 2), timezone='UTC')

If the string provides a fixed offset, the returned object keeps that offset. No assumption is necessary.

>>> parse('2015-01-01 00:01:02 -0800')
Delorean(datetime=datetime.datetime(2015, 1, 1, 0, 1, 2), timezone='UTC-08:00')

A timezone-less string does not identify an instant by itself. For compatibility, Delorean assumes UTC by default. Pass a different assume_timezone when you know which timezone its clock reading uses.

>>> parse('2015-01-01 00:01:02', assume_timezone='America/Toronto')
Delorean(datetime=datetime.datetime(2015, 1, 1, 0, 1, 2), timezone='America/Toronto')

Pass None when timezone-less input should be treated as an error rather than an assumed UTC value.

>>> parse('2015-01-01 00:01:02', assume_timezone=None)
Traceback (most recent call last):
...
DeloreanInvalidDatetime: ...

assume_timezone is only a fallback. It has no effect when the string already includes a timezone or offset.

>>> parse('2015-01-01 00:01:02 -0800', assume_timezone='UTC')
Delorean(datetime=datetime.datetime(2015, 1, 1, 0, 1, 2), timezone='UTC-08:00')

The older timezone argument is a stronger override: it discards any parsed offset and treats the clock reading as local to the requested timezone. When supplied, it takes precedence over assume_timezone.

>>> parse('2015-01-01 00:01:02 -0500', timezone='US/Pacific')
Delorean(datetime=datetime.datetime(2015, 1, 1, 0, 1, 2), timezone='US/Pacific')
delorean.range_daily(start=None, stop=None, timezone='UTC', count=None)

This an alternative way to generating sets of Delorean objects with DAILY stops

delorean.range_hourly(start=None, stop=None, timezone='UTC', count=None)

This an alternative way to generating sets of Delorean objects with HOURLY stops

delorean.range_monthly(start=None, stop=None, timezone='UTC', count=None)

This an alternative way to generating sets of Delorean objects with MONTHLY stops

delorean.range_yearly(start=None, stop=None, timezone='UTC', count=None)

This an alternative way to generating sets of Delorean objects with YEARLY stops

delorean.stops(freq, interval=1, count=None, wkst=None, bysetpos=None, bymonth=None, bymonthday=None, byyearday=None, byeaster=None, byweekno=None, byweekday=None, byhour=None, byminute=None, bysecond=None, timezone='UTC', start=None, stop=None)

Yield a Delorean object for each stop matching the settings passed in.

delorean.timezone(name)

Return the timezone that name identifies.

Parameters:

name – An IANA zone name such as "US/Eastern", a fixed offset written as "UTC-08:00", or a tzinfo object, which is returned unchanged so this can normalize whatever a caller supplies.

Raises:

DeloreanInvalidTimezone – If the name identifies no known zone.

>>> timezone('US/Eastern')
zoneinfo.ZoneInfo(key='US/Eastern')
>>> timezone('UTC-08:00')
datetime.timezone(datetime.timedelta(days=-1, seconds=57600))

Added in version 2.0.

delorean.utcnow()

Return a Delorean object for the current UTC date and time, setting the timezone to UTC.