Metadata-Version: 2.4
Name: discord-date-transformer
Version: 0.1.0
Summary: Reusable date and time transformers for discord.py application commands.
License-Expression: MIT
License-File: LICENSE.md
Keywords: app-commands,date,datetime,discord,discord.py,slash-commands,transformer
Author: Eli-ezer Reuven Ramirez Ruiz
Author-email: ramirez.ruiz.eliezer.reuven@gmail.com
Requires-Python: >=3.12
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Requires-Dist: discord.py (>=2.7.1,<3.0.0)
Project-URL: Documentation, https://discord-date-transformer.readthedocs.io/
Project-URL: Issues, https://github.com/ezer-mackenzie/discord-date-transformer/issues
Project-URL: Repository, https://github.com/ezer-mackenzie/discord-date-transformer
Description-Content-Type: text/markdown

# discord-date-transformer

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

[![CI](https://github.com/ezer-mackenzie/discord-date-transformer/actions/workflows/ci.yml/badge.svg)](https://github.com/ezer-mackenzie/discord-date-transformer/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/discord-date-transformer)](https://pypi.org/project/discord-date-transformer/)
[![Python](https://img.shields.io/pypi/pyversions/discord-date-transformer)](https://pypi.org/project/discord-date-transformer/)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE.md)

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

## Installation

```bash
pip install discord-date-transformer
```

## Quick start

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

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

### 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 in version 0.1.0.

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

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

Run the complete local checks:

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

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

## License

Released under the [MIT License](LICENSE.md).

