0

Year

tm_year

1970–2038

Wider on some platforms.

1

Month

tm_mon

1–12

1 is January; 12 is December.

2

Day

tm_mday

1–31

3

Hour

tm_hour

0–23

0 is midnight; 12 is noon.

4

Minute

tm_min

0–59

5

Second

tm_sec

0–61

60 and 61 for leap seconds.

6

Weekday

tm_wday

0–6

0 is Monday; 6 is Sunday.

7

Year day

tm_yday

1–366

Day number within the year.

8

DST flag

tm_isdst

–1 to 1

-1 means library determines DST.

asctime

asctime([tupletime])

Accepts a timetuple and returns a readable 24-character string such as 'Sun Jan 8 14:41:06 2017'. asctime() without arguments is like asctime(localtime(time())) (formats current time in local time).

clock

clock()

Returns the current CPU time as a floating-point number of seconds, but is platform dependent. Deprecated in v3. To measure computational costs of different approaches, use the standard library module timeit, covered in “The timeit module” instead. To implement a timeout or schedule events, in v3, use perf_counter() or process_time() instead. See also the sched module for multithreading safe event scheduling.

ctime

ctime([secs])

Like asctime(localtime(secs)), accepts an instant expressed in seconds since the epoch and returns a readable 24-character string form of that instant, in local time. ctime() without arguments is like asctime() (formats the current time instant in local time).

gmtime

gmtime([secs])

Accepts an instant expressed in seconds since the epoch and returns a timetuple t with the UTC time (t.tm_isdst is always 0). gmtime() without arguments is like gmtime(
time()) (returns the timetuple for the current time instant).

localtime

localtime([secs])

Accepts an instant expressed in seconds since the epoch and returns a timetuple t with the local time (t.tm_isdst is 0 or 1, depending on whether DST applies to instant secs by local rules). localtime() without arguments is like localtime(time()) (returns the timetuple for the current time instant).

mktime

mktime(tupletime)

Accepts an instant expressed as a timetuple in local time and returns a floating-point value with the instant expressed in seconds since the epoch.^a DST, the last item in tupletime, is meaningful: set it to 0 to get solar time, to 1 to get DST, or to -1 to let mktime compute whether DST is in effect at the given instant.

monotonic

monotonic()

v3 only. Like time(), returns the current time instant, a float with seconds since the epoch. Guaranteed to never go backward between calls, even when the system clock is adjusted (e.g., due to leap seconds).

perf_counter

perf_counter()

v3 only. Returns the value in fractional seconds using the highest-resolution clock available to get accuracy for short durations. It is system-wide and includes time elapsed during sleep. Use only the difference between successive calls, as there is no defined reference point.

process_time

process_time()

v3 only. Returns the value in fractional seconds using the highest-resolution clock available to get accuracy for short durations. It is process-wide and doesn’t include time elapsed during sleep. Use only the difference between successive calls, as there is no defined reference point.

sleep

sleep(secs)

Suspends the calling thread for secs seconds. The calling thread may start executing again before secs seconds (when it’s the main thread and some signal wakes it up) or after a longer suspension (depending on system scheduling of processes and threads). You can call sleep with secs=0 to offer other threads a chance to run, incurring no significant delay if the current thread is the only one ready to run.

strptime

strptime(str,[fmt='%a %b %d %H:%M:%S %Y'])

Parses str according to format string fmt and returns the instant as a timetuple. The format string’s syntax is as covered in strftime earlier.

time

time()

Returns the current time instant, a float with seconds since the epoch. On some (mostly, older) platforms, the precision of this time is as low as one second. May return a lower value in a subsequent call if the system clock is adjusted backward between calls (e.g., due to leap seconds).

timezone

timezone

The offset in seconds of the local time zone (without DST) from UTC (>0 in the Americas; <=0 in most of Europe, Asia, and Africa).

tzname

tzname

A pair of locale-dependent strings, which are the names of the local time zone without and with DST, respectively.

country_timezones

country_timezones(code)

Returns a list of time zone names corresponding to the country whose two-letter ISO code is code. For example, pytz.country_timezones('US') returns a list of 22 strings, from 'America/New_York' to 'Pacific/Honolulu'.

timezone

timezone(name)

Returns an instance of tzinfo corresponding to the time zone named name.

For example, to print the Honolulu equivalent of midnight, December 31, 2005, in New York:

dt = datetime.datetime(2005,12,31,
tzinfo=pytz.timezone('America/New_York'))
print(dt.astimezone(
  pytz.timezone('Pacific/Honolulu')))
# prints: 2005-12-30 19:00:00-10:00

easter

easter.easter(year)

Returns the datetime.date object for Easter of the given year. For example:

from dateutil import easter
print(easter.easter(2006))

prints 2006-04-16.

parser

parser.parse(s)

Returns the datetime.datetime object denoted by string s, with very permissive (AKA “fuzzy”) parsing rules. For example:

from dateutil import parser
print(parser.parse('Saturday, January 28, 2006, 
                    at 11:15pm'))

prints 2006-01-28 23:15:00.

relativedelta

relativedelta.relativedelta(...)

You can call relativedelta with two instances of datetime.datetime: the resulting relativedelta instance captures the relative difference between the two arguments. Alternatively, you can call relativedelta with a named argument representing absolute information (year, month, day, hour, minute, second, microsecond); relative information (years, months, weeks, days, hours, minutes, seconds, microseconds), which may have positive or negative values; or the special named argument weekday, which can be a number from 0 (Monday) to 6 (Sunday), or one of the module attributes MO, TU,…, SU, which can also be called with a numeric argument n to specify the nth weekday. In any case, the resulting relativedelta instance captures the information in the call. For example, after:

from dateutil import relativedelta
r = relativedelta.relativedelta(weekday=relativedelta.MO(1))

r means “next Monday.” You can add a relativedelta instance to a datetime.datetime instance to get a new datetime.datetime instance at the stated relative delta from the other:

print(datetime.datetime(2006,1,29)+r)

# prints: 2006-01-30

print(datetime.datetime(2006,1,30)+r)

# prints: 2006-01-30

print(datetime.datetime(2006,1,31)+r)

# prints: 2006-02-06

Note that “next Monday,” by relativedelta’s interpretation, is the very same date, if that day is already a Monday (so, a more detailed name might be “the first date, on or following the given date, which falls on a Monday”). dateutil’s site has detailed explanations of the rules defining the inevitably complicated behavior of relativedelta instances.

rrule

rrule.rrule(freq, ...)

Module rrule implements RFC2445 (also known as the iCalendar RFC), in all the glory of its 140+ pages. freq must be one of the constant attributes of module rrule: YEARLY, MONTHLY, WEEKLY, DAILY, HOURLY, MINUTELY, or SECONDLY. After mandatory argument freq may optionally come some of many possible named arguments, such as interval=2, to specify that the recurrence is only on alternate occurrences of the specified frequency (for example, rrule.rrule(rrule.YEARLY) repeats every year, while rrule.rrule(rrule.YEARLY, interval=7) repeats only every seven years, as a typical academic sabbatical year would).

after

r.after(d, inc=False)

Returns the earliest datetime.datetime instance that’s an occurrence of recurrence rule r and happens after date d (when inc is true, an occurrence happening on the date d itself is also acceptable).

before

r.before(d, inc=False)

Returns the latest datetime.datetime instance that’s an occurrence of recurrence rule r and happens before date d (when inc is true, an occurrence happening on date d itself is also acceptable).

between

r.between(start, finish, inc=False)

Returns all datetime.datetime instances that are occurrences of recurrence rule r and happen between the dates start and finish (when inc is true, occurrences on the dates start and finish themselves are also acceptable).

For example, to say “once a week throughout January 2018,” the snippet:

start=datetime.datetime(2018,1,1)
r=rrule.rrule(rrule.WEEKLY, dtstart=start)
for d in r.between(start,datetime.datetime(2018,2,1),True):
    print(d.date(),end=' ')

prints: 2018-01-01 2018-01-08 2018-01-15 2018-01-22 2018-01-29

count

r.count()

Returns the number of occurrences of recurrence rule r (may loop forever when r has an unbounded number of occurrences).

scheduler

class scheduler([timefunc],[delayfunc])

The arguments timefunc and delayfunc are mandatory in v2, and optional in v3 (where they default to time.monotonic and time.sleep, respectively).

timefunc must be callable without arguments to get the current time instant (in any unit of measure); for example, you can pass time.time (or, in v3 only, time.monotonic). delayfunc is callable with one argument (a time duration, in the same units as timefunc) to delay the current thread for that time; for example, you can pass time.sleep. scheduler calls delayfunc(0) after each event to give other threads a chance; this is compatible with time.sleep. By taking functions as arguments, scheduler lets you use whatever “simulated time” or “pseudotime” fits your application’s needs (a great example of the dependency injection design pattern for purposes not necessarily related to testing).

cancel

s.cancel(event_token)

Removes an event from s’s queue. event_token must be the result of a previous call to s.enter or s.enterabs, and the event must not yet have happened; otherwise, cancel raises RuntimeError.

empty

s.empty()

Returns True when s’s queue is currently empty; otherwise, False.

enterabs

s.enterabs(when,priority,func,args=(),kwargs={})

Schedules a future event (a callback to func(args, kwargs)) at time when. This is the v3 signature; in v2, sequence args is mandatory, and mapping kwargs is not allowed.

when is in the units used by the time functions of s. Should several events be scheduled for the same time, s executes them in increasing order of priority. enterabs returns an event token t, which you may pass to s.cancel to cancel this event.

enter

s.enter(delay,priority,func,args=(),kwargs={})

Like enterabs, except that delay is a relative time (a positive difference forward from the current instant), while enterabs’s argument when is an absolute time (a future instant). In v3, args is optional and kwargs is added.

To schedule an event for repeated execution, use a little wrapper function; for example:

def enter_repeat(s, first_delay, period, priority, func, args):
    def repeating_wrapper():
        s.enter(period, priority, repeating_wrapper, ())
        func(*args)
    s.enter(first_delay, priority, repeating_wrapper, ())

run

s.run(blocking=True)

Runs scheduled events. In v2, or if blocking is true (v3 only), s.run loops until s.empty(), using the delayfunc passed on s’s initialization to wait for each scheduled event. If blocking is false (v3 only), executes any soon-to-expire events, then returns the next event’s deadline (if any). When a callback func raises an exception, s propagates it, but s keeps its own state, removing the event from the schedule. If a callback func runs longer than the time available before the next scheduled event, s falls behind but keeps executing scheduled events in order, never dropping any. Call s.cancel to drop an event explicitly if that event is no longer of interest.

calendar

calendar(year,w=2,l=1,c=6)

Returns a multiline string with a calendar for year year formatted into three columns separated by c spaces. w is the width in characters of each date; each line has length 21*w+18+2*c. l is the number of lines for each week.

firstweekday

firstweekday()

Returns the current setting for the weekday that starts each week. By default, when calendar is first imported, this is 0, meaning Monday.

isleap

isleap(year)

Returns True if year is a leap year; otherwise, False.

leapdays

leapdays(y1,y2)

Returns the total number of leap days in the years within range(y1,y2) (remember, this means that y2 is excluded).

month

month(year,month,w=2,l=1)

Returns a multiline string with a calendar for month month of year year, one line per week plus two header lines. w is the width in characters of each date; each line has length 7*w+6. l is the number of lines for each week.

monthcalendar

monthcalendar(year,month)

Returns a list of lists of ints. Each sublist denotes a week. Days outside month month of year year are set to 0; days within the month are set to their day-of-month, 1 and up.

monthrange

monthrange(year,month)

Returns two integers. The first one is the code of the weekday for the first day of the month month in year year; the second one is the number of days in the month. Weekday codes are 0 (Monday) to 6 (Sunday); month numbers are 1 to 12.

prcal

prcal(year,w=2,l=1,c=6)

Like print(calendar.calendar(year,w,l,c)).

prmonth

prmonth(year,month,w=2,l=1)

Like print(calendar.month(year,month,w,l)).

setfirstweekday

setfirstweekday(weekday)

Sets the first day of each week to weekday code weekday. Weekday codes are 0 (Monday) to 6 (Sunday). calendar supplies the attributes MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, and SUNDAY, whose values are the integers 0 to 6. Use these attributes when you mean weekdays (e.g., calendar.FRIDAY instead of 4) to make your code clearer and more readable.

timegm

timegm(tupletime)

The inverse of time.gmtime: accepts a time instant in timetuple form and returns that instant as a float num of seconds since the epoch.

weekday

weekday(year,month,day)

Returns the weekday code for the given date. Weekday codes are 0 (Monday) to 6 (Sunday); month numbers are 1 (Jan) to 12 (Dec).