TimeFormat API

API documentation for the TimeFormat library.

The TimeFormat Python library provides a flexible alternative to the time.strftime() function that is bundled with Python.

Rationale

The time.strftime() function relies on the underlying 'C' library implementation, which while fast, has several limitations:

Implemented functionality varies from platform to platform.
Control over padding (leading zeros, leading spaces, no padding) is limited.
Different platforms produce different results for the same formatting codes.
No format is possible that produces strings compatible with the W3C DateTime Note when timezones are required.

TimeFormat API

There are two public functions in the TimeFormat API, one accepts new formatting codes, and one is backwards compatible with the formatting codes used in time.strftime.

format (informat [,intime] [,utctime])

Returns a Unicode string with the date/time expanded according to the passed in format. If a date/time tuple is not specified then time.localtime() is used as the date/time value. If utctime is set to true then the time is interpreted as being in UTC, otherwise it is taken as being in the local timezone.

Formatting codes accepted by the format function are of the form: %CODE[MODIFIER]. The use of [MODIFIER] is optional.

CODE	Value and default modifier.
a	Weekday in locale (Default Modifier: LONG)
b	Month in locale (Default Modifier: LONG)
c	Locale's date/time representation
C	Century as a decimal.
d	Day of month (Default Modifier: 0)
H	Hour in 24 hour format (Default Modifier: 0)
I	Hour in 12 hour format (Default Modifier: 0)
j	Day of year as a number (Default Modifier: 0)
m	Month of year as a number (Default Modifier: 0)
M	Minute as a number (Default Modifier: 0)
n	Newline
p	Locale's AM/PM
P	Locale's am/pm
r	Locale's time in AM/PM format
S	Second as a number (Default Modifier: 0)
t	Tab character.
T	Timezone offset with no colon (e.g. -0400)
U	Week number (Sunday first day of week) (Default Modifier: 0)
w	Week day as a number (0 = Sunday)
W	Week number (Monday first day) (Default Modifier: 0)
x	Locale's date representation
X	Locale's time representation
y	Year without century (Default Modifier: 0)
Y	Year with century
Z	Timezone TLA (e.g. GMT)
z	Timezone in W3C Note format (-hh:mm, +hh:mm or Z)

Modifiers are only applicable on a sub-set of codes, as defined here:

MODIFIER	Applicable Codes	Description
SHORT	a,b	Use a short version if available.
LONG	a,b	Use a long version if available.
0	d,H,I,j,m,M,S,W,Y	Pad with leading zero's
SP	d,H,I,j,m,M,S,W,Y	Pad with leading space's
NP	d,H,I,j,m,M,S,W,Y	Do not pad

Example: At 16:18 the format string "%I[NP]:%M" will produce "4:18".

strftime (informat [,intime])

Returns a Unicode string with the date/time expanded according to the passed in format. If a date/time tuple is not specified then time.localtime() is used as the date/time value. The formatting codes accepted by strftime are a super-set of those handled by time.strftime().

This function works by converting the strftime codes into TimeFormat codes, and then expanding the resulting formatting string. It is more efficient to use the format() function directly.

The mapping used from strftime codes to TimeFormat codes is as follows:

strftime Code	TimeFormat Codes
A	%a[LONG]
B	%b[LONG]
C	%C
D	%m[0]/%d[0]/%y[0]
F	%Y-%m[0]-%d[0]
H	%H[0]
I	%I[0]
M	%M[0]
P	%P
R	%H[0]:%M[0]
S	%S[0]
T	%H[0]:%M[0]:%S[0]
U	%U
W	%W[0]
X	%X
Y	%Y
Z	%Z
a	%a[SHORT]
b	%b[SHORT]
c	%c
d	%d[0]
e	%d[SP]
h	%b[SHORT]
j	%j[0]
k	%H[SP]
l	%I[SP]
m	%m[0]
n	%n
p	%p
r	%r
t	%t
u	%u
w	%w
x	%x
y	%y[0]
z	%T

Limitations

TimeFormat has a couple of limitations:

If the locale.nl_langinfo function is not available then all locale specific values will assume defaults.
The TimeFormat codes %p, %P, %U, and %W are implemented by calling time.strftime().

Sections

Software

The full list of my published Software