trac.util.datefmt – Date and Time manipulation

Since version 0.10, Trac mainly uses datetime.datetime objects for handling date and time values. This enables us to properly deal with timezones so that time can be shown in the user’s own local time.

Current time

trac.util.datefmt.datetime_now()

[tz] -> new datetime with tz’s local day and time.

trac.util.datefmt.time_now()

time() -> floating point number

Return the current time in seconds since the Epoch. Fractions of a second may be present if the system clock provides them.

Conversion

From “anything” to a datetime:

trac.util.datefmt.to_datetime(t, tzinfo=None)

Convert t into a datetime object in the tzinfo timezone.

If no tzinfo is given, the local timezone localtz will be used.

t is converted using the following rules:

  • if it is timezone-“naive”, it is localized to tzinfo
  • if it is already timezone-aware, t is mapped to the given timezone (datetime.datetime.astimezone)
  • If t is None, the current time will be used.
  • If t is a number, it is interpreted as a timestamp.

Any other input will trigger a TypeError.

All returned datetime instances are timezone aware and normalized.

A datetime can be converted to milliseconds and microseconds timestamps. The latter is the preferred representation for dates and times values for storing them in the database, since Trac 0.12.

trac.util.datefmt.to_timestamp(dt)

Return the corresponding POSIX timestamp

trac.util.datefmt.to_utimestamp(dt)

Return a microsecond POSIX timestamp for the given datetime.

Besides to_datetime, there’s a specialized conversion from microseconds timestamps to datetime:

trac.util.datefmt.from_utimestamp(ts)

Return the datetime for the given microsecond POSIX timestamp.

Parsing

trac.util.datefmt.parse_date(text, tzinfo=None, locale=None, hint='date')

Formatting

trac.util.datefmt.pretty_timedelta(time1, time2=None, resolution=None)

Calculate time delta between two datetime objects. (the result is somewhat imprecise, only use for prettyprinting).

If either time1 or time2 is None, the current time will be used instead.

trac.util.datefmt.format_datetime(t=None, format='%x %X', tzinfo=None, locale=None)

Format the datetime object t into an unicode string

If t is None, the current time will be used.

The formatting will be done using the given format, which consist of conventional strftime keys. In addition the format can be ‘iso8601’ to specify the international date format (compliant with RFC 3339).

tzinfo will default to the local timezone if left to None.

Derivatives:

trac.util.datefmt.format_date(t=None, format='%x', tzinfo=None, locale=None)

Convenience method for formatting the date part of a datetime object. See format_datetime for more details.

trac.util.datefmt.format_time(t=None, format='%X', tzinfo=None, locale=None)

Convenience method for formatting the time part of a datetime object. See format_datetime for more details.

Propose suggestion for date/time input format:

trac.util.datefmt.get_date_format_hint(locale=None)

Present the default format used by format_date in a human readable form. This is a format that will be recognized by parse_date when reading a date.

trac.util.datefmt.get_datetime_format_hint(locale=None)

Present the default format used by format_datetime in a human readable form. This is a format that will be recognized by parse_date when reading a date.

trac.util.datefmt.http_date(t=None)

Format datetime object t as a rfc822 timestamp

trac.util.datefmt.is_24_hours(locale)

Returns True for 24 hour time formats.

Formatting and parsing according to user preferences:

trac.util.datefmt.user_time(req, func, *args, **kwargs)

A helper function which passes to tzinfo and locale keyword arguments of func using req parameter. It is expected to be used with format_* and parse_date methods in trac.util.datefmt package.

Parameters:
  • req – a instance of Request
  • func – a function which must accept tzinfo and locale keyword arguments
  • args – arguments which pass to func function
  • kwargs – keyword arguments which pass to func function

jQuery UI datepicker helpers

trac.util.datefmt.get_date_format_jquery_ui(locale)

Get the date format for the jQuery UI datepicker library.

trac.util.datefmt.get_time_format_jquery_ui(locale)

Get the time format for the jQuery UI timepicker addon.

trac.util.datefmt.get_day_names_jquery_ui(req)

Get the day names for the jQuery UI datepicker library

trac.util.datefmt.get_first_week_day_jquery_ui(req)

Get first week day for jQuery date picker

trac.util.datefmt.get_month_names_jquery_ui(req)

Get the month names for the jQuery UI datepicker library

trac.util.datefmt.get_timezone_list_jquery_ui(t=None)

Get timezone list for jQuery timepicker addon

Timezone utilities

trac.util.datefmt.localtz

A global LocalTimezone instance.

class trac.util.datefmt.LocalTimezone(offset=None)

Bases: datetime.tzinfo

A ‘local’ time zone implementation

trac.util.datefmt.all_timezones

List of all available timezones. If pytz is installed, this corresponds to a rich variety of “official” timezones, otherwise this corresponds to FixedOffset instances, ranging from GMT -12:00 to GMT +13:00.

trac.util.datefmt.timezone(tzname)

Fetch timezone instance by name or raise KeyError

trac.util.datefmt.get_timezone(tzname)

Fetch timezone instance by name or return None

class trac.util.datefmt.FixedOffset(offset, name)

Bases: datetime.tzinfo

Fixed offset in minutes east from UTC.