Skip to main content

discord-date-transformer

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

CI PyPI Python License: MIT

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

Installation

pip install discord-date-transformer

Quick start

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})"
    )

Available transformers

Annotation Example input Return type Accepted syntax
ISODateTransform 2026-08-30 datetime.date Values accepted by date.fromisoformat()
ISODateTimeTransform 2026-08-30T18:30 datetime.datetime Values accepted by datetime.fromisoformat()
TimeTransform 18:30:45 datetime.time Values accepted by time.fromisoformat()
DurationTransform 2h datetime.timedelta One positive integer followed by s, m, h, d, or w
DateRangeTransform 2026-08-01/2026-08-30 tuple[date, date] Two ISO dates separated by /, with start no later than end
TimezoneTransform America/Santiago zoneinfo.ZoneInfo An available IANA timezone identifier

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

Date ranges

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

Timezones

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 syntax

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

Unit Meaning
s seconds
m minutes
h hours
d days
w weeks

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

Error handling

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.

Requirements

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

Development

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.

License

Released under the MIT License.

Metadata

Release files for discord-date-transformer 0.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for discord-date-transformer 0.2.0
File Size Uploaded Provenance Actions
discord_date_transformer-0.2.0.tar.gz 5.0 kB With provenance Details for discord_date_transformer-0.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for discord-date-transformer 0.2.0
File Interpreter ABI Platform Actions
discord_date_transformer-0.2.0-py3-none-any.whl Python 3 none any Details for discord_date_transformer-0.2.0-py3-none-any.whl

Total release size: 13.2 kB

Release files / discord_date_transformer-0.2.0.tar.gz

Download URL discord_date_transformer-0.2.0.tar.gz
Size 5.0 kB
Tags Source
SHA-256 checksum
How to use checksums
a288278e457a57d3221917d210a4d48f4f9d4e851c9844ef7cfa2fad1a7ad6d0
BLAKE2b-256 checksum
How to use checksums
abdae5bb7b5c25562a3ad93f8062821f90c0c9f440013ebf1bd6be38deea1076
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Aug 30, 2026.

Transparency log

Release files / discord_date_transformer-0.2.0-py3-none-any.whl

Download URL discord_date_transformer-0.2.0-py3-none-any.whl
Size 8.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
8c47c5044f78051ff2c7e552828434e95879d68eed3336e025e83fffb4823af4
BLAKE2b-256 checksum
How to use checksums
3a99ed7b9162c0dd1738b89071771a0861820b1fecb17f9ff03d037cd9c0ad3b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Aug 30, 2026.

Transparency log

Security for discord-date-transformer 0.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for discord_date_transformer-0.2.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Aug 30, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.2.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page