API reference
Time
Read times written in plain words, show dates that match each reader's clock, and wait.
Most time functions take plain words, like "tomorrow 5pm", "in 2 hours" or "next friday". They read them in your server's timezone, set in the dashboard settings. Without one, the bot uses UTC.
Only sleep needs await.
get_time#
Turns plain words into a date and time.
get_time(time, tz=None)| Argument | What it does |
|---|---|
time | Plain words, like "friday 8pm". |
tz | A timezone name, like "Europe/London". Defaults to the server's. |
Returns the time in UTC. Text it cannot read gives the current time.
start = get_time("in 3 days")
set_content(f"Starts on {format_date(start, '%A')}.")timestamp#
Makes a Discord timestamp. Discord shows it in each reader's own timezone.
timestamp(time, format="", tz=None)format | Shows like |
|---|---|
t | 9:41 PM |
T | 9:41:30 PM |
d | 06/20/2026 |
D | June 20, 2026 |
f or empty | June 20, 2026 9:41 PM |
F | Saturday, June 20, 2026 9:41 PM |
R | in 2 hours, or 3 days ago |
set_content(f"The giveaway ends {timestamp('in 24 hours', 'R')}.")R counts on its own. You do not need to edit the message.
Tip
Already have a Unix time, like user.unix_joined_at? Write <t:...:R> yourself: f"<t:{user.unix_joined_at}:R>".
format_date#
Writes a date as text, in the server's timezone.
format_date(when=None, format="%B %d, %Y", tz=None)when is plain words, a date, or nothing for now. format uses Python date codes.
format_date() # "June 20, 2026"
format_date("next monday", "%A") # "Monday"| Code | Means |
|---|---|
%Y | Year, like 2026 |
%B / %b | Month name, full or short |
%m | Month number |
%d | Day of the month |
%A / %a | Weekday, full or short |
%H:%M | 24-hour time |
%I:%M %p | 12-hour time |
Note
Use format_date instead of .strftime(). Calling .strftime() yourself fails here.
time_ago#
Says how long ago, or how far ahead, a time is.
time_ago(when=None, tz=None, future=False)time_ago("3 days ago") # "3 days ago"natural_day#
Says "today", "tomorrow" or "yesterday", or else a short date.
natural_day(when=None, format="%b %d", tz=None)natural_date#
A short date. It drops the year when it is this year.
natural_date(when=None, tz=None) # "Jun 20"natural_delta#
Turns a length of time into words.
natural_delta(value, months=True, minimum_unit="seconds")value is a length of time, or a number of seconds.
natural_delta(3700) # "an hour"precise_delta#
Like natural_delta, but exact.
precise_delta(value, minimum_unit="seconds", suppress=(), format="%0.2f")precise_delta(3700) # "1 hour, 1 minute and 40 seconds"get_delta#
The time left until a future time.
get_delta(future, tz=None)left = get_delta("next saturday 8pm")
set_content(f"{precise_delta(left, minimum_unit='minutes')} to go!")sleep#
Waits a number of seconds before the next line runs. Write await yourself.
await sleep(seconds)The most is 86,400 seconds (one day).
msg = send_message(channel, "This message deletes itself in 10 seconds.")
await sleep(10)
delete_message(channel.id, msg.id)Tip
For waits longer than a few minutes, use Scheduling. A scheduled action still runs after the bot restarts. A sleep does not.
Number helpers#
These make numbers easier to read.
| Function | Example | Result |
|---|---|---|
intcomma(value) | intcomma(1234567) | 1,234,567 |
intword(value) | intword(1200000) | 1.2 million |
ordinal(value) | ordinal(3) | 3rd |
apnumber(value) | apnumber(4) | four |
natural_size(value) | natural_size(3000000) | 3.0 MB |
fractional(value) | fractional(1.5) | 1 1/2 |
Other time tools#
| Name | What it is |
|---|---|
to_utc(time) | Turns a date with a timezone into UTC. |
datetime(year, month, day, hour=12, minute=0, second=0) | Makes a date by hand. |
pydatetime | Python's date tools: datetime, date, time, timedelta, timezone. |
pytz, zoneinfo, timezone | Timezone tools. |