# 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.

```python
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.

```python
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.

```python
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 |

```python
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.

```python
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.

```python
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.

```python
time_ago(when=None, tz=None, future=False)
```

```python
time_ago("3 days ago")   # "3 days ago"
```

## natural_day

Says "today", "tomorrow" or "yesterday", or else a short date.

```python
natural_day(when=None, format="%b %d", tz=None)
```

## natural_date

A short date. It drops the year when it is this year.

```python
natural_date(when=None, tz=None)   # "Jun 20"
```

## natural_delta

Turns a length of time into words.

```python
natural_delta(value, months=True, minimum_unit="seconds")
```

`value` is a length of time, or a number of seconds.

```python
natural_delta(3700)   # "an hour"
```

## precise_delta

Like `natural_delta`, but exact.

```python
precise_delta(value, minimum_unit="seconds", suppress=(), format="%0.2f")
```

```python
precise_delta(3700)   # "1 hour, 1 minute and 40 seconds"
```

## get_delta

The time left until a future time.

```python
get_delta(future, tz=None)
```

```python
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.

```python
await sleep(seconds)
```

The most is 86,400 seconds (one day).

```python
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](https://ccbot.app/docs/reference/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. |