xoutil.datetime - Basic date and time types

Extends the standard datetime module.

  • Python’s datetime.strftime doesn’t handle dates previous to 1900. This module define classes to override date and datetime to support the formatting of a date through its full proleptic Gregorian date range.

Based on code submitted to comp.lang.python by Andrew Dalke, copied from Django and generalized.

You may use this module as a drop-in replacement of the standard library datetime module.

xoutil.datetime.new_date(*args, **kw)[source]

Generate a safe date from a legacy datetime date object.

xoutil.datetime.new_datetime(*args, **kw)[source]

Generate a safe datetime given a legacy date or datetime object.

xoutil.datetime.strfdelta(delta)[source]

Format a timedelta using a smart pretty algorithm.

Only two levels of values will be printed.

>>> def t(h, m):
...     return timedelta(hours=h, minutes=m)

>>> strfdelta(t(4, 56)) == '4h 56m'
True
xoutil.datetime.strftime(dt, fmt)[source]

Used as strftime method of date and datetime redefined classes.

Also could be used with standard instances.

xoutil.datetime.get_month_first(ref=None)[source]

Given a reference date, returns the first date of the same month. If ref is not given, then uses current date as the reference.

xoutil.datetime.get_month_last(ref=None)[source]

Given a reference date, returns the last date of the same month. If ref is not given, then uses current date as the reference.

xoutil.datetime.get_next_month(ref=None, lastday=False)[source]

Get the first or last day of the next month.

If lastday is False return the first date of the next month. Otherwise, return the last date.

The next month is computed with regards to a reference date. If ref is None, take the current date as the reference.

Examples:

>>> get_next_month(date(2017, 1, 23))
date(2017, 2, 1)
>>> get_next_month(date(2017, 1, 23), lastday=True)
date(2017, 2, 28)

New in version 1.7.3.

xoutil.datetime.is_full_month(start, end)[source]

Returns true if the arguments comprises a whole month.

xoutil.datetime.daterange([start, ]stop[, step])[source]

Similar to standard ‘range’ function, but for date objets.

Returns an iterator that yields each date in the range of [start, stop), not including the stop.

If start is given, it must be a date (or datetime) value; and in this case only stop may be an integer meaning the numbers of days to look ahead (or back if stop is negative).

If only stop is given, start will be the first day of stop’s month.

step, if given, should be a non-zero integer meaning the numbers of days to jump from one date to the next. It defaults to 1. If it’s positive then stop should happen after start, otherwise no dates will be yielded. If it’s negative stop should be before start.

As with range, stop is never included in the yielded dates.

class xoutil.datetime.TimeSpan(start_date=None, end_date=None)[source]

A continuous span of time.

Time spans objects are iterable. They yield exactly two times: first the start date, and then the end date:

>>> ts = TimeSpan('2017-08-01', '2017-09-01')
>>> tuple(ts)
(date(2017, 8, 1), date(2017, 9, 1))

Time spans objects have two items:

>>> ts[0]
date(2017, 8, 1)

>>> ts[1]
date(2017, 9, 1)

>>> ts[:]
(date(2017, 8, 1), date(2017, 9, 1))

Two time spans are equal if their start_date and end_date are equal. When comparing a time span with a date, the date is coerced to a time span (from_date()).

A time span with its start set to None is unbound to the past. A time span with its end set to None is unbound to the future. A time span that is both unbound to the past and the future contains all possible dates. A time span that is not unbound in any direction is bound .

A bound time span is valid if its start date comes before its end date.

Time spans can intersect, compared for containment of dates and by the subset/superset order operations (<=, >=). In this regard, they represent the set of dates between start and end, inclusively.

Warning

Time spans don’t implement the union or difference operations expected in sets because the difference/union of two span is not necessarily continuous.

classmethod from_date(date)[source]

Return a new time span that covers a single date.

past_unbound

True if the time span is not bound into the past.

future_unbound

True if the time span is not bound into the future.

unbound

True if the time span is unbound into the past or unbount into the future or both.

bound

True if the time span is not unbound.

valid

A bound time span is valid if it starts before it ends.

Unbound time spans are always valid.

__le__(other)[source]

True if other is a superset.

issubset()

An alias for __le__().

__ge__(other)[source]

True if other is a subset.

issuperset()

An alias for __ge__().

covers()

An alias for __ge__().

isdisjoint(other)[source]
overlaps(other)[source]

Test if the time spans overlaps.

__and__(other)[source]

Get the time span that is the intersection with another time span.

If two time spans don’t overlap, return the empty time span.

If other is not a TimeSpan we try to create one. If other is a date, we create the TimeSpan that starts and end that very day. Other types are passed unchanged to the constructor.

__mul__()

An alias for __and__().

intersection(*others)[source]

Return self [& other1 & ...].

EmptyTimeSpan

The empty time span. It’s not an instance of TimeSpan but engage set-like operations: union, intersection, etc.

No date is a member of the empty time span. The empty time span is a proper subset of any time span. It’s only a superset of itself. It’s not a proper superset of any other time span nor itself.

This instance is a singleton.