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.epochconverts 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.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_stris discarded. To supply a timezone only when the string has none, useassume_timezoneinstead.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. Whenyearfirstis 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
tzinfoobject to apply whendatetime_strcontains no timezone or UTC offset. It defaults to"UTC"for compatibility with earlier versions. PassNoneto assume nothing, which turns timezone-less input into an error.
- Raises:
DeloreanInvalidDatetime – If the string contains no timezone and
assume_timezoneisNone. DeloreanInvalidDatetime is a ValueError, as is the error raised for an unreadable string.
Added in version 1.1.0: The
assume_timezoneparameter 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_timezonewhen 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
Nonewhen 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_timezoneis 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
timezoneargument 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 overassume_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.