discord-date-transformer

Reusable date and time transformers for discord.py application commands.

The package provides small, typed annotations that parse explicit temporal values in Discord slash commands. It intentionally avoids natural-language parsing.

pip install discord-date-transformer

import discord
from discord import app_commands

from discord_date_transformer import (
    DurationTransform,
    ISODateTransform,
    TimeTransform,
)


@app_commands.command()
async def create_event(
    interaction: discord.Interaction,
    event_date: ISODateTransform,
    event_time: TimeTransform,
    duration: DurationTransform,
) -> None:
    await interaction.response.send_message(
        f"Event: {event_date} {event_time} ({duration})"
    )

The concrete transformer classes are also public: ISODateTransformer, ISODateTimeTransformer, TimeTransformer, DurationTransformer, DateRangeTransformer, and TimezoneTransformer.

Date ranges use the exact syntax START/END. Both components follow date.fromisoformat(), and the end date may equal but cannot precede the start. The returned tuple is ordered as (start, end).

Timezone identifiers are resolved by zoneinfo.ZoneInfo using the IANA timezone database available on the host. Identifiers are case-sensitive; UTC and America/Santiago are valid examples.

Duration input uses exactly one unit and is case-sensitive:

Zero, negative, decimal, whitespace-padded, uppercase, and compound durations such as 1h30m are rejected.

Invalid input raises discord.app_commands.TransformerError with the original parsing exception chained as its cause. This lets normal discord.py application command error handling process every parser failure consistently.

• Python 3.12 or newer
• discord.py 2.7.1 or newer, below 3.0

git clone https://github.com/ezer-mackenzie/discord-date-transformer.git
cd discord-date-transformer
uv sync --all-groups

Run the complete local checks:

uv run ruff check .
uv run ruff format --check .
uv run pytest
uv run mypy

See CONTRIBUTING.md for contribution and release instructions, SECURITY.md for private vulnerability reporting, and CHANGELOG.md for release history.

Released under the MIT License.