A few conveniences to do with dates and times.

Latest release 20260912: New as_datetime() to convert various things into a timezone aware datetime, hauled in from cs.feeds.

There are some other PyPI modules providing richer date handling than the stdlib datetime module. This module mostly contains conveniences used in my other code; you're welcome to it, but it does not pretend to be large or complete.

Short summary:

• as_datetime: Turn a value into a timezone aware datetime.

• datetime2unixtime: Convert a timezone aware datetime to a UNIX timestamp. WARNING: a naive datetime is assumed to be in UTC.

• isodate: Return a date in ISO8601 YYYY-MM-DD format, or YYYYMMDD if not dashed.

• localdate2unixtime: Convert a localtime date into a UNIX timestamp.

• tzinfoHHMM: tzinfo class based on +HHMM / -HHMM strings.

• unixtime2datetime: Convert a a UNIX timestamp to a datetime in the timezone tz. Note: the default timezone is UTC, not the local timezone.

• UNIXTimeMixin: A mixin for classes with a .unixtime attribute, a float storing a UNIX timestamp.

Functions

as_datetime(dt: float | str | datetime.date | datetime.datetime, *, tz: datetime.tzinfo = datetime.timezone.utc) -> datetime.datetime

Turn a value into a timezone aware datetime.

Parameters:

• dt: the datetime specification, a str or float or date or datetime
• tz: optional tzinfo specifying the target timezone, default UTC

The conversion of dt is as follows:

• datetime: dt.astimezone(tz=tz)
• date: rather arbitrarily assume it is in the target timezone
• float: a UNIX timestamp (seconds since the epoch)
• str: try datetime.fromisoformat then datetime.strptime("%a, %d %b %Y %H:%M:%S %z")

datetime2unixtime(dt)

Convert a timezone aware datetime to a UNIX timestamp. WARNING: a naive datetime is assumed to be in UTC.

isodate(when=None, dashed=True)

Return a date in ISO8601 YYYY-MM-DD format, or YYYYMMDD if not dashed.

Modern Pythons have a datetime.isoformat method, you should use that.

localdate2unixtime(d)

Convert a localtime date into a UNIX timestamp.

unixtime2datetime(unixtime, *, tz: datetime.tzinfo = datetime.timezone.utc)

Convert a a UNIX timestamp to a datetime in the timezone tz. Note: the default timezone is UTC, not the local timezone.

Classes

class UNIXTimeMixin

A mixin for classes with a .unixtime attribute, a float storing a UNIX timestamp.

UNIXTimeMixin.dict

Read-only proxy of a mapping.

UNIXTimeMixin.firstlineno

int([x]) -> integer int(x, base=10) -> integer

Convert a number or string to an integer, or return 0 if no arguments are given. If x is a number, return x.int(). For floating-point numbers, this truncates towards zero.

If x is not a number or if base is given, then x must be a string, bytes, or bytearray instance representing an integer literal in the given base. The literal can be preceded by '+' or '-' and be surrounded by whitespace. The base defaults to 10. Valid bases are 0 and 2-36. Base 0 means to interpret the base from the string as an integer literal.

int('0b100', base=0) 4

UNIXTimeMixin.static_attributes

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable's items.

If the argument is a tuple, the return value is the same object.

UNIXTimeMixin.as_datetime(self, tz: datetime.tzinfo = datetime.timezone.utc)

Return self.unixtime as a datetime with the timezone tz (default UTC).

UNIXTimeMixin.datetime

The unixtime as a UTC datetime.

class tzinfoHHMM(datetime.tzinfo)

tzinfo class based on +HHMM / -HHMM strings.

tzinfoHHMM.dict

Read-only proxy of a mapping.

tzinfoHHMM.firstlineno

int([x]) -> integer int(x, base=10) -> integer

Convert a number or string to an integer, or return 0 if no arguments are given. If x is a number, return x.int(). For floating-point numbers, this truncates towards zero.

If x is not a number or if base is given, then x must be a string, bytes, or bytearray instance representing an integer literal in the given base. The literal can be preceded by '+' or '-' and be surrounded by whitespace. The base defaults to 10. Valid bases are 0 and 2-36. Base 0 means to interpret the base from the string as an integer literal.

int('0b100', base=0) 4

tzinfoHHMM.static_attributes

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable's items.

If the argument is a tuple, the return value is the same object.

Release Log

Release 20260912: New as_datetime() to convert various things into a timezone aware datetime, hauled in from cs.feeds.

Release 20250724:

• unixtime2datetime: default tz now UTC.
• Some doc updates.

Release 20230210:

• Drop Python 2 support.
• Make timezones mandatory where previously they were assumed.

Release 20210306: Initial release, used by cs.sqltags.